mockpit 1.1.0 → 1.3.0

package/README.md

@@ -51,11 +51,14 @@ mockpit turns that into a design-decision loop:
    panel goes, which of two layouts. The question lives in the mock, not in
    chat; the agent tells you where to look and ends its turn. Options bound to
    a variant or to knob values render as pictures; hovering one previews it on
-   the stage, clicking picks it. After the look, **Mix** offers to borrow a part
-   from another look. Variants the agent forgot to ask about get a built-in
-   **Which one?**.
+   the stage, clicking picks it, and the part it changed is outlined. A
+   region the agent drew several ways (a slot: one `data-part`, a `data-fill`
+   per alternative) is asked about once; a slot inside a fill is asked only
+   while that fill is chosen. Variants the agent forgot to ask about get a
+   built-in **Which one?**.
 3. **Tune.** Parts the agent marked are selectable on the stage. Tune lists
-   them with the knobs it declared for each, plus a comment field. Presets
+   them with the knobs it declared for each, a **Borrow** line for a part
+   another look draws differently, plus a comment field. Presets
    save a set of tuned values in your browser.
 4. **Send.** Everything above is a draft (it survives a reload) until one
    **Send**. A mock with a single variant and no questions gets **Accept /
@@ -70,8 +73,12 @@ mockpit turns that into a design-decision loop:
 
 **Home** lists the project's mocks with a thumbnail, their states and how many
 questions are open, with "Answer next ›" to jump to the first one. Dark and
-light themes, toggled from the top bar. On a narrow screen the panel becomes a
-bottom sheet.
+light themes, toggled from the top bar. On a phone or an iPad in portrait the
+design is a canvas you pan and pinch, at each width the agent names (or one you
+pick: Phone 390, Tablet 744, Desktop 820, Wide 1280) side by side, and the
+questions float over it in a card you can snap to a corner, a side or the
+bottom, or tuck against an edge. On a desktop, Inspect opens the stage full
+screen to pan and pinch-zoom it.
 
 ## Quick start
 

package/bin/mockpit.js

@@ -37,7 +37,9 @@ the loop (never blocks on the user):
   1. mockpit init once per repo; read the brief (mockpit guide).
   2. mockpit publish once per variant; mark parts with data-part.
   3. A choice is several variants plus one ask that binds them: mockpit ask
-     with options bound to variants. One render plus a control: --knobs.
+     with options bound to variants. A variant decides everything it differs
+     on; don't re-ask it. Visual options carry a variant or knob set. One
+     render plus a control: --knobs.
   4. Tell the user in one line where to look, then end your turn. The question
      itself lives in the mock (ask), never in chat. The user answers in the
      browser at their own pace. Never poll.
@@ -60,11 +62,17 @@ verbs:
                         alone keeps a surface, a missing id removes it
       --parts <name=file|->  instead: replace just that data-part's element in
                         the latest version (repeatable; name#key targets one instance)
+      --fills <part#fill=file|->  instead: replace or add one fill of a slot in
+                        the latest version (repeatable)
       --title <t>       mock title
       --kind <k>        component|page (default component)
       --knobs <json|file>  knobs in tunekit usePane shape, keyed by path
       --from <N>        branch from version N
       --prompt <text>   what prompted this version
+      --note <text>     one line on what this variant is, shown beside it
+      --widths <list>   device widths to show it at, e.g. 390,1280
+      --flow <name> [--step <N>]  make this screen step N of a flow (0 takes
+                        it out); with no html it only places the screen
       --project <name>  project (default: git remote, else directory name)
       --kit <id>        opt the html surface into a kit (repeatable; see "mockpit kits")
       --md/--mermaid/--diff/--terminal/--data/--code/--image <file|->
@@ -72,7 +80,8 @@ verbs:
                         --data is a JSON tree)
   mockpit ask --mock <slug> "<question>" --option <label[=variant]> ...
                                           ask the user; bind options to variants
-      --option <l[=v]>  an option (repeatable); "=variant" binds it to a variant
+      --option <l[=v]>  an option (repeatable); "=variant" binds it to a variant,
+                        "=variant@3" to its version 3, "=knob:path=value" sets one knob
       --scope <s>       mock|state|part (default mock)
       --state <label>   the state a state-scoped ask is about
       --part <name>     the part a part-scoped ask is about
@@ -153,6 +162,7 @@ mockpit icons remove <set> [<set>...]
   publish: `mockpit publish --mock <slug> --html <file> [options]
 mockpit publish --mock <slug> --surfaces <json|file> [options]
 mockpit publish --mock <slug> --parts <name=file|-> ... [options]
+mockpit publish --mock <slug> --fills <part#fill=file|-> ... [options]
   Creates the mock, state or variant, or the next version of an existing one.
   --state <label>    state in the user's words (omit for a single-state mock)
   --variant <name>   variant label (default "default")
@@ -160,30 +170,48 @@ mockpit publish --mock <slug> --parts <name=file|-> ... [options]
                      a missing id removes it, order is the list order
   --parts <name=file|->   replace only the element carrying data-part="name"
                      (name#key for one instance) in the latest version; repeatable
+  --fills <part#fill=file|->  replace the element carrying data-part="part"
+                     data-fill="fill" in the latest version, or add it after
+                     that slot's other fills; the marks are added if missing
   --title <t>        mock title
   --kind <k>         component|page (default component)
   --knobs <json|file>  knobs in tunekit usePane shape
   --from <N>         branch from version N
+  --fork <v[@N]>     start this new variant from sibling v (its version N, else
+                     its latest); alone it copies v, with --parts/--fills it
+                     edits the copy
   --prompt <text>    what prompted this version
+  --note <text>      one line on what this variant is, shown beside it (never
+                     inside the design)
+  --widths <list>    device widths the mock is judged at, side by side, e.g.
+                     390,1280 (the ones the user ships to)
+  --flow <name>      a flow this screen is a step of: the screens the user moves
+                     between, in order, across mocks; without html it only
+                     places the existing screen
+  --step <N>         its 1-based place in the flow (moves it if it is there);
+                     0 takes it out; omitted, it joins at the end
   --project <name>   project (default: git remote, else directory name)
   --md/--mermaid/--diff/--terminal/--data/--code/--image <file>  more surfaces
   --json / --quiet
   Prints the parts found per state, parts that vanished or were renamed,
   nudges, a ready-to-run "mockpit ask" when variants have no ask, and feedback.`,
   ask: `mockpit ask --mock <slug> "<question>" --option <label[=variant]> ... [--scope mock|state|part]
-  [--state s] [--part p] [--multi] [--id id]
+  [--state s] [--part p] [--multi] [--id id] [--after <ask id>]
   mockpit ask --mock <slug> --asks <json|file>
   Ask the user. A choice is several variants plus one ask that binds them.
   Then tell the user where to look and end your turn.`,
-  read: `mockpit read [slug] [--project <name>] [--body] [--history]
-  No slug: one line per mock (states, variants, open asks) plus pending, what
+  read: `mockpit read [slug] [--project <name>] [--body] [--history] [--tree]
+  No slug: one line per mock (states, variants, open asks), one per flow, plus pending, what
   the user is doing now. A slug: the mock's states, variants, asks with
-  answers, parts, knobs and last tuned values, plus its pending, as JSON.
-  --body includes surfaces, --history version rows. Never consumes feedback.`,
+  answers, parts, knobs and settled values, plus its pending, as JSON.
+  --body includes surfaces, --history version rows. --tree (no slug): the
+  project as a tree, each mock's variants with status and forkedFrom, and the
+  mocks it uses and is used in, as JSON. Never consumes feedback.`,
   feedback: `mockpit feedback [--project <name>] [--session <id>]
   Returns at once with {feedback, pending} as JSON: one batch per mock the user
   sent since you last heard ({mock, reply: {asks, mix, tuned, comments},
-  comments, accepted, archived}), delivered once across feedback, watch and
+  comments, accepted, archived, dropped}, or {mock, resolved: true, dismissed} when the
+  user closed it unanswered), delivered once across feedback, watch and
   every write; and pending ({mock, viewerOpen, draft}) so you can tell the
   user "take your time" or "2 of 3 answered". Run it when the user says they
   answered.`,
@@ -200,7 +228,8 @@ mockpit publish --mock <slug> --parts <name=file|-> ... [options]
   Claude Code, arm it under Monitor after asking, then end the turn).
   Delivery is shared with feedback and every write: each Send arrives once.`,
   export: `mockpit export --mock <slug> [--state s] [--variant v] [--out <dir>]
-  Write index.html + history.json per state to .mockpit/accepted/<mock>/<state>/.`,
+  Write index.html + history.json per state to .mockpit/accepted/<mock>/<state>/;
+  with slots, index.html is the chosen screen, plus source.html and decisions.json.`,
   upload: `mockpit upload <file> [--kind image|file] [--session <id>]
   Upload an asset; prints its id and URL. Use the id as an image surface's assetId.`,
   guide: `mockpit guide [--topic <id>] [--project <name>]
@@ -807,6 +836,7 @@ function printPublished(result, flags) {
     console.log(`parts${state ? ` (${state})` : ""}: ${parts.map((p) => p.name).join(", ")}`);
   }
   if (result.applied?.length) console.log(`applied: ${result.applied.join(", ")}`);
+  if (result.flow) console.log(flowLine(result.flow));
   const changes = result.partChanges;
   if (changes?.renamed?.length) {
     console.log(`renamed: ${changes.renamed.map((r) => `${r.from} → ${r.to}`).join(", ")}`);
@@ -819,6 +849,11 @@ function printPublished(result, flags) {
   printFeedback(result.feedback);
 }
 
+function flowLine(flow) {
+  const steps = flow.steps.map((x) => (x.state === null ? x.mock : `${x.mock}/${x.state}`));
+  return `flow ${flow.name}: ${steps.length ? steps.join(" → ") : "empty, removed"}`;
+}
+
 // Only speak when there IS feedback: an empty line per write is pure token
 // cost, and the cursor guarantees anything pending arrives on some write.
 function printFeedback(feedback) {
@@ -849,9 +884,15 @@ function parsePublishFlags() {
       html: { type: "string" },
       surfaces: { type: "string" },
       parts: { type: "string", multiple: true },
+      fills: { type: "string", multiple: true },
       knobs: { type: "string" },
       from: { type: "string" },
+      fork: { type: "string" },
       prompt: { type: "string" },
+      note: { type: "string" },
+      widths: { type: "string" },
+      flow: { type: "string" },
+      step: { type: "string" },
       kit: { type: "string", multiple: true },
       layout: { type: "string" },
       md: { type: "string", multiple: true },
@@ -870,18 +911,27 @@ function parsePublishFlags() {
 
 // `--parts name=file` (repeatable; `name#key` targets one instance): the new
 // outer html of one part, spliced server-side into the latest version.
-function readPartFlags(values, slug) {
+// `--fills part#fill=file` is the same for one alternative of a slot.
+function readPartFlags(values, slug, flag = "parts") {
   if (!values?.length) return undefined;
-  const example = `mockpit publish --mock ${slug} --parts body=body.html`;
+  const example =
+    flag === "parts"
+      ? `mockpit publish --mock ${slug} --parts body=body.html`
+      : `mockpit publish --mock ${slug} --fills entry#skeleton=skeleton.html`;
   const parts = {};
   let stdin = false;
   for (const raw of values) {
     const at = raw.indexOf("=");
-    if (at <= 0 || at === raw.length - 1) die(`--parts needs name=file (got "${raw}")`, example);
+    if (at <= 0 || at === raw.length - 1) {
+      die(
+        `--${flag} needs ${flag === "parts" ? "name" : "part#fill"}=file (got "${raw}")`,
+        example,
+      );
+    }
     const name = raw.slice(0, at);
     const file = raw.slice(at + 1);
     if (file === "-") {
-      if (stdin) die("only one --parts can read stdin", example);
+      if (stdin) die(`only one --${flag} can read stdin`, example);
       stdin = true;
     } else if (!existsSync(file)) die(`cannot read ${file}`, `ls ${file}`);
     parts[name] = readContent(file);
@@ -897,6 +947,13 @@ async function publishMock() {
   if (from !== undefined && !Number.isInteger(from)) {
     die(`--from must be a version number (got "${flags.from}")`, `mockpit read ${slug} --history`);
   }
+  const step = flags.step === undefined ? undefined : Number(flags.step);
+  if (step !== undefined && !(Number.isInteger(step) && step >= 0)) {
+    die(
+      `--step must be a place in the flow, 1 or more, or 0 (got "${flags.step}")`,
+      `mockpit read`,
+    );
+  }
   const file = flags.html ?? positionals[0];
   const composed =
     file !== undefined || tokens.some((t) => t.kind === "option" && SURFACE_FLAGS.has(t.name));
@@ -904,16 +961,18 @@ async function publishMock() {
     composed && "--html",
     flags.surfaces !== undefined && "--surfaces",
     flags.parts?.length && "--parts",
+    flags.fills?.length && "--fills",
   ].filter(Boolean);
   if (given.length > 1) {
     die(
-      `pass one of --html, --surfaces or --parts, not ${given.join(" and ")}`,
+      `pass one of --html, --surfaces, --parts or --fills, not ${given.join(" and ")}`,
       `mockpit publish --help`,
     );
   }
   // Checked before the session exists so a typo'd path leaves nothing behind on the server.
   if (file && file !== "-" && !existsSync(file)) die(`cannot read ${file}`, `ls ${file}`);
   const parts = readPartFlags(flags.parts, slug);
+  const fills = readPartFlags(flags.fills, slug, "fills");
   let surfaces =
     flags.surfaces === undefined ? undefined : readJsonFlag("surfaces", flags.surfaces);
   if (surfaces !== undefined && !Array.isArray(surfaces)) {
@@ -933,7 +992,7 @@ async function publishMock() {
     }
     surfaces.push(...(await surfacesFromFlags(flags, tokens, { session, layout: flags.layout })));
   }
-  if (!surfaces && !parts)
+  if (!surfaces && !parts && !fills && !flags.fork && flags.flow === undefined)
     die(`no html for ${slug}`, `mockpit publish --mock ${slug} --html <file>`);
   const body = {
     session,
@@ -945,9 +1004,20 @@ async function publishMock() {
     kind: flags.kind,
     ...(flags.knobs !== undefined && { knobs: readJsonFlag("knobs", flags.knobs) }),
     ...(from !== undefined && { from }),
+    ...(flags.fork !== undefined && { fork: flags.fork }),
     prompt: flags.prompt,
+    note: flags.note,
+    ...(flags.widths !== undefined && {
+      widths: flags.widths
+        .split(",")
+        .filter((w) => w.trim())
+        .map((w) => Number(w)),
+    }),
+    ...(flags.flow !== undefined && { flow: flags.flow }),
+    ...(step !== undefined && { step }),
     ...(surfaces && { surfaces }),
     ...(parts && { parts }),
+    ...(fills && { fills }),
   };
   const result = await api(
     "/api/mocks",
@@ -958,11 +1028,31 @@ async function publishMock() {
   return result;
 }
 
-// "Quiet" is an unbound option; "Quiet=quiet" binds it to the quiet variant.
+// "Quiet" is an unbound option; "Quiet=quiet" binds it to the quiet variant;
+// "Before=quiet@2" to its version 2 ("=@2" names the state's only variant);
+// "Above=knob:trim.position=top" sets one knob. The value is JSON when it
+// parses (17, true), else a string, so slider and toggle values keep their type.
 function parseOption(raw) {
+  const knob = raw.indexOf("=knob:");
+  if (knob > 0) {
+    const pair = raw.slice(knob + "=knob:".length);
+    const eq = pair.indexOf("=");
+    if (eq <= 0)
+      die(`option "${raw}" needs knob:<path>=<value>`, "--option Above=knob:trim.position=top");
+    const text = pair.slice(eq + 1);
+    let value = text;
+    try {
+      value = JSON.parse(text);
+    } catch {}
+    return { label: raw.slice(0, knob), set: { [pair.slice(0, eq)]: value } };
+  }
   const at = raw.lastIndexOf("=");
   if (at <= 0) return { label: raw };
-  return { label: raw.slice(0, at), variant: raw.slice(at + 1) };
+  const label = raw.slice(0, at);
+  const bound = raw.slice(at + 1);
+  const pin = /^(.*)@(\d+)$/.exec(bound);
+  if (!pin) return { label, variant: bound };
+  return { label, ...(pin[1] ? { variant: pin[1] } : {}), version: Number(pin[2]) };
 }
 
 // One feedback batch, one line — for a background monitor's notifications.
@@ -986,6 +1076,13 @@ function printRun(r) {
 function watchLines(batch) {
   const lines = [];
   const name = batch.mock ?? "a mock";
+  if (batch.handoff) lines.push(`mockpit handoff on ${name}: ${batch.handoff}`);
+  if (batch.resolved) {
+    const n = batch.dismissed?.length ?? 0;
+    lines.push(
+      `mockpit resolved ${name}: ${n ? `${n} question${n === 1 ? "" : "s"} dismissed unanswered (${batch.dismissed.map((d) => d.text || d.ask).join("; ")}); don't ask again` : "closed by the user"}`,
+    );
+  }
   if (batch.reply) {
     const r = batch.reply;
     const bits = [
@@ -1004,6 +1101,7 @@ function watchLines(batch) {
             .join(", ")}`
         : "",
       r.comments?.length ? `${r.comments.length} comment${r.comments.length === 1 ? "" : "s"}` : "",
+      r.reactions?.length ? r.reactions.join(", ") : "",
       r.decision ? r.decision.kind : "",
       r.text ?? "",
     ].filter(Boolean);
@@ -1320,6 +1418,7 @@ const commands = {
         part: { type: "string" },
         multi: { type: "boolean" },
         id: { type: "string" },
+        after: { type: "string" },
         asks: { type: "string" },
       },
     });
@@ -1357,6 +1456,7 @@ const commands = {
           ...(flags.state && { state: flags.state }),
           ...(flags.part && { part: flags.part }),
           ...(flags.multi && { multi: true }),
+          ...(flags.after && { after: flags.after }),
         },
       ];
     }
@@ -1380,6 +1480,7 @@ const commands = {
         `asked on ${result.mock}: ${ask.text} [${ask.options.map((o) => o.label).join(" | ")}]`,
       );
     }
+    for (const nudge of result.nudges ?? []) console.log(`nudge: ${nudge}`);
     console.log(`tell the user to look at ${result.url}, then end your turn`);
     printFeedback(result.feedback);
   },
@@ -1393,10 +1494,20 @@ const commands = {
         project: { type: "string" },
         body: { type: "boolean" },
         history: { type: "boolean" },
+        tree: { type: "boolean" },
       },
     });
     const project = resolveProject(flags).name;
     if (positionals.length > 1) die("read takes one mock slug", "mockpit read writer");
+    if (flags.tree) {
+      return out(
+        await api(
+          `/api/projects/${encodeURIComponent(project)}/tree`,
+          {},
+          { report: "die", fix: `mockpit read --project ${project}` },
+        ),
+      );
+    }
     if (positionals.length === 1) {
       const slug = slugify(positionals[0]);
       return out(
@@ -1424,9 +1535,10 @@ const commands = {
     for (const m of mocks) {
       const states = m.states.length ? m.states.join(" / ") : "single state";
       console.log(
-        `  ${m.slug} · ${m.kind} · ${states} · ${m.variants} variant${m.variants === 1 ? "" : "s"}${m.open ? ` · ${m.open} open` : ""}`,
+        `  ${m.slug} · ${m.kind} · ${states} · ${m.variants} variant${m.variants === 1 ? "" : "s"}${m.resolvedAt ? " · resolved" : m.open ? ` · ${m.open} open` : ""}`,
       );
     }
+    for (const flow of list.flows ?? []) console.log(`  ${flowLine(flow)}`);
     for (const line of pendingLines(list.pending)) console.log(line);
   },
   async export() {
@@ -1452,6 +1564,15 @@ const commands = {
       const dir = join(root, entry.state === null ? "default" : slugify(entry.state));
       mkdirSync(dir, { recursive: true });
       writeFileSync(join(dir, "index.html"), entry.html ?? "");
+      // The screen with every fill, when index.html is the composed choice.
+      if (entry.source) writeFileSync(join(dir, "source.html"), entry.source);
+      const decided = data.decisions?.states?.[entry.state ?? ""];
+      if (decided) {
+        writeFileSync(
+          join(dir, "decisions.json"),
+          JSON.stringify({ ...decided, knobs: data.decisions.knobs }, null, 2) + "\n",
+        );
+      }
       writeFileSync(
         join(dir, "history.json"),
         JSON.stringify(

package/dist/mcp/server.js

@@ -6,7 +6,7 @@ import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { MCP_INSTRUCTIONS, MCP_SERVER_INFO, runToolResult, STDIO_MCP_CATALOG, STDIO_MCP_TOOLS, STDIO_RUN_CATALOG, STDIO_RUN_TOOLS, toolResult, } from "../server/mcpSpec.js";
+import { MCP_INSTRUCTIONS, MCP_SERVER_INFO, runToolResult, STDIO_MCP_CATALOG, STDIO_MCP_TOOLS, STDIO_RUN_CATALOG, STDIO_RUN_TOOLS, toolResult, withFeedbackImages, } from "../server/mcpSpec.js";
 import { RUN_INSTRUCTIONS } from "../server/runApi.js";
 // Point at a deployed instance later by setting MOCKPIT_URL.
 const API = process.env.MOCKPIT_URL ?? "http://localhost:8228";
@@ -156,6 +156,7 @@ const handlers = {
             ...args,
             html,
             parts: readPartFiles(args.parts),
+            fills: readPartFiles(args.fills),
             session,
             agent: AGENT,
             project: resolveProject(args.project),
@@ -169,13 +170,15 @@ const handlers = {
             project: resolveProject(args.project),
         });
     },
-    read: (args) => json(args.mock === undefined
-        ? `/api/mocks${query({ project: resolveProject(args.project) })}`
-        : `/api/mocks/${enc(args.mock)}${query({
-            project: resolveProject(args.project),
-            body: args.body,
-            history: args.history,
-        })}`),
+    read: (args) => json(args.mock === undefined && args.tree === true
+        ? `/api/projects/${enc(resolveProject(args.project))}/tree`
+        : args.mock === undefined
+            ? `/api/mocks${query({ project: resolveProject(args.project) })}`
+            : `/api/mocks/${enc(args.mock)}${query({
+                project: resolveProject(args.project),
+                body: args.body,
+                history: args.history,
+            })}`),
     // Never waits: the server reads from the session's cursor, shared with
     // piggyback and `mockpit watch`, so each Send is delivered exactly once.
     async feedback(args) {
@@ -230,18 +233,35 @@ async function run(args) {
         body: JSON.stringify({ code, session, project: resolveProject(args.project), agent: AGENT }),
     });
 }
+async function loadImage(ref) {
+    const res = await fetch(`${API}/a/${encodeURIComponent(ref.id)}`, {
+        headers: TOKEN ? { authorization: `Bearer ${TOKEN}` } : {},
+    });
+    if (!res.ok)
+        return null;
+    return {
+        data: new Uint8Array(await res.arrayBuffer()),
+        mimeType: res.headers.get("content-type") ?? "image/png",
+    };
+}
 const server = new McpServer(MCP_SERVER_INFO, {
     instructions: CODE_MODE ? RUN_INSTRUCTIONS : MCP_INSTRUCTIONS,
 });
 if (CODE_MODE) {
     const [{ name, ...config }] = STDIO_RUN_TOOLS;
-    server.registerTool(name, config, async (args) => runToolResult(await run(args)));
+    server.registerTool(name, config, async (args) => {
+        const envelope = await run(args);
+        return withFeedbackImages(runToolResult(envelope), envelope, loadImage);
+    });
 }
 else {
     for (const tool of STDIO_MCP_TOOLS) {
         const handler = handlers[tool.name];
         const { name, ...config } = tool;
-        server.registerTool(name, config, async (args) => toolResult(name, await handler(args)));
+        server.registerTool(name, config, async (args) => {
+            const value = await handler(args);
+            return withFeedbackImages(toolResult(name, value), value, loadImage);
+        });
     }
 }
 // Replaces the SDK's own listing (registered above), so stdio advertises the