mockpit 1.0.0 → 1.2.0

package/extensions/mockpit.js

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { basename, resolve } from "node:path";
 
@@ -127,8 +128,19 @@ function resolveProjectName(cwd) {
   );
 }
 
+// Names this client in the server's event log, with the version that would
+// show it running behind the server.
+const CLIENT = `pi/${(() => {
+  try {
+    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+  } catch {
+    return "unknown";
+  }
+})()}`;
+
 function authHeaders(extra = {}) {
   return {
+    "x-mockpit-client": CLIENT,
     ...(process.env.MOCKPIT_TOKEN ? { authorization: `Bearer ${process.env.MOCKPIT_TOKEN}` } : {}),
     ...extra,
   };
@@ -208,6 +220,7 @@ function feedbackLines(feedback) {
   const lines = [];
   for (const batch of feedback ?? []) {
     const prefix = batch.mock ? `${batch.mock}: ` : "";
+    if (batch.handoff) lines.push(`- ${prefix}${batch.handoff}`);
     const reply = batch.reply;
     if (reply) {
       for (const a of reply.asks ?? []) {
@@ -234,17 +247,19 @@ function feedbackLines(feedback) {
   return lines;
 }
 
-// What the user is doing right now, so the agent can say "take your time".
-// viewerOpen is workspace-wide, so it is said once rather than per mock.
+// What the user is doing right now, per mock, so the agent can say "take your time".
 function pendingLines(pending) {
-  const rows = [pending ?? []].flat();
-  const lines = rows
-    .filter((p) => p.draft)
-    .map(
-      (p) =>
-        `- ${p.mock}: the user is answering (${p.draft.answered} of ${p.draft.of} answered, ${p.draft.comments} comments)`,
+  const lines = [pending ?? []]
+    .flat()
+    .flatMap((p) =>
+      p.draft
+        ? [
+            `- ${p.mock}: the user is answering (${p.draft.answered} of ${p.draft.of} answered, ${p.draft.comments} comments)`,
+          ]
+        : p.viewerOpen
+          ? [`- ${p.mock}: open in the viewer`]
+          : [],
     );
-  if (lines.length === 0 && rows.some((p) => p.viewerOpen)) lines.push("- the viewer is open");
   return lines.length ? ["Pending:", ...lines] : [];
 }
 

package/guide/topics/asks.md

@@ -7,9 +7,12 @@ where to look and end your turn.
 
 ```sh
 mockpit ask --mock writer "Which look?" --option Quiet=quiet --option Dark=dark --id look
+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.
+
 ## Shape
 
 The same JSON goes to `--asks`, MCP `ask` and `POST /api/mocks/:id/asks`:
@@ -60,10 +63,14 @@ An option binds to one of:
 - 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.
+
 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, so don't add your own; the option id `other` is reserved.
+ask (both take attached images), so don't add your own; the option id `other`
+is reserved.
 
 ## The Look ask
 
@@ -72,16 +79,21 @@ 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.
 
+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
 binding them returns a nudge and a ready `suggestedAsk` (mock-wide when the
-variant names line up across states, else for that state). 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.
-
-Until an ask binds them, the viewer shows a built-in "Which one?" with a
-picture of each variant, so the user can still choose in one Send. Its answer
+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.

package/guide/topics/feedback.md

@@ -24,7 +24,8 @@ It returns at once:
             "ask": "trim",
             "text": "Trim above or below?",
             "chosen": [{ "id": "below", "label": "Below", "set": { "trim.position": "bottom" } }],
-            "note": "below on mobile only"
+            "note": "below on mobile only",
+            "noteImages": [{ "id": "k3Jf9xQ2aLw", "url": "http://localhost:8228/a/k3Jf9xQ2aLw" }]
           },
           {
             "ask": "lang",
@@ -35,6 +36,7 @@ It returns at once:
         "mix": { "body": "quiet" },
         "tuned": { "body.size": 19 },
         "comments": [{ "part": "title", "state": "Writing", "text": "bigger" }],
+        "reactions": ["👍 part \"title\" (variant dark, state Writing)"],
         "text": "close, go dark"
       },
       "comments": [],
@@ -53,8 +55,8 @@ It returns at once:
 ```
 
 `feedback` holds one batch per mock, in delivery order. `pending` is what the
-user is doing right now, per mock: `viewerOpen` says a browser has the
-workspace open, `draft` is their unsent progress (`null` when there is none).
+user is doing right now, per mock: `viewerOpen` says a browser has that
+mock on screen, `draft` is their unsent progress (`null` when there is none).
 An empty `feedback` with a draft means "still answering": tell the user to take
 their time, don't ask again. `mockpit read` returns `pending` too, without
 taking any feedback.
@@ -64,18 +66,26 @@ taking any feedback.
 1. `answers` and `asks` decide structure. A variant-bound answer has already
    accepted that variant and archived its siblings (`accepted`, `archived`).
    Stop iterating on the archived ones. The ask `variant` (per state
-   `variant:<state>`) is the viewer's built-in "Which one?", read like any
+   `variant:<state>`) is the viewer's built-in Look ask, read like any
    other. A `chosen` entry with `other: true` is
    the user's own answer (its `label`), not one of your options; it flips no
    variant and sets no knob. `note` qualifies the answer and may come with
-   nothing chosen.
+   nothing chosen. The user can attach images (screenshots, references) to
+   either: `images` on the `other` choice, `noteImages` on the ask, each
+   `{id, url}`; the text may then be `""`. Look at every one. Over MCP they
+   also arrive as image content in the same result; elsewhere fetch the `url`
+   (with your token, if the server has one) and open the file.
 2. `tuned` holds knob values. Write them back into the source as the new
    defaults. tunekit's skill (`skills/tunekit` in the tunekit package) covers
    applying copied values.
 3. `mix` maps a part to the variant it should come from. Compose that part from
-   the other look into the chosen one.
+   the other look into the chosen one. If `mix` conflicts with an answer, the
+   answer wins.
 4. `comments` are anchored on a part in a state (`part: null` means no part).
-   Address each one.
+   Address each one. `reactions` are one-tap verdicts, one line each:
+   👍 keep it, 👎 rework it, "more like this" go further that way. A reaction
+   without a part is about the whole variant; one may end with the user's
+   note in quotes. Reactions never also appear in `comments`.
 5. `decision` (`{kind: accept|revise|drop, state, variant}`) comes instead of
    answers when the mock has no asks and the user pressed Accept, Revise or
    Drop.

package/guide/topics/knobs.md

@@ -2,9 +2,9 @@
 
 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 knob with three or fewer discrete options (a
-toggle, a short select) gets a nudge in the publish response; keep it only if
-one render plus that control really shows the choice.
+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.
 
 ## Declaring
 

package/guide/topics/surfaces.md

@@ -90,11 +90,11 @@ bytes dedupe. An asset lives as long as something references it. The limit is
 
 Each thing you add lights up its part of the viewer.
 
-| 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 "Which one?" 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 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                      |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mockpit",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "A design-decision loop for terminal coding agents — agents publish mocks with states and variants, ask questions and expose knobs; you answer, tune and comment, then send one reply.",
   "keywords": [
     "agent-tools",
@@ -82,7 +82,7 @@
     "lint:fix": "oxlint . --fix",
     "changeset": "changeset",
     "changeset:status": "changeset status",
-    "release:version": "changeset version",
+    "release:version": "changeset version && npm install --package-lock-only --ignore-scripts",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.workers.json --noEmit && tsc -p tsconfig.viewer.json --noEmit",
     "clean:dist": "node scripts/clean-dist.ts",
     "build": "npm run clean:dist && tsc -p tsconfig.build.json && npm run build:viewer",

package/skills/mockpit/SKILL.md

@@ -19,8 +19,10 @@ The loop never waits for the user:
 2. `mockpit publish --mock <slug> --state "<user's words>" --variant <v> --html f.html`,
    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`. When a
-   publish result nudges, send its `suggestedAsk`.
+   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`. When a publish result nudges, send its
+   `suggestedAsk`.
 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.