# Research notes The builder does not need this file. It records where the design came from (provenance) and how the spec was checked. Nothing in it is a requirement: `spec.md`, `design.md` and `tasks.md` are complete without it. This spec describes a hand-drawn-style whiteboard modelled on Excalidraw, the open-source virtual whiteboard. Excalidraw's code is MIT-licensed. This spec still describes the app in its own words and its own design: - No Excalidraw code, text, icons, fonts (Virgil, Excalifont, Nunito and the like) or branding are used. - The default product name is "Whiteboard" (see "Names and words" in `spec.md`). - What is shared on purpose: - The open `.excalidraw` / `.excalidrawlib` JSON file format, so files move both ways. - The same open-source libraries: roughjs (MIT), perfect-freehand (MIT) and fractional-indexing (CC0). - The hand-drawn font Kalam (SIL Open Font License). ## Sources - **Source code:** `github.com/excalidraw/excalidraw` (MIT) at commit `82190fb28f58070b34b4017e70c0e2e83701a8e3` (2026-11-15). It was read for: - the file format and element fields (`packages/element/src/types.ts`, `packages/excalidraw/data/json.ts`, `data/library.ts`, `data/restore.ts`) - fractional ordering (`fractionalIndex.ts`) and reconciliation (`data/reconcile.ts`) - the collaboration link shapes and timing constants (`excalidraw-app/collab`, `excalidraw-app/data/index.ts`, `app_constants.ts`) - rough rendering options and the dark-mode filter - **Observed behaviour:** REA (`rea-agents`, the official npm package) captured a browser scenario of the public site excalidraw.com in headless Chromium at 1440×900 on 2026-11-16 (IST). The steps were load, help dialog, pick rectangle, main menu and library, with accessibility snapshots and screenshots. - Capture evidence id: `ev_a57c16cb1bb2c63d545abf2dd4da0c94005dcaec9ba92bf3c6645a01bada35ec` - Summary view: `ev_1c7ef34528d053bf93fe88fa17c3252c5de7409866016a026f97e17f8a2f9369` - It was used to confirm the toolbar order and keys, the help dialog groups, the main-menu items, the theme shortcut, the zoom/undo/help placement and the local-first welcome text. - **Cloudflare documentation** (developers.cloudflare.com, read 2026-11-16) on: - Workers static assets (`run_worker_first`, single-page-application fallback) - R2 - Durable Objects with SQLite storage, alarms, the WebSocket Hibernation API and the 2 MB per-value storage limit (hence the chunked snapshot) - the Workers Rate Limiting binding (`ratelimits`, periods of 10 or 60 s) - Cloudflare Access self-hosted applications (only for the README's note on restricting a deployed site; the app has no access setting) - **Settings:** the app's only inputs are `app_name` and `accent_color`. `spekkr.inputs.json` holds exactly those two keys, generated from the `spekkr.json` defaults when missing (spec "Read `spekkr.inputs.json` first"). ## How it was checked A full build following this spec was made from scratch on Workers + R2 + Durable Objects. It passed: - `npm run typecheck` - 44 Vitest unit tests - 22 Playwright end-to-end tests against `wrangler dev`, including multi-browser live sessions, encrypted links opened in fresh browsers, and the rate limit - `wrangler deploy --dry-run` Nothing was deployed. The screenshots in `shots/` come from that build. A first version had accounts, server-side drawings and read-only links. It was cut back to the observed app's model: drawings stay in the browser, and the server only stores encrypted shares. Building it exposed these gaps, now fixed in the spec: - **Ellipse fills:** filling every rough path even-odd erased ellipse fills. R8 now gives the per-shape fill rule. - **Double-click on touchpads:** double-click to enter a group or edit text needs a fallback when the second click lands as a plain click (R10). - **Freehand tool:** the tool stays active after a stroke (R5), like the observed app. - **Image flips:** these must flip the image's `scale`, not only its position (R11). - **`#json=` links:** a link opened in an already-open tab must load (hash change → reload, R24). - **Unknown fields:** element `customData` and `link` must survive open/save (R19). Unknown arrowhead names become none. - **Session ordering:** a shape still being drawn has no order key. When a remote update arrived mid-stroke, it was given a guessed key that could tie with another element, so two people saw different stacking (about one run in four). Now: - Unkeyed elements stay on top during a merge and are never sent. - Re-keying bumps the version, so the fix reaches everyone (R25, design "Ordering"). - **Stored session scene:** upstream-style 20-second snapshots left the stored scene stale, so someone opening the link after everyone left saw old content. Clients now store the encrypted scene one second after changes settle, and on leaving (`save` message, R25). - **Rate limits vs. reconnects:** a per-address limit of 30 session connections per minute was hit by normal reconnect bursts. It is now 120 (R26). - **Second build:** a separate builder rebuilt the app from the spec files alone and passed every requirement. It reported 13 places where the text was loose. Each one is now pinned down: - the Shift+arrow step (R9) - the wheel zoom factor (R1) - the 10 px click/drag threshold and the 8 px line-finish distance - the z-order rule (R12) - real-outline arrow ends (R4) - the line origin (design "Element model") - the dark-mode image filter (R21) - the rounded-rectangle fill rule (R8) - the path cache key (R8) - the 426 body (R26) - the inputs file - stored-bitmap vs element size for images (R7) - rate limits checked last (R26) - **Saved app state:** this keeps only `viewBackgroundColor`, `gridSize` and `gridModeEnabled`. Upstream's `gridStep` and `lockedMultiSelections` are left out. ## Where this differs from the observed app - **Storage:** Excalidraw's hosted app keeps rooms and share blobs in Firebase. Here they live in one Durable Object per room (relay + encrypted snapshot) and in R2, still end-to-end encrypted with the key in the URL fragment. - **Chosen to match the observed app on purpose:** - Share links never expire, and there is no lifecycle rule (R24). - Ending a session only disconnects the person who ends it. There is no "end for everyone" (R25). - Share links are deflated before encryption, like upstream's pako step. Here it uses the browser's `CompressionStream("deflate")`, which writes the same zlib format. The cap stays at 10 MB on the compressed, encrypted bytes. - The constants come from upstream's `constants.ts` and `App.wheel.ts`: arrow-key nudge 1/5 (grid: size/1), `DRAGGING_THRESHOLD` 10, `LINE_CONFIRM_THRESHOLD` 8, and the wheel zoom formula. The 4 MB image cap is upstream's `FILE_UPLOAD_MAX_BYTES`. - Z-order steps past the next element (or its whole group) whether or not it overlaps, as upstream's `zindex.ts` does. - Alt-click on Hachure gives zigzag, as upstream's fill picker does. - **Sessions and accounts:** - Idle rooms are deleted after 24 hours. - The hosted app's paid tier (accounts, cloud storage) is not modelled. - **Left out:** frames, embeds, the laser pointer, elbow arrows (imported ones draw as plain polylines), sticky notes, crop, text-to-diagram, AI features, the command palette, find on canvas, element links, languages other than English, the minimap and the public library site. - **Fonts:** three font families (Hand-drawn = Kalam, Normal, Code) instead of upstream's set. Other upstream font numbers draw with the nearest of the three (spec R6) and are kept in the file. ## v0.1.1: mobile text editing A person using the deployed v0.1.0 build on a phone reported that the UI disappeared, for example while adding text. Reproduced with Playwright's iPhone 13 and Pixel 5 emulation: typing a line past the screen's edge scrolled the fixed app root sideways by ~450 px, and more lines with the keyboard up scrolled it down too, so the toolbar and menu went off-screen (toolbar x ≈ −443, y ≈ −29). The cause was the browser revealing the caret by scrolling the nearest scrollable box, the app root, which carries every floating control. Excalidraw avoids it with a dedicated editor container (`.excalidraw-textEditorContainer`, `overflow: hidden`) whose scroll it resets and turns into a canvas pan plus 5 px (`CARET_FOLLOW_PADDING`, `onEditorBoxScroll` in `textWysiwyg.tsx`). It also sets `maximum-scale=1, user-scalable=no` in its viewport meta, which stops iOS from zooming into a focused field. v0.1.1 requires both (R6, R22, design "Text editor layer") and adds `1-mobile.spec.ts`. The new tests fail on the v0.1.0 code and pass on the fix.