[data-reveal]{opacity:1!important;transform:none!important}
AntelopeJS DMS
DocumentationAnnotations

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

ts
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[] }
FieldMeaning
idA random, URL-safe id.
anchorWhat 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.
offsetWhere 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.
text1 to 2,000 characters.
statusopen or resolved.
createdAtWhen the comment was pinned, in ISO 8601.
resolvedAtWhen the comment was resolved. Present only while it is resolved.
versionThe seq of the newest version when the comment was pinned.
resolvedVersionThe seq of the newest version when the comment was resolved. Reopening the comment clears it.
stateThe 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:

FieldMeaning
pageThe id of the page the comment is on now.
pathThe 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:

FieldMeaning
pointerThe spec pointer of what the comment is on, ready for mockup_patch_spec. A block pointer, or a page pointer such as /pages/2.
nodeThe 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 id gets one, b- and eight random characters, written into spec.json.
  • A block whose id the DMS stamped is unique in the whole spec, so the comment follows it to another page.
  • A block whose id an 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.

RouteBodyAnswer
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.
StatusWhen
400The 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.
404The spec has no such page or block, or no comment has that id.
409Two 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.