mockpit 2.0.0 → 3.1.0

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}`;
@@ -150,28 +150,35 @@ export function createRunFlow(deps) {
                     return [await deps.guide(await projectOf()), "brief"];
                 if (!isGuideTopic(topic))
                     throw new Error(unknownTopicMessage(String(topic)));
-                return [await deps.guide("", topic), String(topic)];
+                return [
+                    await deps.guide(topic === "system" ? await projectOf() : "", 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 +187,27 @@ 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 system([v]) {
+                const given = plain(v ?? {});
+                const named = project ?? (typeof given.project === "string" ? given.project : undefined);
+                const writing = Object.keys(given).some((k) => !["session", "project", "agent"].includes(k));
+                // A write lands on a project the script names, never on whichever is first.
+                if (writing && !named)
+                    throw new Error("system writes need a project: pass {project} to run, or run in a session that has one");
+                const r = await mine(given);
+                const value = await take(flows.system(named ?? (await projectOf()), r, flowCtx));
+                return [
+                    value,
+                    value.changed?.length ? `r${value.rev}: ${value.changed.join("; ")}` : `r${value.rev}`,
+                ];
             },
             async edit([v]) {
                 const r = await mine(plain(v));
@@ -206,8 +232,12 @@ 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)`];
+                if (r.design === undefined) {
+                    const value = await take(flows.exportSystem(r.project ?? project ?? (await projectOf())));
+                    return [value, `${value.project} system r${value.rev}`];
+                }
+                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; palette?: string; 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  system?: { rev: number; changes: 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?: \"system\" | \"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  /** The project's system: sheet, tokens, scales, palettes, project knobs. No argument reads it;\n   * each key replaces its part (tokens, scales, palettes upsert by name). Applies to every design at once. */\n  system(v?: { sheet?: string; classes?: { name: string; note: string }[]; fonts?: { family: string; href?: string }[]; tokens?: unknown[]; scales?: unknown[]; roles?: { name: string; note: string }[]; palettes?: unknown[]; pairs?: [string, string, number][]; as?: Record<string, string>; knobs?: Knobs; remove?: { tokens?: string[]; palettes?: string[]; scales?: string[] }; restore?: number }): Promise<{ rev: number; changed?: string[]; kept?: string[]; checks: string[]; url: string }>;\n  export(v: Ref): Promise<{ states: { state: string | null; variant: string; version: number; html: string; allFills?: string }[]; reply: unknown }>;\n  /** Without design: the project's system for code. css holds the default palette on :root and kept ones by [data-palette]. */\n  export(v: {}): Promise<{ rev: number; sheet: string; css: string; tokens: unknown; knobs: Record<string, unknown>; additions: { knob: string; value: string; style: string }[]; components: { slug: string; purpose: string; source: string | null }[] }>;\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", "system", "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,38 +20,49 @@ 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;
-  options: { id?: string; label: string; variant?: string; set?: Knobs; recommended?: boolean }[];
+  id?: string; text: string; scope?: "design" | "state" | "part"; state?: string; part?: string; multi?: boolean;
+  options: { id?: string; label: string; variant?: string; set?: Knobs; palette?: string; 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 }[];
+  system?: { rev: number; changes: 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
+  guide(topic?: "system" | "knobs" | "asks" | "surfaces" | "html" | "feedback" | "http" | "scripts"): Promise<string>;
+  /** 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 } }>;
+  /** The project's system: sheet, tokens, scales, palettes, project knobs. No argument reads it;
+   * each key replaces its part (tokens, scales, palettes upsert by name). Applies to every design at once. */
+  system(v?: { sheet?: string; classes?: { name: string; note: string }[]; fonts?: { family: string; href?: string }[]; tokens?: unknown[]; scales?: unknown[]; roles?: { name: string; note: string }[]; palettes?: unknown[]; pairs?: [string, string, number][]; as?: Record<string, string>; knobs?: Knobs; remove?: { tokens?: string[]; palettes?: string[]; scales?: string[] }; restore?: number }): Promise<{ rev: number; changed?: string[]; kept?: string[]; checks: string[]; url: string }>;
   export(v: Ref): Promise<{ states: { state: string | null; variant: string; version: number; html: string; allFills?: string }[]; reply: unknown }>;
+  /** Without design: the project's system for code. css holds the default palette on :root and kept ones by [data-palette]. */
+  export(v: {}): Promise<{ rev: number; sheet: string; css: string; tokens: unknown; knobs: Record<string, unknown>; additions: { knob: string; value: string; style: string }[]; components: { slug: string; purpose: string; source: string | null }[] }>;
   /** 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 +75,20 @@ export const RUN_FUNCTIONS = [
     "ask",
     "feedback",
     "say",
+    "move",
     "edit",
+    "system",
     "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() " +

package/dist/server/sqlStore.d.ts

@@ -1,13 +1,26 @@
-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";
+import { type Ask, type JumpRows, type DesignKind, type Asset, type Comment, type CommentQuery, type CommitReplyInput, type CreateAssetInput, type CreateCommentInput, type CreateDesignInput, type CreatePostInput, type CreateSessionInput, type Draft, type Knobs, type Design, type DesignNotes, type AnswerAddition, type AnswerSet, type AnswerStanding, type StateOutline, type Post, type CopyRef, type LiveCopy, type PostHead, type PostQuery, type PostStatus, type PostVersion, type Reply, type Session, type Embed, type Flow, type FlowStep, type ForkRef, type SqlStorage, type Store, type Surface, type UpdateDesignInput, type UpdatePostInput, type AmendPostInput, type DecisionVariant } from "./types.ts";
+import { type System } from "./system.ts";
+import type { Mode } from "./themes.ts";
 export declare class SqlStore implements Store {
     private sql;
     private assetRefCache;
-    constructor(sql: SqlStorage);
+    private postCache;
+    private postCacheBytes;
+    private postCacheLimit;
+    private raw;
+    private holdPostDrop;
+    constructor(sql: SqlStorage, opts?: {
+        postCacheBytes?: number;
+    });
     private atomic;
     private tables;
     private columns;
     private addMissing;
+    private migrateToDesignWords;
+    private migrateAskScopeWord;
+    private renameMocksToDesigns;
     private migrate;
+    private migrateSituations;
     private migrateToContractTerms;
     private createIndexes;
     private migrateLegacy;
@@ -16,7 +29,7 @@ export declare class SqlStore implements Store {
     private migrateSurfaceIds;
     private migrateToItems;
     private migrateToVersions;
-    private migrateToMocks;
+    private migrateToDesigns;
     private migrateToSketches;
     private settingSync;
     private insertVersion;
@@ -24,7 +37,7 @@ export declare class SqlStore implements Store {
     private historiesFor;
     private rowsToPosts;
     private rowToSession;
-    private rowToMock;
+    private rowToDesign;
     private rowToPost;
     private rowToAsset;
     private rowToComment;
@@ -41,165 +54,197 @@ export declare class SqlStore implements Store {
     getSetting(key: string): Promise<string | null>;
     setSetting(key: string, value: string): Promise<void>;
     listProjects(): Promise<import("./types.ts").ProjectSummary[]>;
-    listMocks(project?: string): Promise<Mock[]>;
-    getMock(id: string): Promise<Mock | null>;
-    findMock(project: string, slug: string): Promise<Mock | null>;
-    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>;
+    listJumpRows(): Promise<JumpRows>;
+    listDesigns(project?: string): Promise<Design[]>;
+    getDesign(id: string): Promise<Design | null>;
+    findDesign(project: string, slug: string): Promise<Design | null>;
+    createDesign(input: CreateDesignInput): Promise<Design>;
+    updateDesign(id: string, patch: UpdateDesignInput): Promise<Design | null>;
+    removeDesign(id: string): Promise<boolean>;
+    nameFirstState(id: string, state: string): Promise<Design | null>;
+    renameDesign(id: string, slug: string): Promise<Design | null>;
     renameProject(from: string, to: string): Promise<boolean>;
+    getSystem(project: string): Promise<System | null>;
+    putSystem(system: System, meta: {
+        sessionId: string | null;
+        summary: string;
+    }): Promise<System>;
+    commitSystemDecision(input: {
+        system: System;
+        summary: string;
+        tell: {
+            sessionId: string;
+            payload: Reply;
+        } | null;
+    }): Promise<Comment | null>;
+    private writeSystem;
+    listSystemRevisions(project: string): Promise<{
+        rev: number;
+        at: string;
+        sessionId: string | null;
+        summary: string;
+    }[]>;
+    getSystemRevision(project: string, rev: number): Promise<System | null>;
+    private migrateSystems;
     private flowsOf;
     private writeFlow;
     listFlows(project: string): Promise<Flow[]>;
     placeFlowStep(project: string, name: string, screen: FlowStep, step: number): Promise<Flow | null>;
-    putDraft(mockId: string, draft: Draft | null): Promise<{
-        draft: Draft | null;
+    putDraft(designId: string, draft: Draft | null): Promise<{
         id: string;
         project: string;
         slug: string;
         title: string;
-        kind: import("./types.ts").MockKind;
+        kind: DesignKind;
         area: string | null;
         source: string | null;
         states: string[];
-        situations: Record<string, string[]>;
         asks: Ask[];
         knobs: Knobs;
         widths: number[];
         sessionId: string | null;
-        closedAt: string | null;
+        shortlist: boolean;
+        archivedAt: string | null;
+        archiveReason: string | null;
+        notes: DesignNotes | null;
+        stateOutlines: Record<string, StateOutline>;
+        answerAdditions: AnswerAddition[];
+        standings: Record<string, AnswerStanding>;
+        sets: AnswerSet[];
         createdAt: string;
         updatedAt: string;
+        draft: Draft | null;
     } | null>;
-    private touchMock;
+    private touchDesign;
     listPosts(query?: PostQuery): Promise<Post[]>;
+    listPostHeads(project?: string): Promise<PostHead[]>;
+    listCopies(project: string): Promise<LiveCopy[]>;
+    private postsOfDesign;
+    private trimPostCache;
+    private writingPosts;
+    private cachedPost;
+    private recache;
     countPostsBySession(): Promise<Map<string, number>>;
     getPost(id: string): Promise<Post | null>;
-    findPost(mockId: string, state: string | null, variant: string): Promise<Post | null>;
+    findPost(designId: string, state: string | null, variant: string): Promise<Post | null>;
     createPost(input: CreatePostInput): Promise<Post | null>;
     updatePost(id: string, patch: UpdatePostInput): Promise<{
-        author?: string | undefined;
-        embeds: Embed[];
-        state: string | null;
-        version: number;
-        updatedAt: string;
-        history: PostVersion[];
-        from: number;
-        prompt: string;
-        note?: string | undefined;
-        knobs?: Knobs | undefined;
-        title: string;
-        surfaces: Surface[];
         id: string;
         sessionId: string;
-        mock: string;
+        design: string;
         variant: string;
         status: PostStatus;
         createdAt: string;
         forkedFrom?: ForkRef;
-        starred?: true;
+        copiedFrom?: CopyRef;
         acceptedVersion?: number;
         hiddenVersions?: number[];
-    } | null>;
-    removePost(id: string): Promise<boolean>;
-    setPostStatus(id: string, status: PostStatus, acceptedVersion?: number): Promise<{
-        status: PostStatus;
-        id: string;
-        sessionId: string;
-        mock: string;
-        state: string | null;
-        variant: string;
+        archiveReason?: string;
+        archivedAt?: string;
+        stayedVersion?: number;
+        rewrites?: number;
+        contract: number;
+        system?: number | undefined;
         title: string;
         surfaces: Surface[];
-        createdAt: string;
-        updatedAt: string;
-        version: number;
-        history: PostVersion[];
-        knobs?: Knobs;
-        note?: string;
+        knobs?: Knobs | undefined;
+        description?: string | undefined;
         embeds: Embed[];
-        forkedFrom?: ForkRef;
-        starred?: true;
-        hiddenVersions?: number[];
-        from?: number;
-        prompt?: string;
-        author?: string;
-    } | {
-        status: PostStatus;
-        acceptedVersion: number;
-        id: string;
-        sessionId: string;
-        mock: string;
         state: string | null;
-        variant: string;
-        title: string;
-        surfaces: Surface[];
-        createdAt: string;
-        updatedAt: string;
         version: number;
+        updatedAt: string;
         history: PostVersion[];
-        knobs?: Knobs;
-        note?: string;
-        embeds: Embed[];
-        forkedFrom?: ForkRef;
-        starred?: true;
-        hiddenVersions?: number[];
-        from?: number;
-        prompt?: string;
-        author?: string;
+        from: number;
+        prompt: string;
+        author?: string | undefined;
+        publishedBy?: string | undefined;
     } | null>;
-    setPostStarred(id: string, starred: boolean): Promise<{
+    amendPost(id: string, version: number, patch: AmendPostInput): Promise<{
         id: string;
         sessionId: string;
-        mock: string;
+        design: string;
         state: string | null;
         variant: string;
         status: PostStatus;
-        title: string;
-        surfaces: Surface[];
         createdAt: string;
         updatedAt: string;
         version: number;
         history: PostVersion[];
-        knobs?: Knobs;
-        note?: string;
-        embeds: Embed[];
         forkedFrom?: ForkRef;
+        copiedFrom?: CopyRef;
         acceptedVersion?: number;
         hiddenVersions?: number[];
-        from?: number;
-        prompt?: string;
-        author?: string;
-    } | {
-        starred: true;
-        id: string;
-        sessionId: string;
-        mock: string;
-        state: string | null;
-        variant: string;
-        status: PostStatus;
+        archiveReason?: string;
+        archivedAt?: string;
+        stayedVersion?: number;
+        publishedBy?: string;
+        system?: number;
         title: string;
         surfaces: Surface[];
-        createdAt: string;
-        updatedAt: string;
-        version: number;
-        history: PostVersion[];
-        knobs?: Knobs;
-        note?: string;
+        knobs?: Knobs | undefined;
+        description?: string | undefined;
         embeds: Embed[];
-        forkedFrom?: ForkRef;
-        acceptedVersion?: number;
-        hiddenVersions?: number[];
-        from?: number;
-        prompt?: string;
-        author?: string;
+        from?: number | undefined;
+        prompt?: string | undefined;
+        author?: string | undefined;
+        amendedAt: string;
+        rewrites: number;
+        contract: number;
+    } | null>;
+    setPosterOnce(id: string, version: number, poster: string, mode?: Mode, system?: number): Promise<boolean>;
+    withdrawVersion(id: string, version: number, embeds: Embed[]): Promise<{
+        post: null;
+    } | {
+        post: {
+            id: string;
+            sessionId: string;
+            design: string;
+            state: string | null;
+            variant: string;
+            status: PostStatus;
+            createdAt: string;
+            knobs?: Knobs;
+            description?: string;
+            forkedFrom?: ForkRef;
+            copiedFrom?: CopyRef;
+            acceptedVersion?: number;
+            archiveReason?: string;
+            archivedAt?: string;
+            stayedVersion?: number;
+            title: string;
+            surfaces: Surface[];
+            embeds: Embed[];
+            updatedAt: string;
+            version: number;
+            history: PostVersion[];
+            from?: number | undefined;
+            prompt?: string | undefined;
+            author?: string | undefined;
+            publishedBy?: string | undefined;
+            amendedAt?: string | undefined;
+            hiddenVersions?: number[] | undefined;
+            contract?: number | undefined;
+            system?: number | undefined;
+            rewrites: number;
+        };
     } | null>;
+    removePost(id: string): Promise<boolean>;
+    setPostStatus(id: string, status: PostStatus, acceptedVersion?: number): Promise<Post | null>;
+    setPostArchived(id: string, archivedAt: string, reason: string | null): Promise<Post | null>;
+    setForkedFrom(id: string, from: ForkRef | null): Promise<Post | null>;
+    bumpRewrites(designId: string): Promise<void>;
     setVersionHidden(id: string, version: number, hidden: boolean): Promise<Post | null>;
+    deleteOldVersions(id: string, versions: number[]): Promise<Post | null>;
+    setPostReason(id: string, reason: string | null): Promise<Post | null>;
+    setPostStayed(id: string, version: number): Promise<Post | null>;
     listComments(query: CommentQuery): Promise<Comment[]>;
     private insertComment;
     createComment(input: CreateCommentInput): Promise<Comment | null>;
     removeComment(id: string): Promise<Comment | null>;
+    listDecisionSources(project: string): Promise<{
+        variants: DecisionVariant[];
+        decidedAt: Record<string, string>;
+    }>;
     commitReply(input: CommitReplyInput): Promise<Comment | null>;
     private referencedAssetIds;
     private addAssetRefs;