mockpit 2.0.0 → 3.0.0

package/dist/server/mcpSpec.js

@@ -4,24 +4,23 @@ import { GUIDE_TOPICS } from "./designGuide.js";
 import { feedbackImages } from "./feedbackBatch.js";
 import { KIT_IDS } from "./kits.js";
 import { RUN_DESCRIPTION } from "./runApi.js";
-import { SURFACE_KINDS } from "./types.js";
+import { MAX_NOTES, SURFACE_KINDS } from "./types.js";
 export const MCP_SERVER_INFO = { name: "mockpit", version: "0.2.0" };
 // The `kind` enum both MCP transports advertise — derived from the one canonical
 // 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 " +
+export const MCP_INSTRUCTIONS = "Mockpit shows design work to the user: project > design > state > variant > version. publish " +
     "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",
+    design: "Design slug, title 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",
+    title: "Design title",
     session: "Session id from an earlier publish",
     sessionTitle: "Task name; used only when creating the session",
     agent: "Agent name for a new session",
@@ -29,11 +28,13 @@ 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",
+    amend: "Replace the latest version in place: a fix before the user acts on it",
+    withdraw: "Take the latest version back, before the user acts on it",
     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",
+    description: "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",
+    kind: "Only when building the product's screens: screen, component (a reusable design screens embed). With no html it plans one, drawn by a later publish. Omit for ideas, 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",
@@ -82,8 +83,12 @@ export const mcpSurfaceSchema = z
 const askSchema = z.object({
     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(),
+    scope: z.enum(["design", "state", "part"]).optional(),
     state: z.string().optional(),
+    states: z
+        .array(z.string())
+        .optional()
+        .describe("Design-wide question: the states its answers can be seen on, best first"),
     part: z.string().optional().describe("data-part name, for scope part"),
     multi: z.boolean().optional(),
     after: z
@@ -96,6 +101,9 @@ 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}"),
+        style: z.string().optional().describe("With a set of a new value: its CSS"),
+        fill: z.string().optional().describe("With a set of {part: new fill}: its html"),
+        html: z.string().optional().describe("Or a whole page"),
         recommended: z.boolean().optional().describe("The one you would pick; one per ask"),
     })),
 });
@@ -131,22 +139,21 @@ function zodParam(p) {
     return p.req ? s : s.optional();
 }
 const P = {
-    mock: { t: "string", d: field.mock, req: true },
+    design: { t: "string", d: field.design, req: true },
     state: { t: "string", d: field.state },
     variant: { t: "string", d: field.variant },
     project: { t: "string", d: field.project },
     session: { t: "string", d: field.session },
 };
-const VARIANT_REF = { mock: P.mock, state: P.state, variant: P.variant, project: P.project };
+const VARIANT_REF = { design: P.design, state: P.state, variant: P.variant, project: P.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), parts or fills (splice the latest version). Returns parts per state, nudges, feedback.",
+        description: "Create or version one variant of one state of a design. One of html, surfaces (the full ordered list), parts or fills (splice the latest version); or kind screen or component and none of them, to plan it. 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: ["page", "component", "sketch"], d: field.kind },
+            kind: { t: "enum", values: ["screen", "component", "idea"], d: field.kind },
             area: { t: "string", d: field.area },
             source: { t: "string", d: field.source },
             html: { t: "string", d: field.html },
@@ -164,8 +171,10 @@ export const MCP_TOOL_DEFS = [
             variantKnobs: { t: "object", d: field.variantKnobs },
             from: { t: "integer", d: field.from },
             fork: { t: "string", d: field.fork },
+            amend: { t: "boolean", d: field.amend },
+            withdraw: { t: "boolean", d: field.withdraw },
             prompt: { t: "string", d: field.prompt },
-            note: { t: "string", d: field.note },
+            description: { t: "string", d: field.description },
             widths: { t: "integers", d: field.widths },
             flow: { t: "string", d: field.flow },
             step: { t: "integer", d: field.step },
@@ -177,9 +186,9 @@ export const MCP_TOOL_DEFS = [
     },
     {
         name: "ask",
-        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.",
+        description: "Ask structured questions on a design. 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,
+            design: P.design,
             project: P.project,
             asks: { t: "asks", d: "Questions with options", req: true },
             session: P.session,
@@ -188,21 +197,25 @@ export const MCP_TOOL_DEFS = [
     },
     {
         name: "read",
-        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.",
+        description: "Read this first. Both forms carry decisionList: what the user already settled in this project; it stands unless they say otherwise. Without design: every design (slug, states, variants, open questions), flows, plus pending. With design: its notes (a spec; the user's edits stand), 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 },
+            design: { t: "string", d: field.design },
             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)",
+                d: "Without design: the project as a tree (each design's variants with status and forkedFrom, the designs it embeds and is embedded in)",
+            },
+            decisions: {
+                t: "boolean",
+                d: "Only the whole decision list, when decisionList says it was cut",
             },
         },
     },
     {
         name: "feedback",
-        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).",
+        description: "Returns at once: what the user sent since you last heard (one batch per design: reply answers, borrowed parts, tuned knobs, part comments, verdict; thread messages; inUse/archived), delivered once, plus pending (viewer open, draft progress).",
         params: {
             project: P.project,
             session: { t: "string", d: "Session id returned by publish", req: true },
@@ -211,7 +224,7 @@ export const MCP_TOOL_DEFS = [
     },
     {
         name: "say",
-        description: "Post a short plain-text message in a mock's thread. Returns feedback.",
+        description: "Post a short plain-text message in a design's thread. Returns feedback.",
         params: {
             ...VARIANT_REF,
             message: { t: "string", d: "Plain text", req: true },
@@ -219,6 +232,24 @@ export const MCP_TOOL_DEFS = [
         },
         httpOnly: ["session"],
     },
+    {
+        name: "move",
+        description: "Tidy up variants: to or toState moves them there and out of here; archive takes them out of view; restore brings them back; a group goes along; one in use stays. Only when the user asks: hideOlder hides each variant's older versions (variants optional: all of them), and deleteOlder deletes them for good, skipping any that a reply, comment, question, embed, copy or fork still points at, or that is in use. Confirm a delete first: it can't be undone. Returns feedback.",
+        params: {
+            design: P.design,
+            state: P.state,
+            variants: { t: "strings", d: "Variant names; required except with hideOlder or deleteOlder" },
+            to: { t: "string", d: "Target design; default this one" },
+            toState: { t: "string", d: "Target state; created if new" },
+            archive: { t: "boolean" },
+            restore: { t: "boolean" },
+            hideOlder: { t: "boolean", d: "Hide all but each variant's newest visible version" },
+            deleteOlder: { t: "boolean", d: "Delete them instead; permanent, skips what's referenced" },
+            project: P.project,
+            session: P.session,
+        },
+        httpOnly: ["session"],
+    },
     {
         name: "export",
         description: "The html in use (else current) per state, version history, screenshot URL, knobs, the settled values and the last reply.",
@@ -226,17 +257,22 @@ export const MCP_TOOL_DEFS = [
     },
     {
         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.",
+        description: "Change a design without a new version; a new slug rewrites every reference to the old one. Without design, rename renames the project and areaOrder orders its areas. Returns feedback.",
         params: {
-            mock: { t: "string", d: field.mock },
+            design: { t: "string", d: field.design },
             project: P.project,
             slug: { t: "string" },
             title: { t: "string" },
-            kind: { t: "enum", values: ["page", "component", "sketch"] },
+            kind: { t: "enum", values: ["screen", "component", "idea"] },
             area: { t: "string" },
             source: { t: "string" },
+            firstState: { t: "string", d: "Names a design's one unnamed state, so it can have more" },
+            notes: {
+                t: "string",
+                d: `A short plain-text spec, at most ${MAX_NOTES} characters; "" clears. Not applied over the user's own edit, and the result says so`,
+            },
             rename: { t: "string", d: "New project name" },
-            areaOrder: { t: "strings", d: "Without mock: Home's area order" },
+            areaOrder: { t: "strings", d: "Without design: Home's area order" },
             session: P.session,
         },
         httpOnly: ["session"],
@@ -294,14 +330,14 @@ 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 flowSchema = o({ name: str, steps: z.array(o({ design: str, state: nullStr })) });
 const feedbackSchema = o({
-    mock: nullStr,
+    design: nullStr,
     reply: o({
         asks: z.array(o({
             ask: str,
             chosen: z.array(o({ label: str, other: z.literal(true).optional() })),
-            note: str.optional(),
+            description: str.optional(),
         })),
         borrowed: bag.describe("Part → the variant to take it from"),
         tuned: bag,
@@ -309,39 +345,47 @@ const feedbackSchema = o({
         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"),
+            .describe("Use this or New version on one variant"),
+        more: o({
+            ask: str,
+            text: str,
+            existing: strs,
+            note: str.optional(),
+            answered: z.array(o({ ask: str, text: str, chosen: strs, comment: str.optional() })),
+        })
+            .optional()
+            .describe("The user wants more answers to this question: ask it again, same id, with them"),
     })
         .nullable()
         .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() })
+    edited: o({
+        kind: str.optional(),
+        area: nullStr.optional(),
+        notes: nullStr.optional(),
+    })
         .optional()
-        .describe("The user moved the mock from Home: its kind or area now"),
+        .describe("The user moved the design from Home (its kind or area now) or edited its notes"),
 }).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(),
+    design: str,
+    archived: z.literal(true).optional(),
     viewerOpen: z.boolean(),
     draft: o({ answered: num, of: num, comments: num, touchedAt: str }).nullable(),
 }).meta({ id: "Pending" });
 const writeOutput = {
-    post: o({ state: nullStr, variant: str, version: num }),
+    post: o({ state: nullStr, variant: str, version: num })
+        .optional()
+        .describe("Absent when planned: nothing is drawn yet"),
+    planned: z.boolean().optional(),
     sessionId: str,
     url: str.describe("Viewer link for the user"),
-    parts: partsByState,
+    parts: partsByState.optional(),
     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"),
@@ -378,10 +422,25 @@ const OUTPUT_SCHEMAS = {
         feedback: feedbackRide,
     },
     feedback: {
-        feedback: z.array(feedbackSchema).describe("One batch per mock; empty when nothing is new"),
+        feedback: z.array(feedbackSchema).describe("One batch per design; empty when nothing is new"),
         pending: z.array(pendingSchema),
     },
     say: { feedback: feedbackRide },
+    move: {
+        variants: z.array(o({ state: str.nullable(), variant: str, status: str })),
+        versions: z
+            .array(o({ state: str.nullable(), variant: str, version: num }))
+            .optional()
+            .describe("With hideOlder or deleteOlder: what was hidden or deleted"),
+        skipped: z.array(o({ state: str.nullable().optional(), variant: str, version: num.optional(), why: str })),
+        to: o({ design: str, title: str, state: str.nullable() }).optional(),
+        saved: z
+            .array(o({ state: str.nullable(), variant: str, already: z.boolean() }))
+            .optional()
+            .describe("What each is called there"),
+        url: str,
+        feedback: feedbackRide,
+    },
     edit: {
         renamed: o({ from: str, to: str }).optional(),
         areaOrder: strs.optional(),
@@ -390,7 +449,7 @@ const OUTPUT_SCHEMAS = {
         feedback: feedbackRide,
     },
     read: {
-        mocks: z.array(o({ slug: str, states: strs, variants: num, open: num })).optional(),
+        designs: 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
@@ -414,7 +473,20 @@ const OUTPUT_SCHEMAS = {
         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]),
+        decisionList: o({
+            total: num,
+            lines: z.array(o({
+                design: str,
+                text: str,
+                here: z.boolean().optional().describe("From the design read"),
+                edited: z.boolean().optional(),
+                archived: z.boolean().optional(),
+            })),
+            more: str.optional(),
+        }).optional(),
+        total: num.optional(),
+        lines: z.array(bag).optional(),
+        pending: z.union([z.array(pendingSchema), pendingSchema]).optional(),
     },
     export: {
         states: z.array(o({

package/dist/server/parts.js

@@ -48,8 +48,16 @@ export function partsInHtml(html) {
     }
     return [...byName.values()];
 }
+// Cached per surfaces array, which a stored post never mutates: a design's view
+// asks for every variant's parts on every read. Callers must not change the result.
+const bySurfaces = new WeakMap();
 export function partsInSurfaces(surfaces) {
-    return mergeParts(surfaces.flatMap((s) => (s.kind === "html" ? [partsInHtml(s.html)] : [])));
+    const hit = bySurfaces.get(surfaces);
+    if (hit)
+        return hit;
+    const parts = mergeParts(surfaces.flatMap((s) => (s.kind === "html" ? [partsInHtml(s.html)] : [])));
+    bySurfaces.set(surfaces, parts);
+    return parts;
 }
 // Union several part lists by name, first occurrence first.
 export function mergeParts(lists) {

package/dist/server/run.d.ts

@@ -77,6 +77,6 @@ export interface RunDeps {
         status: number;
     }>;
 }
-export declare const RUN_UNAVAILABLE = "run is not available on this deployment: it has no script sandbox. Use the mock tools (or REST) instead";
+export declare const RUN_UNAVAILABLE = "run is not available on this deployment: it has no script sandbox. Use the design tools (or REST) instead";
 export declare function cut(s: string, max: number): string;
 export declare function createRunFlow(deps: RunDeps): (body: any, ctx: FlowContext) => Promise<FlowResult>;

package/dist/server/run.js

@@ -26,7 +26,7 @@ export const DEFAULT_RUN_LIMITS = {
     maxInflight: 4,
     maxRuns: 4,
 };
-export const RUN_UNAVAILABLE = "run is not available on this deployment: it has no script sandbox. Use the mock tools (or REST) instead";
+export const RUN_UNAVAILABLE = "run is not available on this deployment: it has no script sandbox. Use the design tools (or REST) instead";
 const text = (v, max) => typeof v === "string" && v.trim() ? v.trim().slice(0, max) : undefined;
 const plain = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : {};
 // Keep the head and the tail: the start says what a value is, the end is where
@@ -40,7 +40,7 @@ export function cut(s, max) {
 }
 function writeSummary(body) {
     const post = body?.post;
-    const slug = body?.mock?.slug ?? "?";
+    const slug = body?.design?.slug ?? "?";
     if (!post)
         return slug;
     return `${slug}/${post.state ? `${post.state}/` : ""}${post.variant} v${post.version}`;
@@ -152,26 +152,30 @@ export function createRunFlow(deps) {
                     throw new Error(unknownTopicMessage(String(topic)));
                 return [await deps.guide("", topic), String(topic)];
             },
-            async read([mock, opts]) {
-                if ((mock === undefined || mock === null) && plain(opts).tree === true) {
+            async read([design, opts]) {
+                if (plain(opts).decisions === true) {
+                    const value = await take(flows.decisions({ project: await projectOf() }));
+                    return [value, `${value.total} decisions`];
+                }
+                if ((design === undefined || design === null) && plain(opts).tree === true) {
                     const value = await take(flows.tree({ project: await projectOf() }));
-                    return [value, `${value.tree.length} mocks`];
+                    return [value, `${value.tree.length} designs`];
                 }
-                if (mock === undefined || mock === null) {
+                if (design === undefined || design === null) {
                     const value = await take(flows.list({ project: await projectOf() }));
-                    return [value, `${value.mocks.length} mocks`];
+                    return [value, `${value.designs.length} designs`];
                 }
                 const o = plain(opts);
-                const value = await take(flows.get(mock, { project, body: o.body === true, history: o.history === true }));
-                return [value, String(value?.slug ?? mock)];
+                const value = await take(flows.get(design, { project, body: o.body === true, history: o.history === true }));
+                return [value, String(value?.slug ?? design)];
             },
             async publish([v]) {
                 const value = await take(flows.publish({ ...(await mine(plain(v))), agent }, flowCtx));
                 return [value, writeSummary(value)];
             },
-            async ask([mock, asks]) {
-                const value = await take(flows.ask(mock, await mine({ asks }), flowCtx));
-                return [value, `${value.mock} ${value.asks.length} ask(s)`];
+            async ask([design, asks]) {
+                const value = await take(flows.ask(design, await mine({ asks }), flowCtx));
+                return [value, `${value.design} ${value.asks.length} ask(s)`];
             },
             async feedback() {
                 const value = await take(flows.feedback(await mine({}), flowCtx));
@@ -180,8 +184,13 @@ export function createRunFlow(deps) {
             },
             async say([v, message]) {
                 const r = plain(v);
-                await take(flows.say(r.mock, { ...(await mine(r)), message }, flowCtx));
-                return [null, String(r.mock ?? "?")];
+                await take(flows.say(r.design, { ...(await mine(r)), message }, flowCtx));
+                return [null, String(r.design ?? "?")];
+            },
+            async move([v]) {
+                const r = plain(v);
+                const value = await take(flows.move(r.design, await mine(r), flowCtx));
+                return [value, `${value.variants.length} moved`];
             },
             async edit([v]) {
                 const r = await mine(plain(v));
@@ -206,8 +215,8 @@ export function createRunFlow(deps) {
             },
             async export([v]) {
                 const r = plain(v);
-                const value = await take(flows.exportMock(r.mock, { ...r, project }, flowCtx));
-                return [value, `${value.mock} ${value.states.length} state(s)`];
+                const value = await take(flows.exportDesign(r.design, { ...r, project }, flowCtx));
+                return [value, `${value.design} ${value.states.length} state(s)`];
             },
         };
         const call = (name, argsJson) => {

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; 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 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 = { design: 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?: \"design\" | \"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 }; planned?: true; 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  design: string | null;\n  reply: null | { asks: { ask: string; chosen: { id: string; label: string; other?: true }[]; comment?: 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};\ntype Pending = { design: string; archived?: 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  /** Read first: decisionList is what the user already settled; it stands unless they say otherwise.\n   * No design: every design, the flows, plus pending. With one: its states, variants, asks, parts, knobs.\n   * opts.decisions: only the whole list, when a read cut it. */\n  read(design?: string, opts?: { body?: boolean; history?: boolean; decisions?: boolean }): Promise<unknown>;\n  /** Creates or versions (design, 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   * None of them, with kind screen or component: plans it, for a later publish to draw. */\n  publish(v: Ref & { title?: string; kind?: \"screen\" | \"component\" | \"idea\"; 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; description?: string; widths?: number[]; flow?: string; step?: number }): Promise<Written>;\n  ask(design: 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  /** to or toState moves variants there; archive hides them; restore brings them back. */\n  move(v: Ref & { variants: string[]; to?: string; toState?: string; archive?: boolean; restore?: boolean }): Promise<{ variants: { state: string | null; variant: string; status: string }[]; skipped: { variant: string; why: string }[]; url: string }>;\n  /** No new version; \"\" clears. { rename } or { areaOrder } without design edits the project.\n   * notes: a short plain-text spec; not applied over the user's own edit (notes.applied says). */\n  edit(v: { design?: string; slug?: string; title?: string; kind?: string; area?: string; source?: string; firstState?: string; notes?: string; rename?: string; areaOrder?: string[] }): Promise<{ url: string; notes?: { applied: boolean; text?: 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", "move", "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: \"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_EXAMPLE = "const html = (tone) => `<section data-part=\"hero\" class=\"${tone}\"><h1>Writer</h1></section>`;\nawait mockpit.publish({ design: \"writer\", variant: \"calm\", html: html(\"calm\") });\nawait mockpit.publish({ design: \"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

@@ -8,7 +8,7 @@ export const RUN_API = `// The body of an async function, in plain JavaScript (n
 // \`await mockpit.*\`, \`return\` a JSON value, print() adds an output line.
 // No network, timers, imports or process. Session, project and agent are fixed
 // for the run; pass the returned session to the next run.
-type Ref = { mock: string; state?: string; variant?: string };
+type Ref = { design: string; state?: string; variant?: string };
 type Knobs = Record<string, unknown>; // path → [default,min,max,step] | boolean | {type:"select",options} | "#hex"
 type Surface =
   | { kind: "html"; html: string; kits?: string[] }
@@ -20,37 +20,42 @@ type Surface =
   | { kind: "json"; data: unknown; title?: string }
   | { kind: "code"; code: string; language?: string; lineStart?: number };
 type Ask = {
-  id?: string; text: string; scope?: "mock" | "state" | "part"; state?: string; part?: string; multi?: boolean;
+  id?: string; text: string; scope?: "design" | "state" | "part"; state?: string; part?: string; multi?: boolean;
   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 }[] }[];
+  post?: { state: string | null; variant: string; version: number }; planned?: true; url: string;
+  parts?: { state: string | null; parts: { name: string }[] }[];
   partChanges?: { vanished: string[]; renamed: { from: string; to: string }[] };
   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 }[]; borrowed: Record<string, string>; tuned: Knobs; comments: { part: string | null; text: string }[]; verdict?: { kind: "use" | "revise"; state: string | null; variant: string; version?: number } };
+  design: string | null;
+  reply: null | { asks: { ask: string; chosen: { id: string; label: string; other?: true }[]; comment?: 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; closed?: true; viewerOpen: boolean; draft: null | { answered: number; of: number; comments: number; touchedAt: string } };
+type Pending = { design: string; archived?: 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
+  /** Read first: decisionList is what the user already settled; it stands unless they say otherwise.
+   * No design: every design, the flows, plus pending. With one: its states, variants, asks, parts, knobs.
+   * opts.decisions: only the whole list, when a read cut it. */
+  read(design?: string, opts?: { body?: boolean; history?: boolean; decisions?: boolean }): Promise<unknown>;
+  /** Creates or versions (design, 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 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[] }>;
+   * fills {"part#fill": outer html}, replacing or adding one fill of a part.
+   * None of them, with kind screen or component: plans it, for a later publish to draw. */
+  publish(v: Ref & { title?: string; kind?: "screen" | "component" | "idea"; 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; description?: string; widths?: number[]; flow?: string; step?: number }): Promise<Written>;
+  ask(design: 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>;
-  /** 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 }>;
+  /** to or toState moves variants there; archive hides them; restore brings them back. */
+  move(v: Ref & { variants: string[]; to?: string; toState?: string; archive?: boolean; restore?: boolean }): Promise<{ variants: { state: string | null; variant: string; status: string }[]; skipped: { variant: string; why: string }[]; url: string }>;
+  /** No new version; "" clears. { rename } or { areaOrder } without design edits the project.
+   * notes: a short plain-text spec; not applied over the user's own edit (notes.applied says). */
+  edit(v: { design?: string; slug?: string; title?: string; kind?: string; area?: string; source?: string; firstState?: string; notes?: string; rename?: string; areaOrder?: string[] }): Promise<{ url: string; notes?: { applied: boolean; text?: 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 }>;
@@ -64,18 +69,19 @@ export const RUN_FUNCTIONS = [
     "ask",
     "feedback",
     "say",
+    "move",
     "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") });
+await mockpit.publish({ design: "writer", variant: "calm", html: html("calm") });
+await mockpit.publish({ design: "writer", variant: "bold", html: html("bold") });
 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;`;
-export const RUN_DESCRIPTION = "Run a script against mockpit, which shows design work to the user (project > mock > state > " +
+export const RUN_DESCRIPTION = "Run a script against mockpit, which shows design work to the user (project > design > state > " +
     "variant > version). Publish variants and ask in one call; nothing waits for the user. Returns " +
     "value, prints, calls (every host call in order: which writes landed), error {kind, message, " +
     "line} and feedback (every batch received, even if the script failed). Read mockpit.guide() " +