mockpit 3.0.0 → 3.1.0

package/dist/server/mcpSpec.d.ts

@@ -8,14 +8,14 @@ export declare const MCP_INSTRUCTIONS: string;
 export declare const mcpSurfaceSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     kind: z.ZodOptional<z.ZodEnum<{
-        html: "html";
+        code: "code";
         diff: "diff";
+        html: "html";
         image: "image";
+        json: "json";
         markdown: "markdown";
-        terminal: "terminal";
         mermaid: "mermaid";
-        json: "json";
-        code: "code";
+        terminal: "terminal";
     }>>;
     html: z.ZodOptional<z.ZodString>;
     kits: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -30,8 +30,8 @@ export declare const mcpSurfaceSchema: z.ZodObject<{
         language: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     layout: z.ZodOptional<z.ZodEnum<{
-        unified: "unified";
         split: "split";
+        unified: "unified";
     }>>;
     assetId: z.ZodOptional<z.ZodString>;
     alt: z.ZodOptional<z.ZodString>;
@@ -54,7 +54,7 @@ type Param = {
     d?: string;
     req?: boolean;
 } | {
-    t: "surfaces" | "asks" | "object" | "integers" | "strings";
+    t: "surfaces" | "asks" | "object" | "objects" | "named" | "pairs" | "json" | "integers" | "strings";
     d?: string;
     req?: boolean;
 };
@@ -72,115 +72,115 @@ export declare const HTTP_MCP_TOOLS: ({
     _meta: {
         "anthropic/alwaysLoad": boolean;
     };
-    outputSchema?: Json | undefined;
     name: string;
     description: string;
     inputSchema: Json;
+    outputSchema?: Json | undefined;
 } | {
     _meta?: undefined;
-    outputSchema?: Json | undefined;
     name: string;
     description: string;
     inputSchema: Json;
+    outputSchema?: Json | undefined;
 })[];
 export declare const STDIO_MCP_CATALOG: ({
     _meta: {
         "anthropic/alwaysLoad": boolean;
     };
-    outputSchema?: Json | undefined;
     name: string;
     description: string;
     inputSchema: Json;
+    outputSchema?: Json | undefined;
 } | {
     _meta?: undefined;
-    outputSchema?: Json | undefined;
     name: string;
     description: string;
     inputSchema: Json;
+    outputSchema?: Json | undefined;
 })[];
 export declare const HTTP_RUN_TOOLS: ({
     _meta: {
         "anthropic/alwaysLoad": boolean;
     };
-    outputSchema?: Json | undefined;
     name: string;
     description: string;
     inputSchema: Json;
+    outputSchema?: Json | undefined;
 } | {
     _meta?: undefined;
-    outputSchema?: Json | undefined;
     name: string;
     description: string;
     inputSchema: Json;
+    outputSchema?: Json | undefined;
 })[];
 export declare const STDIO_RUN_CATALOG: ({
     _meta: {
         "anthropic/alwaysLoad": boolean;
     };
-    outputSchema?: Json | undefined;
     name: string;
     description: string;
     inputSchema: Json;
+    outputSchema?: Json | undefined;
 } | {
     _meta?: undefined;
-    outputSchema?: Json | undefined;
     name: string;
     description: string;
     inputSchema: Json;
+    outputSchema?: Json | undefined;
 })[];
 export declare const STDIO_MCP_TOOLS: ({
     _meta: {
         "anthropic/alwaysLoad": boolean;
     };
-    outputSchema?: z.ZodObject<{
-        [x: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-    }, z.core.$loose> | undefined;
     name: string;
     description: string;
     inputSchema: Readonly<{
         [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
     }>;
-} | {
-    _meta?: undefined;
     outputSchema?: z.ZodObject<{
         [x: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
     }, z.core.$loose> | undefined;
+} | {
+    _meta?: undefined;
     name: string;
     description: string;
     inputSchema: Readonly<{
         [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
     }>;
+    outputSchema?: z.ZodObject<{
+        [x: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    }, z.core.$loose> | undefined;
 })[];
 export declare const STDIO_RUN_TOOLS: ({
     _meta: {
         "anthropic/alwaysLoad": boolean;
     };
-    outputSchema?: z.ZodObject<{
-        [x: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-    }, z.core.$loose> | undefined;
     name: string;
     description: string;
     inputSchema: Readonly<{
         [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
     }>;
-} | {
-    _meta?: undefined;
     outputSchema?: z.ZodObject<{
         [x: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
     }, z.core.$loose> | undefined;
+} | {
+    _meta?: undefined;
     name: string;
     description: string;
     inputSchema: Readonly<{
         [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
     }>;
+    outputSchema?: z.ZodObject<{
+        [x: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    }, z.core.$loose> | undefined;
 })[];
 export declare const MCP_TOOL_NAMES: string[];
 export declare function toolResult(name: string, value: unknown): {
-    structuredContent?: Record<string, unknown> | undefined;
     content: {
         type: "text";
         text: string;
     }[];
+    structuredContent?: Record<string, unknown> | undefined;
 };
 export declare const MAX_RESULT_IMAGES = 8;
 export declare function withFeedbackImages<T extends {
@@ -190,11 +190,11 @@ export declare function withFeedbackImages<T extends {
     mimeType: string;
 } | null>): Promise<T>;
 export declare function runToolResult(envelope: unknown): {
-    isError?: boolean | undefined;
-    structuredContent?: Record<string, unknown> | undefined;
     content: {
         type: "text";
         text: string;
     }[];
+    structuredContent?: Record<string, unknown> | undefined;
+    isError?: boolean | undefined;
 };
 export {};

package/dist/server/mcpSpec.js

@@ -103,6 +103,10 @@ const askSchema = z.object({
         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"),
+        palette: z
+            .string()
+            .optional()
+            .describe("Or a palette id of the project's system; the answer makes it the default"),
         html: z.string().optional().describe("Or a whole page"),
         recommended: z.boolean().optional().describe("The one you would pick; one per ask"),
     })),
@@ -122,6 +126,23 @@ function zodParam(p) {
         case "object":
             s = z.record(z.string(), z.unknown());
             break;
+        case "objects":
+            s = z.array(z.record(z.string(), z.unknown()));
+            break;
+        // A list of objects where a bare name stands for {name}.
+        case "named":
+            s = z.array(z.union([z.string(), z.record(z.string(), z.unknown())]));
+            break;
+        // [foreground, background, minimum?]
+        case "pairs":
+            s = z.array(z
+                .array(z.union([z.string(), z.number()]))
+                .min(2)
+                .max(3));
+            break;
+        case "json":
+            s = z.unknown();
+            break;
         case "integer":
             s = z.number().int();
             break;
@@ -252,8 +273,8 @@ export const MCP_TOOL_DEFS = [
     },
     {
         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,
+        description: "The html in use (else current) per state, version history, screenshot URL, knobs, the settled values and the last reply. Without design: the project's system for code (sheet, tokens as CSS and JSON, settled project knobs, components' sources).",
+        params: { ...VARIANT_REF, design: { t: "string", d: field.design } },
     },
     {
         name: "edit",
@@ -290,10 +311,34 @@ export const MCP_TOOL_DEFS = [
         httpOnly: ["session"],
         stdioExtra: { path: { t: "string", d: "Local file path; use instead of data" } },
     },
+    {
+        name: "system",
+        description: "Read or change the project's system (sheet, tokens, scales, palettes, project knobs), which every render wears at once. No arguments reads it; each argument replaces its part, tokens, scales and palettes upsert. Shapes: topic system.",
+        params: {
+            project: P.project,
+            sheet: { t: "string", d: "CSS; no @import" },
+            classes: { t: "named", d: "[{name, note}] or names" },
+            fonts: { t: "objects", d: "[{family, href?}]" },
+            tokens: { t: "objects", d: "[{name, type, value, note?}]" },
+            scales: {
+                t: "objects",
+                d: "[{id, family: type|space, prefix, steps, zero, base, ratio, fluid?}]",
+            },
+            roles: { t: "named", d: "[{name, note}] or names" },
+            palettes: { t: "objects", d: "[{id, label, note, light, dark}]" },
+            pairs: { t: "pairs", d: "[[fg, bg, min?]]" },
+            as: { t: "object" },
+            knobs: { t: "object", d: "Project knobs" },
+            remove: { t: "object", d: "{tokens?, palettes?, scales?}" },
+            restore: { t: "integer", d: "A revision, alone" },
+            session: P.session,
+        },
+        httpOnly: ["session"],
+    },
     {
         name: "guide",
         description: "Fetch the brief: the loop, parts, asks and knobs, feedback, the html contract, and this " +
-            "project's palette, kit and icons. Read it before the first publish. Pass topic for one " +
+            "project's system, kit and icons. Read it before the first publish. Pass topic for one " +
             `reference section (${GUIDE_TOPICS.join(", ")}).`,
         params: {
             project: P.project,
@@ -441,6 +486,14 @@ const OUTPUT_SCHEMAS = {
         url: str,
         feedback: feedbackRide,
     },
+    system: {
+        rev: num,
+        changed: strs.optional().describe("What this write changed, as the Thread says it"),
+        checks: strs,
+        nudges: strs.optional(),
+        url: str,
+        feedback: feedbackRide.optional(),
+    },
     edit: {
         renamed: o({ from: str, to: str }).optional(),
         areaOrder: strs.optional(),
@@ -470,6 +523,9 @@ const OUTPUT_SCHEMAS = {
             .optional()
             .describe("Per state, the version the user put in use; export and embeds resolve to it"),
         knobs: bag.optional(),
+        system: str
+            .optional()
+            .describe("Without design: what the project's renders wear (rev, palettes, counts, failing checks)"),
         settled: bag.optional().describe("Every knob value the user has sent, later replies winning"),
         tree: z.array(bag).optional(),
         flows: z.array(flowSchema).optional(),
@@ -479,6 +535,7 @@ const OUTPUT_SCHEMAS = {
                 design: str,
                 text: str,
                 here: z.boolean().optional().describe("From the design read"),
+                system: z.boolean().optional().describe("The project's own, on every design"),
                 edited: z.boolean().optional(),
                 archived: z.boolean().optional(),
             })),
@@ -489,7 +546,8 @@ const OUTPUT_SCHEMAS = {
         pending: z.union([z.array(pendingSchema), pendingSchema]).optional(),
     },
     export: {
-        states: z.array(o({
+        states: z
+            .array(o({
             state: nullStr,
             variant: str,
             version: num,
@@ -497,9 +555,17 @@ const OUTPUT_SCHEMAS = {
             html: str.describe("With fills: only the chosen ones"),
             allFills: str.optional().describe("With fills: the html with every fill"),
             markdown: str,
-        })),
-        settled: bag,
-        reply: bag.nullable(),
+        }))
+            .optional(),
+        settled: bag.optional(),
+        reply: bag.nullable().optional(),
+        sheet: str.optional().describe("Without design: the project's sheet"),
+        css: str
+            .optional()
+            .describe("Without design: tokens as CSS, the default palette on :root, kept ones by [data-palette]"),
+        tokens: bag.optional().describe("Without design: the same as data"),
+        knobs: bag.optional().describe("Without design: the project knobs' values"),
+        components: z.array(bag).optional(),
     },
 };
 // The core loop, loaded up front by harnesses that defer the rest of the
@@ -515,9 +581,11 @@ function shapeFor(tool, transport) {
         shape[key] =
             transport === "stdio" && key === "html" && tool.name === "publish"
                 ? z.string().optional().describe(`${field.html}; or a file path`)
-                : transport === "stdio" && key === "poster" && tool.name === "publish"
-                    ? z.string().optional().describe(`${p.d}; or an image file path`)
-                    : zodParam(p);
+                : transport === "stdio" && key === "sheet" && tool.name === "system"
+                    ? z.string().optional().describe(`${p.d}; or a file path`)
+                    : 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/run.js

@@ -150,7 +150,10 @@ 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([design, opts]) {
                 if (plain(opts).decisions === true) {
@@ -192,6 +195,20 @@ export function createRunFlow(deps) {
                 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));
                 const value = await take(editCall(flows, r, flowCtx, project));
@@ -215,6 +232,10 @@ export function createRunFlow(deps) {
             },
             async export([v]) {
                 const r = plain(v);
+                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)`];
             },

package/dist/server/runApi.d.ts

@@ -1,5 +1,5 @@
-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 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({ 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;

package/dist/server/runApi.js

@@ -21,7 +21,7 @@ type Surface =
   | { kind: "code"; code: string; language?: string; lineStart?: number };
 type Ask = {
   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 }[];
+  options: { id?: string; label: string; variant?: string; set?: Knobs; palette?: string; recommended?: boolean }[];
 };
 type Written = {
   post?: { state: string | null; variant: string; version: number }; planned?: true; url: string;
@@ -34,10 +34,11 @@ type Feedback = {
   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 }[];
+  system?: { rev: number; changes: 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>;
+  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. */
@@ -56,7 +57,12 @@ declare const mockpit: {
   /** 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 }>;
 };
@@ -71,6 +77,7 @@ export const RUN_FUNCTIONS = [
     "say",
     "move",
     "edit",
+    "system",
     "export",
     "upload",
 ];

package/dist/server/sqlStore.d.ts

@@ -1,4 +1,5 @@
-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 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 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;
@@ -63,12 +64,33 @@ export declare class SqlStore implements Store {
     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(designId: string, draft: Draft | null): Promise<{
-        draft: Draft | null;
         id: string;
         project: string;
         slug: string;
@@ -91,6 +113,7 @@ export declare class SqlStore implements Store {
         sets: AnswerSet[];
         createdAt: string;
         updatedAt: string;
+        draft: Draft | null;
     } | null>;
     private touchDesign;
     listPosts(query?: PostQuery): Promise<Post[]>;
@@ -106,19 +129,6 @@ export declare class SqlStore implements Store {
     findPost(designId: string, state: string | null, variant: string): Promise<Post | null>;
     createPost(input: CreatePostInput): Promise<Post | null>;
     updatePost(id: string, patch: UpdatePostInput): Promise<{
-        publishedBy?: string | undefined;
-        author?: string | undefined;
-        embeds: Embed[];
-        state: string | null;
-        version: number;
-        updatedAt: string;
-        history: PostVersion[];
-        from: number;
-        prompt: string;
-        description?: string | undefined;
-        knobs?: Knobs | undefined;
-        title: string;
-        surfaces: Surface[];
         id: string;
         sessionId: string;
         design: string;
@@ -133,18 +143,23 @@ export declare class SqlStore implements Store {
         archivedAt?: string;
         stayedVersion?: number;
         rewrites?: number;
-    } | null>;
-    amendPost(id: string, version: number, patch: AmendPostInput): Promise<{
-        amendedAt: string;
-        rewrites: number;
-        author?: string | undefined;
-        prompt?: string | undefined;
-        from?: number | undefined;
-        embeds: Embed[];
-        description?: string | undefined;
-        knobs?: Knobs | undefined;
+        contract: number;
+        system?: number | undefined;
         title: string;
         surfaces: Surface[];
+        knobs?: Knobs | undefined;
+        description?: string | undefined;
+        embeds: Embed[];
+        state: string | null;
+        version: number;
+        updatedAt: string;
+        history: PostVersion[];
+        from: number;
+        prompt: string;
+        author?: string | undefined;
+        publishedBy?: string | undefined;
+    } | null>;
+    amendPost(id: string, version: number, patch: AmendPostInput): Promise<{
         id: string;
         sessionId: string;
         design: string;
@@ -163,25 +178,24 @@ export declare class SqlStore implements Store {
         archivedAt?: string;
         stayedVersion?: number;
         publishedBy?: string;
+        system?: number;
+        title: string;
+        surfaces: Surface[];
+        knobs?: Knobs | undefined;
+        description?: string | undefined;
+        embeds: Embed[];
+        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): Promise<boolean>;
+    setPosterOnce(id: string, version: number, poster: string, mode?: Mode, system?: number): Promise<boolean>;
     withdrawVersion(id: string, version: number, embeds: Embed[]): Promise<{
         post: null;
     } | {
         post: {
-            rewrites: number;
-            hiddenVersions?: number[] | undefined;
-            amendedAt?: string | undefined;
-            publishedBy?: string | undefined;
-            author?: string | undefined;
-            prompt?: string | undefined;
-            from?: number | undefined;
-            title: string;
-            surfaces: Surface[];
-            embeds: Embed[];
-            updatedAt: string;
-            version: number;
-            history: PostVersion[];
             id: string;
             sessionId: string;
             design: string;
@@ -197,6 +211,21 @@ export declare class SqlStore implements Store {
             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>;