mockpit 1.2.0 → 2.0.0

package/dist/server/mcpSpec.d.ts

@@ -19,6 +19,7 @@ export declare const mcpSurfaceSchema: z.ZodObject<{
     }>>;
     html: z.ZodOptional<z.ZodString>;
     kits: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    poster: z.ZodOptional<z.ZodString>;
     markdown: z.ZodOptional<z.ZodString>;
     mermaid: z.ZodOptional<z.ZodString>;
     patch: z.ZodOptional<z.ZodString>;
@@ -53,7 +54,7 @@ type Param = {
     d?: string;
     req?: boolean;
 } | {
-    t: "surfaces" | "asks" | "object";
+    t: "surfaces" | "asks" | "object" | "integers" | "strings";
     d?: string;
     req?: boolean;
 };
@@ -131,9 +132,9 @@ export declare const STDIO_MCP_TOOLS: ({
     _meta: {
         "anthropic/alwaysLoad": boolean;
     };
-    outputSchema?: z.ZodObject<Readonly<{
-        [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-    }>, z.core.$loose> | undefined;
+    outputSchema?: z.ZodObject<{
+        [x: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    }, z.core.$loose> | undefined;
     name: string;
     description: string;
     inputSchema: Readonly<{
@@ -141,9 +142,9 @@ export declare const STDIO_MCP_TOOLS: ({
     }>;
 } | {
     _meta?: undefined;
-    outputSchema?: z.ZodObject<Readonly<{
-        [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-    }>, z.core.$loose> | undefined;
+    outputSchema?: z.ZodObject<{
+        [x: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    }, z.core.$loose> | undefined;
     name: string;
     description: string;
     inputSchema: Readonly<{
@@ -154,9 +155,9 @@ export declare const STDIO_RUN_TOOLS: ({
     _meta: {
         "anthropic/alwaysLoad": boolean;
     };
-    outputSchema?: z.ZodObject<Readonly<{
-        [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-    }>, z.core.$loose> | undefined;
+    outputSchema?: z.ZodObject<{
+        [x: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    }, z.core.$loose> | undefined;
     name: string;
     description: string;
     inputSchema: Readonly<{
@@ -164,9 +165,9 @@ export declare const STDIO_RUN_TOOLS: ({
     }>;
 } | {
     _meta?: undefined;
-    outputSchema?: z.ZodObject<Readonly<{
-        [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-    }>, z.core.$loose> | undefined;
+    outputSchema?: z.ZodObject<{
+        [x: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    }, z.core.$loose> | undefined;
     name: string;
     description: string;
     inputSchema: Readonly<{

package/dist/server/mcpSpec.js

@@ -10,14 +10,15 @@ export const MCP_SERVER_INFO = { name: "mockpit", version: "0.2.0" };
 // list (types.ts) so the MCP tier can never fall behind what REST/CLI accept.
 const SURFACE_KIND_ENUM = [...SURFACE_KINDS];
 export const MCP_INSTRUCTIONS = "Mockpit shows design work to the user: project > mock > state > variant > version. publish " +
-    "each variant (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. One render plus a " +
+    "each variant (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 (ask). One render plus a " +
     "control: declare a knob. Say where to look, then end your turn; nothing waits. When the " +
     "user says they answered, call feedback. Writes return feedback too; it is delivered once. " +
     "Fetch guide before html.";
 const field = {
     mock: "Mock slug or id",
     state: "State label; omit if single-state",
+    situation: 'Another render of this state ("Couldn\'t save", "Loading"); publish the state itself first',
     variant: 'Variant label; default "default"',
     project: "Default: the session's project",
     title: "Mock title",
@@ -28,8 +29,17 @@ const field = {
     knobs: 'Global knobs (tunekit usePane shape) keyed by path: [default,min,max,step], boolean, {type:"select",options}, "#hex"',
     variantKnobs: "Knobs this variant alone has",
     from: "Branch from this version",
+    fork: 'Start this new variant from a sibling: "variant" or "variant@N"; alone it copies it, with parts/fills it edits the copy',
     prompt: "What prompted this version; usually omit",
+    note: "What this variant is; shown beside it, never in the html",
+    widths: "Widths it ships at, side by side: [390,1280]",
+    kind: "Only when building the product's screens: page (a screen), component (a piece pages embed). Omit for sketches, diagrams and reviews",
+    area: 'Product area in the project\'s words; Home groups by it. "" clears',
+    source: 'Code path implementing it. "" clears',
+    flow: "Flow this state is a step of; alone, only places it",
+    step: "1-based place; 0 removes",
     kits: `Opt-in bundles: ${KIT_IDS.join("|")}`,
+    poster: "Still of the page (asset id) shown instead of running it; resend when the page changes",
 };
 const diffFileSchema = z.object({
     filename: z.string(),
@@ -48,6 +58,7 @@ export const mcpSurfaceSchema = z
     kind: z.enum(SURFACE_KIND_ENUM).optional(),
     html: z.string().optional().describe(field.html),
     kits: z.array(z.string()).optional().describe(field.kits),
+    poster: z.string().optional().describe(field.poster),
     markdown: z.string().optional().describe("Prose; raw HTML is escaped"),
     mermaid: z.string().optional().describe("Diagram source; do not set colors"),
     patch: z.string().optional().describe("Preferred over files"),
@@ -69,17 +80,23 @@ export const mcpSurfaceSchema = z
     description: "Set kind and its field: html, markdown, mermaid, patch|files (diff), assetId (image), text (terminal), data (json), code",
 });
 const askSchema = z.object({
-    id: z.string().optional().describe("Stable id; reusing one replaces that ask"),
+    id: z.string().optional().describe("Stable id; reusing one replaces that question"),
     text: z.string().describe("The question, one sentence"),
     scope: z.enum(["mock", "state", "part"]).optional(),
     state: z.string().optional(),
     part: z.string().optional().describe("data-part name, for scope part"),
     multi: z.boolean().optional(),
+    after: z
+        .string()
+        .optional()
+        .describe("Id of an earlier ask this depends on; it opens once that one is answered"),
     options: z.array(z.object({
         id: z.string().optional(),
         label: z.string(),
         variant: z.string().optional().describe("Bind to a published variant"),
+        version: z.number().int().optional().describe("And one version of it"),
         set: z.record(z.string(), z.unknown()).optional().describe("Or to knob values {path: value}"),
+        recommended: z.boolean().optional().describe("The one you would pick; one per ask"),
     })),
 });
 function zodParam(p) {
@@ -100,6 +117,12 @@ function zodParam(p) {
         case "integer":
             s = z.number().int();
             break;
+        case "integers":
+            s = z.array(z.number().int());
+            break;
+        case "strings":
+            s = z.array(z.string());
+            break;
         default:
             s = p.t === "string" ? z.string() : p.t === "number" ? z.number() : z.boolean();
     }
@@ -118,21 +141,34 @@ const VARIANT_REF = { mock: P.mock, state: P.state, variant: P.variant, project:
 export const MCP_TOOL_DEFS = [
     {
         name: "publish",
-        description: "Create or version one variant of one state of a mock. One of html, surfaces (the full ordered list) or parts (splices the latest version). Returns parts per state, nudges, feedback.",
+        description: "Create or version one variant of one state of a mock. One of html, surfaces (the full ordered list), parts or fills (splice the latest version). Returns parts per state, nudges, feedback.",
         params: {
             ...VARIANT_REF,
+            situation: { t: "string", d: field.situation },
             title: { t: "string", d: field.title },
-            kind: { t: "enum", values: ["component", "page"] },
+            kind: { t: "enum", values: ["page", "component", "sketch"], d: field.kind },
+            area: { t: "string", d: field.area },
+            source: { t: "string", d: field.source },
             html: { t: "string", d: field.html },
+            poster: { t: "string", d: field.poster },
             surfaces: {
                 t: "surfaces",
                 d: "Full ordered list: {id} keeps a surface, a missing id removes it",
             },
-            parts: { t: "object", d: '{"name"|"name#key": outer html}; splices marked parts' },
+            parts: { t: "object", d: '{"name"|"name#key": outer html}; splices declared parts' },
+            fills: {
+                t: "object",
+                d: '{"part#fill": outer html}; replaces that fill of a part, or adds it after its others',
+            },
             knobs: { t: "object", d: field.knobs },
             variantKnobs: { t: "object", d: field.variantKnobs },
             from: { t: "integer", d: field.from },
+            fork: { t: "string", d: field.fork },
             prompt: { t: "string", d: field.prompt },
+            note: { t: "string", d: field.note },
+            widths: { t: "integers", d: field.widths },
+            flow: { t: "string", d: field.flow },
+            step: { t: "integer", d: field.step },
             session: P.session,
             sessionTitle: { t: "string", d: field.sessionTitle },
             agent: { t: "string", d: field.agent },
@@ -141,7 +177,7 @@ export const MCP_TOOL_DEFS = [
     },
     {
         name: "ask",
-        description: "Ask structured questions on a mock. A choice is several variants plus one ask that binds them; options may also set knob values. Reusing an ask id replaces it.",
+        description: "Ask structured questions on a mock. A choice is several variants plus one question that binds them; options may also set knob values. Reusing a question id replaces it.",
         params: {
             mock: P.mock,
             project: P.project,
@@ -152,17 +188,21 @@ export const MCP_TOOL_DEFS = [
     },
     {
         name: "read",
-        description: "Without mock: every mock (slug, states, variants, open asks) plus pending. With mock: its states, variants, asks with answers, parts, knobs and last tuned values, plus pending. Never consumes feedback.",
+        description: "Without mock: every mock (slug, states, variants, open questions), flows, plus pending. With mock: its states, variants, questions with answers, parts, knobs and settled values (every answer's set and tuning sent so far), plus pending. Never consumes feedback.",
         params: {
             mock: { t: "string", d: field.mock },
             project: P.project,
             body: { t: "boolean", d: "Include each variant's surfaces" },
             history: { t: "boolean", d: "Include version rows" },
+            tree: {
+                t: "boolean",
+                d: "Without mock: the project as a tree (each mock's variants with status and forkedFrom, the mocks it embeds and is embedded in)",
+            },
         },
     },
     {
         name: "feedback",
-        description: "Returns at once: what the user sent since you last heard (one batch per mock: reply answers, mix, tuned knobs, part comments, comments, accepted/archived), delivered once, plus pending (viewer open, draft progress).",
+        description: "Returns at once: what the user sent since you last heard (one batch per mock: reply 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).",
         params: {
             project: P.project,
             session: { t: "string", d: "Session id returned by publish", req: true },
@@ -181,9 +221,26 @@ export const MCP_TOOL_DEFS = [
     },
     {
         name: "export",
-        description: "The accepted (or current) html per state, version history, screenshot URL, knobs and the last reply's tuned values.",
+        description: "The html in use (else current) per state, version history, screenshot URL, knobs, the settled values and the last reply.",
         params: VARIANT_REF,
     },
+    {
+        name: "edit",
+        description: "Change a mock without a new version; a new slug rewrites every reference to the old one. Without mock, rename renames the project and areaOrder orders its areas. Returns feedback.",
+        params: {
+            mock: { t: "string", d: field.mock },
+            project: P.project,
+            slug: { t: "string" },
+            title: { t: "string" },
+            kind: { t: "enum", values: ["page", "component", "sketch"] },
+            area: { t: "string" },
+            source: { t: "string" },
+            rename: { t: "string", d: "New project name" },
+            areaOrder: { t: "strings", d: "Without mock: Home's area order" },
+            session: P.session,
+        },
+        httpOnly: ["session"],
+    },
     {
         name: "upload",
         description: "Upload bytes and return id and URL. Reference id as an image surface's assetId.",
@@ -235,7 +292,9 @@ const nullStr = z.string().nullable();
 const strs = z.array(z.string());
 const bag = z.record(z.string(), z.unknown());
 const variantRef = o({ state: nullStr, variant: str });
+const inUseRef = o({ state: nullStr, variant: str, version: num });
 const partsByState = z.array(o({ state: nullStr, parts: z.array(o({ name: str })) }));
+const flowSchema = o({ name: str, steps: z.array(o({ mock: str, state: nullStr })) });
 const feedbackSchema = o({
     mock: nullStr,
     reply: o({
@@ -244,22 +303,37 @@ const feedbackSchema = o({
             chosen: z.array(o({ label: str, other: z.literal(true).optional() })),
             note: str.optional(),
         })),
-        mix: bag,
+        borrowed: bag.describe("Part → the variant to take it from"),
         tuned: bag,
         comments: z.array(o({ part: nullStr, text: str })),
         reactions: strs.optional().describe('One-tap reactions, e.g. 👍 part "hero" (variant B)'),
+        verdict: o({ kind: z.enum(["use", "revise"]), state: nullStr, variant: str })
+            .optional()
+            .describe("Use this or Revise on one variant"),
     })
         .nullable()
-        .describe("The user's Send; null if only comments"),
-    comments: z.array(o({ seq: num, text: str })),
-    accepted: z.array(variantRef),
+        .describe("The user's Send; null if only messages"),
+    messages: z.array(o({ seq: num, text: str })).describe("What the user wrote in the thread"),
+    inUse: z.array(inUseRef).describe("In use, each at the version the user put in use"),
     archived: z.array(variantRef),
+    closed: z
+        .literal(true)
+        .optional()
+        .describe("The user closed the mock: its open questions were closed unanswered"),
+    dismissed: z
+        .array(o({ ask: str, text: str }))
+        .optional()
+        .describe("The questions the close dismissed; don't ask them again"),
+    edited: o({ kind: str.optional(), area: nullStr.optional() })
+        .optional()
+        .describe("The user moved the mock from Home: its kind or area now"),
 }).meta({ id: "Feedback" });
 // Typed once, on feedback: repeating it on every write would cost more than
 // the rest of the write's output schema.
 const feedbackRide = z.array(bag).describe("Feedback batches as the feedback tool returns");
 const pendingSchema = o({
     mock: str,
+    closed: z.literal(true).optional(),
     viewerOpen: z.boolean(),
     draft: o({ answered: num, of: num, comments: num, touchedAt: str }).nullable(),
 }).meta({ id: "Pending" });
@@ -271,6 +345,11 @@ const writeOutput = {
     partChanges: o({ vanished: strs, renamed: z.array(o({ from: str, to: str })) }).optional(),
     nudges: strs.optional(),
     suggestedAsk: bag.optional().describe("Send with ask when a nudge names it"),
+    suggestedFillAsks: z
+        .array(bag)
+        .optional()
+        .describe("A question per part with fills that none sets; send with ask"),
+    flow: flowSchema.optional(),
     feedback: feedbackRide,
 };
 const OUTPUT_SCHEMAS = {
@@ -303,17 +382,51 @@ const OUTPUT_SCHEMAS = {
         pending: z.array(pendingSchema),
     },
     say: { feedback: feedbackRide },
+    edit: {
+        renamed: o({ from: str, to: str }).optional(),
+        areaOrder: strs.optional(),
+        url: str,
+        nudges: strs.optional(),
+        feedback: feedbackRide,
+    },
     read: {
         mocks: z.array(o({ slug: str, states: strs, variants: num, open: num })).optional(),
         states: strs.optional(),
         asks: z.array(o({ id: str, text: str })).optional(),
-        variants: z.array(o({ state: nullStr, variant: str, status: str, version: num })).optional(),
+        variants: z
+            .array(o({
+            state: nullStr,
+            variant: str,
+            status: z.enum(["open", "inUse", "archived"]),
+            version: num,
+            inUseVersion: num.optional().describe("Set while in use: the version in use"),
+            history: z
+                .array(o({ version: num, hidden: z.boolean().optional() }))
+                .optional()
+                .describe("With history: version rows; hidden ones the user put away are flagged"),
+        }))
+            .optional(),
+        inUse: z
+            .array(inUseRef)
+            .optional()
+            .describe("Per state, the version the user put in use; export and embeds resolve to it"),
         knobs: bag.optional(),
-        tuned: bag.optional().describe("Knob values from the latest reply"),
+        settled: bag.optional().describe("Every knob value the user has sent, later replies winning"),
+        tree: z.array(bag).optional(),
+        flows: z.array(flowSchema).optional(),
         pending: z.union([z.array(pendingSchema), pendingSchema]),
     },
     export: {
-        states: z.array(o({ state: nullStr, variant: str, version: num, html: str, markdown: str })),
+        states: z.array(o({
+            state: nullStr,
+            variant: str,
+            version: num,
+            latest: num.optional().describe("Your newer version, not in use yet"),
+            html: str.describe("With fills: only the chosen ones"),
+            allFills: str.optional().describe("With fills: the html with every fill"),
+            markdown: str,
+        })),
+        settled: bag,
         reply: bag.nullable(),
     },
 };
@@ -330,7 +443,9 @@ function shapeFor(tool, transport) {
         shape[key] =
             transport === "stdio" && key === "html" && tool.name === "publish"
                 ? z.string().optional().describe(`${field.html}; or a file path`)
-                : zodParam(p);
+                : transport === "stdio" && key === "poster" && tool.name === "publish"
+                    ? z.string().optional().describe(`${p.d}; or an image file path`)
+                    : zodParam(p);
     }
     return shape;
 }

package/dist/server/postSurfaces.js

@@ -6,23 +6,14 @@ const MERMAID_PARSE_NEXT_STEPS = [
     'Keep the diagram declaration on the first non-comment line (for example, "flowchart TD").',
     "Reduce the diagram to a minimal valid form, then add statements back until the failing line is isolated.",
 ];
-const requiredString = (name) => z.string({
-    required_error: `requires string "${name}"`,
-    invalid_type_error: `requires string "${name}"`,
-});
+const requiredString = (name) => z.string({ error: `requires string "${name}"` });
 const optionalLooseString = z.preprocess((v) => (typeof v === "string" ? v : undefined), z.string().optional());
 const looseLayout = z.preprocess((v) => (v === "unified" || v === "split" ? v : undefined), z.enum(["unified", "split"]).optional());
 const optionalLooseNumber = z.preprocess((v) => (typeof v === "number" && Number.isFinite(v) ? v : undefined), z.number().optional());
 const strictDiffFile = z.object({
     filename: requiredString("filename"),
-    before: z.string({
-        required_error: 'requires string "before" and "after"',
-        invalid_type_error: 'requires string "before" and "after"',
-    }),
-    after: z.string({
-        required_error: 'requires string "before" and "after"',
-        invalid_type_error: 'requires string "before" and "after"',
-    }),
+    before: z.string({ error: 'requires string "before" and "after"' }),
+    after: z.string({ error: 'requires string "before" and "after"' }),
     language: z.string().optional(),
 });
 const looseDiffFile = z
@@ -53,17 +44,20 @@ const strictHtmlSurface = z.object({
     kind: z.literal("html"),
     html: requiredString("html"),
     kits: z.array(z.string()).optional(),
+    poster: z.string().min(1).optional(),
 });
 const looseHtmlSurface = z
     .object({
     kind: z.literal("html"),
     html: requiredString("html"),
     kits: z.unknown().optional(),
+    poster: optionalLooseString,
 })
     .transform((p) => ({
     kind: "html",
     html: p.html,
     ...(Array.isArray(p.kits) ? { kits: p.kits.filter((k) => typeof k === "string") } : {}),
+    ...(p.poster ? { poster: p.poster } : {}),
 }));
 // Strict mode rejects an unknown id with the valid set, so a CLI/REST typo is a
 // clean 400; loose mode filters unknown ids out rather than dropping the whole

package/dist/server/richRender.js

@@ -139,7 +139,9 @@ blockquote {
   color: var(--muted);
 }
 table { border-collapse: collapse; font-size: 13px; }
-th, td { border: 0.5px solid var(--border); padding: 4px 8px; text-align: left; }
+/* break-word, not the body's anywhere: anywhere lets a column shrink to one
+   letter, so a long cell beside it squeezes "Topic" into "Top/ic". */
+th, td { border: 0.5px solid var(--border); padding: 4px 8px; text-align: left; overflow-wrap: break-word; }
 th { background: var(--hover); }
 img { max-width: 100%; height: auto; border-radius: 6px; }
 hr { border: none; border-top: 0.5px solid var(--border); margin: 1em 0; }

package/dist/server/run.js

@@ -9,7 +9,7 @@
 // that is counted, bounded and logged.
 import { decodeBase64 } from "./base64.js";
 import { isGuideTopic, unknownTopicMessage } from "./designGuide.js";
-import { unwrap } from "./mcpHttp.js";
+import { editCall, unwrap } from "./mcpHttp.js";
 import { RUN_FUNCTIONS } from "./runApi.js";
 // A script never waits for the user, so the wall clock is only a sandbox guard:
 // 10 s clears a run of publishes with room to spare. 32 MiB and a 256 KiB stack are what the spike showed safe (512 KiB overflows the host
@@ -153,6 +153,10 @@ export function createRunFlow(deps) {
                 return [await deps.guide("", topic), String(topic)];
             },
             async read([mock, opts]) {
+                if ((mock === undefined || mock === null) && plain(opts).tree === true) {
+                    const value = await take(flows.tree({ project: await projectOf() }));
+                    return [value, `${value.tree.length} mocks`];
+                }
                 if (mock === undefined || mock === null) {
                     const value = await take(flows.list({ project: await projectOf() }));
                     return [value, `${value.mocks.length} mocks`];
@@ -179,6 +183,11 @@ export function createRunFlow(deps) {
                 await take(flows.say(r.mock, { ...(await mine(r)), message }, flowCtx));
                 return [null, String(r.mock ?? "?")];
             },
+            async edit([v]) {
+                const r = await mine(plain(v));
+                const value = await take(editCall(flows, r, flowCtx, project));
+                return [value, value.renamed ? `${value.renamed.from} → ${value.renamed.to}` : "edited"];
+            },
             async upload([data, opts]) {
                 if (typeof data !== "string" || !data)
                     throw new Error("upload needs base64 data");

package/dist/server/runApi.d.ts

@@ -1,6 +1,6 @@
-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 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; recommended?: boolean }[];\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; suggestedFillAsks?: Ask[]; // send 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 }[]; borrowed: Record<string, string>; tuned: Knobs; comments: { part: string | null; text: string }[]; verdict?: { kind: \"use\" | \"revise\"; state: string | null; variant: string; version?: number } };\n  messages: { text: string; state: string | null; variant: string | null }[];\n  inUse: { state: string | null; variant: string; version: number }[]; archived: { state: string | null; variant: string }[];\n  closed?: true; dismissed?: { ask: string; text: string }[];\n};\ntype Pending = { mock: string; closed?: true; 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, the flows, 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   * fills {\"part#fill\": outer html}, replacing or adding one fill of a part. */\n  publish(v: Ref & { situation?: string; title?: string; kind?: \"page\" | \"component\" | \"sketch\"; area?: string; source?: string; html?: string; poster?: string; surfaces?: (Surface | { id: string })[]; parts?: Record<string, string>; fills?: Record<string, string>; knobs?: Knobs; variantKnobs?: Knobs; from?: number; prompt?: string; note?: string; widths?: number[]; flow?: string; step?: 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  /** No new version; \"\" clears. { rename } or { areaOrder } without mock edits the project. */\n  edit(v: { mock?: string; slug?: string; title?: string; kind?: string; area?: string; source?: string; rename?: string; areaOrder?: string[] }): Promise<{ url: string }>;\n  export(v: Ref): Promise<{ states: { state: string | null; variant: string; version: number; html: string; allFills?: 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", "edit", "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;";
+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: \"tone\", text: \"Calm or bold?\",\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;";
 export declare const RUN_DESCRIPTION: string;
 export declare const RUN_INSTRUCTIONS: string;

package/dist/server/runApi.js

@@ -2,8 +2,8 @@
 // tool description, the scripts guide topic and `mockpit run --help`, so the
 // tiers cannot describe different APIs. Hand-shaped rather than generated from
 // mcpSpec: a generator repeats Surface per tool and the run-level params on
-// every function, roughly tripling the size. test/run.test.ts checks that every
-// host function named here exists and vice versa.
+// every function, roughly tripling the size. Every host function named here
+// must exist, and vice versa.
 export const RUN_API = `// The body of an async function, in plain JavaScript (no TypeScript syntax).
 // \`await mockpit.*\`, \`return\` a JSON value, print() adds an output line.
 // No network, timers, imports or process. Session, project and agent are fixed
@@ -21,33 +21,37 @@ type Surface =
   | { kind: "code"; code: string; language?: string; lineStart?: number };
 type Ask = {
   id?: string; text: string; scope?: "mock" | "state" | "part"; state?: string; part?: string; multi?: boolean;
-  options: { id?: string; label: string; variant?: string; set?: Knobs }[];
+  options: { id?: string; label: string; variant?: string; set?: Knobs; recommended?: boolean }[];
 };
 type Written = {
   post: { state: string | null; variant: string; version: number }; url: string;
   parts: { state: string | null; parts: { name: string }[] }[];
   partChanges?: { vanished: string[]; renamed: { from: string; to: string }[] };
-  nudges?: string[]; suggestedAsk?: Ask; // send it with ask when nudged
+  nudges?: string[]; suggestedAsk?: Ask; suggestedFillAsks?: Ask[]; // send with ask when nudged
 };
 type Feedback = {
   mock: string | null;
-  reply: null | { asks: { ask: string; chosen: { id: string; label: string; other?: true }[]; note?: string }[]; mix: Knobs; tuned: Knobs; comments: { part: string | null; text: string }[] };
-  comments: { text: string; state: string | null; variant: string | null }[];
-  accepted: { state: string | null; variant: string }[]; archived: { state: string | null; variant: string }[];
+  reply: null | { asks: { ask: string; chosen: { id: string; label: string; other?: true }[]; note?: string }[]; borrowed: Record<string, string>; tuned: Knobs; comments: { part: string | null; text: string }[]; verdict?: { kind: "use" | "revise"; state: string | null; variant: string; version?: number } };
+  messages: { text: string; state: string | null; variant: string | null }[];
+  inUse: { state: string | null; variant: string; version: number }[]; archived: { state: string | null; variant: string }[];
+  closed?: true; dismissed?: { ask: string; text: string }[];
 };
-type Pending = { mock: string; viewerOpen: boolean; draft: null | { answered: number; of: number; comments: number; touchedAt: string } };
+type Pending = { mock: string; closed?: true; viewerOpen: boolean; draft: null | { answered: number; of: number; comments: number; touchedAt: string } };
 declare const mockpit: {
   guide(topic?: "knobs" | "asks" | "surfaces" | "html" | "feedback" | "http" | "scripts"): Promise<string>;
-  /** No mock: every mock plus pending. With one: its states, variants, asks, parts, knobs. */
+  /** No mock: every mock, the flows, plus pending. With one: its states, variants, asks, parts, knobs. */
   read(mock?: string, opts?: { body?: boolean; history?: boolean }): Promise<unknown>;
   /** 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>;
+   * ({id} alone keeps that surface, a missing id is removed); parts {"name"|"name#key": outer html};
+   * fills {"part#fill": outer html}, replacing or adding one fill of a part. */
+  publish(v: Ref & { situation?: string; title?: string; kind?: "page" | "component" | "sketch"; area?: string; source?: string; html?: string; poster?: string; surfaces?: (Surface | { id: string })[]; parts?: Record<string, string>; fills?: Record<string, string>; knobs?: Knobs; variantKnobs?: Knobs; from?: number; prompt?: string; note?: string; widths?: number[]; flow?: string; step?: number }): Promise<Written>;
   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>;
-  export(v: Ref): Promise<{ states: { state: string | null; variant: string; version: number; html: string }[]; reply: unknown }>;
+  /** No new version; "" clears. { rename } or { areaOrder } without mock edits the project. */
+  edit(v: { mock?: string; slug?: string; title?: string; kind?: string; area?: string; source?: string; rename?: string; areaOrder?: string[] }): Promise<{ url: string }>;
+  export(v: Ref): Promise<{ states: { state: string | null; variant: string; version: number; html: string; allFills?: string }[]; reply: unknown }>;
   /** data: base64 bytes. Use id as an image surface's assetId. */
   upload(data: string, opts: { contentType: string; filename?: string; kind?: "image" | "file" }): Promise<{ id: string; url: string }>;
 };
@@ -60,13 +64,14 @@ export const RUN_FUNCTIONS = [
     "ask",
     "feedback",
     "say",
+    "edit",
     "export",
     "upload",
 ];
 export const RUN_EXAMPLE = `const html = (tone) => \`<section data-part="hero" class="\${tone}"><h1>Writer</h1></section>\`;
 await mockpit.publish({ mock: "writer", variant: "calm", html: html("calm") });
 await mockpit.publish({ mock: "writer", variant: "bold", html: html("bold") });
-const { url } = await mockpit.ask("writer", [{ id: "look", text: "Which look?",
+const { url } = await mockpit.ask("writer", [{ id: "tone", text: "Calm or bold?",
   options: [{ label: "Calm", variant: "calm" }, { label: "Bold", variant: "bold" }] }]);
 // Tell the user where to look and end the turn; a later run reads mockpit.feedback().
 return url;`;