Mockups
A JSON spec of one or more DMS pages, drawn by the real block renderer and redrawn on every save, with fixture data and annotations.
A mockup is a JSON file that describes one or more DMS pages. The backend compiles it against the block types registered now, and /mockup draws each page with DmsBlockPreview, the renderer of the block preview page. A save shows in the open viewer in under a second, with no typecheck and no page reload. Because the mockup draws real blocks, it shows only what the DMS can draw.
Availability
The DMS serves mockups only when the AntelopeJS runtime runs in development mode (GetRuntimeInfo().dev). ajs project dev and ajs project run start it in that mode. Neither docsPreview: true nor DMS_DOCS_PREVIEW=1 turns mockups on.
The routes and the viewer serve the platform owner only. Every route answers 401 to a request with no session and 403 to any other signed-in user, the same answer as the Branding editor's routes. The viewer is owner-only. The Roles editor does not list it, and a role that holds its permission still cannot open it. The routes read and write the files of the project the backend runs in. The MCP mockup tools read those files directly, not through these routes.
File layout
<project root>/
mockups/
<name>/
spec.json the spec you write
annotations.json written by the DMS when a reviewer annotates a node
The project root is the working directory of the backend process. <name> matches ^[a-z0-9][a-z0-9-]{0,63}$. The DMS ignores a directory whose name does not match, and a directory without spec.json.
@antelopejs/dms ships two files under node_modules/@antelopejs/dms/data/:
mockup-spec.schema.json, the JSON Schema ofspec.jsonover the built-in block types.mockup-example/spec.json, a two-page example that compiles with no issue.
Spec
{
"$schema": "../../node_modules/@antelopejs/dms/data/mockup-spec.schema.json",
"version": 1,
"title": "Order desk",
"pages": [
{
"id": "orders",
"title": "Orders",
"options": { "theme": "light", "locale": "en", "padding": true },
"fixtures": { "orders": [{ "_id": "o1", "customer": "Acme", "total": 120 }] },
"tree": [{ "type": "KpiCard", "options": { "title": "Revenue", "staticValue": 48210 } }]
}
]
}
| Field | Meaning |
|---|---|
$schema | Optional. Points an editor at the JSON Schema. |
version | Always 1. |
title | Optional. The title of the mockup. |
source | Optional. Who wrote the mockup: chat, claude-code or codex. |
built | Optional. Written by the build: { at, pages }. Without it, the mockup is a draft. |
built.at | When the build finished, an ISO 8601 date and time. |
built.pages | 1 to 50 { path, title? }. path starts with one /, not // or /\, and holds no whitespace or control character, 2048 characters at most. The path stands in for a missing title. |
pages | 1 to 50 pages. The whole file nests at most 100 levels of objects and arrays. |
pages[].id | Matches ^[a-z0-9][a-z0-9-]{0,63}$. Unique in the spec. |
pages[].title | The title of the page. |
pages[].options.theme | light or dark. |
pages[].options.locale | A locale the dashboard knows, such as fr-FR. |
pages[].options.padding | Pads the blocks off the edges of the frame. Defaults to true. |
pages[].fixtures | Data the blocks of the page read. Each key matches ^[A-Za-z0-9_-]{1,64}$ and holds any JSON value. |
pages[].livePage | Set on a page converted from a live page, or by the build on each page it built: { ref, version }, the page's builder ref and the version of its source file at the conversion or build. See Edit a live page as a mockup. |
pages[].liveRoutes | The live route of each fixture key, such as {"sales":"/api/sales"}: a built.pages path, where spaces may pad a token. See Live routes. |
pages[].tree | The blocks of the page, top to bottom. |
The envelope is strict: a key it does not list is an issue.
Nodes
A node is the tree format of DmsBlockPreview:
| Field | Meaning |
|---|---|
type | A registered block type, such as KpiCard, or sketch. It wins over componentName. |
componentName | The component a registered block type emits, such as dms-kpi-card. |
options | The options the block's component receives. |
children | The nested nodes. A container lists the block types it takes in allowedChildren (a Grid takes only GridRow); a block that is no container takes only the children its block options name, such as a ChartCard's chart. |
id | The id of a child under its parent, unique among its siblings. |
slot | The slot of the parent the child renders in. |
colSpan | The columns a child spans in a grid. |
For every block that takes no controller class, the options a component receives are its factory's options, with two exceptions:
- An option that holds a block, such as the
chartof aChartCard, is a child whoseidis the option's name. - A
Formsection either holds its ownfields, as theFormfactory takes them, or lists fields offieldsby id infieldIds, as the component receives them. The compiler hands the component the second shape: each section's own fields move after the form'sfields, in order.
The compiler validates a block's options with ValidateBlockOptions against the block types registered when the spec is read. A block that an installed module registers is accepted like a built-in one. GET /api/mockup/schema describes the same set.
Fixtures
A string option of the form fixture:<key>, at any depth, names a key of the page's fixtures. The compiler replaces it with /api/mockup/<name>/pages/<page>/fixtures/<key>, the route that answers that value.
{
"type": "ChartCard",
"options": { "title": "Revenue", "fetchUrl": "fixture:revenue", "valueFormat": "currency", "currencyCode": "EUR" },
"children": [{ "id": "chart", "type": "ChartArea", "options": { "xaxisType": "datetime" } }]
}
A key that the page does not hold is an issue at the option's pointer. The compiler still replaces the reference, and the block shows the error that a missing route gives it.
Live routes
liveRoutes maps a fixture key to the route of the live app that answers the same data. A page that has it is compiled twice: once on its fixtures, as tree, and once with each key it maps read from its route instead, as realTree. A table's fixture:<key> then reads the route as is, without the /rows suffix, so the route must answer { results, total } as a list route does. The viewer's Real data switch picks one of the two trees. The issues come from the fixture side only.
{
"id": "sales",
"title": "Sales",
"liveRoutes": { "api-sales": "/api/sales" },
"fixtures": { "api-sales": null },
"tree": [{ "id": "sales", "type": "ChartCard", "options": { "title": "Sales", "fetchUrl": "fixture:api-sales" } }]
}
With Real data off, the preview calls no live route. A fixture:<key> reads its fixture. Any other string in an option the preview requests or loads (a *Url, url or location option, an image src, an *Endpoint), at any depth and in any block, is replaced with a fixture route that answers an error, so the block shows its error state. The same option keeps its route in realTree.
The viewer and the mockup thumbnails also load the preview as /dms-preview?fixtures=only, which puts a Content Security Policy on its document: images, media and requests reach the mockup's routes, the dashboard's own (its realtime session, icons and system state) and its assets only. A fixture value that a cell turns into a request, such as an image cell holding a URL or a file cell holding a file key, is refused by the browser and never reaches the server. Switching Real data on loads the preview again without the policy.
Controller blocks
TableView and ResourceForm take a controller class in code. A mockup builds them from fixtures:
TableViewtakes the options ofTableView.fromSource.fetchUrlisfixture:<key>and names an array of row objects. Each column'stypeis a data type id, such asstring,number,date,booleanorselect. The compiler builds the table with the realTableView.fromSource, reading its rows from/api/mockup/<name>/pages/<page>/fixtures/<key>/rows.ResourceFormtakes a serialized form: itsfields, and afetchUrlof the formfixture:<key>that names the record object. It has nosubmitUrl. The compiler validates it as aForm.
A table's capabilities default to search, sort and paginate. The rows route does not filter, so a tab filter, a quick filter or queryParamFilters draws but does not narrow the rows. A column has no display. Another block type that takes a controller class is an issue, and the preview draws it as a block that needs a backend.
Sketches
A sketch draws static HTML and CSS of a part that no DMS block draws. The viewer renders it in an <iframe sandbox=""> with the CSP default-src 'none'; style-src 'unsafe-inline'; img-src data:; font-src data: and a <base href="about:srcdoc">, so an #anchor scrolls inside the frame, and labels it Custom.
{
"type": "sketch",
"options": {
"html": "<ol class=\"steps\"><li>Ordered</li><li>Packed</li></ol>",
"css": ".steps{display:flex;gap:12px}",
"height": 160,
"caption": "Delivery journey"
}
}
| Option | Meaning |
|---|---|
html | The markup, up to 524,288 characters. Required. |
css | The style sheet, up to 524,288 characters. |
height | The frame height in pixels, from 80 to 1,200. Defaults to 320. |
caption | Up to 200 characters. |
A sketch has no children. The compiler checks it as the frame will read it, and emits only the markup it checked; Sketch check lists what it refuses. A refused sketch is emitted with an empty html and no css, and each refusal is an issue.
Compiled state
GET /api/mockup/<name> and the state event answer a MockupState:
interface PreviewNode {
type?: string;
componentName?: string;
options?: Record<string, unknown>;
children?: PreviewNode[];
id?: string;
slot?: string;
colSpan?: number;
}
interface MockupState {
name: string;
title?: string;
revision: number;
pages: Array<{
id: string;
title: string;
options: { theme?: "light" | "dark"; locale?: string; padding?: boolean };
tree: PreviewNode[];
realTree?: PreviewNode[];
livePage?: { ref: string };
paths: Record<string, string>;
}>;
issues: Array<{ path: string; message: string }>;
}
| Field | Meaning |
|---|---|
revision | Increases by one each time the backend reads spec.json. |
tree | The page's nodes with fixture references replaced, controller blocks built and sketches checked. |
realTree | tree with each key of liveRoutes read from its live route. Present only when the page has liveRoutes. Its layout paths are tree's. |
livePage | The ref of the live page the spec page was converted from. |
paths | The spec pointer of each node, keyed by the layout path DmsBlockPreview gives it: block-<i> for root i, then <parent path>.<child id or index>. |
issues | Empty when the spec is valid. Each path is a JSON pointer into spec.json, such as /pages/0/tree/1/children/0/options/title. "" names the whole file. |
Compilation is lenient. A node with invalid options, or with an unknown type, is still in tree, and its issues are listed. When spec.json is not valid JSON, or its envelope breaks the rules above, issues says why and pages keeps the last pages that compiled.
HTTP API
Every route is under /api/mockup.
| Route | Answer |
|---|---|
GET /api/mockup | { results, total }, one row per mockup, newest spec.json first. See Listing. |
GET /api/mockup/schema | The JSON Schema of the spec, built from the block types registered now. |
GET /api/mockup/schema/blocks | { blocks }: every registered block type, as ListBlockTypes describes it. |
GET /api/mockup/:name | The MockupState. 404 when spec.json is missing. |
GET /api/mockup/:name/events | Server-sent events. See Events. 404 when spec.json is missing. |
GET /api/mockup/:name/spec | { spec, digest }: spec.json as written, fixture: references included, and a digest of its text. |
PUT /api/mockup/:name/spec | Body { spec, digest? }. Checks the spec as mockup_write_spec does and answers { ok: true, digest } or { ok: false, errors }. 409 with the current digest when digest no longer matches the file. |
GET /api/mockup/:name/pages/:page/fixtures/:key | The fixture value. |
GET /api/mockup/:name/pages/:page/fixtures/:key/rows | { results, total } over an array of row objects. 404 when the fixture is not one. |
GET /api/mockup/:name/annotations | { annotations }, each where its block is now. |
POST /api/mockup/:name/annotations | Body { page, path, text }. Anchors the note to that block and answers it. 404 unless path names a node of page page. 409 when spec.json does not parse or the block cannot be told apart. |
PATCH /api/mockup/:name/annotations/:id | Body { status?, text? }. Answers the annotation. |
POST /api/mockup/from-page | Body { path } or { pageRef }, with replace? and digest?. Converts the page into a mockup, or opens the one it has. See Edit a live page as a mockup. 400 for a replace without digest, 404 for a page the builder does not know, 409 when digest no longer matches the file. |
The rows route reads these query parameters:
| Parameter | Meaning |
|---|---|
offset | The first row to answer. Defaults to 0. |
limit | How many rows to answer. Every row from offset when absent. |
search | Keeps the rows where a string, number or boolean value contains it, ignoring case. |
sortKey | The row field to sort on. Numbers, and text that reads as a number such as "1.25", sort by value first; then other text in reading order, ignoring case and accents; then any other value by its JSON text. Rows without the field come last in either direction. |
sortDirection | asc or desc. Defaults to asc. |
A name, page id, fixture key or annotation id that does not match its pattern answers 404, before the DMS builds any path from it.
Events
GET /api/mockup/:name/events opens a text/event-stream. While a stream is open, the DMS watches mockups/<name>/ and reads a changed file once 40 ms pass without another change.
| Event | When | data |
|---|---|---|
state | On connect, then after each change of spec.json. | The MockupState as JSON. |
annotations | After each change of annotations.json or of spec.json, because a spec change moves where the notes' blocks are. | { annotations } |
When spec.json is deleted, the next state keeps the last pages and has one issue that says the file is missing. When the module stops, the DMS ends every stream. The browser's EventSource reconnects once the backend is back.
Annotations
A reviewer annotates a block from the viewer. Mockup annotations describes annotations.json and how a note follows its block.
Listing
/mockups shows each mockup as a card that opens /mockup?name=<name>. It exists only in development, has no menu entry, and only the platform owner reaches it, from a header icon. It is a table view over GET /api/mockup, whose row is { name, title?, pages, openComments, source?, updatedAt, status }, plus builtAt and builtPages when status is built.
Each entry of builtPages is { path, title, pageId?, changed }. pageId is the spec page whose livePage is the page at path. changed is true when the builder's version of that page is no longer the one livePage records, so editing the page's source changes it and touching the file does not. A card with a changed page reads Out of sync, and each changed page offers Update from page: it converts that page again over its own spec page (POST /api/mockup/from-page with mockup), which clears that page alone. A built page with no linked spec page never reads as changed and offers no update.
A row reads spec.json as far as it reads cleanly: a file that is not JSON lists as a draft of no pages, and an invalid source or built reads as absent. openComments counts the open annotations, 0 when annotations.json is missing or unreadable.
Viewer
/mockup is a hidden, owner-only page that renders the DmsMockupViewer component with the bare preview layout.
| Query parameter | Meaning |
|---|---|
name | The mockup to show. Without it, the page lists the mockups. |
page | The id of the page to show. |
width | desktop or mobile. |
mode | edit (the default) or comment. |
data | real or sample. Overrides the default of the Real data switch. |
The viewer opens the event stream, embeds /dms-preview in an iframe, and sends the current page's tree (or realTree with Real data on), theme, locale and padding in a render message on every state event. The render also carries the mockup's pages as navigation, which the preview draws as the dashboard's sidebar: picking a page there opens it, and below the dashboard's desktop width the sidebar folds behind a menu button.
In Comment mode, a click on a block opens a note box on its spec node. A note box closes when an edit removes that block or puts another node in its place, since pointers follow positions.
In Edit mode, a developer changes the spec in place: select a block, add one from the catalog by dragging it onto the page or with Enter, move, duplicate, delete and restyle blocks, edit a text by double-clicking it, and add, rename, reorder and remove pages. The inspector offers only an option's visual settings, from the groups content, appearance, layout and features. Each edit is written with PUT /api/mockup/:name/spec about 150 ms after the last one, with the digest the viewer last read or wrote. When another writer, such as mockup_patch_spec, changed the file in between, the write answers 409: the viewer takes the file as it is now, starts its undo history over and says so. A note's stamp on the file keeps the editor's undo history: see Mockup annotations. Ctrl or Cmd+Z undoes, and Shift+Ctrl or Shift+Cmd+Z redoes.
The Real data switch shows when the page has liveRoutes. It is on by default for a page converted from a live page and off for any other; ?data= and the developer's choice override that default. A mockup without live routes has no switch.
Data wiring is never edited in the viewer. "Connect data with the AI", "Ask the AI to change it" on a sketch, and "Build it" dispatch a cancelable dms:assistant-prompt event on window (MOCKUP_ASSISTANT_PROMPT_EVENT, detail MockupAssistantPrompt). The DMS assistant claims it with preventDefault(); when nobody does, the viewer shows the request to copy into another AI tool. On a page converted from a live page, "Build it" adds target: { pageRef } to the event, and the copy says to build into that page instead of creating a new one.
Deleting the whole mockups/ directory while a viewer is open stops its updates; reload the viewer once the directory is back.
Regenerate the schema
The shipped schema covers the built-in block types. Regenerate it after a change to a block's options:
pnpm --dir packages/dms mockup:schema
pnpm --dir packages/dms mockup:schema:check fails when the committed file is stale. CI runs it.