mockpit 1.1.0 → 1.2.0

package/dist/server/runApi.d.ts

@@ -1,4 +1,4 @@
-export declare const RUN_API = "// The body of an async function, in plain JavaScript (no TypeScript syntax).\n// `await mockpit.*`, `return` a JSON value, print() adds an output line.\n// No network, timers, imports or process. Session, project and agent are fixed\n// for the run; pass the returned session to the next run.\ntype Ref = { mock: string; state?: string; variant?: string };\ntype Knobs = Record<string, unknown>; // path \u2192 [default,min,max,step] | boolean | {type:\"select\",options} | \"#hex\"\ntype Surface =\n  | { kind: \"html\"; html: string; kits?: string[] }\n  | { kind: \"markdown\"; markdown: string }\n  | { kind: \"diff\"; patch?: string; files?: { filename: string; before: string; after: string }[]; layout?: \"unified\" | \"split\" }\n  | { kind: \"image\"; assetId: string; alt?: string; caption?: string }\n  | { kind: \"terminal\"; text: string; cols?: number; title?: string }\n  | { kind: \"mermaid\"; mermaid: string }\n  | { kind: \"json\"; data: unknown; title?: string }\n  | { kind: \"code\"; code: string; language?: string; lineStart?: number };\ntype Ask = {\n  id?: string; text: string; scope?: \"mock\" | \"state\" | \"part\"; state?: string; part?: string; multi?: boolean;\n  options: { id?: string; label: string; variant?: string; set?: Knobs }[];\n};\ntype Written = {\n  post: { state: string | null; variant: string; version: number }; url: string;\n  parts: { state: string | null; parts: { name: string }[] }[];\n  partChanges?: { vanished: string[]; renamed: { from: string; to: string }[] };\n  nudges?: string[]; suggestedAsk?: Ask; // send it with ask when nudged\n};\ntype Feedback = {\n  mock: string | null;\n  reply: null | { asks: { ask: string; chosen: { id: string; label: string; other?: true }[]; note?: string }[]; mix: Knobs; tuned: Knobs; comments: { part: string | null; text: string }[] };\n  comments: { text: string; state: string | null; variant: string | null }[];\n  accepted: { state: string | null; variant: string }[]; archived: { state: string | null; variant: string }[];\n};\ntype Pending = { mock: string; viewerOpen: boolean; draft: null | { answered: number; of: number; comments: number; touchedAt: string } };\ndeclare const mockpit: {\n  guide(topic?: \"knobs\" | \"asks\" | \"surfaces\" | \"html\" | \"feedback\" | \"http\" | \"scripts\"): Promise<string>;\n  /** No mock: every mock plus pending. With one: its states, variants, asks, parts, knobs. */\n  read(mock?: string, opts?: { body?: boolean; history?: boolean }): Promise<unknown>;\n  /** Creates or versions (mock, state, variant). One of: html; surfaces, the full ordered list\n   * ({id} alone keeps that surface, a missing id is removed); parts {\"name\"|\"name#key\": outer html}. */\n  publish(v: Ref & { title?: string; kind?: \"component\" | \"page\"; html?: string; surfaces?: (Surface | { id: string })[]; parts?: Record<string, string>; knobs?: Knobs; variantKnobs?: Knobs; from?: number }): Promise<Written>;\n  ask(mock: string, asks: Ask[]): Promise<{ asks: { id: string; text: string }[]; url: string }>;\n  /** Never waits: what the user sent since you last heard, and what they are doing now. */\n  feedback(): Promise<{ feedback: Feedback[]; pending: Pending[] }>;\n  say(v: Ref, message: string): Promise<void>;\n  export(v: Ref): Promise<{ states: { state: string | null; variant: string; version: number; html: string }[]; reply: unknown }>;\n  /** data: base64 bytes. Use id as an image surface's assetId. */\n  upload(data: string, opts: { contentType: string; filename?: string; kind?: \"image\" | \"file\" }): Promise<{ id: string; url: string }>;\n};\ndeclare function print(...values: unknown[]): void;";
+export declare const RUN_API = "// The body of an async function, in plain JavaScript (no TypeScript syntax).\n// `await mockpit.*`, `return` a JSON value, print() adds an output line.\n// No network, timers, imports or process. Session, project and agent are fixed\n// for the run; pass the returned session to the next run.\ntype Ref = { mock: string; state?: string; variant?: string };\ntype Knobs = Record<string, unknown>; // path \u2192 [default,min,max,step] | boolean | {type:\"select\",options} | \"#hex\"\ntype Surface =\n  | { kind: \"html\"; html: string; kits?: string[] }\n  | { kind: \"markdown\"; markdown: string }\n  | { kind: \"diff\"; patch?: string; files?: { filename: string; before: string; after: string }[]; layout?: \"unified\" | \"split\" }\n  | { kind: \"image\"; assetId: string; alt?: string; caption?: string }\n  | { kind: \"terminal\"; text: string; cols?: number; title?: string }\n  | { kind: \"mermaid\"; mermaid: string }\n  | { kind: \"json\"; data: unknown; title?: string }\n  | { kind: \"code\"; code: string; language?: string; lineStart?: number };\ntype Ask = {\n  id?: string; text: string; scope?: \"mock\" | \"state\" | \"part\"; state?: string; part?: string; multi?: boolean;\n  options: { id?: string; label: string; variant?: string; set?: Knobs }[];\n};\ntype Written = {\n  post: { state: string | null; variant: string; version: number }; url: string;\n  parts: { state: string | null; parts: { name: string }[] }[];\n  partChanges?: { vanished: string[]; renamed: { from: string; to: string }[] };\n  nudges?: string[]; suggestedAsk?: Ask; // send it with ask when nudged\n};\ntype Feedback = {\n  mock: string | null;\n  reply: null | { asks: { ask: string; chosen: { id: string; label: string; other?: true }[]; note?: string }[]; mix: Knobs; tuned: Knobs; comments: { part: string | null; text: string }[] };\n  comments: { text: string; state: string | null; variant: string | null }[];\n  accepted: { state: string | null; variant: string }[]; archived: { state: string | null; variant: string }[];\n};\ntype Pending = { mock: string; viewerOpen: boolean; draft: null | { answered: number; of: number; comments: number; touchedAt: string } };\ndeclare const mockpit: {\n  guide(topic?: \"knobs\" | \"asks\" | \"surfaces\" | \"html\" | \"feedback\" | \"http\" | \"scripts\"): Promise<string>;\n  /** No mock: every mock plus pending. With one: its states, variants, asks, parts, knobs. */\n  read(mock?: string, opts?: { body?: boolean; history?: boolean }): Promise<unknown>;\n  /** Creates or versions (mock, state, variant). One of: html; surfaces, the full ordered list\n   * ({id} alone keeps that surface, a missing id is removed); parts {\"name\"|\"name#key\": outer html}. */\n  publish(v: Ref & { title?: string; kind?: \"component\" | \"page\"; html?: string; surfaces?: (Surface | { id: string })[]; parts?: Record<string, string>; knobs?: Knobs; variantKnobs?: Knobs; from?: number }): Promise<Written>;\n  ask(mock: string, asks: Ask[]): Promise<{ asks: { id: string; text: string }[]; url: string; nudges?: string[] }>;\n  /** Never waits: what the user sent since you last heard, and what they are doing now. */\n  feedback(): Promise<{ feedback: Feedback[]; pending: Pending[] }>;\n  say(v: Ref, message: string): Promise<void>;\n  export(v: Ref): Promise<{ states: { state: string | null; variant: string; version: number; html: string }[]; reply: unknown }>;\n  /** data: base64 bytes. Use id as an image surface's assetId. */\n  upload(data: string, opts: { contentType: string; filename?: string; kind?: \"image\" | \"file\" }): Promise<{ id: string; url: string }>;\n};\ndeclare function print(...values: unknown[]): void;";
 export declare const RUN_FUNCTIONS: readonly ["guide", "read", "publish", "ask", "feedback", "say", "export", "upload"];
 export type RunFunction = (typeof RUN_FUNCTIONS)[number];
 export declare const RUN_EXAMPLE = "const html = (tone) => `<section data-part=\"hero\" class=\"${tone}\"><h1>Writer</h1></section>`;\nawait mockpit.publish({ mock: \"writer\", variant: \"calm\", html: html(\"calm\") });\nawait mockpit.publish({ mock: \"writer\", variant: \"bold\", html: html(\"bold\") });\nconst { url } = await mockpit.ask(\"writer\", [{ id: \"look\", text: \"Which look?\",\n  options: [{ label: \"Calm\", variant: \"calm\" }, { label: \"Bold\", variant: \"bold\" }] }]);\n// Tell the user where to look and end the turn; a later run reads mockpit.feedback().\nreturn url;";

package/dist/server/runApi.js

@@ -43,7 +43,7 @@ declare const mockpit: {
   /** Creates or versions (mock, state, variant). One of: html; surfaces, the full ordered list
    * ({id} alone keeps that surface, a missing id is removed); parts {"name"|"name#key": outer html}. */
   publish(v: Ref & { title?: string; kind?: "component" | "page"; html?: string; surfaces?: (Surface | { id: string })[]; parts?: Record<string, string>; knobs?: Knobs; variantKnobs?: Knobs; from?: number }): Promise<Written>;
-  ask(mock: string, asks: Ask[]): Promise<{ asks: { id: string; text: string }[]; url: string }>;
+  ask(mock: string, asks: Ask[]): Promise<{ asks: { id: string; text: string }[]; url: string; nudges?: string[] }>;
   /** Never waits: what the user sent since you last heard, and what they are doing now. */
   feedback(): Promise<{ feedback: Feedback[]; pending: Pending[] }>;
   say(v: Ref, message: string): Promise<void>;

package/dist/server/sqlStore.d.ts

@@ -26,7 +26,7 @@ export declare class SqlStore implements Store {
     private rowToPost;
     private rowToAsset;
     private rowToComment;
-    listSessions(): Promise<Session[]>;
+    listSessions(project?: string): Promise<Session[]>;
     getSession(id: string): Promise<Session | null>;
     getSessionByKey(key: string): Promise<Session | null>;
     createSession(input: CreateSessionInput): Promise<Session>;
@@ -34,6 +34,8 @@ export declare class SqlStore implements Store {
     removeSession(id: string): Promise<boolean>;
     private touch;
     markAgentSeen(sessionId: string, seq: number): Promise<void>;
+    touchAgent(sessionId: string): Promise<void>;
+    handOff(sessionId: string, seen: Pick<Session, "agentSeq" | "agentActiveAt">, toSeq: number): Promise<boolean>;
     getSetting(key: string): Promise<string | null>;
     setSetting(key: string, value: string): Promise<void>;
     listProjects(): Promise<import("./types.ts").ProjectSummary[]>;

package/dist/server/sqlStore.js

@@ -1,4 +1,4 @@
-import { collectAssetIds, DEFAULT_PROJECT, DEFAULT_VARIANT, hashAssetId, HISTORY_LIMIT, htmlSurface, MAX_WORKSPACE_ASSET_BYTES, newId, normalizeSurfaceIds, projectFromCwd, reservedAgent, selectEvictions, slugify, stripNul, summarizeProjects, } from "./types.js";
+import { collectAssetIds, collectAttachedIds, DEFAULT_PROJECT, DEFAULT_VARIANT, hashAssetId, HISTORY_LIMIT, htmlSurface, MAX_WORKSPACE_ASSET_BYTES, newId, normalizeSurfaceIds, projectFromCwd, reservedAgent, selectEvictions, slugify, stripNul, summarizeProjects, } from "./types.js";
 function parseJson(raw, fallback) {
     if (typeof raw !== "string" || !raw)
         return fallback;
@@ -65,7 +65,7 @@ export class SqlStore {
       CREATE TABLE IF NOT EXISTS sessions (
         id TEXT PRIMARY KEY, agent TEXT NOT NULL, title TEXT, cwd TEXT,
         createdAt TEXT NOT NULL, lastActiveAt TEXT NOT NULL,
-        agentSeq INTEGER NOT NULL DEFAULT 0, project TEXT, key TEXT
+        agentSeq INTEGER NOT NULL DEFAULT 0, project TEXT, key TEXT, agentActiveAt TEXT
       );
       CREATE TABLE IF NOT EXISTS mocks (
         id TEXT PRIMARY KEY, project TEXT NOT NULL, slug TEXT NOT NULL, title TEXT NOT NULL,
@@ -100,6 +100,7 @@ export class SqlStore {
             agentSeq: "INTEGER NOT NULL DEFAULT 0",
             project: "TEXT",
             key: "TEXT",
+            agentActiveAt: "TEXT",
         });
         if (legacy)
             this.migrateLegacy();
@@ -381,6 +382,8 @@ export class SqlStore {
             lastActiveAt: r.lastActiveAt,
             agentSeq: r.agentSeq ?? 0,
             project: r.project ?? null,
+            agentActiveAt: r.agentActiveAt ?? null,
+            keyed: r.key != null,
         };
     }
     rowToMock(r) {
@@ -458,11 +461,13 @@ export class SqlStore {
         };
     }
     // --- sessions ---
-    async listSessions() {
-        return this.sql
-            .exec("SELECT * FROM sessions ORDER BY lastActiveAt DESC")
-            .toArray()
-            .map((r) => this.rowToSession(r));
+    async listSessions(project) {
+        const rows = project === undefined
+            ? this.sql.exec("SELECT * FROM sessions ORDER BY lastActiveAt DESC").toArray()
+            : this.sql
+                .exec("SELECT * FROM sessions WHERE project = ? ORDER BY lastActiveAt DESC", project)
+                .toArray();
+        return rows.map((r) => this.rowToSession(r));
     }
     async getSession(id) {
         const rows = this.sql.exec("SELECT * FROM sessions WHERE id = ?", id).toArray();
@@ -485,8 +490,10 @@ export class SqlStore {
             lastActiveAt: now,
             agentSeq: 0,
             project: stripNul(input.project)?.trim() || projectFromCwd(stripNul(input.cwd ?? null)) || null,
+            agentActiveAt: now,
+            keyed: !!stripNul(input.key)?.trim(),
         };
-        this.sql.exec("INSERT INTO sessions (id, agent, title, cwd, createdAt, lastActiveAt, agentSeq, project, key) VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?)", session.id, session.agent, session.title, session.cwd, session.createdAt, session.lastActiveAt, session.project, stripNul(input.key)?.trim() || null);
+        this.sql.exec("INSERT INTO sessions (id, agent, title, cwd, createdAt, lastActiveAt, agentSeq, project, key, agentActiveAt) VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?)", session.id, session.agent, session.title, session.cwd, session.createdAt, session.lastActiveAt, session.project, stripNul(input.key)?.trim() || null, session.agentActiveAt);
         return session;
     }
     async renameSession(id, title) {
@@ -528,6 +535,14 @@ export class SqlStore {
     async markAgentSeen(sessionId, seq) {
         this.sql.exec("UPDATE sessions SET agentSeq = ? WHERE id = ? AND agentSeq < ?", seq, sessionId, seq);
     }
+    async touchAgent(sessionId) {
+        this.sql.exec("UPDATE sessions SET agentActiveAt = ? WHERE id = ?", new Date().toISOString(), sessionId);
+    }
+    async handOff(sessionId, seen, toSeq) {
+        return (this.sql
+            .exec("UPDATE sessions SET agentSeq = ? WHERE id = ? AND agentSeq = ? AND agentActiveAt IS ? AND agentSeq < ? RETURNING id", toSeq, sessionId, seen.agentSeq, seen.agentActiveAt, toSeq)
+            .toArray().length > 0);
+    }
     // --- settings ---
     async getSetting(key) {
         return this.settingSync(key);
@@ -593,6 +608,8 @@ export class SqlStore {
             updatedAt: new Date().toISOString(),
         };
         this.sql.exec("UPDATE mocks SET title = ?, kind = ?, states = ?, asks = ?, knobs = ?, sessionId = ?, updatedAt = ? WHERE id = ?", next.title, next.kind, JSON.stringify(next.states), JSON.stringify(next.asks), JSON.stringify(next.knobs), next.sessionId, next.updatedAt, id);
+        if (patch.asks !== undefined)
+            this.invalidateAssetRefs();
         return next;
     }
     async removeMock(id) {
@@ -612,6 +629,7 @@ export class SqlStore {
         if (!mock)
             return null;
         this.sql.exec("UPDATE mocks SET draft = ? WHERE id = ?", draft ? JSON.stringify(draft) : null, mockId);
+        this.invalidateAssetRefs();
         return { ...mock, draft };
     }
     touchMock(mockId, at) {
@@ -826,6 +844,8 @@ export class SqlStore {
             return null;
         const comment = this.rowToComment(rows[0]);
         this.sql.exec("DELETE FROM comments WHERE id = ?", id);
+        if (comment.kind === "reply")
+            this.invalidateAssetRefs();
         this.touch(comment.sessionId);
         return comment;
     }
@@ -851,6 +871,7 @@ export class SqlStore {
             for (const id of input.archive) {
                 this.sql.exec("UPDATE posts SET status = 'archived' WHERE id = ? AND mockId = ?", id, input.mockId);
             }
+            this.invalidateAssetRefs();
             return comment;
         });
     }
@@ -865,6 +886,17 @@ export class SqlStore {
         for (const r of this.sql.exec("SELECT surfaces FROM post_versions").toArray()) {
             collectAssetIds(parseJson(r.surfaces, []), out);
         }
+        // The user's attachments: in a draft, in a sent reply, on an answered ask.
+        for (const r of this.sql.exec("SELECT asks, draft FROM mocks").toArray()) {
+            collectAttachedIds(parseJson(r.draft, null), out);
+            for (const ask of parseJson(r.asks, []))
+                collectAttachedIds(ask, out);
+        }
+        for (const r of this.sql
+            .exec("SELECT payload FROM comments WHERE kind = 'reply' AND payload IS NOT NULL")
+            .toArray()) {
+            collectAttachedIds(parseJson(r.payload, null), out);
+        }
         // An installed icon set is referenced by its project's design, not by a
         // surface; evicting it would blank that project's icons.
         for (const r of this.sql

package/dist/server/types.d.ts

@@ -8,6 +8,8 @@ export interface Session {
     lastActiveAt: string;
     agentSeq: number;
     project: string | null;
+    agentActiveAt: string | null;
+    keyed: boolean;
 }
 export declare const SURFACE_KINDS: readonly ["html", "diff", "image", "markdown", "terminal", "mermaid", "json", "code"];
 export type SurfaceKind = (typeof SURFACE_KINDS)[number];
@@ -214,6 +216,8 @@ export interface Ask {
     answer?: AskAnswer;
     other?: string;
     note?: string;
+    otherImages?: string[];
+    noteImages?: string[];
     at: string;
 }
 export declare const OTHER_ID = "other";
@@ -222,12 +226,17 @@ export interface PartCommentAnchor {
     quote?: string;
     selector?: string;
     box?: number[];
+    width?: number;
 }
+export declare const REACTIONS: readonly ["up", "down", "more"];
+export type Reaction = (typeof REACTIONS)[number];
 export interface PartComment {
     part: string | null;
     state: string | null;
     text: string;
     anchor?: PartCommentAnchor;
+    reaction?: Reaction;
+    variant?: string;
 }
 export interface ReplyDecision {
     kind: "accept" | "revise" | "drop";
@@ -242,6 +251,8 @@ export interface Draft {
     comments: PartComment[];
     others?: Record<string, string>;
     notes?: Record<string, string>;
+    otherImages?: Record<string, string[]>;
+    noteImages?: Record<string, string[]>;
     updatedAt: string;
 }
 export interface Reply {
@@ -253,6 +264,8 @@ export interface Reply {
     comments: PartComment[];
     others?: Record<string, string>;
     notes?: Record<string, string>;
+    otherImages?: Record<string, string[]>;
+    noteImages?: Record<string, string[]>;
     text?: string;
     decision?: ReplyDecision;
 }
@@ -523,13 +536,15 @@ export interface PostQuery {
     sessionId?: string;
 }
 export interface Store {
-    listSessions(): Promise<Session[]>;
+    listSessions(project?: string): Promise<Session[]>;
     getSession(id: string): Promise<Session | null>;
     getSessionByKey(key: string): Promise<Session | null>;
     createSession(input: CreateSessionInput): Promise<Session>;
     renameSession(id: string, title: string): Promise<Session | null>;
     removeSession(id: string): Promise<boolean>;
     markAgentSeen(sessionId: string, seq: number): Promise<void>;
+    touchAgent(sessionId: string): Promise<void>;
+    handOff(sessionId: string, seen: Pick<Session, "agentSeq" | "agentActiveAt">, toSeq: number): Promise<boolean>;
     getSetting(key: string): Promise<string | null>;
     setSetting(key: string, value: string): Promise<void>;
     listProjects(): Promise<ProjectSummary[]>;
@@ -572,6 +587,8 @@ export declare const HISTORY_LIMIT = 20;
 export declare function reservedAgent(name: string): string;
 export declare function stripNul<T extends string | null | undefined>(s: T): T;
 export declare const MAX_ASSET_BYTES: number;
+export declare const ATTACHABLE_IMAGE_TYPES: ReadonlySet<string>;
+export declare const MAX_ASK_IMAGES = 6;
 export declare const MAX_WORKSPACE_ASSET_BYTES: number;
 export declare const newId: () => string;
 export declare function hashAssetId(data: Uint8Array): Promise<string>;
@@ -583,13 +600,19 @@ export declare function projectFromCwd(cwd: string | null | undefined): string |
 export declare const htmlSurface: (html: string, kits?: unknown) => HtmlSurface;
 export declare const askAnswered: (a: Pick<Ask, "answer" | "other" | "note">) => boolean;
 export declare const openAsks: (mock: Pick<Mock, "asks">) => Ask[];
-export declare function builtinAskCount(mock: Pick<Mock, "asks" | "states">, posts: Pick<Post, "mock" | "state" | "variant" | "status">[], mockId: string): number;
+export declare function builtinAskIds(mock: Pick<Mock, "asks" | "states">, posts: Pick<Post, "mock" | "state" | "variant" | "status">[], mockId: string): string[];
+export declare const builtinAskCount: (mock: Pick<Mock, "asks" | "states">, posts: Pick<Post, "mock" | "state" | "variant" | "status">[], mockId: string) => number;
 export declare const openCount: (mock: Pick<Mock, "id" | "asks" | "states">, posts: Pick<Post, "mock" | "state" | "variant" | "status">[]) => number;
+export declare function draftedCount(mock: Pick<Mock, "id" | "asks" | "states" | "draft">, posts: Pick<Post, "mock" | "state" | "variant" | "status">[]): number | null;
 export declare const BUILTIN_ASK_ID = "variant";
 export declare function builtinAsk(mock: Pick<Mock, "states">, posts: Pick<Post, "state" | "variant">[], id: string): Ask | undefined;
 export declare function summarizeProjects(mocks: Mock[], sessions: Session[], posts?: Post[]): ProjectSummary[];
 export declare function surfacesByteLength(surfaces: Surface[]): number;
 export declare function collectAssetIds(surfaces: Surface[], out: Set<string>): void;
+export declare function collectAttachedIds(holder: {
+    otherImages?: unknown;
+    noteImages?: unknown;
+} | null | undefined, out: Set<string>): void;
 export interface EvictionCandidate {
     id: string;
     byteLength: number;

package/dist/server/types.js

@@ -54,6 +54,10 @@ export function isSandboxedSurfaceKind(kind) {
 // The viewer's write-in option on every ask. Reserved, so a delivered
 // `{id: "other", other: true}` choice never shadows an option the agent declared.
 export const OTHER_ID = "other";
+// A one-tap verdict on a part (or, with part null, on the variant itself),
+// for a reviewer on a phone who would rather not type: like, dislike, or
+// "more like this". Rides as a part comment, so it travels in the one reply.
+export const REACTIONS = ["up", "down", "more"];
 export const HISTORY_LIMIT = 20;
 // "user" is the reserved trust label for genuine human comments. A session
 // agent with that name could otherwise have its programmatic comments delivered
@@ -73,6 +77,15 @@ export function stripNul(s) {
 // budget the store evicts down to. One Durable Object holds the whole workspace, so
 // the budget sits well under its ~10 GB SQLite ceiling.
 export const MAX_ASSET_BYTES = 5 * 1024 * 1024;
+// What the user may attach to a write-in or a note: raster formats a model can
+// read. SVG is active content, so it is never attachable.
+export const ATTACHABLE_IMAGE_TYPES = new Set([
+    "image/png",
+    "image/jpeg",
+    "image/webp",
+    "image/gif",
+]);
+export const MAX_ASK_IMAGES = 6;
 export const MAX_WORKSPACE_ASSET_BYTES = 2 * 1024 * 1024 * 1024;
 // Short, unguessable id: 8 random bytes (64 bits) as 11 url-safe base64 chars.
 // These double as bearer capabilities: in publicRead mode `/s/:id` and
@@ -145,7 +158,7 @@ export const openAsks = (mock) => mock.asks.filter((a) => !askAnswered(a));
 // rule as viewer/src/logic.ts builtinAsks, so Home, `read` and `pending` count
 // the question the user actually sees. Answering it archives the losers, which
 // is what makes it stop counting.
-export function builtinAskCount(mock, posts, mockId) {
+export function builtinAskIds(mock, posts, mockId) {
     const live = (state) => posts
         .filter((p) => p.mock === mockId && p.state === state && p.status !== "archived")
         .map((p) => p.variant);
@@ -159,14 +172,30 @@ export function builtinAskCount(mock, posts, mockId) {
     const states = mock.states.length ? mock.states : [null];
     const needing = states.filter(needs);
     if (!needing.length)
-        return 0;
+        return [];
     const key = (state) => [...live(state)].sort().join("\n");
     const first = key(needing[0]);
     return needing.length === states.length && states.every((st) => key(st) === first)
-        ? 1
-        : needing.length;
+        ? [BUILTIN_ASK_ID]
+        : needing.map((st) => (st === null ? BUILTIN_ASK_ID : `${BUILTIN_ASK_ID}:${st}`));
 }
+export const builtinAskCount = (mock, posts, mockId) => builtinAskIds(mock, posts, mockId).length;
 export const openCount = (mock, posts) => openAsks(mock).length + builtinAskCount(mock, posts, mock.id);
+// How many of the open asks the user's unsent draft already speaks for (a
+// pick, a write-in or a note), so Home can show a started mock as "draft 2/4";
+// null when there is no draft. A count only: the draft's content stays private.
+export function draftedCount(mock, posts) {
+    const d = mock.draft;
+    if (!d)
+        return null;
+    const open = [...openAsks(mock).map((a) => a.id), ...builtinAskIds(mock, posts, mock.id)];
+    const said = (id) => {
+        const a = d.answers[id];
+        const picked = Array.isArray(a) ? a.length > 0 : a !== undefined;
+        return picked || d.others?.[id] !== undefined || d.notes?.[id] !== undefined;
+    };
+    return open.filter(said).length;
+}
 // The viewer's built-in "Which one?" for variants no agent ask binds: `variant`
 // mock-wide, `variant:<state>` per state. Never stored; synthesized from the
 // variants so a reply answering it validates, flips and reads like any ask. An
@@ -275,6 +304,20 @@ export function collectAssetIds(surfaces, out) {
             out.add(p.assetId);
     }
 }
+// The images a draft, a reply or a sent ask carries (all keep the user's
+// attachments in otherImages / noteImages).
+export function collectAttachedIds(holder, out) {
+    for (const map of [holder?.otherImages, holder?.noteImages]) {
+        if (!map || typeof map !== "object")
+            continue;
+        for (const ids of Array.isArray(map) ? [map] : Object.values(map)) {
+            if (Array.isArray(ids))
+                for (const id of ids)
+                    if (typeof id === "string")
+                        out.add(id);
+        }
+    }
+}
 // Pick the assets to evict so `incomingBytes` fits under `budget`. Oldest
 // (lastAccessedAt) first, but unreferenced assets go before referenced ones —
 // a live embed is only evicted as a last resort, once unreferenced candidates

package/extensions/mockpit.js

@@ -220,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 ?? []) {

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": [],
@@ -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.1.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",

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.