# Whiteboard ## What this builds A virtual whiteboard for sketching diagrams that look hand-drawn. People draw on an infinite canvas with these tools: - rectangles, diamonds, ellipses - arrows that stick to shapes, lines - freehand strokes, text, images They style shapes from a side panel and arrange them with selection, groups, alignment and layers. They can: - undo anything - export PNG or SVG images - save and open `.excalidraw` JSON files (the format of the widely used open-source whiteboard, so files move both ways) - keep a personal library of reusable shapes - switch to dark mode and use it on a phone There are no accounts. **Drawings live in the browser**: the canvas at `/` is kept in that browser's storage (R23), and files carry drawings anywhere else (R19). The server only handles what people share, and it can't read any of it: - **Shareable links:** an end-to-end encrypted snapshot whose key stays in the link (R24). - **Live collaboration:** everyone in a session sees each other's edits and cursors in real time. Sessions are also end-to-end encrypted (R25). Anyone who can reach the site can use both, so they have size and rate limits (R26). It is one Cloudflare Worker: - The React single-page app is the Worker's static assets. - A small API runs in the Worker. It stores encrypted share links and encrypted session images in one R2 bucket. - Each live session is one Durable Object. It relays encrypted WebSocket messages and keeps the latest encrypted scene for people who join later. - There is no database. It runs on a laptop with `npm install` and `npm run dev` (`wrangler dev` with local R2 and Durable Objects, and no Cloudflare account). It deploys with `npm run deploy` and needs no other service. Read `spekkr.inputs.json` first. It sits at the repository root. If it is missing, create it from the `customize.settings` defaults in `spekkr.json`; with the defaults its full contents are: ```json { "app_name": "Whiteboard", "accent_color": "#4c6ef5" } ``` It has exactly these two keys: - **`app_name`:** the product name (default "Whiteboard"). It is the page title and the welcome text on the canvas. - **`accent_color`:** the accent colour (default `#4c6ef5`). It is used for primary buttons, selection outlines and handles, active tools and focus rings. `design.md` has: - the stack, Cloudflare config and storage layout - the element model and file formats - the rendering rules, sync and collaboration protocols, and API - every screen and the look `tasks.md` is the build order. `research.md` records where the design came from; the builder does not need it, and nothing in it is a requirement. ## Names and words - The product is called `app_name` everywhere. The built app never shows the name, logo or wordmark of any other whiteboard product. The brand mark is a plain rounded square in the accent colour. - "Excalidraw" may appear only where the file format needs it: the `.excalidraw` / `.excalidrawlib` extensions and the `"type": "excalidraw"` / `"excalidrawlib"` values inside files. - Interface text the spec quotes is the text to use. Other text is the builder's own, short and plain. - No image, font or icon file is copied from another product. Icons are inline SVG drawn in the app's own code. - The hand-drawn font is Kalam (SIL Open Font License) from `@fontsource/kalam`. - The other two font choices use system font stacks. ## Words used here - **Scene coordinates:** positions on the infinite canvas. **Screen coordinates:** CSS pixels in the window. `screen = (scene + scroll) × zoom`. - **Click vs drag:** a press counts as a drag once the pointer has moved 10 screen pixels or more from where it went down; less than that, it is a click (Excalidraw's dragging threshold). - **Element:** one thing on the canvas: rectangle, diamond, ellipse, arrow, line, freedraw, text or image. Its fields are in `design.md` ("Element model"). - **Live elements:** elements with `isDeleted` false. Deleted elements are kept as tombstones only where sync needs them. - **Linear element:** an arrow or a line. Its first point is always `[0, 0]`, and `x`, `y` is that first point's scene position. The other points are offsets from it and may be negative. `width`/`height` are the size of the points' bounding box. - **Binding:** an arrow end attached to a shape, so the arrow follows the shape when it moves. - **Group:** elements that share a group id in `groupIds` and are selected together. Groups nest; the last id is the outermost group. - **Browser canvas:** the scene kept in this browser's storage. - **Session:** a live collaboration room. **Session link:** `/#room=<20 hex>,<22-char key>`. - **Shareable link:** `/#json=<22-char id>,<22-char key>`. - **Host:** the person who started a session. **Guest:** anyone who joined it by link. - **MB:** 1,048,576 bytes. ## Out of scope These are not built: - frames, embeds and iframes - the laser pointer, sticky notes - elbow arrows (imported elbowed arrows draw as plain polylines) - image cropping, element hyperlinks - the command palette, find on canvas - text-to-diagram and AI features - languages other than English - a public library catalogue - PNG files that carry the scene inside them - presenting or slides - comments, version history beyond undo - accounts, sign-in, drawings stored on the server, read-only links that follow later edits, teams or shared folders (sharing is by encrypted link and live session only) Import counts elements of unknown kinds, leaves them out, and says so (R19). ## Requirements Each requirement ends with an "Accept when" line naming the tests that prove it. Test names are in "Tests" at the end. ### R1. Infinite canvas, zoom and pan - The editor fills the window with one ``. It is drawn at the device pixel ratio and redrawn on resize. The scene has no edges. - **View state:** `{ scrollX, scrollY, zoom }`, with `screen = (scene + scroll) × zoom`. - Zoom is clamped to 10 %–3000 % and rounded to 0.001. - The bottom-left zoom control has "Zoom out" (−10 points), "Reset zoom" (shows the percentage and sets 100 % around the window centre) and "Zoom in" (+10 points). - **Keys:** Ctrl/⌘ `+`/`=` zoom in, Ctrl/⌘ `-` zoom out, Ctrl/⌘ `0` resets to 100 %. Shift+1 zooms to fit all elements (padding 40 px, never above 100 %). Shift+2 fits the selection. - **Wheel:** - With Ctrl/⌘ held (and trackpad pinch, which browsers send as Ctrl+wheel), the wheel zooms around the pointer: the scene point under the pointer stays under it. - Zoom step per wheel event, as in Excalidraw: `d = clamp(deltaY, −10, 10)`, `zoom' = zoom − d / 100 + log10(max(1, zoom)) × −sign(deltaY) × min(1, |deltaY| / 20)`, then clamped and rounded as above. So one notch zooms by 10 points at 100 % and by more above it. - Otherwise the wheel pans by its deltas, and Shift+wheel pans horizontally. - **Panning:** drag with the Hand tool (H), drag with the middle mouse button, or hold Space and drag. On touch screens, a two-finger drag pans and a pinch zooms around the fingers' midpoint. - **First view:** opening a scene that has elements fits it to the window (never above 100 %). An empty scene opens at 100 % with the origin at the top left. - The view is not stored with a drawing or the browser canvas; each opening fits the scene again. Accept when: "R1 R16 zoom, pan, fit, the eraser, and the shortcuts help" passes. ### R2. Shapes - **Toolbar:** a toolbar (`role="toolbar"`, name "Tools") at the top centre. Each tool is a button with the tool's name as its accessible name, an icon, and its key shown small. The tools, with their keys: - Hand (panning tool) H; Selection V or 1 - Rectangle R or 2; Diamond D or 3; Ellipse O or 4 - Arrow A or 5; Line L or 6; Draw P, X or 7 - Text T or 8; Insert image 9; Eraser E or 0 - A lock button before them, "Keep selected tool active after drawing" (Q), with `aria-pressed`. - The active tool has `aria-pressed="true"`. - **Drawing a shape:** - Dragging with Rectangle, Diamond or Ellipse draws from the press point to the pointer. Shift keeps the shape square or circular. - A click (under the 10-pixel drag threshold) makes a 100×100 shape centred on the click. - Dragging back past the start point flips the box, and the stored x/y/width/height stay positive. - **After drawing:** the new element is selected and the tool returns to Selection, unless the lock is on. - **New elements:** - They take the current style (R13). - They get a random `seed`, `version` 1, a random `versionNonce`, and a fractional `index` above every other element. - Rectangles default to round corners (`roundness: {type: 3}`); diamonds to `{type: 2}`; ellipses have none. - With the grid on, corners snap to the grid (R17). Accept when: "R2 shapes: drag to draw, Shift for squares, a click makes a default shape, Q keeps the tool" passes. ### R3. Arrows and lines - **Drawing:** - Dragging with Arrow or Line makes a two-point element. - A click (under the 10-pixel drag threshold) starts a multi-point element: each click adds a point and the last segment follows the pointer. - Enter, Escape, a double-click, or a click within 8 screen pixels of the last fixed point finishes it. - Shift locks each segment to 15° steps. - **Arrowheads:** arrows default to no start arrowhead and an "arrow" end arrowhead. Lines have none. - The style panel lists None, Arrow, Triangle, Triangle outline, Bar, Circle, Circle outline and Diamond for each end. - An imported `dot` is read as `circle`. An imported `diamond_outline` is kept and drawn as an outlined diamond. - **Edges:** "Round" draws a smooth curve through the points; "Sharp" draws straight segments. - **Closed lines:** a line whose `polygon` flag is true is closed and can have a background fill. - **Editing points:** a selected two-or-more-point linear element shows a handle on every point. Dragging a point moves just that point; the element's x/y/width/height are recomputed from the points. Accept when: "R3 R4 arrows and lines: two-point drags, multi-point clicks, binding that follows shapes" passes. ### R4. Arrow binding - **Binding targets:** rectangles, diamonds, ellipses, text and images can be bound to. Locked elements can't. - **Binding on draw:** when an arrow's start or end is placed within 10 screen pixels of the topmost bindable element's outline, or inside it, that end binds: - The arrow stores `startBinding`/`endBinding` as `{ elementId, fixedPoint: [fx, fy], mode: "orbit" }`, where `fixedPoint` is where the end sits as a fraction (0–1) of the target's unrotated box. - The target's `boundElements` gets `{ id, type: "arrow" }`. - While drawing, the target under the pointer is outlined in the accent colour. - **End placement:** a bound end does not sit inside the shape. Take the ray from the target's centre toward the neighbouring point, in the target's unrotated frame. Find where it leaves the target's real outline: the box for rectangles, text and images, the ellipse for ellipses, and the rhombus through the box's edge midpoints for diamonds. Move 4 units further out along the same ray, then rotate with the target. For a two-point arrow bound at both ends, the line goes toward the other target's centre. - **Keeping bindings up to date:** - Moving, resizing or rotating a target re-places the bound ends of every arrow bound to it, in the same undo step. - Deleting a target removes the bindings that point at it. - Deleting an arrow removes it from its targets' `boundElements`. - Duplicating a target together with its arrow re-points the copies at each other. Duplicating the target alone leaves the copy unbound. - Moving the arrow itself by its body unbinds both ends. Accept when: "R3 R4 arrows and lines: two-point drags, multi-point clicks, binding that follows shapes" and the unit tests "arrow binding" pass. ### R5. Freehand drawing - The Draw tool records every pointer position while the button is down, as points relative to the first one, along with pen pressure when the device reports it (`pressures`; otherwise `simulatePressure: true`). - The stroke is drawn as a filled outline from `perfect-freehand` with these settings: - size `strokeWidth × 4.25`, thinning 0.6, smoothing 0.5, streamline 0.5 - easing `sin(t·π/2)`, last true - With a background colour, the area enclosed by the points is filled as a rough polygon under the stroke. - After a stroke the tool stays on Draw and nothing is selected. Accept when: "R5 R6 freehand drawing and text" passes. ### R6. Text - **Starting text:** a click with the Text tool, or a double-click on empty canvas with Selection, starts a text element there. - A `