Annotations
The annotations.json file that stores a mockup's comments, how a comment names its block, and the routes and functions that read and write comments.
The DMS stores the comments of a mockup in mockups/<name>/annotations.json. Each comment is an annotation. It names its block by the block's id, not by its position, so it still finds the block after an insert, a move or a page rename.
File format
interface StoredAnnotation {
id: string;
anchor: { block: string; steps: string[]; page?: string } | { page: string };
offset: { x: number; y: number };
text: string;
status: "open" | "resolved";
createdAt: string;
resolvedAt?: string;
version?: number;
resolvedVersion?: number;
state?: string;
}
// annotations.json: { "version": 3, "annotations": StoredAnnotation[] }
| Field | Meaning |
|---|---|
id | A random, URL-safe id. |
anchor | What the comment is about. { page } alone is a comment on that page. Otherwise block names a block by its id, and each entry of steps names a child below it by its id. With page, the block is looked up on that page only. |
offset | Where the pin sits on its block, or its page, as fractions from 0 to 1 from the top left corner. { x: 1, y: 0 } is the top right corner. |
text | 1 to 2,000 characters. |
status | open or resolved. |
createdAt | When the comment was pinned, in ISO 8601. |
resolvedAt | When the comment was resolved. Present only while it is resolved. |
version | The seq of the newest version when the comment was pinned. |
resolvedVersion | The seq of the newest version when the comment was resolved. Reopening the comment clears it. |
state | The named state of the sketch under the pin, such as empty. Absent on any other block. |
A file of version 2, from before pins, is still read. Its comments sit at the top left corner of their blocks, and the next change writes the file as version 3.
Served fields
The routes, the event stream and the MCP tools serve each comment as a MockupAnnotation, which adds two fields resolved against the current spec.json:
| Field | Meaning |
|---|---|
page | The id of the page the comment is on now. |
path | The spec pointer of the block now, such as /pages/0/tree/1/children/0. Absent on a page comment. |
Both are absent when the block or page was removed, or when two blocks match the anchor. The comment stays, and the viewer shows it in the tray of comments without a block. A comment never moves to another block by itself. Put back a block with the same id, or drag the pin onto a block.
The mockup_annotations tool adds two more fields, so the agent can patch a commented block without reading the whole spec:
| Field | Meaning |
|---|---|
pointer | The spec pointer of what the comment is on, ready for mockup_patch_spec. A block pointer, or a page pointer such as /pages/2. |
node | The block as spec.json holds it now. Absent on a page comment. |
How a comment finds its block
A node's id is unique only among its siblings, and a copy keeps it. To give a comment a stable target, the DMS stamps an id on the block:
- A block with no
idgets one,b-and eight random characters, written intospec.json. - A block whose
idthe DMS stamped is unique in the whole spec, so the comment follows it to another page. - A block whose
idan author wrote is found through the ids above it and the id of its page. After that page is renamed or removed, the comment has no location.
Keep a block's id when you move or rewrite it, in the viewer and in a tool call. Give a copy a new id, or none. Two blocks with the same stamped id are an issue, and a write of that spec is refused. The viewer's Duplicate drops the stamped ids of the block it copies.
Comments belong to versions
A comment pinned on version 2 and resolved after the agent wrote version 3 has version: 2 and resolvedVersion: 3. Moving or editing a comment keeps its version.
Consecutive writes by one author can fold into one version. A comment pinned and resolved inside one fold then has the same version and resolvedVersion. Write the spec first and resolve the comment afterwards, so resolvedVersion names the version that holds the fix.
A comment written before versions existed is served as pinned on the newest version.
Routes
Every route is under /api/mockup/:name/annotations, in development and for the platform owner only.
| Route | Body | Answer |
|---|---|---|
GET /annotations | { annotations } | |
POST /annotations | { page, path?, offset, state?, text } | The new comment. Without path, a comment on the page page. |
PATCH /annotations/:id | { status?, text?, place? } | The comment. place is { page, path?, offset, state? } and moves the pin. |
DELETE /annotations/:id | { id }. The comment is gone for good. |
| Status | When |
|---|---|
400 | The body has another key, an offset outside 0 to 1, a state that is not a state name, or a text over 2,000 characters. |
404 | The spec has no such page or block, or no comment has that id. |
409 | Two blocks share the target's ids, or spec.json does not parse. Nothing changes. |
GET /api/mockup/:name/history counts the comments of each version, and GET /api/mockup/:name/history/:seq lists the comments pinned on that version.
Functions for backend code
packages/dms/src/mockup/annotations.ts exports the same store as plain functions, for a tool that runs in the backend: listAnnotations(name), createAnnotation(name, draft), updateAnnotation(name, id, patch) and deleteAnnotation(name, id). createAnnotation answers { kind: "created", annotation } and updateAnnotation answers { kind: "updated", annotation }, or the reason nothing changed.