Mockup annotations
How a reviewer's note on a mockup names its block by id, so it follows the block through inserts, moves, removals and page renames.
A reviewer annotates a block from the viewer. A note names its block by the block's id, not by where the block is, so it still names that block after an insert, a move, a removal or a page rename, whether the editor, mockup_patch_spec or a whole-spec write made the change. The DMS stores annotations in mockups/<name>/annotations.json:
interface StoredAnnotation {
id: string;
anchor: { block: string; steps: string[]; page?: string };
text: string;
status: "open" | "resolved";
createdAt: string;
resolvedAt?: string;
}
// annotations.json: { "version": 2, "annotations": StoredAnnotation[] }
interface MockupAnnotation extends StoredAnnotation {
page?: string;
path?: string;
}
| Field | Meaning |
|---|---|
id | A random, URL-safe id. |
anchor | The block the note is about: the one node whose id is block, then down through the one child whose id is each of steps. Without page, block is a stamped id, looked up in the whole spec. With page, block is an id an author wrote, looked up on the page page only. |
page | The id of the page the block is on now. Served, never stored. |
path | The spec pointer of the block now, such as /pages/0/tree/1/children/0. Served, never stored. |
text | 1 to 2,000 characters. |
createdAt | ISO 8601. |
resolvedAt | ISO 8601. Set while the annotation is resolved. |
The API, the event stream and the MCP tools serve each note as MockupAnnotation: page and path are resolved against the current spec.json on every read, so they follow the block. Both are absent when the block was removed, or when it cannot be told apart because two blocks match its anchor. The note stays, and the viewer says its block was removed. A note never moves to another block. Put a block back with the same id and the note finds it again.
A node's id is unique only among its siblings, and copies keep it, so an id an author wrote does not name one block. Some ids also carry meaning: a block option child such as a ChartCard's chart has the option's key. The DMS never renames an id. To anchor a note it walks up from the node to the nearest node that has no id or a stamped one:
- A node with no
idgets a fresh one,b-and eight random characters, written tospec.json, and the note anchors there. - A node with a stamped
idanchors there. A stampedidnames one block in the whole spec, so the note follows the block to another page and through a page rename. - The
idof each node the walk passes on the way is a step. Achartchild anchors as theidof its card, then the stepchart. - When the node and every node above it have an
idan author wrote, there is nothing to stamp. The note anchors on those ids and on the id of its page, and names the block whose root has thatidon that page only. After that page is renamed or removed, or when two blocks of the page match, the note has no location.
The stamp sets the id and keeps the file's layout: a file on one line stays on one line, the indentation of the first indented line stays, and so do CRLF line endings and a final line ending. The rest is written as JSON.stringify writes it: keys keep their order, except that keys which are whole numbers move first in their object.
Keep a block's id when you move or rewrite it, in the editor and in a tool call: the id is what the notes on it hold on to. Give a copy a new id, or none: a spec in which two blocks have the same stamped id has an issue at the id of the second in document order, which names the first, so a write of it is refused. The editor's duplicate leaves out the stamped ids of the block it copies and of its children.
The DMS writes the file one change at a time and replaces it whole, through a temporary file and a rename, so concurrent annotations are all kept. A change that stamps an id takes the spec's write lock first, then the annotations file's, so it cannot interleave with another write of the spec. The module src/mockup/annotations.ts exports the same store as plain functions, listAnnotations(name), createAnnotation(name, draft) and updateAnnotation(name, id, patch), for a tool that runs in the backend. createAnnotation answers { kind: "created", annotation }, or why it made none.
In the editor
A file that only gained the id a new note stamped on a block is no other writer's change, also when it is the viewer's own write whose answer was lost: the viewer keeps its undo history and the edit it has not written yet, adds the id to them, and writes that edit over the file. It follows the block from step to step of the history, so an undo or a redo keeps the id on that block, and a step where the block does not exist, such as before it was inserted or after it was removed, gets no id.