mockpit 1.3.0 → 3.0.0

package/dist/server/mcpSpec.js

@@ -4,23 +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 " +
-    "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 " +
+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",
     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",
@@ -28,13 +28,19 @@ 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]",
-    flow: "Flow this screen is a step of; alone, only places it",
+    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",
     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 +59,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,10 +81,14 @@ 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(),
+    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
@@ -90,6 +101,10 @@ 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"),
     })),
 });
 function zodParam(p) {
@@ -113,6 +128,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();
     }
@@ -121,37 +139,42 @@ 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,
             title: { t: "string", d: field.title },
-            kind: { t: "enum", values: ["component", "page"] },
+            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 },
+            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 },
             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 },
@@ -163,9 +186,9 @@ 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 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,
@@ -174,21 +197,25 @@ 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: "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 uses and is used 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, 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 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 },
@@ -197,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 },
@@ -205,11 +232,51 @@ 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.",
         params: VARIANT_REF,
     },
+    {
+        name: "edit",
+        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: {
+            design: { t: "string", d: field.design },
+            project: P.project,
+            slug: { t: "string" },
+            title: { t: "string" },
+            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 design: 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.",
@@ -263,52 +330,69 @@ 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(),
         })),
-        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 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 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
-        .literal(true)
-        .optional()
-        .describe("The user resolved the mock: its open asks were closed unanswered"),
-    dismissed: z
-        .array(o({ ask: str, text: str }))
+    edited: o({
+        kind: str.optional(),
+        area: nullStr.optional(),
+        notes: nullStr.optional(),
+    })
         .optional()
-        .describe("The asks the resolution closed; don't ask them again"),
+        .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,
-    resolved: 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"),
+    suggestedFillAsks: z
+        .array(bag)
+        .optional()
+        .describe("A question per part with fills that none sets; send with ask"),
     flow: flowSchema.optional(),
     feedback: feedbackRide,
 };
@@ -338,21 +422,43 @@ 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(),
+        url: str,
+        nudges: strs.optional(),
+        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
             .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()
@@ -367,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({
@@ -375,7 +494,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 +515,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/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/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.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

@@ -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
@@ -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,18 @@ 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));
+                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)
@@ -201,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 }[];\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 = { 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: \"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({ 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;