Live page mockups
How mockup_from_page turns an existing page into a mockup, and how mockup_apply_to_page writes the mockup back into that page.
An existing page can become a mockup, so you review a change before it reaches the page. The dashboard has no button for it. Ask the agent to turn the page into a mockup. Two MCP tools do the work:
mockup_from_pageconverts the page into a spec page.mockup_apply_to_pagewrites the reviewed spec page back into the page.
Both run only when the backend runs in development.
Convert a page
mockup_from_page takes the page's builder ref as pageRef. It reads the page through the builder and writes mockups/<name>/spec.json. The name comes from the page's route: /charts/sales gives charts-sales, and / gives home. The answer holds the url to open, /mockup?name=<name>&page=<page>.
Each block of the page becomes one node at its place, with its name as id, its slot and its colSpan:
| Block on the page | Node in the mockup |
|---|---|
| A block the mockup can draw | The same block, with the options the builder reads. Options the page's source locks are left out, and the page keeps them. |
An option that holds a block, such as a ChartCard's chart | A child whose id is the option's name. |
An option whose name ends in Url, such as fetchUrl | fixture:<key>, with the route recorded in liveRoutes. The fixture holds a sample shaped as the block reads it, so the page shows data on its first draw. |
A TableView bound to a resource | A table over the resource's listed fields, with made-up rows. Its live route is the resource's list route. |
| Anything the mockup cannot draw | A Custom sketch that names the block and says why. This covers custom components, values set in code, routes built from the page's parameters, and blocks the mockup refuses. |
No block is dropped. The answer lists each sketch with the block's builder path and the reason, and the fixture keys that Real data reads.
The spec page also takes the page's title, icon and description. The page's headerActions are not converted, because the builder does not read a page's layout. A page under a sidebar section of its own gets that section as a spec category.
The spec page records the page in livePage, as { ref, version }. Building the mockup later updates that page and never creates another.
Convert again
Asking again for the same page opens the same mockup, writes nothing and answers the outcome reopened. When the page's source changed since, the answer also says stale: true. To convert it again, the agent passes replace: true. The page is converted over its mockup page, and the other pages of the spec stay.
A mockup of that name that was made by hand, or from another page, is never reused. The new mockup takes the name <name>-2, then <name>-3.
Convert into an existing mockup
To mock up a change across several pages, start with an empty mockup and pass its name as into:
{ "pageRef": "/invoices", "into": "redesign" }
The page is converted as above and added at its real place in the mockup:
- Its sidebar section becomes the mockup category with the same id, else the same title, else a new category. A page of the default Pages section takes no category.
- Within its section, it goes before the first converted page that comes after it in the app's menu. Otherwise it goes last in its section.
- Its id is its route's slug, with a suffix when the mockup already has that id, such as
orders-2.
| Outcome | When |
|---|---|
added | The page was added. The answer holds { ok: true, outcome, mockup, page, url, sketches, liveRoutes }. |
replaced | The mockup already held the page and the call passed replace: true. The page keeps its id and its place. |
conflict | The mockup already holds the page, by livePage.ref. Nothing is written. |
not_found | The mockup does not exist. |
invalid | The mockup's spec.json breaks the schema. |
New pages of the mockup are written with the spec tools. Build it then names every page to build: the converted pages update their live pages, and the new ones become new pages.
Write the mockup back
mockup_apply_to_page takes { mockup, page } and writes that spec page back into the page its livePage names. It converts the live page again, pairs each node with the block it stands for, and writes the whole block tree in one write. The write happens only if the page is still at livePage.version.
| Node | Effect on the page |
|---|---|
| Unchanged | The block is kept as it is, at the node's place. |
| A Custom sketch that stands for a block | The block is kept. An edited sketch is listed in wiring. |
| Options edited | The options are written. A fixture:<key> option gets its live route back. A locked option is never written. |
A TableView bound to a resource | The options a mockup draws are written. The rest stay. |
| Moved to another parent | The block moves, when the builder can write all of it. Otherwise it stays where it was. |
| Gone from the mockup | The block is removed. |
| New | The block is added, named after its id. An id the page cannot use becomes a valid name, such as revenue-2 becoming revenue_2. |
The page's title, icon and description are written in the same write. A field the mockup dropped is cleared.
What stays for code
The answer's wiring list names what only code or data wiring can do, and the tool never writes it. Examples are a fixture with no live route, a new or edited sketch, a change to a table's columns, and the page's headerActions, which go in the page's DefaultLayout({ headerActions }) by hand. Each entry gives the node's pointer in spec.json. The answer also lists the builder paths it kept, wrote, added and removed.
When it refuses
Nothing is written in any of these cases.
| Answer | When |
|---|---|
stale | The page changed since the conversion. The answer gives the currentVersion. |
not_found | The mockup, its spec page, or the live page does not exist. The tool never creates a page. |
not_linked | The spec page has no livePage, because it was not converted from a live page. |
invalid | The spec breaks its schema, or the builder refuses the draft. A draft is refused when it does not typecheck, or when a block would send a request outside the page's data API. See Requests a built block sends. |
unreadable | The builder cannot read the live page. |
After the write, the tool records the page's new version in livePage.version. A second apply of the same mockup then writes nothing new.