mockpit 1.2.0 → 2.0.0

package/extensions/mockpit.js

@@ -28,10 +28,10 @@ const feedbackGuideline =
 // The never-block loop, in the words of every other tier: nothing waits for
 // the user, so the agent ends its turn and reads feedback when told.
 const loopGuidelines = [
-  "Publish each variant with mockpit_publish (name states in the user's words; mark parts with data-part); publish again to revise.",
-  "A choice is several variants plus one ask that binds them: mockpit_ask with options bound to the variants. One render plus a control: declare a knob.",
+  "Publish each variant with mockpit_publish (name states in the user's words; declare parts with data-part); publish again to revise.",
+  "A choice is several variants plus one question that binds them: mockpit_ask with options bound to the variants. One render plus a control: declare a knob.",
   "Tell the user in one line where to look, then end your turn. The question lives in the mock, never in chat. Never poll.",
-  "When the user says they answered, call mockpit_feedback. Every write also returns feedback; read it.",
+  "A reply sent from the viewer arrives on its own as a mockpit message; act on it. If the user says they answered and none came, call mockpit_feedback. Every write also returns feedback; read it.",
 ];
 
 const surfaceSchema = {
@@ -209,18 +209,47 @@ async function requestText(path) {
   return text;
 }
 
+// A poster may name an image file: it goes up as an asset, and the publish
+// carries its id. Anything else is already an asset id.
+async function posterId(value, ctx) {
+  if (typeof value !== "string" || !value) return undefined;
+  const file = resolve(ctx.cwd, value);
+  let data;
+  try {
+    data = await readFile(file);
+  } catch {
+    return value;
+  }
+  const ext = file.split(".").pop()?.toLowerCase();
+  const asset = await requestJson("/api/assets", {
+    method: "POST",
+    body: JSON.stringify({
+      data: data.toString("base64"),
+      contentType: ext === "jpg" || ext === "jpeg" ? "image/jpeg" : `image/${ext}`,
+      filename: file.split(/[\\/]/).pop(),
+    }),
+  });
+  return asset.id;
+}
+
 function rememberSession(state, sessionId) {
   if (typeof sessionId === "string" && sessionId) state.sessionId = sessionId;
 }
 
-// `feedback` is one batch per mock: the user's reply (answers, mix, tuned
-// knob values, part comments) plus any plain comments. Rendered one line per
-// thing the user said, so nothing is summarized away.
+// `feedback` is one batch per mock: the user's reply (answers, borrowed parts,
+// tuned knob values, part comments, verdict) plus any thread messages.
+// Rendered one line per thing the user said, so nothing is summarized away.
 function feedbackLines(feedback) {
   const lines = [];
   for (const batch of feedback ?? []) {
     const prefix = batch.mock ? `${batch.mock}: ` : "";
     if (batch.handoff) lines.push(`- ${prefix}${batch.handoff}`);
+    if (batch.closed) {
+      const asks = (batch.dismissed ?? []).map((d) => d.text || d.ask).join("; ");
+      lines.push(
+        `- ${prefix}closed by the user${asks ? `, unanswered: ${asks}; don't ask again` : ""}`,
+      );
+    }
     const reply = batch.reply;
     if (reply) {
       for (const a of reply.asks ?? []) {
@@ -228,21 +257,35 @@ function feedbackLines(feedback) {
         lines.push(`- ${prefix}${a.text || a.ask} → ${chosen || "(no pick)"}`);
         if (a.note) lines.push(`  note: ${a.note}`);
       }
-      for (const [part, variant] of Object.entries(reply.mix ?? {})) {
-        lines.push(`- ${prefix}use ${variant}'s ${part}`);
+      for (const [part, variant] of Object.entries(reply.borrowed ?? {})) {
+        lines.push(`- ${prefix}borrow ${part} from ${variant}`);
       }
       for (const [path, value] of Object.entries(reply.tuned ?? {})) {
         lines.push(`- ${prefix}tuned ${path} = ${JSON.stringify(value)}`);
       }
       for (const c of reply.comments ?? []) {
+        if (c.borrow) {
+          lines.push(
+            `- ${prefix}borrow ${c.borrow.part ? `${c.borrow.part} ` : ""}from ${c.borrow.from} into ${c.variant}@${c.version}${c.text ? `: ${c.text}` : ""}`,
+          );
+          continue;
+        }
         lines.push(
           `- ${prefix}${c.part ? `[${c.part}${c.state ? ` · ${c.state}` : ""}] ` : ""}${c.text}`,
         );
       }
-      if (reply.decision) lines.push(`- ${prefix}${reply.decision.kind} ${reply.decision.variant}`);
+      if (reply.verdict) lines.push(`- ${prefix}${reply.verdict.kind} ${reply.verdict.variant}`);
       if (reply.text) lines.push(`- ${prefix}${reply.text}`);
     }
-    for (const c of batch.comments ?? []) lines.push(`- ${prefix}${c.text}`);
+    for (const c of batch.messages ?? []) lines.push(`- ${prefix}${c.text}`);
+    if (batch.edited) {
+      const e = batch.edited;
+      const moved = [
+        e.kind ? `now a ${e.kind}` : "",
+        e.area !== undefined ? (e.area ? `area ${e.area}` : "no area") : "",
+      ].filter(Boolean);
+      lines.push(`- ${prefix}the user moved it from Home (${moved.join(", ")})`);
+    }
   }
   return lines;
 }
@@ -269,6 +312,42 @@ function feedbackSummary(feedback) {
   return `\n\nUser feedback delivered with this result:\n${lines.join("\n")}`;
 }
 
+const pause = (ms, signal) =>
+  new Promise((done) => {
+    const timer = setTimeout(done, ms);
+    signal.addEventListener("abort", () => (clearTimeout(timer), done()), { once: true });
+  });
+
+// The user's reply wakes the idle agent, as the Claude Code plugin's monitor
+// does. Reading feedback advances the server's cursor, so the message carries
+// the whole reply: a nudge to call mockpit_feedback would come back empty.
+// followUp waits for a busy agent to finish rather than cutting into its work.
+async function watchReplies(pi, state, signal) {
+  while (!signal.aborted) {
+    if (!state.sessionId) {
+      await pause(2000, signal);
+      continue;
+    }
+    try {
+      const query = new URLSearchParams({ session: state.sessionId, author: "user", wait: "60" });
+      const result = await requestJson(`/api/comments?${query}`, { signal });
+      const lines = feedbackLines(result.feedback);
+      if (!lines.length || signal.aborted) continue;
+      pi.sendMessage(
+        {
+          customType: "mockpit-reply",
+          content: `The user replied in mockpit:\n${lines.join("\n")}`,
+          display: true,
+          details: { feedback: result.feedback },
+        },
+        { triggerTurn: true, deliverAs: "followUp" },
+      );
+    } catch {
+      await pause(2000, signal);
+    }
+  }
+}
+
 function reconstructSession(ctx) {
   let sessionId = process.env.MOCKPIT_SESSION || undefined;
   for (const entry of ctx.sessionManager.getBranch()) {
@@ -286,9 +365,17 @@ function reconstructSession(ctx) {
 
 export default function mockpitExtension(pi) {
   const state = { sessionId: process.env.MOCKPIT_SESSION || undefined };
+  let watching;
 
   pi.on("session_start", (_event, ctx) => {
     state.sessionId = reconstructSession(ctx);
+    watching?.abort();
+    watching = undefined;
+    // print and json runs end after one prompt; nobody is there to wake.
+    if (ctx.mode === "tui" || ctx.mode === "rpc") {
+      watching = new AbortController();
+      void watchReplies(pi, state, watching.signal);
+    }
     ctx.ui.setStatus(
       "mockpit",
       state.sessionId
@@ -297,6 +384,12 @@ export default function mockpitExtension(pi) {
     );
   });
 
+  // After shutdown pi refuses calls from this extension, so the loop stops first.
+  pi.on("session_shutdown", () => {
+    watching?.abort();
+    watching = undefined;
+  });
+
   pi.registerCommand("mockpit", {
     description: "Show mockpit extension status or reset its remembered session: /mockpit [reset]",
     handler: async (args, ctx) => {
@@ -358,13 +451,23 @@ export default function mockpitExtension(pi) {
         ...mockProps,
         title: { type: "string", description: "Mock title" },
         kind: { type: "string", enum: ["component", "page"], description: "Mock kind" },
-        html: { type: "string", description: "HTML body fragment; mark parts with data-part" },
+        area: {
+          type: "string",
+          description: 'Where in the product it belongs ("Shell"); Home groups by it. "" clears',
+        },
+        source: { type: "string", description: 'Code path that implements it. "" clears' },
+        html: { type: "string", description: "HTML body fragment; declare parts with data-part" },
         path: { type: "string", description: "File to read the html from instead" },
+        poster: {
+          type: "string",
+          description:
+            "A still of the page (image file path, or asset id) that Studio and Home show instead of running it; send one with every version that changes the page",
+        },
         surfaces: surfacesSchema,
         parts: {
           type: "object",
           description:
-            '{"name"|"name#key": outer html}; splices marked parts of the latest version',
+            '{"name"|"name#key": outer html}; splices declared parts of the latest version',
         },
         knobs: { type: "object", description: "Knobs in tunekit usePane shape, keyed by path" },
         variantKnobs: { type: "object", description: "Knobs this variant alone has" },
@@ -378,11 +481,13 @@ export default function mockpitExtension(pi) {
         ? await readFile(resolve(ctx.cwd, params.path), "utf8")
         : params.html;
       const { path: _path, ...rest } = params;
+      const poster = await posterId(params.poster, ctx);
       const result = await requestJson("/api/mocks", {
         method: "POST",
         body: JSON.stringify({
           ...rest,
           html,
+          ...(poster === undefined ? {} : { poster }),
           project: projectOf(params, ctx),
           session: state.sessionId,
           // Only used when this publish creates the session.
@@ -424,7 +529,7 @@ export default function mockpitExtension(pi) {
     name: "mockpit_ask",
     label: "Mockpit Ask",
     description:
-      "Ask structured questions on a mock. A choice is several variants plus one ask that binds them ({label, variant}); options may also set knob values ({label, set}). Reusing an ask id replaces it.",
+      "Ask structured questions on a mock. A choice is several variants plus one question that binds them ({label, variant}); options may also set knob values ({label, set}). Reusing a question id replaces it.",
     promptSnippet: "Ask the user to choose between mockpit variants.",
     promptGuidelines: [
       "Use mockpit_ask once the variants are published, tell the user where to look, then end your turn.",
@@ -515,7 +620,7 @@ export default function mockpitExtension(pi) {
     name: "mockpit_feedback",
     label: "Mockpit Feedback",
     description:
-      "Returns at once: what the user sent since you last heard (one batch per mock: answers, mix, tuned knobs, part comments, comments, accepted/archived), delivered once, plus pending (viewer open, draft progress).",
+      "Returns at once: what the user sent since you last heard (one batch per mock: answers, borrowed parts, tuned knobs, part comments, verdict; thread messages; inUse/archived; or closed with the questions it dismissed), delivered once, plus pending (viewer open, draft progress).",
     promptSnippet: "Read the user's mockpit reply when they say they answered.",
     promptGuidelines: [
       "Call mockpit_feedback when the user says they answered; it returns at once, so do not call it in a loop.",
@@ -576,12 +681,70 @@ export default function mockpitExtension(pi) {
     },
   });
 
+  pi.registerTool({
+    name: "mockpit_edit",
+    label: "Mockpit Edit",
+    description:
+      'Change a mock without a new version: slug, title, kind, area, source ("" clears). A new slug rewrites every embed, data-goto and flow step naming the old one. Or, with no mock, rename the project (rename) or order its areas on Home (areaOrder). Returns feedback.',
+    promptSnippet: "Rename, retitle or reclassify a mockpit mock, or rename the project.",
+    promptGuidelines: [feedbackGuideline],
+    parameters: {
+      type: "object",
+      properties: {
+        mock: { type: "string", description: "Mock slug or id" },
+        project: { type: "string", description: "Project name; defaults to the repo" },
+        slug: { type: "string", description: "New slug" },
+        title: { type: "string", description: "Mock title" },
+        kind: { type: "string", enum: ["page", "component", "sketch"] },
+        area: { type: "string", description: 'Area in the product; "" clears' },
+        source: { type: "string", description: 'Code path that implements it; "" clears' },
+        rename: { type: "string", description: "Without mock: the project's new name" },
+        areaOrder: {
+          type: "array",
+          items: { type: "string" },
+          description: "Without mock: Home's area order; unlisted areas follow alphabetically",
+        },
+      },
+    },
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const project = projectOf(params, ctx);
+      const { rename, areaOrder, ...fields } = params;
+      const onProject = rename !== undefined || areaOrder !== undefined;
+      if (onProject && params.mock !== undefined) {
+        throw new Error('"rename" and "areaOrder" edit the project; edit the mock without them');
+      }
+      const result = onProject
+        ? await requestJson(`/api/projects/${encodeURIComponent(project)}`, {
+            method: "PATCH",
+            body: JSON.stringify({ name: rename, areaOrder, session: state.sessionId }),
+          })
+        : await requestJson(mockPath(params.mock ?? ""), {
+            method: "PATCH",
+            body: JSON.stringify({ ...fields, project, session: state.sessionId }),
+          });
+      const text = result.renamed
+        ? `renamed ${result.renamed.from} → ${result.renamed.to} · ${result.url}`
+        : result.areaOrder
+          ? `area order ${result.areaOrder.join(", ") || "alphabetical"} · ${result.url}`
+          : `edited ${result.mock.slug} · ${result.url}`;
+      return {
+        content: [
+          {
+            type: "text",
+            text: `${[text, ...(result.nudges ?? []).map((n) => `nudge: ${n}`)].join("\n")}${feedbackSummary(result.feedback)}`,
+          },
+        ],
+        details: { ...result, baseUrl: baseUrl() },
+      };
+    },
+  });
+
   pi.registerTool({
     name: "mockpit_export",
     label: "Mockpit Export",
     description:
-      "The accepted (or current) html per state, version history, and the last reply's tuned values.",
-    promptSnippet: "Export an accepted mockpit mock.",
+      "The html in use (else current) per state, version history, and the last reply's tuned values.",
+    promptSnippet: "Export the design in use from a mockpit mock.",
     parameters: { type: "object", properties: mockProps, required: ["mock"] },
     async execute(_id, params, _signal, _onUpdate, ctx) {
       const query = new URLSearchParams({ project: projectOf(params, ctx) });

package/guide/packs/design-craft.md

@@ -0,0 +1,35 @@
+## Rules
+
+- Before designing something new, ask 2–3 short questions with likely answers
+  as options (who, when, what matters most), then design. When the user asks for
+  a quick draft, skip them and write your assumptions in each variant's note.
+- Variants differ in one clear thing (layout, density, emphasis, voice), are
+  named by what they are, and each note says when it's the best pick and what it
+  costs. Three by default, five at most. A difference that is only colour or
+  size is a knob, not a variant.
+- Don't ask what has a right answer (big enough to tap, undo, readable in light
+  and dark): decide it and say why in one line of the note. Ask only what is the
+  user's to decide.
+- Real content: realistic text and counts, and the awkward cases (a long name,
+  a zero, many items). No lorem.
+- No filler: no subtitles that say nothing, emoji, eyebrow labels, italic last
+  words, pep talk, badges everywhere, decorative gradients or boxes in boxes,
+  unless the user asks for that direction. Filler out, craft in: put the effort
+  into hierarchy, real data and visuals that carry meaning. Never bare by default.
+- Errors say what happened and what to do next. Nothing is cut off at the
+  narrowest width.
+- Once a direction is chosen, add the other situations the state has (empty,
+  many, error, loading) as situations of the state (`--situation`). Not in the
+  first round.
+- Once the user has chosen, the next version is that design with the likely fix
+  applied, and the note says what changed. Don't reopen it with new options; ask
+  one focused question only if it is still off.
+
+## Suggestions
+
+- One word per thing everywhere; buttons say what happens ("Log lunch", not "OK").
+- Make things stand out on purpose: what looks different means something
+  different, and the same meaning looks the same everywhere. Say the meaning in
+  the note when it matters.
+- Gestures the product is judged by are built working in Try mode, every phase
+  including cancel. Not every button.

package/guide/topics/asks.md

@@ -1,17 +1,20 @@
 # mockpit topic: asks
 
-An ask is your structured question on a mock. A choice is several variants
-plus one ask that binds them. Ask only when the decision is really the user's,
-and ask in the mock, never in chat: after asking, tell the user in one line
-where to look and end your turn.
+A question (`ask`) is your structured question on a mock. A choice is several
+variants plus one question that binds them. Ask only when the decision is
+really the user's, and ask in the mock, never in chat: after asking, tell the
+user in one line where to look and end your turn. To the user they are
+questions; `ask` is only the tool's name.
 
 ```sh
-mockpit ask --mock writer "Which look?" --option Quiet=quiet --option Dark=dark --id look
+mockpit ask --mock writer "Quiet or dark?" --option Quiet=quiet --option Dark=dark --id tone
 mockpit ask --mock writer "Trim?" --option Above=knob:trim.position=top --option Below=knob:trim.position=bottom
 mockpit ask --mock writer --asks asks.json
 ```
 
 `=knob:` sets one knob; for an option that sets several, use `--asks` JSON.
+`--recommend Quiet` (`"recommended": true` on one option) marks the one you
+would pick with a quiet dot; the user sees why on hover, in the variant's note.
 
 ## Shape
 
@@ -20,8 +23,8 @@ The same JSON goes to `--asks`, MCP `ask` and `POST /api/mocks/:id/asks`:
 ```json
 [
   {
-    "id": "look",
-    "text": "Which look?",
+    "id": "tone",
+    "text": "Quiet or dark?",
     "scope": "mock",
     "options": [
       { "label": "Quiet", "variant": "quiet" },
@@ -51,49 +54,97 @@ The same JSON goes to `--asks`, MCP `ask` and `POST /api/mocks/:id/asks`:
 
 ## Scope
 
-`scope` says what an ask decides: `mock` (the default), `state` (add `state`)
-or `part` (add `part`, the `data-part` name).
+`scope` says what a question decides: `mock` (the default), `state` (add
+`state`) or `part` (add `part`, the `data-part` name). Scope also says where
+the user sees it: the viewer shows each state with its own questions. A
+`state` question shows on that state, a `part` question on every state that
+declares the part, and a `mock` question whose options name variants on every
+state that has them (any other `mock` question on every state); answered
+once, it counts once.
+
+Only open questions are shown and counted ("1 of 3"). Once a Send answers
+one, it folds into a read-only Answered list and stays out of the next round,
+so ask new questions for what is still open rather than re-sending answered
+ones; the user changes a sent answer only on purpose, and the change arrives
+as a normal Send.
 
 ## Options
 
 An option binds to one of:
 
-- a `variant`: picking it accepts that variant and archives its siblings in
-  that state.
+- a `variant`: picking it puts that variant in use and archives its siblings
+  in that state. Add `version` to offer one version of it (`"version": 2`, CLI
+  `--option Before=quiet@2`): two options can be two versions of one variant,
+  and the picked one is put in use. It needs the question's `state` when the
+  mock has several.
 - a knob `set`: picking it applies those values live.
 - nothing: a plain pill.
 
 Options that change how something looks carry a `variant` or a knob `set`,
 so the user sees them live. Plain pills only for what can't be seen.
 
+When one question only makes sense once another is answered (an accent's
+placement depends on the palette), give it `after: "<that question's id>"`
+(CLI `--after palette`). It stays closed until that one is answered, then its
+pictures render with that answer and say so. Ask the deciding question first.
+
 The viewer shows a picture of each option it can render. `multi: true` allows
-several answers. Option ids default to the slugged label. Reusing an ask `id`
-replaces that ask. The viewer adds an "Other…" write-in and a note to every
-ask (both take attached images), so don't add your own; the option id `other`
-is reserved.
+several answers. Option ids default to the slugged label. Reusing a question
+`id` replaces that question. The viewer adds an "Other…" write-in and a note to
+every question (both take attached images), so don't add your own; the option
+id `other` is reserved.
+
+## Parts with fills
+
+A part with fills is one region with alternatives, in one html. Give each
+alternative the same `data-part` and its own `data-fill`:
+
+```html
+<section data-part="entry" data-part-label="Entry" data-fill="dots" data-fill-label="Typing dots">
+  …
+</section>
+<section data-part="entry" data-fill="skeleton">…</section>
+<section data-part="entry" data-fill="filling" data-fill-default>…</section>
+```
+
+The first fill is the default unless one carries `data-fill-default`. The
+server derives a select knob at the part's name and shows only the chosen
+fill, so you write no switching CSS; give each fill whatever display it
+needs. Draw anything inside a fill, including further parts with fills: one
+inside a fill is asked only while that fill is chosen, right after its
+parent's question.
+
+Publish returns the parts with fills it found (`fills`) and, for each one no
+question sets, a ready `suggestedFillAsks` entry: `scope: "part"`, one option
+per fill with `set: {"entry": "<fill>"}`. Send them with `ask`, relabelled if
+you like. On a pick the viewer outlines the fill on stage. `fills` in publish
+replaces or adds one fill without resending the page (topic `feedback`).
+
+Use fills when the alternatives differ in one region; use variants when the
+whole design differs. Both combine: each variant may have parts with fills.
 
-## The Look ask
+## The variant question
 
-When you publish variants, ask `scope: "mock"` with one option per variant, and
-ask it first. Questions appear in the order you ask them. This one is titled
-"Look" and unlocks Mix, which lets the user borrow a part from another look.
-Variants without a Look ask get a plain switcher in the frame header.
+When you publish variants, ask `scope: "mock"` with one option per variant,
+and ask it first. Questions appear in the order you ask them. Tune then
+offers, per part, to borrow that part from another variant. Variants without
+a variant question get a plain switcher in the frame header.
 
 A variant decides everything it differs on; don't re-ask it. Ask other axes as
 knob `set`s.
 
 ## When you forget to ask
 
-A publish that leaves a state with two or more open variants and no ask
+A publish that leaves a state with two or more open variants and no question
 binding them returns a nudge and a ready `suggestedAsk` (mock-wide when the
 variant names line up across states, else for that state), or your existing
-ask plus the new variants. Send it as is with `ask`, or write your own question
-with options bound to the variants. The CLI prints the `mockpit ask` command
-for you. Sending it stops the nudge and keeps the answered Look ask on the
-mock; the built-in one is gone once answered.
-
-Until an ask binds them, the viewer shows a built-in Look ask with a picture
-of each variant, so the user can still choose in one Send. Its answer
-reads like any other ask under the reserved id `variant` (per state:
-`variant:<state>`), and accepts and archives per state. Your own ask over
-those variants replaces it.
+question plus the new variants. Send it as is with `ask`, or write your own
+question with options bound to the variants. The CLI prints the `mockpit ask`
+command for you. Sending it stops the nudge and keeps your answered question
+on the mock; the built-in one is gone once answered.
+
+Until a question binds them, the viewer shows a built-in "Which variant?"
+with a picture of each variant, so the user can still choose in one Send. Its
+answer reads like any other under the reserved id `variant` (per state:
+`variant:<state>`), and puts in use and archives per state. Your own question
+over those variants replaces it.