mockpit 0.0.0-stage → 1.1.0

package/dist/server/run.d.ts

@@ -0,0 +1,82 @@
+import type { FlowContext, FlowResult } from "./app.ts";
+import type { FeedbackBatch } from "./feedbackBatch.ts";
+import { type GuideTopic } from "./designGuide.ts";
+import { type McpFlows } from "./mcpHttp.ts";
+import type { Asset, AssetKind, Store } from "./types.ts";
+export interface RunLimits {
+    deadlineMs: number;
+    cpuMs: number;
+    memoryBytes: number;
+    stackBytes: number;
+    maxCodeBytes: number;
+    maxOutputChars: number;
+    maxCalls: number;
+    maxInflight: number;
+    maxRuns: number;
+}
+export declare const DEFAULT_RUN_LIMITS: RunLimits;
+export type RunErrorKind = "script" | "timeout" | "limit" | "aborted";
+export interface RunError {
+    kind: RunErrorKind;
+    message: string;
+    line?: number;
+    column?: number;
+}
+export interface ExecRequest {
+    code: string;
+    limits: RunLimits;
+    signal: AbortSignal;
+    call(name: string, argsJson: string): Promise<string>;
+    print(line: string): void;
+}
+export type ExecResult = {
+    ok: true;
+    json?: string;
+} | {
+    ok: false;
+    error: RunError;
+};
+export interface Executor {
+    run(request: ExecRequest): Promise<ExecResult>;
+}
+export interface RunCall {
+    fn: string;
+    ok: boolean;
+    summary: string;
+}
+export interface RunEnvelope {
+    ok: boolean;
+    value?: unknown;
+    prints: string[];
+    calls: RunCall[];
+    error?: RunError;
+    feedback: FeedbackBatch[];
+    session: string | null;
+    truncated?: true;
+}
+export interface RunDeps {
+    store: Store;
+    executor?: Executor;
+    limits: RunLimits;
+    flows: McpFlows;
+    guide(project: string, topic?: GuideTopic): string | Promise<string>;
+    createSession(input: {
+        agent: string;
+        project?: string;
+    }): Promise<string>;
+    uploadAsset(input: {
+        data: Uint8Array;
+        contentType: string;
+        filename?: string;
+        kind?: AssetKind;
+        session?: string;
+    }): Promise<{
+        asset: Omit<Asset, "data">;
+    } | {
+        error: string;
+        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 function cut(s: string, max: number): string;
+export declare function createRunFlow(deps: RunDeps): (body: any, ctx: FlowContext) => Promise<FlowResult>;

package/dist/server/run.js

@@ -0,0 +1,290 @@
+// Server-side codemode: one `run` executes an agent's script against the same
+// flows REST and MCP call, with the caller's identity. Runtime-agnostic — the
+// sandbox itself is an `Executor` the host passes in (server/codeRunner.ts on
+// Node); a deployment without one answers that `run` is unavailable.
+//
+// The script is a new untrusted channel into the trusted origin, gated like the
+// bridge: it never sees a credential, binds only agent verbs (never Send,
+// drafts, accept/drop, settings), and every way out goes through a host call
+// that is counted, bounded and logged.
+import { decodeBase64 } from "./base64.js";
+import { isGuideTopic, unknownTopicMessage } from "./designGuide.js";
+import { unwrap } from "./mcpHttp.js";
+import { RUN_FUNCTIONS } from "./runApi.js";
+// A script never waits for the user, so the wall clock is only a sandbox guard:
+// 10 s clears a run of publishes with room to spare. 32 MiB and a 256 KiB stack are what the spike showed safe (512 KiB overflows the host
+// stack on workerd). The code cap clears a few full-page html variants written
+// as template literals.
+export const DEFAULT_RUN_LIMITS = {
+    deadlineMs: 10_000,
+    cpuMs: 10_000,
+    memoryBytes: 32 * 1024 * 1024,
+    stackBytes: 256 * 1024,
+    maxCodeBytes: 1024 * 1024,
+    maxOutputChars: 24_000,
+    maxCalls: 100,
+    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";
+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
+// a failing log usually explains itself.
+export function cut(s, max) {
+    if (s.length <= max)
+        return s;
+    const keep = Math.max(0, max - 40);
+    const head = Math.ceil(keep / 2);
+    return `${s.slice(0, head)}\n…[${s.length - keep} chars cut]…\n${s.slice(s.length - (keep - head))}`;
+}
+function writeSummary(body) {
+    const post = body?.post;
+    const slug = body?.mock?.slug ?? "?";
+    if (!post)
+        return slug;
+    return `${slug}/${post.state ? `${post.state}/` : ""}${post.variant} v${post.version}`;
+}
+// Host calls past `size` in flight queue rather than fail, so Promise.all over
+// a handful of publishes just works.
+function semaphore(size) {
+    const queue = [];
+    let used = 0;
+    return {
+        async take() {
+            if (used < size) {
+                used++;
+                return;
+            }
+            await new Promise((resolve) => queue.push(resolve));
+        },
+        give() {
+            const next = queue.shift();
+            if (next)
+                next();
+            else
+                used--;
+        },
+    };
+}
+export function createRunFlow(deps) {
+    const { store, flows, limits } = deps;
+    let active = 0;
+    return async function runFlow(body, ctx) {
+        const executor = deps.executor;
+        if (!executor)
+            return { status: 501, body: { error: RUN_UNAVAILABLE } };
+        if (!body || typeof body !== "object")
+            return { status: 400, body: { error: "invalid JSON body" } };
+        const code = body.code;
+        if (typeof code !== "string" || !code.trim()) {
+            return { status: 400, body: { error: 'provide "code": the body of an async function' } };
+        }
+        let sessionId = null;
+        let project = text(body.project, 500);
+        if (typeof body.session === "string" && body.session) {
+            const session = await store.getSession(body.session);
+            if (!session)
+                return { status: 404, body: { error: `session "${body.session}" not found` } };
+            sessionId = session.id;
+            project ??= session.project ?? undefined;
+        }
+        const agent = text(body.agent, 500) ?? "agent";
+        const prints = [];
+        const calls = [];
+        const feedback = [];
+        let printed = 0;
+        let truncated = false;
+        const envelope = (ok, extra) => ({
+            status: 200,
+            body: {
+                ok,
+                ...extra,
+                prints,
+                calls,
+                feedback,
+                session: sessionId,
+                ...(truncated ? { truncated: true } : {}),
+            },
+        });
+        if (new TextEncoder().encode(code).byteLength > limits.maxCodeBytes) {
+            return envelope(false, {
+                error: { kind: "limit", message: `code exceeds ${limits.maxCodeBytes} bytes` },
+            });
+        }
+        if (active >= limits.maxRuns) {
+            return { status: 503, body: { error: "too many concurrent runs; retry shortly" } };
+        }
+        active++;
+        const run = new AbortController();
+        const onAbort = () => run.abort();
+        ctx.signal?.addEventListener("abort", onAbort, { once: true });
+        if (ctx.signal?.aborted)
+            run.abort();
+        // A script is agent code: it never acts as the user, whatever origin sent it.
+        const flowCtx = { ...ctx, viewer: false, strict: false, signal: run.signal };
+        const gate = semaphore(limits.maxInflight);
+        const inflight = new Set();
+        const session = async () => (sessionId ??= await deps.createSession({ agent, project }));
+        const mine = async (v) => ({
+            ...v,
+            session: await session(),
+            ...(project ? { project } : {}),
+        });
+        const take = async (result) => {
+            const value = unwrap(await result);
+            if (Array.isArray(value?.feedback))
+                feedback.push(...value.feedback);
+            return value;
+        };
+        const projectOf = async () => {
+            if (project)
+                return project;
+            const projects = await store.listProjects();
+            return projects[0]?.name ?? "workspace";
+        };
+        // Each host function returns [value the script sees, one-line summary].
+        const host = {
+            async guide([topic]) {
+                if (topic === undefined || topic === null)
+                    return [await deps.guide(await projectOf()), "brief"];
+                if (!isGuideTopic(topic))
+                    throw new Error(unknownTopicMessage(String(topic)));
+                return [await deps.guide("", topic), String(topic)];
+            },
+            async read([mock, opts]) {
+                if (mock === undefined || mock === null) {
+                    const value = await take(flows.list({ project: await projectOf() }));
+                    return [value, `${value.mocks.length} mocks`];
+                }
+                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)];
+            },
+            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 feedback() {
+                const value = await take(flows.feedback(await mine({})));
+                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 }));
+                return [null, String(r.mock ?? "?")];
+            },
+            async upload([data, opts]) {
+                if (typeof data !== "string" || !data)
+                    throw new Error("upload needs base64 data");
+                const o = plain(opts);
+                const result = await deps.uploadAsset({
+                    data: decodeBase64(data),
+                    contentType: typeof o.contentType === "string" ? o.contentType : "",
+                    filename: typeof o.filename === "string" ? o.filename : undefined,
+                    kind: o.kind === "image" || o.kind === "file" ? o.kind : undefined,
+                    session: await session(),
+                });
+                if ("error" in result)
+                    throw new Error(result.error);
+                const { id, contentType, byteLength } = result.asset;
+                return [{ id, url: `${ctx.base}/a/${id}`, contentType, byteLength }, id];
+            },
+            async export([v]) {
+                const r = plain(v);
+                const value = await take(flows.exportMock(r.mock, { ...r, project }, flowCtx));
+                return [value, `${value.mock} ${value.states.length} state(s)`];
+            },
+        };
+        const call = (name, argsJson) => {
+            const entry = { fn: name, ok: false, summary: "cancelled" };
+            calls.push(entry);
+            const fail = (message) => {
+                entry.summary = message;
+                return Promise.reject(new Error(message));
+            };
+            if (run.signal.aborted)
+                return fail("run ended");
+            if (calls.length > limits.maxCalls)
+                return fail(`call limit of ${limits.maxCalls} reached`);
+            const fn = RUN_FUNCTIONS.includes(name)
+                ? host[name]
+                : undefined;
+            if (!fn)
+                return fail(`mockpit.${name} is not a function`);
+            const work = (async () => {
+                await gate.take();
+                try {
+                    if (run.signal.aborted)
+                        throw new Error("run ended");
+                    const args = JSON.parse(argsJson);
+                    const [value, summary] = await fn(Array.isArray(args) ? args : []);
+                    entry.ok = true;
+                    entry.summary = summary;
+                    return JSON.stringify(value ?? null);
+                }
+                catch (err) {
+                    entry.summary = err instanceof Error ? err.message : String(err);
+                    throw err;
+                }
+                finally {
+                    gate.give();
+                }
+            })();
+            inflight.add(work);
+            work.then(() => inflight.delete(work), () => inflight.delete(work));
+            return work;
+        };
+        const print = (line) => {
+            if (truncated)
+                return;
+            if (printed + line.length > limits.maxOutputChars) {
+                truncated = true;
+                prints.push(cut(line, Math.max(0, limits.maxOutputChars - printed)));
+                prints.push("…[further prints cut]");
+                return;
+            }
+            printed += line.length;
+            prints.push(line);
+        };
+        try {
+            let result;
+            try {
+                result = await executor.run({ code, limits, signal: run.signal, call, print });
+            }
+            catch (err) {
+                result = {
+                    ok: false,
+                    error: {
+                        kind: "limit",
+                        message: `sandbox failed: ${err instanceof Error ? err.message : err}`,
+                    },
+                };
+            }
+            // Writes already sent finish and land in `calls`.
+            run.abort();
+            await Promise.allSettled(inflight);
+            if (ctx.signal?.aborted && (result.ok || result.error.kind !== "aborted")) {
+                result = { ok: false, error: { kind: "aborted", message: "the caller went away" } };
+            }
+            if (!result.ok)
+                return envelope(false, { error: result.error });
+            if (result.json === undefined)
+                return envelope(true, {});
+            const room = Math.max(1000, limits.maxOutputChars - printed);
+            if (result.json.length <= room)
+                return envelope(true, { value: JSON.parse(result.json) });
+            truncated = true;
+            return envelope(true, { value: cut(result.json, room) });
+        }
+        finally {
+            ctx.signal?.removeEventListener("abort", onAbort);
+            active--;
+        }
+    };
+}

package/dist/server/runApi.d.ts

@@ -0,0 +1,6 @@
+export declare const RUN_API = "// The body of an async function, in plain JavaScript (no TypeScript syntax).\n// `await mockpit.*`, `return` a JSON value, print() adds an output line.\n// No network, timers, imports or process. Session, project and agent are fixed\n// for the run; pass the returned session to the next run.\ntype Ref = { mock: string; state?: string; variant?: string };\ntype Knobs = Record<string, unknown>; // path \u2192 [default,min,max,step] | boolean | {type:\"select\",options} | \"#hex\"\ntype Surface =\n  | { kind: \"html\"; html: string; kits?: string[] }\n  | { kind: \"markdown\"; markdown: string }\n  | { kind: \"diff\"; patch?: string; files?: { filename: string; before: string; after: string }[]; layout?: \"unified\" | \"split\" }\n  | { kind: \"image\"; assetId: string; alt?: string; caption?: string }\n  | { kind: \"terminal\"; text: string; cols?: number; title?: string }\n  | { kind: \"mermaid\"; mermaid: string }\n  | { kind: \"json\"; data: unknown; title?: string }\n  | { kind: \"code\"; code: string; language?: string; lineStart?: number };\ntype Ask = {\n  id?: string; text: string; scope?: \"mock\" | \"state\" | \"part\"; state?: string; part?: string; multi?: boolean;\n  options: { id?: string; label: string; variant?: string; set?: Knobs }[];\n};\ntype Written = {\n  post: { state: string | null; variant: string; version: number }; url: string;\n  parts: { state: string | null; parts: { name: string }[] }[];\n  partChanges?: { vanished: string[]; renamed: { from: string; to: string }[] };\n  nudges?: string[]; suggestedAsk?: Ask; // send it with ask when nudged\n};\ntype Feedback = {\n  mock: string | null;\n  reply: null | { asks: { ask: string; chosen: { id: string; label: string; other?: true }[]; note?: string }[]; mix: Knobs; tuned: Knobs; comments: { part: string | null; text: string }[] };\n  comments: { text: string; state: string | null; variant: string | null }[];\n  accepted: { state: string | null; variant: string }[]; archived: { state: string | null; variant: string }[];\n};\ntype Pending = { mock: string; viewerOpen: boolean; draft: null | { answered: number; of: number; comments: number; touchedAt: string } };\ndeclare const mockpit: {\n  guide(topic?: \"knobs\" | \"asks\" | \"surfaces\" | \"html\" | \"feedback\" | \"http\" | \"scripts\"): Promise<string>;\n  /** No mock: every mock 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_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;";
+export declare const RUN_DESCRIPTION: string;
+export declare const RUN_INSTRUCTIONS: string;

package/dist/server/runApi.js

@@ -0,0 +1,82 @@
+// The typed surface a `run` script sees, as text. One source for the MCP `run`
+// tool description, the scripts guide topic and `mockpit run --help`, so the
+// tiers cannot describe different APIs. Hand-shaped rather than generated from
+// mcpSpec: a generator repeats Surface per tool and the run-level params on
+// every function, roughly tripling the size. test/run.test.ts checks that every
+// host function named here exists and vice versa.
+export const RUN_API = `// The body of an async function, in plain JavaScript (no TypeScript syntax).
+// \`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 Knobs = Record<string, unknown>; // path → [default,min,max,step] | boolean | {type:"select",options} | "#hex"
+type Surface =
+  | { kind: "html"; html: string; kits?: string[] }
+  | { kind: "markdown"; markdown: string }
+  | { kind: "diff"; patch?: string; files?: { filename: string; before: string; after: string }[]; layout?: "unified" | "split" }
+  | { kind: "image"; assetId: string; alt?: string; caption?: string }
+  | { kind: "terminal"; text: string; cols?: number; title?: string }
+  | { kind: "mermaid"; mermaid: string }
+  | { 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 }[];
+};
+type Written = {
+  post: { state: string | null; variant: string; version: number }; url: string;
+  parts: { state: string | null; parts: { name: string }[] }[];
+  partChanges?: { vanished: string[]; renamed: { from: string; to: string }[] };
+  nudges?: string[]; suggestedAsk?: Ask; // send it with ask when nudged
+};
+type Feedback = {
+  mock: string | null;
+  reply: null | { asks: { ask: string; chosen: { id: string; label: string; other?: true }[]; note?: string }[]; mix: Knobs; tuned: Knobs; comments: { part: string | null; text: string }[] };
+  comments: { text: string; state: string | null; variant: string | null }[];
+  accepted: { state: string | null; variant: string }[]; archived: { state: string | null; variant: string }[];
+};
+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. */
+  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 }>;
+  /** 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>;
+  export(v: Ref): Promise<{ states: { state: string | null; variant: string; version: number; html: string }[]; reply: unknown }>;
+  /** data: base64 bytes. Use id as an image surface's assetId. */
+  upload(data: string, opts: { contentType: string; filename?: string; kind?: "image" | "file" }): Promise<{ id: string; url: string }>;
+};
+declare function print(...values: unknown[]): void;`;
+// The host functions a script can reach, by the dotted name the calls log uses.
+export const RUN_FUNCTIONS = [
+    "guide",
+    "read",
+    "publish",
+    "ask",
+    "feedback",
+    "say",
+    "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") });
+const { url } = await mockpit.ask("writer", [{ id: "look", text: "Which look?",
+  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 > " +
+    "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() " +
+    "before the first html.\n\n" +
+    `\`\`\`ts\n${RUN_API}\n\`\`\`\n\nExample:\n\`\`\`js\n${RUN_EXAMPLE}\n\`\`\``;
+export const RUN_INSTRUCTIONS = "Mockpit shows design work to the user. Call run with a JavaScript body that uses the " +
+    "mockpit API in its description: publish variants, ask, then end your turn. When the user " +
+    "says they answered, run mockpit.feedback(). Feedback is delivered once; read the run's " +
+    "feedback field.";

package/dist/server/slots.d.ts

@@ -0,0 +1,14 @@
+import type { Slot } from "./types.ts";
+export interface SlotTag {
+    raw: string;
+    slug: string;
+    variant: string;
+    version: number | null;
+}
+export declare function parseSlotTags(html: string): SlotTag[];
+export declare function resolveSlots(html: string, currentVersion: (slug: string, variant: string) => number | null): Slot[];
+export declare function expandSlots(html: string, body: (slot: {
+    slug: string;
+    variant: string;
+    version: number | null;
+}) => string | null): string;

package/dist/server/slots.js

@@ -0,0 +1,71 @@
+// Page composition: `<mockpit-slot slug="…" variant="…" version="…">` tags in a
+// page item's html are expanded server-side by inlining the referenced variant
+// version's first html surface body. Snapshot semantics — publish resolves a
+// missing `version` to the component's current one and stores the resolved list
+// on the post, so a page keeps rendering what it was composed from.
+//
+// Runtime-agnostic (no node imports) and string-only: the result is handed to
+// renderHtmlPage, which serves it from /s/:id under the sandbox CSP header, so
+// an inlined component body is exactly as contained as the page's own markup.
+const SLOT_TAG = /<mockpit-slot\b([^>]*?)(?:\/>|>\s*<\/mockpit-slot\s*>|>)/gi;
+const ATTR = /([a-z-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))/gi;
+function attributes(raw) {
+    const out = {};
+    ATTR.lastIndex = 0;
+    let m;
+    while ((m = ATTR.exec(raw)))
+        out[m[1].toLowerCase()] = m[2] ?? m[3] ?? m[4] ?? "";
+    return out;
+}
+export function parseSlotTags(html) {
+    const tags = [];
+    SLOT_TAG.lastIndex = 0;
+    let m;
+    while ((m = SLOT_TAG.exec(html))) {
+        const attrs = attributes(m[1] ?? "");
+        const slug = attrs.slug ?? "";
+        if (!slug)
+            continue;
+        const version = Number(attrs.version);
+        tags.push({
+            raw: m[0],
+            slug,
+            variant: attrs.variant || "default",
+            version: Number.isInteger(version) && version > 0 ? version : null,
+        });
+    }
+    return tags;
+}
+// The slot list to store on a page post: every tag with its version resolved
+// (a missing one pins to the component's current version at publish time).
+export function resolveSlots(html, currentVersion) {
+    const slots = [];
+    for (const tag of parseSlotTags(html)) {
+        const version = tag.version ?? currentVersion(tag.slug, tag.variant);
+        if (version == null)
+            continue;
+        slots.push({ slug: tag.slug, variant: tag.variant, version });
+    }
+    return slots;
+}
+const escapeAttr = (s) => s.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+// Replace each tag with the resolved body. An unresolvable slot renders as an
+// empty marked-up placeholder rather than vanishing, so a broken reference is
+// visible in review instead of silently changing the layout.
+export function expandSlots(html, body) {
+    SLOT_TAG.lastIndex = 0;
+    return html.replace(SLOT_TAG, (raw, attrRaw) => {
+        const attrs = attributes(attrRaw ?? "");
+        const slug = attrs.slug ?? "";
+        if (!slug)
+            return raw;
+        const variant = attrs.variant || "default";
+        const parsed = Number(attrs.version);
+        const version = Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+        const resolved = body({ slug, variant, version });
+        const label = `data-mockpit-slot="${escapeAttr(slug)}" data-mockpit-variant="${escapeAttr(variant)}"${version == null ? "" : ` data-mockpit-version="${version}"`}`;
+        return resolved == null
+            ? `<div ${label} data-mockpit-missing="1"></div>`
+            : `<div ${label}>${resolved}</div>`;
+    });
+}

package/dist/server/sqlStore.d.ts

@@ -0,0 +1,119 @@
+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 MockKind, type Post, type PostQuery, type PostStatus, type PostVersion, type Session, type Slot, type SqlStorage, type Store, type Surface, type UpdateMockInput, type UpdatePostInput } from "./types.ts";
+export declare class SqlStore implements Store {
+    private sql;
+    private assetRefCache;
+    constructor(sql: SqlStorage);
+    private atomic;
+    private tables;
+    private columns;
+    private addMissing;
+    private migrate;
+    private createIndexes;
+    private migrateLegacy;
+    private migrateToSurfaces;
+    private migrateToPosts;
+    private migrateSurfaceIds;
+    private migrateToItems;
+    private migrateToVersions;
+    private migrateToMocks;
+    private settingSync;
+    private insertVersion;
+    private rowToVersion;
+    private historiesFor;
+    private rowsToPosts;
+    private rowToSession;
+    private rowToMock;
+    private rowToPost;
+    private rowToAsset;
+    private rowToComment;
+    listSessions(): Promise<Session[]>;
+    getSession(id: string): Promise<Session | null>;
+    getSessionByKey(key: string): Promise<Session | null>;
+    createSession(input: CreateSessionInput): Promise<Session>;
+    renameSession(id: string, title: string): Promise<Session | null>;
+    removeSession(id: string): Promise<boolean>;
+    private touch;
+    markAgentSeen(sessionId: string, seq: number): Promise<void>;
+    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>;
+    putDraft(mockId: string, draft: Draft | null): Promise<{
+        draft: Draft | null;
+        id: string;
+        project: string;
+        slug: string;
+        title: string;
+        kind: MockKind;
+        states: string[];
+        asks: Ask[];
+        knobs: Knobs;
+        sessionId: string | null;
+        createdAt: string;
+        updatedAt: string;
+    } | null>;
+    private touchMock;
+    listPosts(query?: PostQuery): Promise<Post[]>;
+    countPostsBySession(): Promise<Map<string, number>>;
+    getPost(id: string): Promise<Post | null>;
+    findPost(mockId: string, state: string | null, variant: string): Promise<Post | null>;
+    createPost(input: CreatePostInput): Promise<Post | null>;
+    updatePost(id: string, patch: UpdatePostInput): Promise<{
+        author?: string | undefined;
+        slots: Slot[];
+        state: string | null;
+        version: number;
+        updatedAt: string;
+        history: PostVersion[];
+        from: number;
+        prompt: string;
+        knobs?: Knobs | undefined;
+        title: string;
+        surfaces: Surface[];
+        id: string;
+        sessionId: string;
+        mock: string;
+        variant: string;
+        status: PostStatus;
+        createdAt: string;
+    } | null>;
+    removePost(id: string): Promise<boolean>;
+    setPostStatus(id: string, status: PostStatus): Promise<{
+        status: PostStatus;
+        id: string;
+        sessionId: string;
+        mock: string;
+        state: string | null;
+        variant: string;
+        title: string;
+        surfaces: Surface[];
+        createdAt: string;
+        updatedAt: string;
+        version: number;
+        history: PostVersion[];
+        knobs?: Knobs;
+        slots: Slot[];
+        from?: number;
+        prompt?: string;
+        author?: string;
+    } | null>;
+    listComments(query: CommentQuery): Promise<Comment[]>;
+    private insertComment;
+    createComment(input: CreateCommentInput): Promise<Comment | null>;
+    removeComment(id: string): Promise<Comment | null>;
+    commitReply(input: CommitReplyInput): Promise<Comment | null>;
+    private referencedAssetIds;
+    private addAssetRefs;
+    private invalidateAssetRefs;
+    putAsset(input: CreateAssetInput): Promise<Asset | null>;
+    getAsset(id: string): Promise<Asset | null>;
+    touchAsset(id: string): Promise<void>;
+    listAssets(sessionId: string): Promise<Asset[]>;
+    removeAsset(id: string): Promise<boolean>;
+    isAssetReferenced(id: string): Promise<boolean>;
+}