mockpit 1.1.0 → 1.3.0

package/dist/server/knobs.d.ts

@@ -10,6 +10,10 @@ export declare function explicitKnob(config: KnobConfig): ExplicitKnob;
 export declare function checkKnobConfig(path: string, raw: unknown): Checked<KnobConfig>;
 export declare function checkKnobs(raw: unknown): Checked<Knobs>;
 export declare function checkKnobValue(path: string, config: KnobConfig, value: unknown): Checked<KnobValue>;
-export declare function knobFor(path: string, mock: Pick<Mock, "knobs">, posts: Pick<Post, "knobs">[]): KnobConfig | undefined;
-export declare function checkKnobValues(raw: unknown, mock: Pick<Mock, "knobs">, posts: Pick<Post, "knobs">[], what: string): Checked<Record<string, KnobValue>>;
+export declare function knobFor(path: string, mock: Pick<Mock, "knobs">, posts: (Pick<Post, "knobs"> & {
+    surfaces?: Post["surfaces"];
+})[]): KnobConfig | undefined;
+export declare function checkKnobValues(raw: unknown, mock: Pick<Mock, "knobs">, posts: (Pick<Post, "knobs"> & {
+    surfaces?: Post["surfaces"];
+})[], what: string): Checked<Record<string, KnobValue>>;
 export declare function discreteChoices(config: KnobConfig): number | null;

package/dist/server/knobs.js

@@ -1,6 +1,7 @@
 // Knob schema and value validation (plan Q3: values are checked against the
 // declared schema before they are stored or used). Runtime-agnostic. The config
 // shape mirrors tunekit's usePane config; see the knob types in types.ts.
+import { slotKnobs, slotsInSurfaces } from "./fills.js";
 const MAX_KNOBS = 100;
 const MAX_OPTIONS = 100;
 const MAX_STRING = 500;
@@ -292,13 +293,22 @@ export function checkKnobValue(path, config, value) {
         }
     }
 }
-// The declared knob for a path: the mock's own, else a variant's override.
+// The declared knob for a path: the mock's own, else a variant's override,
+// else the knob a variant's slot implies (fills.ts), so an option can `set` a
+// slot's fill without the agent declaring anything.
 export function knobFor(path, mock, posts) {
     if (Object.hasOwn(mock.knobs, path))
         return mock.knobs[path];
     for (const p of posts)
         if (p.knobs && Object.hasOwn(p.knobs, path))
             return p.knobs[path];
+    for (const p of posts) {
+        if (!p.surfaces)
+            continue;
+        const implied = slotKnobs(slotsInSurfaces(p.surfaces));
+        if (Object.hasOwn(implied, path))
+            return implied[path];
+    }
     return undefined;
 }
 export function checkKnobValues(raw, mock, posts, what) {
@@ -320,11 +330,10 @@ export function checkKnobValues(raw, mock, posts, what) {
     return { ok: true, value: out };
 }
 // How many discrete choices a knob offers, or null when it is continuous. A knob
-// with only a handful is usually a decision dressed as a control (plan D12).
+// with only a handful is usually a decision dressed as a control (plan D12). A
+// toggle is null: on/off reads fine on one render.
 export function discreteChoices(config) {
     const knob = explicitKnob(config);
-    if (knob.type === "toggle")
-        return 2;
     if (knob.type === "select")
         return knob.options.length;
     if (knob.type === "image" && knob.options)

package/dist/server/mcpHttp.d.ts

@@ -8,6 +8,9 @@ export interface McpFlows {
     list: Flow<[query: {
         project?: string;
     }]>;
+    tree: Flow<[query: {
+        project?: string;
+    }]>;
     get: Flow<[ref: unknown, query: {
         project?: unknown;
         body?: boolean;
@@ -23,11 +26,11 @@ export interface McpFlows {
         },
         ctx: FlowContext
     ]>;
-    say: Flow<[ref: unknown, body: any]>;
+    say: Flow<[ref: unknown, body: any, ctx: FlowContext]>;
     feedback: Flow<[query: {
         session?: unknown;
         project?: unknown;
-    }]>;
+    }, ctx: FlowContext]>;
 }
 export interface McpDeps {
     store: Store;

package/dist/server/mcpHttp.js

@@ -1,6 +1,6 @@
 import { decodeBase64 } from "./base64.js";
 import { isGuideTopic, unknownTopicMessage } from "./designGuide.js";
-import { HTTP_MCP_TOOLS, HTTP_RUN_TOOLS, MCP_INSTRUCTIONS, MCP_SERVER_INFO, runToolResult, toolResult, } from "./mcpSpec.js";
+import { HTTP_MCP_TOOLS, HTTP_RUN_TOOLS, MCP_INSTRUCTIONS, MCP_SERVER_INFO, runToolResult, toolResult, withFeedbackImages, } from "./mcpSpec.js";
 import { RUN_INSTRUCTIONS } from "./runApi.js";
 // A flow's error status becomes a tool error carrying the same JSON body the
 // REST tier returns, so the agent sees the hint (states, variants) either way.
@@ -24,6 +24,10 @@ export function registerMcp(app, deps) {
         const projects = await store.listProjects();
         return projects[0]?.name ?? "workspace";
     }
+    async function loadImage(ref) {
+        const asset = await store.getAsset(ref.id);
+        return asset ? { data: asset.data, mimeType: asset.contentType } : null;
+    }
     async function callTool(name, args, ctx) {
         switch (name) {
             case "publish":
@@ -31,6 +35,9 @@ export function registerMcp(app, deps) {
             case "ask":
                 return unwrap(await flows.ask(args.mock, args, ctx));
             case "read":
+                if (args.mock === undefined && args.tree === true) {
+                    return unwrap(await flows.tree({ project: args.project }));
+                }
                 if (args.mock === undefined)
                     return unwrap(await flows.list({ project: args.project }));
                 return unwrap(await flows.get(args.mock, {
@@ -39,9 +46,9 @@ export function registerMcp(app, deps) {
                     history: args.history === true,
                 }));
             case "feedback":
-                return unwrap(await flows.feedback({ session: args.session, project: args.project }));
+                return unwrap(await flows.feedback({ session: args.session, project: args.project }, ctx));
             case "say":
-                return unwrap(await flows.say(args.mock, args));
+                return unwrap(await flows.say(args.mock, args, ctx));
             case "export":
                 return unwrap(await flows.exportMock(args.mock, args, ctx));
             case "upload": {
@@ -124,9 +131,11 @@ export function registerMcp(app, deps) {
                 const name = msg.params?.name;
                 if (name === "run") {
                     const args = msg.params?.arguments ?? {};
-                    return rpc(msg.id, runToolResult(unwrap(await deps.run(args, ctx))));
+                    const envelope = unwrap(await deps.run(args, ctx));
+                    return rpc(msg.id, await withFeedbackImages(runToolResult(envelope), envelope, loadImage));
                 }
-                return rpc(msg.id, toolResult(name, await callTool(name, msg.params?.arguments ?? {}, ctx)));
+                const value = await callTool(name, msg.params?.arguments ?? {}, ctx);
+                return rpc(msg.id, await withFeedbackImages(toolResult(name, value), value, loadImage));
             }
             catch (err) {
                 return rpc(msg.id, {

package/dist/server/mcpSpec.d.ts

@@ -1,4 +1,5 @@
 import * as z from "zod/v4";
+import { type ImageRef } from "./feedbackBatch.ts";
 export declare const MCP_SERVER_INFO: {
     name: string;
     version: string;
@@ -52,7 +53,7 @@ type Param = {
     d?: string;
     req?: boolean;
 } | {
-    t: "surfaces" | "asks" | "object";
+    t: "surfaces" | "asks" | "object" | "integers";
     d?: string;
     req?: boolean;
 };
@@ -130,9 +131,9 @@ export declare const STDIO_MCP_TOOLS: ({
     _meta: {
         "anthropic/alwaysLoad": boolean;
     };
-    outputSchema?: z.ZodObject<Readonly<{
-        [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-    }>, z.core.$loose> | undefined;
+    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<{
@@ -140,9 +141,9 @@ export declare const STDIO_MCP_TOOLS: ({
     }>;
 } | {
     _meta?: undefined;
-    outputSchema?: z.ZodObject<Readonly<{
-        [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-    }>, z.core.$loose> | undefined;
+    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<{
@@ -153,9 +154,9 @@ export declare const STDIO_RUN_TOOLS: ({
     _meta: {
         "anthropic/alwaysLoad": boolean;
     };
-    outputSchema?: z.ZodObject<Readonly<{
-        [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-    }>, z.core.$loose> | undefined;
+    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<{
@@ -163,9 +164,9 @@ export declare const STDIO_RUN_TOOLS: ({
     }>;
 } | {
     _meta?: undefined;
-    outputSchema?: z.ZodObject<Readonly<{
-        [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-    }>, z.core.$loose> | undefined;
+    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<{
@@ -180,6 +181,13 @@ export declare function toolResult(name: string, value: unknown): {
         text: string;
     }[];
 };
+export declare const MAX_RESULT_IMAGES = 8;
+export declare function withFeedbackImages<T extends {
+    content: unknown[];
+}>(result: T, value: unknown, load: (ref: ImageRef) => Promise<{
+    data: Uint8Array;
+    mimeType: string;
+} | null>): Promise<T>;
 export declare function runToolResult(envelope: unknown): {
     isError?: boolean | undefined;
     structuredContent?: Record<string, unknown> | undefined;

package/dist/server/mcpSpec.js

@@ -1,5 +1,7 @@
 import * as z from "zod/v4";
+import { encodeBase64 } from "./base64.js";
 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";
@@ -26,7 +28,12 @@ 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",
+    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",
+    widths: "Widths it ships at, side by side: [390,1280]",
+    flow: "Flow this screen is a step of; alone, only places it",
+    step: "1-based place; 0 removes",
     kits: `Opt-in bundles: ${KIT_IDS.join("|")}`,
 };
 const diffFileSchema = z.object({
@@ -73,10 +80,15 @@ const askSchema = z.object({
     state: z.string().optional(),
     part: z.string().optional().describe("data-part name, for scope part"),
     multi: z.boolean().optional(),
+    after: z
+        .string()
+        .optional()
+        .describe("Id of an earlier ask this depends on; it opens once that one is answered"),
     options: z.array(z.object({
         id: z.string().optional(),
         label: z.string(),
         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}"),
     })),
 });
@@ -98,6 +110,9 @@ function zodParam(p) {
         case "integer":
             s = z.number().int();
             break;
+        case "integers":
+            s = z.array(z.number().int());
+            break;
         default:
             s = p.t === "string" ? z.string() : p.t === "number" ? z.number() : z.boolean();
     }
@@ -116,7 +131,7 @@ const VARIANT_REF = { mock: P.mock, state: P.state, variant: P.variant, 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) or parts (splices the latest version). Returns parts per state, nudges, feedback.",
+        description: "Create or version one variant of one state of a mock. One of html, surfaces (the full ordered list), parts or fills (splice the latest version). Returns parts per state, nudges, feedback.",
         params: {
             ...VARIANT_REF,
             title: { t: "string", d: field.title },
@@ -127,10 +142,19 @@ export const MCP_TOOL_DEFS = [
                 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' },
+            fills: {
+                t: "object",
+                d: '{"part#fill": outer html}; replaces that fill of a slot, or adds it after the 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 },
             prompt: { t: "string", d: field.prompt },
+            note: { t: "string", d: field.note },
+            widths: { t: "integers", d: field.widths },
+            flow: { t: "string", d: field.flow },
+            step: { t: "integer", d: field.step },
             session: P.session,
             sessionTitle: { t: "string", d: field.sessionTitle },
             agent: { t: "string", d: field.agent },
@@ -150,17 +174,21 @@ export const MCP_TOOL_DEFS = [
     },
     {
         name: "read",
-        description: "Without mock: every mock (slug, states, variants, open asks) plus pending. With mock: its states, variants, asks with answers, parts, knobs and last tuned values, plus pending. Never consumes feedback.",
+        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.",
         params: {
             mock: { t: "string", d: field.mock },
             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)",
+            },
         },
     },
     {
         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), delivered once, plus pending (viewer open, draft progress).",
+        description: "Returns at once: what the user sent since you last heard (one batch per mock: reply answers, mix, tuned knobs, part comments, comments, accepted/archived/dropped, or resolved with the asks it dismissed), delivered once, plus pending (viewer open, draft progress).",
         params: {
             project: P.project,
             session: { t: "string", d: "Session id returned by publish", req: true },
@@ -179,7 +207,7 @@ export const MCP_TOOL_DEFS = [
     },
     {
         name: "export",
-        description: "The accepted (or current) html per state, version history, screenshot URL, knobs and the last reply's tuned values.",
+        description: "The html in use (else current) per state, version history, screenshot URL, knobs, the settled values and the last reply.",
         params: VARIANT_REF,
     },
     {
@@ -233,7 +261,9 @@ const nullStr = z.string().nullable();
 const strs = z.array(z.string());
 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 feedbackSchema = o({
     mock: nullStr,
     reply: o({
@@ -245,18 +275,29 @@ const feedbackSchema = o({
         mix: bag,
         tuned: bag,
         comments: z.array(o({ part: nullStr, text: str })),
+        reactions: strs.optional().describe('One-tap reactions, e.g. 👍 part "hero" (variant B)'),
     })
         .nullable()
         .describe("The user's Send; null if only comments"),
     comments: z.array(o({ seq: num, text: str })),
-    accepted: z.array(variantRef),
+    accepted: z.array(inUseRef).describe("Accepted, each at the version 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 }))
+        .optional()
+        .describe("The asks the resolution closed; don't ask them again"),
 }).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(),
     viewerOpen: z.boolean(),
     draft: o({ answered: num, of: num, comments: num, touchedAt: str }).nullable(),
 }).meta({ id: "Pending" });
@@ -268,6 +309,7 @@ const writeOutput = {
     partChanges: o({ vanished: strs, renamed: z.array(o({ from: str, to: str })) }).optional(),
     nudges: strs.optional(),
     suggestedAsk: bag.optional().describe("Send with ask when a nudge names it"),
+    flow: flowSchema.optional(),
     feedback: feedbackRide,
 };
 const OUTPUT_SCHEMAS = {
@@ -288,7 +330,13 @@ const OUTPUT_SCHEMAS = {
         session: nullStr,
     },
     publish: writeOutput,
-    ask: { asks: z.array(o({ id: str, text: str })), open: num, url: str, feedback: feedbackRide },
+    ask: {
+        asks: z.array(o({ id: str, text: str })),
+        open: num,
+        url: str,
+        nudges: strs.optional(),
+        feedback: feedbackRide,
+    },
     feedback: {
         feedback: z.array(feedbackSchema).describe("One batch per mock; empty when nothing is new"),
         pending: z.array(pendingSchema),
@@ -298,13 +346,39 @@ const OUTPUT_SCHEMAS = {
         mocks: 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, version: num })).optional(),
+        variants: z
+            .array(o({
+            state: nullStr,
+            variant: str,
+            status: str,
+            version: num,
+            acceptedVersion: num.optional().describe("Set when accepted: the version in use"),
+            history: z
+                .array(o({ version: num, hidden: z.boolean().optional() }))
+                .optional()
+                .describe("With history: version rows; hidden ones the user put away are flagged"),
+        }))
+            .optional(),
+        inUse: z
+            .array(inUseRef)
+            .optional()
+            .describe("Per state, the version the user put in use; export and embeds resolve to it"),
         knobs: bag.optional(),
-        tuned: bag.optional().describe("Knob values from the latest reply"),
+        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]),
     },
     export: {
-        states: z.array(o({ state: nullStr, variant: str, version: num, html: str, markdown: str })),
+        states: z.array(o({
+            state: nullStr,
+            variant: str,
+            version: num,
+            latest: num.optional().describe("Your newer version, not in use yet"),
+            html: str,
+            markdown: str,
+        })),
+        settled: bag,
         reply: bag.nullable(),
     },
 };
@@ -394,6 +468,22 @@ export function toolResult(name, value) {
         ...(structured ? { structuredContent: value } : {}),
     };
 }
+// The images a result's feedback carries, inlined as image content so the
+// model sees what the user attached instead of only its URL. Capped per result:
+// the rest stay reachable by URL in the JSON.
+export const MAX_RESULT_IMAGES = 8;
+export async function withFeedbackImages(result, value, load) {
+    const batches = value?.feedback;
+    if (!Array.isArray(batches))
+        return result;
+    const images = [];
+    for (const ref of feedbackImages(batches).slice(0, MAX_RESULT_IMAGES)) {
+        const bytes = await load(ref).catch(() => null);
+        if (bytes)
+            images.push({ type: "image", data: encodeBase64(bytes.data), mimeType: bytes.mimeType });
+    }
+    return images.length ? { ...result, content: [...result.content, ...images] } : result;
+}
 // A run that failed is still a full envelope (calls, feedback); isError tells
 // the client the script did not finish.
 export function runToolResult(envelope) {

package/dist/server/postSurfaces.js

@@ -6,23 +6,14 @@ const MERMAID_PARSE_NEXT_STEPS = [
     'Keep the diagram declaration on the first non-comment line (for example, "flowchart TD").',
     "Reduce the diagram to a minimal valid form, then add statements back until the failing line is isolated.",
 ];
-const requiredString = (name) => z.string({
-    required_error: `requires string "${name}"`,
-    invalid_type_error: `requires string "${name}"`,
-});
+const requiredString = (name) => z.string({ error: `requires string "${name}"` });
 const optionalLooseString = z.preprocess((v) => (typeof v === "string" ? v : undefined), z.string().optional());
 const looseLayout = z.preprocess((v) => (v === "unified" || v === "split" ? v : undefined), z.enum(["unified", "split"]).optional());
 const optionalLooseNumber = z.preprocess((v) => (typeof v === "number" && Number.isFinite(v) ? v : undefined), z.number().optional());
 const strictDiffFile = z.object({
     filename: requiredString("filename"),
-    before: z.string({
-        required_error: 'requires string "before" and "after"',
-        invalid_type_error: 'requires string "before" and "after"',
-    }),
-    after: z.string({
-        required_error: 'requires string "before" and "after"',
-        invalid_type_error: 'requires string "before" and "after"',
-    }),
+    before: z.string({ error: 'requires string "before" and "after"' }),
+    after: z.string({ error: 'requires string "before" and "after"' }),
     language: z.string().optional(),
 });
 const looseDiffFile = z

package/dist/server/richRender.js

@@ -139,7 +139,9 @@ blockquote {
   color: var(--muted);
 }
 table { border-collapse: collapse; font-size: 13px; }
-th, td { border: 0.5px solid var(--border); padding: 4px 8px; text-align: left; }
+/* break-word, not the body's anywhere: anywhere lets a column shrink to one
+   letter, so a long cell beside it squeezes "Topic" into "Top/ic". */
+th, td { border: 0.5px solid var(--border); padding: 4px 8px; text-align: left; overflow-wrap: break-word; }
 th { background: var(--hover); }
 img { max-width: 100%; height: auto; border-radius: 6px; }
 hr { border: none; border-top: 0.5px solid var(--border); margin: 1em 0; }

package/dist/server/run.js

@@ -153,6 +153,10 @@ export function createRunFlow(deps) {
                 return [await deps.guide("", topic), String(topic)];
             },
             async read([mock, opts]) {
+                if ((mock === undefined || mock === null) && plain(opts).tree === true) {
+                    const value = await take(flows.tree({ project: await projectOf() }));
+                    return [value, `${value.tree.length} mocks`];
+                }
                 if (mock === undefined || mock === null) {
                     const value = await take(flows.list({ project: await projectOf() }));
                     return [value, `${value.mocks.length} mocks`];
@@ -170,13 +174,13 @@ export function createRunFlow(deps) {
                 return [value, `${value.mock} ${value.asks.length} ask(s)`];
             },
             async feedback() {
-                const value = await take(flows.feedback(await mine({})));
+                const value = await take(flows.feedback(await mine({}), flowCtx));
                 const n = value.feedback.length;
                 return [value, n ? `${n} batch(es)` : "no feedback"];
             },
             async say([v, message]) {
                 const r = plain(v);
-                await take(flows.say(r.mock, { ...(await mine(r)), message }));
+                await take(flows.say(r.mock, { ...(await mine(r)), message }, flowCtx));
                 return [null, String(r.mock ?? "?")];
             },
             async upload([data, opts]) {

package/dist/server/runApi.d.ts

@@ -1,4 +1,4 @@
-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 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  publish(v: Ref & { title?: string; kind?: \"component\" | \"page\"; html?: string; surfaces?: (Surface | { id: string })[]; parts?: Record<string, string>; knobs?: Knobs; variantKnobs?: Knobs; from?: number }): Promise<Written>;\n  ask(mock: string, asks: Ask[]): Promise<{ asks: { id: string; text: string }[]; url: 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_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 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;";

package/dist/server/runApi.js

@@ -38,12 +38,13 @@ type Feedback = {
 type Pending = { mock: string; 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 plus pending. With one: its states, variants, asks, parts, knobs. */
+  /** No mock: every mock, the flows, plus pending. With one: its states, variants, asks, parts, knobs. */
   read(mock?: string, opts?: { body?: boolean; history?: boolean }): Promise<unknown>;
   /** Creates or versions (mock, state, variant). One of: html; surfaces, the full ordered list
-   * ({id} alone keeps that surface, a missing id is removed); parts {"name"|"name#key": outer html}. */
-  publish(v: Ref & { title?: string; kind?: "component" | "page"; html?: string; surfaces?: (Surface | { id: string })[]; parts?: Record<string, string>; knobs?: Knobs; variantKnobs?: Knobs; from?: number }): Promise<Written>;
-  ask(mock: string, asks: Ask[]): Promise<{ asks: { id: string; text: string }[]; url: string }>;
+   * ({id} alone keeps that surface, a missing id is removed); parts {"name"|"name#key": outer html};
+   * fills {"part#fill": outer html}, replacing or adding one alternative of a slot. */
+  publish(v: Ref & { title?: string; kind?: "component" | "page"; html?: string; surfaces?: (Surface | { id: string })[]; parts?: Record<string, string>; fills?: Record<string, string>; knobs?: Knobs; variantKnobs?: Knobs; from?: number; prompt?: string; note?: string; widths?: number[]; flow?: string; step?: number }): Promise<Written>;
+  ask(mock: string, asks: Ask[]): Promise<{ asks: { id: string; text: string }[]; url: string; nudges?: string[] }>;
   /** Never waits: what the user sent since you last heard, and what they are doing now. */
   feedback(): Promise<{ feedback: Feedback[]; pending: Pending[] }>;
   say(v: Ref, message: string): Promise<void>;