mockpit 1.3.0 → 2.0.0

package/dist/server/mcpHttp.js

@@ -11,6 +11,27 @@ export function unwrap(result) {
     }
     return result.body;
 }
+// `edit` is one verb with two shapes: `rename` or `areaOrder` edits the
+// project, anything else edits the mock. Shared by both MCP transports' HTTP
+// side and `run`.
+export function editCall(flows, args, ctx, project) {
+    if (args.rename === undefined && args.areaOrder === undefined) {
+        return flows.edit(args.mock, args, ctx);
+    }
+    if (args.mock !== undefined) {
+        return Promise.resolve({
+            status: 400,
+            body: { error: '"rename" and "areaOrder" edit the project; edit the mock without them' },
+        });
+    }
+    if (!project) {
+        return Promise.resolve({
+            status: 400,
+            body: { error: 'provide "project": the project to edit' },
+        });
+    }
+    return flows.editProject(project, { name: args.rename, areaOrder: args.areaOrder, session: args.session }, ctx);
+}
 export function registerMcp(app, deps) {
     const { flows, store } = deps;
     async function projectOf(args) {
@@ -24,6 +45,15 @@ export function registerMcp(app, deps) {
         const projects = await store.listProjects();
         return projects[0]?.name ?? "workspace";
     }
+    // Only a project the call names, or its session's: a rename never falls back
+    // to whichever project happens to be first.
+    async function namedProject(args) {
+        if (typeof args.project === "string" && args.project)
+            return args.project;
+        if (typeof args.session !== "string")
+            return undefined;
+        return (await store.getSession(args.session))?.project ?? undefined;
+    }
     async function loadImage(ref) {
         const asset = await store.getAsset(ref.id);
         return asset ? { data: asset.data, mimeType: asset.contentType } : null;
@@ -51,6 +81,8 @@ export function registerMcp(app, deps) {
                 return unwrap(await flows.say(args.mock, args, ctx));
             case "export":
                 return unwrap(await flows.exportMock(args.mock, args, ctx));
+            case "edit":
+                return unwrap(await editCall(flows, args, ctx, await namedProject(args)));
             case "upload": {
                 if (typeof args.data !== "string" || args.data.length === 0) {
                     throw new Error("upload needs base64 `data`");

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" | "integers";
+    t: "surfaces" | "asks" | "object" | "integers" | "strings";
     d?: string;
     req?: boolean;
 };

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",
@@ -32,9 +33,13 @@ const field = {
     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]",
-    flow: "Flow this screen is a step of; alone, only places it",
+    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(),
@@ -53,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"),
@@ -74,7 +80,7 @@ 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(),
@@ -90,6 +96,7 @@ const askSchema = z.object({
         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) {
@@ -113,6 +120,9 @@ function zodParam(p) {
         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();
     }
@@ -134,17 +144,21 @@ export const MCP_TOOL_DEFS = [
         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 slot, or adds it after the others',
+                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 },
@@ -163,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,
@@ -174,7 +188,7 @@ export const MCP_TOOL_DEFS = [
     },
     {
         name: "read",
-        description: "Without mock: every mock (slug, states, variants, open asks), flows, plus pending. With mock: its states, variants, asks with answers, parts, knobs and settled values (every answer's set and tuning sent so far), 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,
@@ -182,13 +196,13 @@ export const MCP_TOOL_DEFS = [
             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 uses and is used in)",
+                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/dropped, or resolved with the asks it dismissed), 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 },
@@ -210,6 +224,23 @@ export const MCP_TOOL_DEFS = [
         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.",
@@ -272,32 +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(inUseRef).describe("Accepted, each at the version put in use"),
+        .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),
-    dropped: z.array(variantRef),
-    resolved: z
+    closed: z
         .literal(true)
         .optional()
-        .describe("The user resolved the mock: its open asks were closed unanswered"),
+        .describe("The user closed the mock: its open questions were closed unanswered"),
     dismissed: z
         .array(o({ ask: str, text: str }))
         .optional()
-        .describe("The asks the resolution closed; don't ask them again"),
+        .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,
-    resolved: z.literal(true).optional(),
+    closed: z.literal(true).optional(),
     viewerOpen: z.boolean(),
     draft: o({ answered: num, of: num, comments: num, touchedAt: str }).nullable(),
 }).meta({ id: "Pending" });
@@ -309,6 +345,10 @@ 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,
 };
@@ -342,6 +382,13 @@ 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(),
@@ -350,9 +397,9 @@ const OUTPUT_SCHEMAS = {
             .array(o({
             state: nullStr,
             variant: str,
-            status: str,
+            status: z.enum(["open", "inUse", "archived"]),
             version: num,
-            acceptedVersion: num.optional().describe("Set when accepted: the version in use"),
+            inUseVersion: num.optional().describe("Set while in use: the version in use"),
             history: z
                 .array(o({ version: num, hidden: z.boolean().optional() }))
                 .optional()
@@ -375,7 +422,8 @@ const OUTPUT_SCHEMAS = {
             variant: str,
             version: num,
             latest: num.optional().describe("Your newer version, not in use yet"),
-            html: str,
+            html: str.describe("With fills: only the chosen ones"),
+            allFills: str.optional().describe("With fills: the html with every fill"),
             markdown: str,
         })),
         settled: bag,
@@ -395,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

@@ -44,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/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
@@ -183,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, 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 alternative of a slot. */\n  publish(v: Ref & { title?: string; kind?: \"component\" | \"page\"; html?: 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  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,34 +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, 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};
-   * fills {"part#fill": outer html}, replacing or adding one alternative of a slot. */
-  publish(v: Ref & { title?: string; kind?: "component" | "page"; html?: 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>;
+   * 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 }>;
 };
@@ -61,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;`;

package/dist/server/sqlStore.d.ts

@@ -1,4 +1,4 @@
-import { type Ask, type Asset, type Comment, type CommentQuery, type CommitReplyInput, type CreateAssetInput, type CreateCommentInput, type CreateMockInput, type CreatePostInput, type CreateSessionInput, type Draft, type Knobs, type Mock, type MockKind, type Post, type PostQuery, type PostStatus, type PostVersion, type Session, type Embed, type Flow, type FlowStep, type ForkRef, type SqlStorage, type Store, type Surface, type UpdateMockInput, type UpdatePostInput } from "./types.ts";
+import { type Ask, type Asset, type Comment, type CommentQuery, type CommitReplyInput, type CreateAssetInput, type CreateCommentInput, type CreateMockInput, type CreatePostInput, type CreateSessionInput, type Draft, type Knobs, type Mock, type Post, type PostQuery, type PostStatus, type PostVersion, type Session, type Embed, type Flow, type FlowStep, type ForkRef, type SqlStorage, type Store, type Surface, type UpdateMockInput, type UpdatePostInput } from "./types.ts";
 export declare class SqlStore implements Store {
     private sql;
     private assetRefCache;
@@ -8,6 +8,7 @@ export declare class SqlStore implements Store {
     private columns;
     private addMissing;
     private migrate;
+    private migrateToContractTerms;
     private createIndexes;
     private migrateLegacy;
     private migrateToSurfaces;
@@ -16,6 +17,7 @@ export declare class SqlStore implements Store {
     private migrateToItems;
     private migrateToVersions;
     private migrateToMocks;
+    private migrateToSketches;
     private settingSync;
     private insertVersion;
     private rowToVersion;
@@ -45,6 +47,8 @@ export declare class SqlStore implements Store {
     createMock(input: CreateMockInput): Promise<Mock>;
     updateMock(id: string, patch: UpdateMockInput): Promise<Mock | null>;
     removeMock(id: string): Promise<boolean>;
+    renameMock(id: string, slug: string): Promise<Mock | null>;
+    renameProject(from: string, to: string): Promise<boolean>;
     private flowsOf;
     private writeFlow;
     listFlows(project: string): Promise<Flow[]>;
@@ -55,13 +59,16 @@ export declare class SqlStore implements Store {
         project: string;
         slug: string;
         title: string;
-        kind: MockKind;
+        kind: import("./types.ts").MockKind;
+        area: string | null;
+        source: string | null;
         states: string[];
+        situations: Record<string, string[]>;
         asks: Ask[];
         knobs: Knobs;
         widths: number[];
         sessionId: string | null;
-        resolvedAt: string | null;
+        closedAt: string | null;
         createdAt: string;
         updatedAt: string;
     } | null>;