Web Apps & Utilities

Last updated Oct 2026

Project Q&A Knowledge Base

Overview

Private Collab Whiteboard is a real-time collaborative whiteboard that needs no account, no backend and no database. Everyone in a room draws on a shared infinite canvas, and each browser holds the whole board as a Y.js CRDT document persisted in IndexedDB. Edits pass between browsers through a 35-line PartyKit relay that forwards bytes without reading them. The interesting part is access control without a server: in a password-protected room every frame is AES-256-GCM-encrypted, and every edit is signed with an ECDSA key that viewer links simply don't contain. View-only therefore holds even against a viewer who rewrites the client, and the owner can revoke old links by rotating the room to a new key epoch.

Problem Solved

Most collaborative whiteboards keep your boards on their servers and enforce permissions there, so the provider can read everything and "view-only" means whatever its backend decides. I wanted a whiteboard where the server is untrusted by construction: it can't read the content, and it doesn't need to be asked who may edit. That meant moving both confidentiality and authorization into the browser, with cryptography doing what a permissions table normally does.

Target Users

Small teams sketching something sensitive — architecture diagrams, incident timelines or plans they don't want stored by a third party
Presenters and teachers — share a viewer link and present with the laser pointer, knowing the audience can't alter the board
Anyone who wants a quick shared canvas — open the site, create a room, send the link; no sign-up

Key Features

Real-time collaboration: CRDT sync with live cursors, live previews of shapes as they are drawn, and a presence list
Drawing tools: pencil and highlighter; line, arrow, rectangle, circle, ellipse, diamond and triangle with solid/dashed/dotted strokes, fills and arrowhead options; text; multi-line sticky notes that wrap and scroll; connectors that stay bound to the shapes they link; a fading laser pointer; shape and brush erasers
Editing: Shift multi-select, move, restyle, reorder, lock, copy/paste/duplicate, and undo/redo that only touches your own changes
Infinite canvas: Space-drag or two-finger pan, cursor-centered wheel zoom and pinch zoom from 10% to 500%, and fit-all
Several boards per room: create, rename, clear and delete tabs, with renames synced to everyone
Export: frame the board in a pan/zoom dialog, then save a 2× PNG or a single-page PDF
End-to-end encryption: add a password to any room; the key comes from PBKDF2 (600,000 iterations, random per-room salt) and existing drawings carry over
Owner, editor and viewer links: the role is defined by which private keys the link carries
Revocation: the owner changes the password to move the room to a new epoch, and old links stop producing accepted edits
Offline-first: boards load from IndexedDB and edits made offline merge on reconnect
My Boards: a local history of rooms with role badges, encryption status, last visit and visit count

Technical Highlights

A signed sync layer that makes view-only cryptographic

Encryption hides content from the relay, but every participant who has the password can decrypt, so a client-side readOnly flag stops nobody. I replaced Y.js's stock document-sync protocol with a small layer of my own (js/signed-doc-sync.js, js/protocol.js). Editors sign each update over epoch ‖ update with the epoch's ECDSA P-256 key; every receiving peer checks the epoch, the owner-signed certificate, and the signature before calling Y.applyUpdate, and drops the frame silently on any failure. Viewers are never given a signing key, so their updates fail verification everywhere and never enter anyone's document. The certificate is verified once at start and must pin exactly the editor key in use, or the peer applies nothing. Y.js still does all conflict resolution; only the framing is mine.

Revocation with no server: an owner root of trust and key epochs

The hard problem without a server is revocation: there is no authority to ask whether a link is still valid. js/room-cert.js builds a two-level hierarchy. A per-room owner key signs a certificate binding the current editor public key to an epoch number, and peers trust only an editor key that a valid certificate vouches for. Only the owner link carries the owner private key, and the app never offers it for sharing. Rotation (rotateCapability in room-manager.js, rotateRoom in yjs-setup.js) mints epoch N+1 with a new editor key and password, then broadcasts an owner-signed {type: 'rotate', room, from, to} notice. Peers that verify it mark their epoch superseded and stop applying, broadcasting or relaying its state, so holders of old links can't produce edits anyone accepts.

Treating the shared document as hostile input

In a peer-to-peer app the dangerous input isn't a form field, it's the CRDT. Shape fields, names and presence state arrive from other browsers, and several of them reach innerHTML (the shape-settings header, cursor labels, the user list). I defend at two layers. Allow-lists in js/utils.js and js/shape-schema.js accept only what the app itself produces: safeColor takes hex only, safeToolName maps anything outside 13 known tools to the literal shape, safeNumber rejects non-finite input, and one shared escapeHtml handles text. Behind them, the vercel.json CSP is script-src 'self' with no unsafe-inline, so a missed sink still can't execute script. The same boundary covers denial of service: clampPoints caps a stroke at 5,000 points, safeStrokeWidth clamps line width to 0–200, and remote laser trails are cut to 300 points, so one malicious peer can't stall every other client's render loop.

Connectors that follow shapes without a "connector moved" message

A connector between two boxes must follow them as either one moves, on every client. I store a connector as {fromId, toId, fromAnchor, toAnchor}: the ids of its shapes, plus the compass side of each (n/e/s/w), chosen at creation by nearestAnchors in js/connector-geometry.js. The endpoint coordinates are never stored. Each redraw resolves the anchors against the shapes' current bounding boxes, using an id→shape Map (buildShapeIndex) built once per pass so each lookup is O(1). When a peer moves a box, only the box's own object changes, and every connector on it re-routes when that update lands. Deleting a shape also removes connectors left dangling, in the same transaction, so a single undo restores both (tests/undo-cascade.test.js). Connectors can't bind to other connectors, which rules out recursive resolution.

Pure modules so a canvas app can be unit-tested

Canvas apps tend to bury arithmetic inside event handlers, where only a real browser can test it. I pulled the non-trivial logic into DOM-free modules that take and return plain values: draw-geometry.js (hit-testing, polygon vertices, arrowheads, degenerate-shape detection), connector-geometry.js, text-wrap.js (word wrap with hard breaks, sticky-note scroll extent), laser-trail.js and keyboard-intent.js, alongside the crypto, protocol and link modules. Vitest runs the 26 test files in its Node environment with no DOM. Signed sync is tested end to end with in-memory transports, including forged viewer updates, wrong-epoch replays, and rotation notices not signed by the owner.

Engineering Decisions

Transport: a WebSocket relay over peer-to-peer WebRTC

Constraint: Sync had to work on corporate firewalls, mobile carriers and double-NAT home routers, with the server outside the trust boundary.
Options: A y-webrtc mesh, a self-hosted Y.js WebSocket server, or a broadcast relay on PartyKit.
Choice: The PartyKit relay (party/index.ts), with every payload encrypted in the browser.
Why: WebRTC needs STUN/TURN and still fails on restrictive networks; a WebSocket reaches anywhere HTTPS does. A standard Y.js server applies and stores updates, so it needs plaintext. A relay that only forwards bytes doesn't, and keeps the privacy model of a peer-to-peer design.

Creating the default board lazily

Constraint: If every client ran boards.set('default', new Y.Array()) on load, two people joining together created competing default entries in the boards Y.Map. The CRDT picks one winner by client id, which can orphan the array that actually holds the drawings: the bytes sync, but the content never renders.
Options: Wait out a sync timeout before creating it, let only the owner create it, or create it on the first write.
Choice: yjs-setup.js never creates it; addDrawing in drawing.js creates the array on the first shape, and the board tab bar shows the default tab ("Main") even before it exists.
Why: A joiner receives the existing array in a snapshot and never races to create a rival. That fixes a seeding problem without inventing roles or timing heuristics.

Capabilities in the URL fragment

Constraint: View-only had to survive a hostile viewer who has the password and will edit the URL or patch the JavaScript, with no accounts and no server-side check.
Options: A client-side flag, a signed role string (nothing checks it when an edit arrives), server-issued tokens, or links where the missing key is the enforcement.
Choice: The link fragment carries the keys for its role: viewer links only public keys, editor links add the editor private key, owner links add the owner private key (room-manager.js). Every update's signature is checked before it is applied.
Why: There is nothing to flip. A viewer can't conjure a key by editing a URL, fragments never reach a server, and trust is rooted in the owner key rather than a shared secret. The decoder accepts only the v3 format, because honoring a weaker old one would be a downgrade path.

Whole-object shapes over per-field CRDT maps

Constraint: A board holds many small shapes of a dozen kinds that must be rendered, sanitized, copied, exported and undone.
Options: A nested Y.Map per shape for field-level merges, or one plain JSON object per shape in a Y.Array.
Choice: Plain objects; an edit deletes and re-inserts the shape at its index in one transaction.
Why: Every consumer works on simple values and each edit is one undo step. I accepted the cost: there's no field-level merge, so simultaneous edits to the same shape keep both versions rather than combining them.

Frequently Asked Questions

How does real-time sync work without a database?

Each browser keeps the full board as a Y.js document and persists it to IndexedDB. A local change produces a binary Y.js update, which is wrapped in an {epoch, update, sig} envelope, encrypted if the room has a password, and sent to the relay, which forwards it to everyone else in the room. Because Y.js is a CRDT, peers converge to the same state whatever order updates arrive in. A peer that joins late asks for a snapshot and gets the full state from whoever is online.

What if nobody else is online when I open a board?

You still see everything you've seen before, because your copy lives in IndexedDB. You can draw offline, and your changes merge when someone else is online. Since the relay stores nothing, a board you've never opened can only load while another participant is connected. That is the cost of having no server-side storage.

How does the encryption protect my data?

Adding a password derives an AES-256-GCM key with PBKDF2 (600,000 iterations of SHA-256) over a random 16-byte salt minted for that room. The salt and iteration count travel in the invite link so every peer derives the same key, and the count is clamped to 100,000–5,000,000 on decode, so a tampered link can't weaken the derivation or stall your browser on it. Every frame then gets a random 12-byte IV and is encrypted before it reaches the WebSocket: document updates, snapshots, cursors, names and live previews. The only plaintext frame is a one-field {enc: true} beacon that tells a visitor without a key the room is encrypted.

Is the board encrypted on my own device?

No, and this is deliberate. Encryption protects data in transit and from the relay. Locally, IndexedDB holds the decrypted document so the board opens instantly and works offline, and the invite link carries the password and keys in its fragment, so it sits in your browser history like any URL. Treat an invite link like a password.

How does view-only stop a determined viewer?

It doesn't depend on the viewer's client behaving. A viewer link has only public keys. Every edit in an encrypted room must carry a valid signature from the epoch's editor key, and every peer checks it before applying (signed-doc-sync.js). A viewer who forces their client into edit mode broadcasts updates with no valid signature, and every other peer drops them. Hiding the toolbar for viewers is only cosmetic.

What's the difference between owner, editor and viewer links?

All three are capability links in the URL fragment. A viewer link can decrypt but not sign. An editor link adds the editor private key, so it can draw. An owner link adds the owner private key, so it can also rotate the room. The Invite dialog only offers editor and viewer links; the owner link stays in the creator's address bar.

How does revoking access work without a server?

Only the owner can do it, by changing the password. That mints epoch N+1 with a new editor key and password and broadcasts an owner-signed rotate notice. Connected peers verify it, mark the old epoch superseded, and are told to ask for a new link; the owner is reloaded into the new epoch. Old links can still open whatever their holder already has cached, but can no longer produce edits that current peers accept, and with a new password they can't decrypt new traffic either.

What happens if someone tampers with or truncates an invite link?

parseCapabilityHash in room-manager.js distinguishes three cases. No fragment means an intentionally open room. A valid fragment returns the capability. A fragment that is present but won't decode throws, rather than quietly dropping you into an editable unencrypted room, which would be the dangerous default. A role claimed without its matching key is downgraded, so editing r: 'owner' into a viewer link gives you a viewer.

What happens if two people edit the same shape at once?

Different shapes never conflict. Each shape is a whole JSON object in the board's Y.Array, and moving or restyling one replaces that object. If two people change the same shape at the same instant, Y.js doesn't merge their fields; the merge keeps both replacement versions. In practice two people rarely grab the same shape at once, and I chose this simpler model over a nested map per shape.

How do connectors stay attached when I move a shape?

A connector stores the ids of its two shapes and which side of each it attaches to, not coordinates. Every redraw resolves those sides against the shapes' current bounding boxes, so when anyone moves a connected shape the connector follows on every screen with no extra message. Deleting a linked shape removes the connector in the same step, and undo brings both back.

Why vanilla JavaScript instead of React or Svelte?

The core of the app is imperative Canvas drawing, which a virtual DOM doesn't help with. The rest of the UI (toolbar, tabs, popups, modals) is small enough for direct DOM code. No framework also means no inline bootstraps or runtime-generated scripts to accommodate, which keeps the strict script-src 'self' CSP simple.

How does it perform on large boards?

Each change to the board triggers a full redraw of every shape on the current board; there is no viewport culling or layering yet. Within a redraw, connector endpoints are resolved through an id→shape Map instead of scanning the board, and untrusted strokes are capped at 5,000 points. Overflowing sticky notes draw only the lines inside their visible area. That is comfortable for typical whiteboard sizes (dozens to a few hundred shapes); viewport culling would be the next step for much larger boards.

Can I export a board?

Yes. Save opens a dialog that renders the board into its own canvas, so you can pan and zoom to frame the export independently of your on-screen view. It saves a PNG at twice the preview resolution, or a single-page PDF made with jsPDF from the same render.

Why PartyKit instead of my own WebSocket server?

The relay's only job is fanning out bytes per room. PartyKit gives per-room isolation on Cloudflare's edge, TLS, and a one-command deploy that GitHub Actions runs whenever the server code changes, leaving 35 lines of my own server code. Because the relay holds no keys and no state, swapping hosts means changing PARTYKIT_HOST in js/config.js.

Technology Stack

Core Technologies

Category	Technology	Version	Why this choice
Language	JavaScript (ES modules)	—	The app is an imperative Canvas program; no framework runtime is needed to drive `ctx` calls
Server language	TypeScript	compiled by PartyKit	Type-checked `Party.Server` interface for the relay; the only TypeScript file in the repo
Rendering	HTML5 Canvas 2D	—	One surface for every tool, the live previews, and the off-screen export render
Sync engine	Y.js	^13.6.0 (13.6.29 locked)	Mature JavaScript CRDT with an UndoManager that understands local versus remote changes
Relay	PartyKit	^0.0.115	Per-room WebSocket isolation on Cloudflare's edge, deployed with one command, for a server that only broadcasts
Crypto	Web Crypto API	browser built-in	Native AES-GCM, PBKDF2 and ECDSA with no crypto library in the bundle
Build tool	Vite	^8.0.16	Multi-page builds and a dev server whose middleware can mirror Vercel's routing
Tests	Vitest	^4.1.8	Native ES modules, and runs the pure logic modules in Node with no DOM
Export	jsPDF	^4.2.1	Wraps the rendered canvas image in a single-page PDF

Frontend

Framework: None — vanilla ES modules, four HTML entry points (index.html, room.html, boards.html, how-it-works.html)
Rendering: Canvas 2D for the board; DOM for the toolbar, tabs, popups, modals, and cursor labels
State management: the Y.Doc is the single source of truth (boards Y.Map of Y.Arrays, plus a boardNames Y.Map); ephemeral state (cursors, previews, laser) lives in Y.js awareness
Styling: hand-written CSS (css/styles.css) with CSS custom properties; Inter from Google Fonts
Build tool: Vite in MPA mode (appType: 'mpa')

Backend

Runtime: PartyKit (Cloudflare Workers based)
Server: party/index.ts, 35 lines — forwards each message to every other connection in the room and never inspects it
Wire protocol: one type byte plus payload (js/protocol.js): UPDATE, SNAPSHOT, SNAPSHOT_REQUEST, AWARENESS, ROTATE, and a plaintext PRESENCE_PROBE. Document messages carry an {epoch, update, sig} envelope encoded with lib0
Authorization: capability links (owner / editor / viewer) whose permissions come from the ECDSA P-256 keys they contain, verified by every peer and rooted in a per-room owner key
Encryption: AES-256-GCM on every frame except the presence probe; the relay never holds a key

Infrastructure

Hosting: Vercel (static frontend) and PartyKit (relay, whiteboard-collab in partykit.json)
CI/CD: GitHub Actions. ci.yml runs npm ci, npm test and npm run build on Node 24 for every pull request and push to main. deploy-partykit.yml re-runs the same gates and then partykit deploy, only on pushes that touch party/, partykit.json, the npm manifests, or the workflow itself. Vercel deploys the frontend from Git.
URL routing: cleanUrls: true plus one rewrite, /room/:id → /room, in vercel.json. The rewrite targets the extensionless path because cleanUrls redirects /room.html to /room. The Vite dev middleware in vite.config.js mirrors both rules so local URLs match production.
Security headers (vercel.json): CSP with default-src 'self'; script-src 'self' (no unsafe-inline), connect-src 'self' wss://*.partykit.dev, frame-ancestors 'none', base-uri 'none', form-action 'self'; plus HSTS (two years, subdomains), X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer, and a Permissions-Policy that turns off camera, microphone and geolocation. Google Fonts is the only third-party origin allowed.
Caching: max-age=0, must-revalidate by default; /js/* is served immutable for one year
SEO: canonical links and JSON-LD on the two public pages, robots.txt that disallows /room/, and a two-URL sitemap.xml
Monitoring: none

Development Tools

Package manager: npm (with overrides pinning esbuild ^0.25.12 and undici ^6.26.0)
Dev servers: Vite, plus partykit dev for a local relay; concurrently runs both with npm run dev:all
Testing: Vitest in the Node environment (vitest.config.js), 26 files under tests/ covering key derivation, signing, certificates, the wire protocol, signed sync, the snapshot cache, the transport, capability links, sanitizers, geometry, text wrap, laser trails, keyboard intent, board history, and connector cascade-delete with undo. The logic is factored into browser-free modules so it can be tested without a DOM.
Linting / formatting: none configured
Image generation: scripts/generate-icons.js uses sharp to render the favicon set from public/favicon.svg

Key Dependencies

Package	Purpose
`yjs`	CRDT document: a Y.Map of boards, a Y.Array of shapes per board, and `Y.UndoManager`
`y-indexeddb`	Persists the Y.Doc to IndexedDB, so boards load offline and survive reloads
`y-protocols`	The awareness protocol for presence (cursors, previews, laser trails)
`lib0`	Varint binary encoding for the signed envelopes and awareness frames
`jspdf`	Turns the export render into a downloadable PDF
`partykit`	Relay runtime types and the `dev` / `deploy` CLI
`vite`	Dev server and multi-page production build
`vitest`	Test runner
`concurrently`	Runs Vite and the PartyKit dev server together
`sharp`	Favicon generation

partysocket and y-partykit are still listed in package.json but nothing in the client imports them. The transport in js/sync-provider.js uses the browser's native WebSocket with its own backoff (100 ms doubling to a 2.5 s cap), and document sync is the custom signed layer rather than y-partykit's provider.

Cryptography Stack

Component	Technology	Configuration
Key derivation	PBKDF2-HMAC-SHA-256	600,000 iterations for new rooms. The count travels in the link's `kdf` field and is clamped to `[100,000, 5,000,000]` on decode, so a tampered link can't weaken derivation below the legacy floor or stall a victim on a multi-second one. Links without `kdf` use 100,000.
Salt	16 random bytes per room	Minted with the room and carried in the link, so a password can't be attacked with a table precomputed from the public room ID. Links without a salt fall back to `whiteboard-{roomId}`.
Encryption	AES-256-GCM	Random 12-byte IV per message, prepended to the ciphertext; derived key is non-extractable
Signing	ECDSA P-256 / SHA-256	Raw 64-byte r‖s signatures over `epoch ‖ update`. Chosen over Ed25519 for Web Crypto support across installed browsers
Certificates and notices	ECDSA P-256 over canonical JSON	The owner key signs `{room, epoch, editorPub}` certificates and `{type: 'rotate', room, from, to}` rotation notices
Key handling	Web Crypto	Keys travel as base64 (raw public, PKCS8 private) in the URL fragment and are imported as non-extractable `CryptoKey`s

Browser Requirements

checkBrowserCompatibility() in app.js checks the first four at startup and shows an "unsupported browser" screen if any is missing:

WebSocket
IndexedDB
Web Crypto (crypto.subtle)
TextEncoder / TextDecoder
HTML5 Canvas
ES modules (type="module")

Architecture Overview

System Diagram

flowchart TD
    subgraph Browser["Browser"]
        LP[index.html<br>index-home.js]
        BP[boards.html<br>boards-home.js]
        HW[how-it-works.html]
        RP[room.html]

        subgraph AppCore["Room application"]
            APP[app.js<br>Entry point + UI wiring]
            DRW[drawing.js<br>Canvas engine]
            BRD[boards.js<br>Boards in a room]
            AWR[awareness.js<br>Presence + previews]
            UND[undo-redo.js<br>Y.UndoManager]
            MOD[modal.js<br>Dialogs]
        end

        subgraph Pure["Pure, DOM-free modules"]
            GEO[draw-geometry.js]
            CON[connector-geometry.js]
            TXT[text-wrap.js]
            LAS[laser-trail.js]
            KEY[keyboard-intent.js]
            SAN[shape-schema.js + utils.js<br>Sanitizers]
        end

        subgraph SyncLayer["Sync and trust"]
            YJS[yjs-setup.js<br>Y.Doc + rotation]
            SDS[signed-doc-sync.js<br>Signed / open sync]
            PROTO[protocol.js<br>Envelope + signing]
            SP[sync-provider.js<br>WebSocket transport]
            CRY[crypto.js<br>AES-GCM, PBKDF2, ECDSA]
            CERT[room-cert.js<br>Epoch certificates]
            RM[room-manager.js<br>Capability links]
            SNAP[snapshot-store.js<br>Snapshot cache]
        end

        subgraph Storage["Browser storage"]
            IDB[(IndexedDB<br>Y.Doc)]
            LS[(localStorage<br>history, snapshots, name)]
        end
    end

    subgraph Server["PartyKit"]
        PK[party/index.ts<br>Broadcast relay]
    end

    LP --> RP
    BP --> RP
    LP --> RM
    RP --> APP
    APP --> DRW
    APP --> BRD
    APP --> UND
    APP --> MOD
    APP --> YJS
    DRW --> GEO
    DRW --> CON
    DRW --> TXT
    DRW --> LAS
    DRW --> SAN
    APP --> KEY
    DRW --> AWR
    BRD --> AWR

    YJS --> RM
    YJS --> SDS
    YJS --> IDB
    SDS --> PROTO
    SDS --> CERT
    SDS --> SNAP
    PROTO --> CRY
    CERT --> CRY
    RM --> CRY
    SDS --> SP
    AWR --> SP
    SP --> CRY
    SNAP --> LS
    BRD -.-> LS

    SP <-->|"type byte + payload<br>(ciphertext in encrypted rooms)"| PK

Data Flow

sequenceDiagram
    participant User
    participant Canvas as drawing.js
    participant YDoc as Y.Doc
    participant IDB as IndexedDB
    participant Signed as signed-doc-sync.js
    participant Provider as sync-provider.js
    participant Relay as PartyKit
    participant Peer as Other peer

    User->>Canvas: Finish a stroke or shape
    Canvas->>YDoc: Push shape object to the board's Y.Array
    YDoc->>IDB: Persist locally
    YDoc->>Signed: 'update' event (local origin)

    alt Encrypted room, editor
        Signed->>Signed: Sign (epoch ‖ update) with ECDSA P-256
    else Open room
        Signed->>Signed: Empty signature
    end
    Signed->>Provider: UPDATE {epoch, update, sig}
    opt Encrypted room
        Provider->>Provider: AES-256-GCM encrypt
    end
    Provider->>Relay: WebSocket frame
    Relay->>Peer: Forward to every other connection

    Note over Peer: Viewers can decrypt but<br>hold no editor signing key
    Peer->>Peer: Decrypt, then check epoch, certificate, signature
    Peer-->>Peer: Drop on any failure
    Peer->>Peer: Y.applyUpdate (CRDT merge)
    Peer->>Peer: Observer redraws the canvas

    Note over Signed,Peer: ~1 s after edits stop, the editor also<br>broadcasts a signed full-state SNAPSHOT

A joining peer sends SNAPSHOT_REQUEST when its socket opens and retries every 1.5 s, up to five times, until some state applies. Editors answer with a fresh signed snapshot; viewers relay the last verified snapshot they hold, so a room with only viewers online can still bootstrap a newcomer.

Component Descriptions

app.js — Room entry point

Purpose: Starts the room and connects the UI to the document and sync layers
Location: js/app.js
Key responsibilities: Browser feature check, display-name prompt, role-aware UI (viewers lose editing controls, only the owner sees Change password), per-tool settings remembered within the session, keyboard shortcuts, Space-drag panning and cursor-centered wheel zoom, fit-all, the PNG/PDF export dialog (2× render, jsPDF for PDF), invite / encrypt / rotate actions, and status notices for rotation, wrong password, and "invite link required"

drawing.js — Canvas engine

Purpose: Everything that touches the canvas: rendering, hit-testing, and shape editing
Location: js/drawing.js
Key responsibilities: World/screen coordinate transform; rendering every tool from the current board's Y.Array; mouse, touch and pinch input; selection and Shift multi-select; moving shapes; the settings popup (color, stroke, fill, font, arrowheads, stacking order, connector reversal, lock); copy/paste/duplicate with connector re-pointing; inline text and sticky-note editing; connector creation, rendering and cascade deletion; local and remote live previews; laser trails; lazy creation of a board's array on its first shape; conversion of stroke width to world units; and renderBoardToCanvas, which renders the board into an arbitrary canvas and view for export

Pure geometry and layout modules

Purpose: Logic pulled out of the canvas engine so it can be unit-tested without a DOM
Location: js/draw-geometry.js, js/connector-geometry.js, js/text-wrap.js, js/laser-trail.js, js/keyboard-intent.js
Key responsibilities: draw-geometry.js — arrowheads, diamond/triangle vertices, ray-casting point-in-polygon, dash patterns, text bounds, degenerate-shape detection, and buildShapeIndex, an id→shape Map built once per redraw so connector endpoint lookups are O(1). connector-geometry.js — compass-anchor resolution, choosing facing anchors between two boxes, anchor hints, and finding connectors whose endpoints were deleted. text-wrap.js — greedy word wrap with hard breaks for long words, newline-aware wrapping for sticky notes, and sticky scroll extent. laser-trail.js — drops trail points older than 700 ms. keyboard-intent.js — decides whether Delete/Backspace should consume the event.

shape-schema.js and utils.js — Untrusted-input boundary

Purpose: Make peer-supplied data safe before it reaches the DOM or the renderer
Location: js/shape-schema.js, js/utils.js
Key responsibilities: escapeHtml (the single shared implementation), safeColor (hex only), safeNumber, safeToolName (13 known tools, otherwise the literal shape), and sanitizeShape, which runs a shape's DOM-bound fields through them. For render cost: clampPoints caps a stroke at 5,000 points and safeStrokeWidth clamps line width to 0–200, so a hostile peer can't stall every other client's frame.

yjs-setup.js — Document and sync wiring

Purpose: Builds the per-room Y.Doc and connects storage, transport and the signed sync layer
Location: js/yjs-setup.js
Key responsibilities: Creates the boards and boardNames maps; opens a separate IndexedDB store for encrypted and open rooms; derives the AES key from the capability's password, salt and iteration count; creates SignedDocSync in signed mode for capability rooms and open mode otherwise; copies an open room's existing drawings into the encrypted store when encryption is first added; and implements rotateRoom(), which mints the next epoch, broadcasts the owner-signed notice, and reloads the owner into the new link. It deliberately does not create the default board at startup (see Key Architectural Decisions).

signed-doc-sync.js — Signed document sync

Purpose: Moves Y.js updates between peers and enforces the edit/view-only boundary
Location: js/signed-doc-sync.js
Key responsibilities: Two modes. Signed: verifies the owner-signed certificate once at start and fails closed unless it is for this epoch and pins exactly the editor key in use; signs local updates as an editor; applies only current-epoch, correctly signed updates and snapshots. Open: empty signatures, no verification. Also debounces signed snapshots (1 s), persists and relays the last verified snapshot, retries bootstrap requests, and on a verified owner rotation notice marks the epoch superseded, so it stops applying, broadcasting, or relaying old-epoch state. All async sign/verify work runs through one promise queue so updates apply in arrival order.

protocol.js — Wire format

Purpose: Message types and the bytes that get signed
Location: js/protocol.js
Key responsibilities: Type constants (UPDATE, SNAPSHOT, SNAPSHOT_REQUEST, AWARENESS, ROTATE, PRESENCE_PROBE); encodeEnvelope / decodeEnvelope for epoch ‖ update ‖ sig with lib0; signUpdate / verifyUpdate, which sign the update prefixed by its epoch so a signature can't be replayed into another epoch; and JSON encoding for rotation notices.

sync-provider.js — Transport

Purpose: The WebSocket connection, encryption of frames, and presence
Location: js/sync-provider.js
Key responsibilities: Native WebSocket to /party/{roomId} with exponential-backoff reconnect (100 ms doubling to 2.5 s); wss:// everywhere except canonical loopback hosts; a one-byte type prefix on every frame; AES-256-GCM on every type except PRESENCE_PROBE, silently dropping frames that don't decrypt; Y.js awareness, re-broadcast when a new peer appears because the relay keeps no history; and the plaintext {enc} presence probe, which lets a visitor without a key learn the room is encrypted.

crypto.js — Primitives

Purpose: All Web Crypto usage
Location: js/crypto.js
Key responsibilities: PBKDF2 key derivation with caller-supplied iterations and salt (legacy room-ID salt fallback); AES-256-GCM with a random 12-byte IV per message; ECDSA P-256 key generation, export (raw public, PKCS8 private) and non-extractable import; signData / verifyData (64-byte r‖s, verification never throws); and signStatement / verifyStatement over canonical JSON for certificates and notices.

room-cert.js — Epoch certificates

Purpose: The owner's root of trust over the editor key
Location: js/room-cert.js
Key responsibilities: mintCert signs {room, epoch, editorPub} with the owner key; verifyCert returns the bound epoch and editor key, or null for anything missing, malformed or not owner-signed, and never throws.

room-manager.js — Capability links

Purpose: Encode, decode, mint and rotate the links that grant access
Location: js/room-manager.js
Key responsibilities: mintRoomCapability (owner key pair, first editor key pair, epoch-1 certificate, random salt, iteration count); role-scoped encoders (owner carries both private keys, editor only the editor key, viewer none); a v3-only decoder that downgrades any claimed role lacking its key and clamps kdf; parseCapabilityHash, which throws on a present-but-invalid fragment; owner-only rotateCapability; getShareableLink, which never emits an owner link; and room-ID parsing from /room/{id}.

snapshot-store.js — Snapshot cache

Purpose: Keep the latest verified snapshot so a reconnecting peer has something to apply and relay
Location: js/snapshot-store.js
Key responsibilities: Base64 snapshot in localStorage under wb-snap-{room}-e{epoch}; prunes the room's other epochs on construction. IndexedDB remains the real document store; this is only for bootstrap.

awareness.js — Presence

Purpose: Ephemeral per-user state
Location: js/awareness.js
Key responsibilities: Local user id, name and color; current board; cursor position (throttled to 50 ms); in-progress drawing for live preview; laser trail (remote trails capped at 300 points); the online-users list and cursor labels, with names escaped and colors allow-listed.

boards.js — Boards within a room

Purpose: The tab bar of boards
Location: js/boards.js
Key responsibilities: Create, switch, clear, rename and delete. Labels live in the separate boardNames map, so renaming never changes a board's key, and the default board can be renamed (it shows as "Main") but not deleted. The default tab is shown even before its array exists. Right-click on any tab opens the rename/delete menu.

undo-redo.js — History

Purpose: Collaborative-safe undo
Location: js/undo-redo.js
Key responsibilities: A Y.UndoManager over the boards map with a 500 ms capture window. Remote updates are applied with a dedicated origin, so they never land on the local stack.

modal.js — Dialogs

Purpose: Replacements for native prompt / confirm / alert
Location: js/modal.js
Key responsibilities: Prompt, confirm, alert, the invite dialog (editor or viewer link), password entry, the save/export dialog, and the shortcuts reference.

board-history.js — My Boards

Purpose: Local history of rooms visited
Location: js/board-history.js
Key responsibilities: Save and touch entries with role (owner / collaborator / viewer, never downgrading a recorded owner), encryption flag, last access and visit count; relative-time formatting; role badges.

party/index.ts — Relay

Purpose: Forward bytes between the browsers in a room
Location: party/index.ts
Key responsibilities: On each message, send it to every connection in the room except the sender. No storage, no parsing, no keys; 35 lines.

External Integrations

Service	Purpose	Notes
PartyKit	WebSocket relay	Holds no state and no keys; sees only ciphertext in encrypted rooms. Deployed by GitHub Actions with `PARTYKIT_TOKEN` / `PARTYKIT_LOGIN` secrets
Vercel	Static hosting	Clean URLs, the `/room/:id` rewrite, CSP and security headers from `vercel.json`; deploys from Git
GitHub Actions	CI and relay deploy	Tests and build on every PR and push to `main`; relay deploy is path-filtered and runs behind the same gates
Google Fonts	Inter typeface	The only third-party origin in the CSP

Key Architectural Decisions

CRDT over operational transform

Context: Concurrent edits had to converge with no authoritative server, and offline edits had to merge on reconnect.
Decision: Y.js.
Rationale: OT needs a central server to order operations, which is exactly what this design avoids. A CRDT converges from any delivery order, so the relay can be a plain broadcast and IndexedDB-persisted offline edits merge on reconnect. Y.js is the most mature JavaScript CRDT and its UndoManager already separates local from remote changes.

A broadcast relay over a WebRTC mesh

Context: Sync had to work on corporate networks, mobile carriers and double-NAT home routers, without letting the server into the trust boundary.
Options: y-webrtc peer-to-peer, a self-hosted Y.js WebSocket server, or a broadcast relay on PartyKit.
Decision: PartyKit, with the relay reduced to forwarding bytes.
Rationale: WebRTC needs STUN/TURN and still fails on restrictive networks; a WebSocket reaches anywhere HTTPS does. Encrypting before send keeps the privacy property of a peer-to-peer design. A stock Y.js server would apply and store updates, which needs plaintext; a relay that never parses messages doesn't.

Signature-enforced view-only over a client-side flag

Context: Encryption hides content from the relay, but everyone with the password can decrypt. A view-only link that only sets readOnly in the client is bypassed by editing the URL or the JavaScript.
Options: Trust a client flag, add a server-side auth check (gives the relay a role), or sign every edit and have peers reject unsigned ones.
Decision: Editors sign each update with the epoch's ECDSA P-256 key; every peer verifies before applying; viewer links contain no signing key.
Rationale: Enforcement moves from convention to cryptography. A viewer's forged updates fail verification at every honest peer and never enter anyone's document. No server and no accounts are needed.

Owner root of trust with epoch certificates

Context: If the editor key is simply embedded in links, a leaked link can't be revoked, and "can edit" is indistinguishable from "controls the room". There is no server to ask.
Options: One shared editor key (no revocation), server-issued tokens (needs a server), or a two-level key hierarchy rooted in an owner key.
Decision: Each room has an owner key pair. The owner signs a certificate binding the current editor public key to an epoch number; peers trust an editor key only if a valid certificate vouches for it. Only the owner can mint a new epoch.
Rationale: Rotation becomes "mint epoch N+1 with a new editor key and broadcast an owner-signed notice". Peers on epoch N stop applying its updates, and old links can no longer sign anything a current peer accepts.

ECDSA P-256 over Ed25519

Context: The signature algorithm had to work in whatever browser people already use.
Options: Ed25519 (smaller, modern) or ECDSA P-256 (older, universal).
Decision: ECDSA P-256.
Rationale: Web Crypto's Ed25519 shipped only in recent browser versions and throws "Unrecognized name" on older ones, while P-256 has been available wherever crypto.subtle exists for years. Universal support outweighs Ed25519's size advantage.

A custom signed sync layer instead of the stock Y.js sync protocol

Context: View-only and rotation need every update to be signed, epoch-tagged and verified, but y-protocols' document sync exchanges state vectors and diffs with no place to attach authorship.
Options: Wrap the stock protocol, or replace only document sync while keeping the Y.js CRDT core and the awareness protocol.
Decision: signed-doc-sync.js and protocol.js exchange signed {epoch, update, sig} envelopes, with signed full-state snapshots for bootstrap.
Rationale: Owning the envelope is what makes per-update signatures, epoch replay protection and fail-closed verification possible. Y.js still does all conflict resolution; the cost is a simpler bootstrap (full snapshots rather than state-vector diffs), which is fine at whiteboard document sizes.

Shapes as whole JSON values in a Y.Array

Context: Each board holds dozens to hundreds of shapes of a dozen different kinds.
Options: A nested Y.Map per shape (field-level merging) or a plain JSON object per shape in a Y.Array.
Decision: Plain objects. An edit replaces the object at its index (delete and insert in one transaction), and connectors store only the ids of their two shapes.
Rationale: Rendering, sanitizing, copying, exporting and undo all work on simple values, and one edit is one undo step. The trade-off is no field-level merge: if two people change the same shape at the same instant, the CRDT keeps both replacement versions. On a whiteboard two people rarely grab the same shape at once, so I chose the simpler model.

Strict CSP plus allow-list sanitization

Context: In a peer-to-peer whiteboard the untrusted input is the shared document itself. Shape fields, names and presence state from other peers are interpolated into innerHTML in several places, and escaping at each one is easy to miss.
Options: Escape at each sink, or centralize sanitization and back it with a CSP that blocks script execution if a sink is missed.
Decision: One shared escapeHtml, type-narrowing allow-lists (safeColor, safeNumber, safeToolName, sanitizeShape), and script-src 'self' with no unsafe-inline, plus base-uri 'none' and form-action 'self'.
Rationale: Allow-lists accept only the values the app itself produces, so injected markup collapses to an inert fallback. The CSP is the backstop, and it is why every page script, including the landing and My Boards bootstraps, is a separate ES module file.

Multi-page build over an SPA

Context: Four pages with very different weight: a marketing landing page, an explainer, a history list, and the whiteboard runtime (Y.js, canvas engine, crypto).
Options: An SPA with a router and code splitting, or Vite MPA with one HTML entry per page.
Decision: MPA (vite.config.js lists index, room, boards, howItWorks).
Rationale: The landing page imports only room-ID, history and link-minting modules, never Y.js. No client state needs to survive navigation between pages, so routing reduces to cleanUrls and one rewrite.

IndexedDB for the document, localStorage for small metadata

Context: Boards must reopen instantly and work offline.
Decision: y-indexeddb for the Y.Doc; localStorage for board history, the display name and user id, and the snapshot cache.
Rationale: IndexedDB handles the growing binary document and integrates directly with Y.js. The rest is small and read synchronously at page load, where localStorage is simpler.

Back to All Projects