mockpit 1.3.0 → 3.0.0

package/guide/topics/html.md

@@ -1,9 +1,7 @@
 # mockpit topic: html
 
-An `html` surface is a blank canvas. Custom SVG, bespoke layout, small
-interactions and animation are all fine. Below are the hard rules, the finish
-guardrails, and the vocabulary available inside the frame. `mockpit guide`
-prints this project's real palette, kit and icons.
+An `html` surface is a blank canvas: custom SVG, bespoke layout, small interactions and
+animation are all fine. `mockpit guide` prints this project's palette, kit, icons and rules.
 
 ## Contract
 
@@ -12,18 +10,16 @@ prints this project's real palette, kit and icons.
 - The stage renders your fragment in an 820px-wide frame, scaled to fit the
   user's window. Question pictures and Home thumbnails are the same document,
   shrunk. Height is measured from your content.
-- Keep content in normal flow. The frame measures the document box, so anything
-  out of flow is invisible to the sizer and can leave the surface clipped or
-  stuck at the wrong height.
+- Keep content in normal flow: the frame measures the document box, so anything out of
+  flow can leave the surface clipped or at the wrong height.
   - Never use `position: fixed`.
   - Don't stack `position: absolute` layers over a box with a fixed `height` or
     `min-height`. The overlay grows `scrollHeight` but not the measured box.
   - To overlap elements, grid-stack them: `display: grid` on the container,
     `grid-area: 1 / 1` on each child. The container sizes to the tallest child.
     The `slides` kit does this.
-- Never hardcode a color. `color: #333` disappears in dark mode. Drive every
-  color from the tokens below. Test: if the background were near-black, would
-  everything still read?
+- Never hardcode a color (`color: #333` disappears in dark mode). Drive every color from
+  the tokens below.
 - `<style>` and `<script>` are allowed. Scripts run in a sandboxed iframe with
   no access to the host page.
 
@@ -41,22 +37,16 @@ Mark the components you want feedback on with `data-part="name"` (optional
 apart and keep comments anchored across a rename). The viewer measures their
 boxes, so never hard-code geometry for it. Knob values arrive as unitless
 `--k-<path>` custom properties and `data-k-<path>` attributes on `<html>`; topic
-`knobs` has the details. Alternatives of one region are a slot: the same
+`knobs` has the details. Alternatives of one region are a part with fills: the same
 `data-part` with a `data-fill` each; topic `asks`.
 
-The page must read before any web font or remote stylesheet loads: they are
-decoration, and a slow one delays the frame's layout.
+The page must read before any web font or remote stylesheet loads; a slow one delays the
+frame's layout.
 
-## Finish
+## Scope
 
-These keep mocks feeling native to the viewer. They shape the finish, not the
-idea.
-
-- Flat: no gradients, drop shadows or decorative effects.
-- Sentence case for headings and labels. No emoji.
-- Two font weights: 400 and 500.
 - For diagrams, `<svg width="100%" viewBox="0 0 680 H">` with the classes below.
-- One concept per mock. Publish several small mocks with their own slugs rather
+- One concept per design. Publish several small designs with their own slugs rather
   than one giant page.
 
 ## Theme tokens
@@ -142,26 +132,23 @@ The builtin, issues and slides kits also ship layout helpers (`.row`, `.stack`,
 `.num`, `.kbd`, `.hr`).
 
 ```sh
-mockpit publish --mock ci-status --html status.html --kit issues   # repeat --kit for more
+mockpit publish --design ci-status --html status.html --kit issues   # repeat --kit for more
 ```
 
 ```js
-publish({ mock: "ci-status", surfaces: [{ kind: "html", html, kits: ["issues"] }] });
+publish({ design: "ci-status", surfaces: [{ kind: "html", html, kits: ["issues"] }] });
 ```
 
 A kit only adds vocabulary. Write custom markup right beside kit classes.
 
 ## Tailwind projects
 
-When `mockpit init` found Tailwind v4, the sandbox compiles the repo's own
-Tailwind stylesheet with the browser build, so write the same utility classes
-you write in the repo, including theme classes (`bg-card`,
-`text-muted-foreground`). The browser build cannot load plugins or non-core
-imports, so init strips them; their utilities (`tw-animate-css`, typography)
-are not available, and the brief lists what was stripped. In dark mode the
-frame's `<html>` carries `class="dark"`, so the repo's `.dark` theme applies.
-A Tailwind v3 repo keeps its theme in `tailwind.config`, which the browser
-build cannot load: core utilities work, theme classes do not.
+When `mockpit init` found Tailwind v4, the sandbox compiles the repo's own stylesheet with
+the browser build, so write the repo's utility classes, including theme classes (`bg-card`,
+`text-muted-foreground`). The build can't load plugins or non-core imports, so init strips
+them and the brief lists what was stripped (`tw-animate-css`, typography). In dark mode
+`<html>` carries `class="dark"`, so the repo's `.dark` theme applies. In a Tailwind v3 repo
+core utilities work and theme classes do not, since `tailwind.config` can't load.
 
 ## Icons
 

package/guide/topics/http.md

@@ -1,61 +1,65 @@
 # mockpit topic: http
 
-Every verb works the same on the CLI, MCP and raw HTTP, with the same fields.
-None of them waits for the user.
-
-| CLI                          | MCP                                         | HTTP                                             |
-| ---------------------------- | ------------------------------------------- | ------------------------------------------------ |
-| `mockpit init`               | none                                        | `PUT /api/projects/:name/design`                 |
-| `mockpit publish`            | `publish`                                   | `POST /api/mocks`                                |
-| `mockpit ask`                | `ask`                                       | `POST /api/mocks/:id/asks`                       |
-| `mockpit read [slug]`        | `read`                                      | `GET /api/mocks?project=…`, `GET /api/mocks/:id` |
-| `mockpit feedback`           | `feedback`                                  | `GET /api/feedback?session=…`                    |
-| `mockpit say`                | `say`                                       | `POST /api/mocks/:id/say`                        |
-| `mockpit export`             | `export`                                    | `GET /api/mocks/:id/export`                      |
-| `mockpit upload`             | `upload`                                    | `POST /api/assets`                               |
-| `mockpit guide`              | `guide`                                     | `GET /agent-howto?project=…`                     |
-| `mockpit guide --topic <id>` | `guide({ topic })`                          | `GET /agent-howto?topic=<id>`                    |
-| `mockpit run <file>`         | `run` on `/mcp?mode=code` (topic `scripts`) | `POST /api/run`                                  |
-| `mockpit watch`              | none                                        | none: a CLI stream for background monitors       |
-
-`:id` is the mock id or its slug (add `project` for a slug). Over HTTP the first
-publish creates a session. Pass its `sessionId` as `session` on every later
-call; otherwise each call starts a new session and the reply goes elsewhere.
-`GET /api/feedback` requires it.
+Every verb takes the same fields on the CLI, MCP and raw HTTP. None waits for the user.
+
+| CLI                            | MCP                                         | HTTP                                                                           |
+| ------------------------------ | ------------------------------------------- | ------------------------------------------------------------------------------ |
+| `mockpit init`                 | none                                        | `PUT /api/projects/:name/design`                                               |
+| `mockpit publish`              | `publish`                                   | `POST /api/designs`                                                            |
+| `mockpit ask`                  | `ask`                                       | `POST /api/designs/:id/asks`                                                   |
+| `mockpit read [slug]`          | `read`                                      | `GET /api/designs?project=…`, `GET /api/designs/:id` (`?body=1` adds the html) |
+| `mockpit read --decisions`     | `read({decisions: true})`                   | `GET /api/projects/:name/decisions`                                            |
+| `mockpit feedback`             | `feedback`                                  | `GET /api/feedback?session=…`                                                  |
+| `mockpit say`                  | `say`                                       | `POST /api/designs/:id/say`                                                    |
+| `mockpit move`                 | `move`                                      | `POST /api/designs/:id/move`                                                   |
+| `mockpit edit --design <slug>` | `edit`                                      | `PATCH /api/designs/:id`                                                       |
+| `mockpit edit --notes <t>`     | `edit({ notes })`                           | `PATCH /api/designs/:id` `{notes}`                                             |
+| `mockpit edit --rename <n>`    | `edit({ rename })`                          | `PATCH /api/projects/:name` `{name}`                                           |
+| `mockpit edit --area-order`    | `edit({ areaOrder })`                       | `PATCH /api/projects/:name` `{areaOrder}`                                      |
+| `mockpit export`               | `export`                                    | `GET /api/designs/:id/export`                                                  |
+| `mockpit upload`               | `upload`                                    | `POST /api/assets`                                                             |
+| `mockpit guide`                | `guide`                                     | `GET /agent-howto?project=…`                                                   |
+| `mockpit guide --topic <id>`   | `guide({ topic })`                          | `GET /agent-howto?topic=<id>`                                                  |
+| `mockpit run <file>`           | `run` on `/mcp?mode=code` (topic `scripts`) | `POST /api/run`                                                                |
+| `mockpit watch`                | none                                        | none: a CLI stream for background monitors                                     |
+
+`:id` is the design id or its slug (add `project` for a slug). Over HTTP the first publish
+creates a session: pass its `sessionId` as `session` on every later call, or each call starts
+a new session and the reply goes elsewhere. `GET /api/feedback` requires it.
 
 ## Walkthrough
 
 ```sh
 B=http://localhost:8228
-curl -s -X POST $B/api/mocks -H 'content-type: application/json' -d '{
-  "project": "demo", "mock": "checkout", "title": "Checkout", "state": "Empty cart",
+curl -s -X POST $B/api/designs -H 'content-type: application/json' -d '{
+  "project": "demo", "design": "checkout", "title": "Checkout", "state": "Empty cart",
   "agent": "claude", "knobs": {"pad": [16, 8, 32, 2]}, "widths": [390, 1280],
-  "note": "One column; the summary carries the empty state",
+  "description": "One column; the summary carries the empty state",
   "html": "<section data-part=\"summary\" data-part-label=\"Summary\" style=\"padding:calc(var(--k-pad,16)*1px)\">Your cart is empty</section>"}'
-# → {"mock":{…},"post":{…},"sessionId":"S","url":"…","parts":[{"state":"Empty cart","parts":[{"name":"summary","label":"Summary"}]}],"feedback":[]}
+# → {"design":{…},"post":{…},"sessionId":"S","url":"…","parts":[{"state":"Empty cart","parts":[{"name":"summary","label":"Summary"}]}],"feedback":[]}
 
-# the same (mock, state, variant) again: its next version
-curl -s -X POST $B/api/mocks -H 'content-type: application/json' -d '{
-  "session": "S", "project": "demo", "mock": "checkout", "state": "Empty cart",
+# the same (design, state, variant) again: its next version
+curl -s -X POST $B/api/designs -H 'content-type: application/json' -d '{
+  "session": "S", "project": "demo", "design": "checkout", "state": "Empty cart",
   "html": "<section data-part=\"total\" data-part-label=\"Summary\">Nothing here yet</section>"}'
 # → …,"partChanges":{"vanished":[],"renamed":[{"from":"summary","to":"total"}]}
 
-curl -s -X POST $B/api/mocks/checkout/asks -H 'content-type: application/json' -d '{
+curl -s -X POST $B/api/designs/checkout/asks -H 'content-type: application/json' -d '{
   "session": "S", "project": "demo", "asks": [{"id": "pad", "text": "How roomy?", "scope": "part",
   "part": "total", "options": [{"label": "Tight", "set": {"pad": 8}}, {"label": "Roomy", "set": {"pad": 24}}]}]}'
 
 # tell the user where to look and end your turn; once they say they answered:
 curl -s "$B/api/feedback?session=S"
-# → {"feedback":[{"mock":"checkout","reply":{…},"accepted":[…],"archived":[]}],
-#    "pending":[{"mock":"checkout","viewerOpen":true,"draft":null}]}
+# → {"feedback":[{"design":"checkout","reply":{…},"messages":[],"inUse":[…],"archived":[]}],
+#    "pending":[{"design":"checkout","viewerOpen":true,"draft":null}]}
 
-curl -s -X POST $B/api/mocks/checkout/say -H 'content-type: application/json' -d '{
-  "session": "S", "project": "demo", "message": "Accepted; wiring it up"}'
+curl -s -X POST $B/api/designs/checkout/say -H 'content-type: application/json' -d '{
+  "session": "S", "project": "demo", "message": "In use; wiring it up"}'
 
-curl -s "$B/api/mocks/checkout/export?project=demo"
+curl -s "$B/api/designs/checkout/export?project=demo"
 ```
 
-A publish that leaves two or more variants with no ask binding them adds
+A publish that leaves two or more variants with no question binding them adds
 `nudges` and a ready `suggestedAsk`; POST it to `/asks` as `{"asks": [...]}`.
 
 ## Errors
@@ -63,7 +67,7 @@ A publish that leaves two or more variants with no ask binding them adds
 Every CLI command fails with one line plus an optional fix, exit code 2:
 
 ```
-error demo has no mock "writr"
+error demo has no design "writr"
   fix: mockpit read --project demo
 ```
 
@@ -72,6 +76,5 @@ Nothing is written on a failed command, so a retry is safe. HTTP errors are
 
 ## Remote
 
-A deployed mockpit needs `MOCKPIT_URL` and `MOCKPIT_TOKEN` in your environment.
-The CLI and MCP server send the token for you. For curl, add
-`-H "Authorization: Bearer $MOCKPIT_TOKEN"`.
+A deployed mockpit needs `MOCKPIT_URL` and `MOCKPIT_TOKEN` in your environment. The CLI and
+MCP server send the token. For curl, add `-H "Authorization: Bearer $MOCKPIT_TOKEN"`.

package/guide/topics/knobs.md

@@ -1,21 +1,19 @@
 # mockpit topic: knobs
 
-A knob is a value the user tunes live on one render. Use one when one render
-plus a control shows the choice. A choice is several variants plus one ask
-that binds them; for that, publish variants and ask instead (topic `asks`).
-A 2–3 option knob is a choice: ask with options that `set` it. Publishing
-one returns that nudge. Declare knobs for what is worth fine-tuning (size,
-spacing, colour, density) even when the user did not ask; they wait in Tune.
+A knob is a value the user tunes live on one render. For a choice between renders, publish
+variants and ask (topic `asks`). A 2–3 option knob is a choice: ask with options that `set`
+it; publishing one returns that nudge. Declare knobs for what is worth fine-tuning (size,
+spacing, colour, density) even unasked; they wait in Tune.
 
 ## Declaring
 
 Knobs use tunekit's `usePane` shape, keyed by path. `"size"` is global,
-`"body.size"` belongs to the `body` part. Mock-wide knobs go in `--knobs` (MCP
+`"body.size"` belongs to the `body` part. Design-wide knobs go in `--knobs` (MCP
 and HTTP `knobs`). Over MCP and HTTP, knobs only one variant has go in
 `variantKnobs`.
 
 ```sh
-mockpit publish --mock writer --state "Writing" --html w.html --knobs '{"body.size":[17,14,22,1]}'
+mockpit publish --design writer --state "Writing" --html w.html --knobs '{"body.size":[17,14,22,1]}'
 ```
 
 | shape                                                          | control        |
@@ -69,5 +67,4 @@ from script.
 <div class="trim-bottom" data-part="trim">Chapter 7</div>
 ```
 
-An ask option can set knob values too (`"set": {"trim.position": "bottom"}`),
-which turns a knob into a question. See topic `asks`.
+Topic `asks`: an option's `"set": {"trim.position": "bottom"}` turns a knob into a question.

package/guide/topics/scripts.md

@@ -1,29 +1,23 @@
 # mockpit topic: scripts
 
-`run` executes a JavaScript script on the server against the mockpit API. One
-run can publish two variants and ask which one: three tool calls in one. A
-script never waits for the user. End the turn after the run that asks; when
-the user says they answered, a later run reads `mockpit.feedback()`.
+`run` executes a JavaScript script on the server against the mockpit API: one run can
+publish two variants and ask which. A script never waits for the user. End the turn after the
+run that asks; once they say they answered, a later run reads `mockpit.feedback()`.
 
 ## When to use it
 
-- Your client loads every MCP tool into each conversation and has no codemode
-  of its own (claude.ai, Desktop and ChatGPT connectors). Connect to
-  `/mcp?mode=code` instead of `/mcp`: one `run` tool.
-- You work from a shell and want the whole loop in one file:
-  `mockpit run loop.js`.
-- Skip it when your harness already turns MCP tools into code (pi, Cloudflare
-  Agents). A script inside a script means double escaping; use the plain tools.
-- The Cloudflare Worker has no sandbox. There `run` answers that it is
-  unavailable.
+- Your client loads every MCP tool into each conversation and has no codemode of its own
+  (claude.ai, Desktop and ChatGPT connectors): connect to `/mcp?mode=code` for one `run` tool.
+- You work from a shell and want the whole loop in one file: `mockpit run loop.js`.
+- Skip it when your harness already turns MCP tools into code (pi, Cloudflare Agents).
+- On the Cloudflare Worker, which has no sandbox, `run` answers that it is unavailable.
 
 | CLI                                 | MCP                                                                       | HTTP                                               |
 | ----------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------- |
 | `mockpit run <file>` (`-` is stdin) | `run` on `/mcp?mode=code`, or stdio with `MOCKPIT_MCP_MODE=code` (`path`) | `POST /api/run {code, session?, project?, agent?}` |
 
-The session, project and agent are fixed for a run. The result carries the
-`session`; pass it to the next run so its `feedback()` hears the reply. The CLI and the
-stdio server keep one session for you.
+The session, project and agent are fixed for a run. The result carries the `session`; pass it
+to the next run so its `feedback()` hears the reply. The CLI and stdio server keep one for you.
 
 ## The API
 
@@ -40,12 +34,12 @@ const card = (tone) => `
     <h1>Writer</h1>
     <button data-part="cta">Start writing</button>
   </section>`;
-await mockpit.publish({ mock: "writer", title: "Writer", variant: "calm", html: card("calm") });
-await mockpit.publish({ mock: "writer", variant: "bold", html: card("bold") });
+await mockpit.publish({ design: "writer", title: "Writer", variant: "calm", html: card("calm") });
+await mockpit.publish({ design: "writer", variant: "bold", html: card("bold") });
 const { url } = await mockpit.ask("writer", [
   {
-    id: "look",
-    text: "Which look?",
+    id: "tone",
+    text: "Calm or bold?",
     options: [
       { label: "Calm", variant: "calm" },
       { label: "Bold", variant: "bold" },
@@ -55,8 +49,7 @@ const { url } = await mockpit.ask("writer", [
 return url;
 ```
 
-Tell the user in one line where to look, then end your turn. Once they say
-they answered:
+Tell the user where to look and end your turn. Once they say they answered:
 
 ```js
 const { feedback, pending } = await mockpit.feedback();
@@ -80,32 +73,29 @@ return feedback.length ? feedback : pending;
 }
 ```
 
-- `calls` lists every host call in order. After a failure it tells you which
-  writes landed. A rerun publishes new versions, so check it first.
-- `feedback` holds every batch the run received, from `feedback()` and from
-  the feedback that rides on writes. It is there even when the script threw or
-  ran out of time. Feedback is delivered once: read it here, not from a later
-  call.
+- `calls` lists every host call in order. After a failure it shows which writes landed; a
+  rerun publishes new versions, so check it first.
+- `feedback` holds every batch the run received, from `feedback()` and from writes, even when
+  the script threw or timed out. It is delivered once: read it here.
 - `error.kind` is `script` (a throw or a syntax error, with `line` and
   `column`), `timeout`, `limit` (CPU, memory, code size, call count) or
   `aborted` (the caller went away).
 
 ## Errors
 
-A host call that fails rejects with the message REST would give, so
-`try`/`catch` works:
+A failed host call rejects with REST's message, so `try`/`catch` works:
 
 ```js
 try {
   await mockpit.publish({
-    mock: "writer",
+    design: "writer",
     variant: "calm",
     parts: { hero: '<section data-part="hero">…</section>' },
   });
 } catch (e) {
   print("part splice failed:", e.message);
   await mockpit.publish({
-    mock: "writer",
+    design: "writer",
     variant: "calm",
     html: '<section data-part="hero">…</section>',
   });
@@ -124,6 +114,5 @@ try {
 | Host calls | 100 per run, 4 in flight                                     |
 | Runs       | 4 at a time per server                                       |
 
-No network, timers, imports, `require` or `process` exist in the sandbox. The
-only way out is `mockpit.*`, and it can do what your token can over REST, no
-more.
+The sandbox has no network, timers, imports, `require` or `process`. The only way out is
+`mockpit.*`, with what your token can do over REST.

package/guide/topics/surfaces.md

@@ -5,6 +5,7 @@ A variant version is an ordered list of surfaces. Each has a `kind`:
 ```
 { "kind": "html", "html": "<p>...</p>" }
 { "kind": "html", "html": "<ul class=\"tree\">…</ul>", "kits": ["issues"] }
+{ "kind": "html", "html": "<canvas>…</canvas>", "poster": "<id from an upload>" }
 { "kind": "markdown", "markdown": "## Plan\n\n1. …" }
 { "kind": "mermaid", "mermaid": "flowchart TD; A[Start] --> B{Ok?}" }
 { "kind": "diff", "patch": "<unified or git diff text>", "layout": "split" }
@@ -20,10 +21,8 @@ On the CLI: `--html`, `--md`, `--diff`, `--mermaid`, `--terminal`, `--code`,
 
 ## Picking a kind
 
-Pick by what the thing is:
-
-- `html`: you are drawing. UI, diagrams, data viz, anything interactive. Design
-  mocks use this. Topic `html` has its contract.
+- `html`: you are drawing: UI, diagrams, data viz, anything interactive. Topic `html` has its
+  contract.
 - `markdown`: prose, plans, tradeoffs. Tag fenced code to highlight it.
   `![caption](/a/<id>)` embeds an uploaded image. Raw HTML in the source is
   escaped.
@@ -47,40 +46,33 @@ from data, so send data, never markup.
 
 ## Composition: embeds
 
-Any mock can embed another mock of the project in its html with
-`<mockpit-embed slug="button"></mockpit-embed>` (`<mockpit-slot>` still works;
-a slot is now a region with fills, topic `asks`). The server inlines that
-mock's html body in place, inside the embedding frame, and expands the
-component's own embeds in turn (up to 6 levels), so build a page from
-sections and sections from components, each its own mock with its own
-variants and questions.
-
-- No `version`: the embed follows the component's version in use once the user
-  accepted one, else its latest, so a new version of the button shows in every
-  page that uses it without republishing them. `version="3"` pins it.
-- No `variant`: the component's accepted variant (else `default`). Name one to
+Any design can embed another of the project in its html with
+`<mockpit-embed slug="button"></mockpit-embed>`. The server inlines that design's html body in
+place and expands its own embeds (up to 6 levels), so build a screen from sections and sections
+from components, each its own design with its own variants and questions.
+
+- No `version`: follows the component's version in use, else its latest, without republishing
+  what embeds it. `version="3"` pins it.
+- No `variant`: the component's variant in use (else `default`). Name one to
   show a specific variant.
-- The component shows as decided: its slots keep only the fills the user
+- The component shows as decided: its parts with fills keep only the fills the user
   settled on, and its other settled knob values ride on the embed's wrapper
   (`data-k-<path>` and `--k-<path>`), so write its knob CSS as
   `[data-k-tone="loud"] .chip`, not `html[data-k-tone=…]`.
 - `read` lists each variant's `embeds` as they render now (nested included,
   with every version, for the user to peek back) and `publishedWith`, the
   versions it rendered with when you published it.
-- A chain that loops back on itself is refused at publish. An unknown slug
-  renders as an empty placeholder, not silently dropped.
+- A chain that loops back is refused at publish. An unknown slug renders as an empty placeholder.
 
 ## Editing one surface
 
-`publish` with `surfaces` takes the full ordered list, so one call adds, edits,
-removes and reorders. Every write returns each surface's `id`
-(`post.surfaces`). In the next list, an entry that is only `{ "id": "…" }`
-keeps that surface unchanged, an `id` with content replaces it in place, an
-entry without an `id` is new, an id you leave out is removed, and the list
-order is the new order:
+`publish` with `surfaces` takes the full ordered list, so one call adds, edits, removes and
+reorders. Every write returns each surface's `id` (`post.surfaces`). In the next list: `{ "id": "…" }`
+alone keeps a surface, an `id` with content replaces it, no `id` is new, a missing id is removed,
+and list order is the new order:
 
 ```json
-{ "mock": "writer", "surfaces": [{ "kind": "markdown", "markdown": "## Why" }, { "id": "s1" }] }
+{ "design": "writer", "surfaces": [{ "kind": "markdown", "markdown": "## Why" }, { "id": "s1" }] }
 ```
 
 An unknown id fails with the surfaces present and writes nothing.
@@ -96,21 +88,38 @@ POST /api/assets   (raw)   Content-Type: image/png   <bytes>   ?filename=shot.pn
 POST /api/assets   (json)  { "data": "<base64>", "contentType": "image/png", "filename": "shot.png" }
 ```
 
-An asset's id is the SHA-256 of its bytes. You can derive the URL locally
-(`mockpit asset-url shot.png`) and write `<img src="/a/<hash>">` before the
-upload finishes; the viewer waits briefly for an in-flight asset. Identical
-bytes dedupe. An asset lives as long as something references it. The limit is
-5 MB per asset.
+An asset's id is the SHA-256 of its bytes, so identical bytes dedupe. You can derive the URL
+locally (`mockpit asset-url shot.png`) and write `<img src="/a/<hash>">` before the upload
+finishes; the viewer waits briefly for an in-flight asset. An asset lives as long as something
+references it. Limit: 5 MB per asset.
 
-## What the user sees
+## Posters
+
+A heavy page (3D, WebGL, a running canvas) costs a live frame in every overview card, and a
+browser holds only about 16. A still as the html's `poster` fixes that: Studio and Home show the
+picture, Stage still runs the page.
+
+The CLI and the stdio MCP server take one for you, with a local Chrome or Chromium, just after
+each publish that doesn't send its own. It arrives seconds later and the publish doesn't wait for
+it. With no browser there is none, and the page runs live as before. Send your own to choose the
+moment; yours always wins. Over raw HTTP and `/mcp`, only yours exists:
 
-Each thing you add lights up its part of the viewer.
+```
+CLI  mockpit publish --design onni --variant felt --html felt.html --poster felt.png
+MCP  publish { design, variant, html, poster: "<asset id, or an image path on stdio>" }
+HTTP POST /api/designs { …, "html": "…", "poster": "<asset id>" }
+```
+
+A version that changes the page without a new poster (`--parts`, `--fills`, a fork with edits)
+drops it, so send one with each, or let the CLI or stdio server take the new one.
+
+## What the user sees
 
-| you publish            | the user gets                                        |
-| ---------------------- | ---------------------------------------------------- |
-| a plain mock, any kind | the stage and Thread, with Accept / Revise / Drop    |
-| several variants       | a switcher, plus a built-in Look ask until you ask   |
-| asks                   | Questions: picture options on the stage, then Send   |
-| `data-part`            | Tune's component list and comments anchored on parts |
-| `knobs`                | Tune's controls, live on the stage                   |
-| several states         | the state strip under the stage                      |
+| you publish              | the user gets                                        |
+| ------------------------ | ---------------------------------------------------- |
+| a plain design, any kind | the stage and Thread, with Use this / New version    |
+| several variants         | a switcher, plus a built-in variant question         |
+| questions (`ask`)        | Questions: picture options on the stage, then Send   |
+| `data-part`              | Tune's component list and comments anchored on parts |
+| `knobs`                  | Tune's controls, live on the stage                   |
+| several states           | the state tabs above the stage                       |

package/opencode/mockpit.js

@@ -0,0 +1,120 @@
+// Waits for a Send on each mockpit session this OpenCode process has used, and
+// wakes the OpenCode session that last called it. Nothing runs before a mockpit call.
+// One default export serves both OpenCode lines: 1.x calls server() and 2.x setup(),
+// and 2.x doesn't run 1.x plugins. No imports, so the package has no dependencies.
+
+const BASE = (process.env.MOCKPIT_URL || "http://localhost:8228").replace(/\/+$/, "");
+const HEADERS = {
+  "x-mockpit-client": "opencode",
+  ...(process.env.MOCKPIT_TOKEN ? { authorization: `Bearer ${process.env.MOCKPIT_TOKEN}` } : {}),
+};
+
+const pause = (ms, signal) =>
+  new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener("abort", () => (clearTimeout(timer), resolve()), { once: true });
+  });
+
+// A shell command, or 2.x's code tool, which is how it calls MCP tools, names mockpit
+// only in its arguments.
+const isMockpitCall = (tool, args) =>
+  /mockpit/i.test(tool) ||
+  (/^(bash|shell|execute)$/i.test(tool) && /\bmockpit/.test(JSON.stringify(args ?? "")));
+
+// A write's result names its session. The rest don't, and the MCP server records the
+// directory it runs in, so the newest session there is this process's own.
+async function mockpitSession(output, directory) {
+  const named = /\\?"sessionId\\?"\s*:\s*\\?"([^"\\]+)/.exec(output ?? "")?.[1];
+  if (named) return named;
+  const res = await fetch(`${BASE}/api/sessions`, { headers: HEADERS });
+  if (!res.ok) return undefined;
+  const newest = (await res.json())
+    .filter((s) => s.cwd === directory)
+    .sort((a, b) => String(b.lastActiveAt).localeCompare(String(a.lastActiveAt)))[0];
+  return newest?.id;
+}
+
+const wakeText = (batches) =>
+  `The user replied in the mockpit viewer on ${[...new Set(batches.map((b) => b.design ?? "a design"))].join(", ")}. Call mockpit's feedback for the reply.`;
+
+function createWaker(wake) {
+  const callers = new Map();
+  const stop = new AbortController();
+
+  async function wait(session) {
+    while (!stop.signal.aborted) {
+      try {
+        const query = new URLSearchParams({ session, author: "user", wait: "60", peek: "1" });
+        const res = await fetch(`${BASE}/api/comments?${query}`, {
+          headers: HEADERS,
+          signal: stop.signal,
+        });
+        if (!res.ok) {
+          await pause(2000, stop.signal);
+          continue;
+        }
+        const batches = (await res.json()).feedback ?? [];
+        if (batches.length === 0 || stop.signal.aborted) continue;
+        // The reply stays on the session's cursor, so a wake that fails loses only the
+        // wake: feedback or the next write still delivers it.
+        await wake(callers.get(session), wakeText(batches));
+      } catch {
+        await pause(2000, stop.signal);
+      }
+    }
+  }
+
+  return {
+    async noteCall({ tool, args, output, sessionID, directory }) {
+      if (!isMockpitCall(tool, args)) return;
+      const session = await mockpitSession(output, directory).catch(() => undefined);
+      if (!session) return;
+      const known = callers.has(session);
+      callers.set(session, sessionID);
+      if (!known) void wait(session);
+    },
+    stop: () => stop.abort(),
+  };
+}
+
+const text = (result) => (typeof result === "string" ? result : JSON.stringify(result ?? ""));
+
+export default {
+  id: "mockpit",
+
+  server: async ({ client, directory }) => {
+    const waker = createWaker(async (sessionID, message) => {
+      await client.session.promptAsync({
+        path: { id: sessionID },
+        body: { parts: [{ type: "text", text: message }] },
+      });
+    });
+    return {
+      "tool.execute.after": async (input, output) => {
+        await waker.noteCall({
+          tool: input.tool,
+          args: input.args,
+          output: output?.output,
+          sessionID: input.sessionID,
+          directory,
+        });
+      },
+    };
+  },
+
+  setup: async (ctx) => {
+    const waker = createWaker(async (sessionID, message) => {
+      await ctx.session.synthetic({ sessionID, text: message, description: "mockpit reply" });
+    });
+    await ctx.tool.hook("execute.after", async (event) => {
+      await waker.noteCall({
+        tool: event.tool,
+        args: event.input,
+        output: event.status === "completed" ? text(event.result) : undefined,
+        sessionID: event.sessionID,
+        directory: process.cwd(),
+      });
+    });
+    return () => waker.stop();
+  },
+};