mockpit 1.2.0 → 2.0.0

package/dist/server/fills.d.ts

@@ -0,0 +1,41 @@
+import type { Knobs, Surface } from "./types.ts";
+export interface Fill {
+    name: string;
+    label?: string;
+}
+export interface SlotInfo {
+    part: string;
+    label?: string;
+    fills: Fill[];
+    default: string;
+    parent: {
+        part: string;
+        fill: string;
+    } | null;
+}
+interface Range {
+    part: string;
+    fill: string;
+    start: number;
+    end: number;
+    tagEnd: number;
+}
+export interface FillScan {
+    slots: SlotInfo[];
+    ranges: Range[];
+}
+export declare function scanFills(html: string): FillScan;
+export declare function slotKnobs(slots: SlotInfo[]): Knobs;
+export declare function slotCss(slots: SlotInfo[]): string;
+export declare function composeFills(html: string, chosen: Record<string, string>): string;
+export declare function slotsInSurfaces(surfaces: Surface[]): SlotInfo[];
+export type FillSplice = {
+    ok: true;
+    surfaces: Surface[];
+    applied: string[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare function spliceFills(surfaces: Surface[], edits: Record<string, string>): FillSplice;
+export {};

package/dist/server/fills.js

@@ -0,0 +1,328 @@
+// Slots: a part with alternative fills, declared in the agent's own markup.
+//
+//   <section data-part="entry" data-fill="dots">…</section>
+//   <section data-part="entry" data-fill="skeleton">…</section>
+//
+// Elements sharing a `data-part` name with two or more distinct `data-fill`
+// values make one slot. The first fill in document order is the default unless
+// one carries `data-fill-default`. A fill may hold further slots: the scan
+// records, for each slot, the fill it sits in, so the viewer can ask about it
+// only while that fill is chosen.
+//
+// String-only and runtime-agnostic, like parts.ts: identity is read from the
+// markup, never from a DOM. The scan is a tolerant tag walker, not a parser:
+// it tracks open elements to know containment and each fill's extent, skips
+// comments and raw-text elements, and treats an unclosed element as ending at
+// the next close of an outer one.
+const VOID = new Set([
+    "area",
+    "base",
+    "br",
+    "col",
+    "embed",
+    "hr",
+    "img",
+    "input",
+    "link",
+    "meta",
+    "param",
+    "source",
+    "track",
+    "wbr",
+]);
+const RAW = new Set(["script", "style", "textarea", "title"]);
+const TOKEN = /<!--[\s\S]*?-->|<\/([A-Za-z][\w:-]*)\s*>|<([A-Za-z][\w:-]*)((?:\s[^<>]*?)?)(\/?)>/g;
+// Longest names first, and each must end at the name's end: `data-fill`
+// must not match the start of `data-fill-label`.
+const ATTR = /\s(data-part-label|data-part|data-fill-label|data-fill-default|data-fill)(?=[\s=/>]|$)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+// A slot's knob path is its part name, so the name must be a valid path segment.
+const PATH_SEGMENT = /^[A-Za-z_][\w-]{0,63}$/;
+const MAX_SLOTS = 100;
+const decode = (s) => s
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;|&apos;/g, "'")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&")
+    .trim()
+    .slice(0, 200);
+function attributes(raw) {
+    const out = {};
+    ATTR.lastIndex = 0;
+    let m;
+    while ((m = ATTR.exec(raw)))
+        out[m[1]] = decode(m[2] ?? m[3] ?? m[4] ?? "");
+    return out;
+}
+export function scanFills(html) {
+    const { slots, ranges } = scanAll(html);
+    const real = slots.filter((s) => s.fills.length >= 2);
+    const isSlot = new Set(real.map((s) => s.part));
+    return { slots: real, ranges: ranges.filter((r) => isSlot.has(r.part)) };
+}
+// Every part carrying `data-fill`, a lone fill included: a splice may add the
+// second fill that makes it a slot.
+function scanAll(html) {
+    const ranges = [];
+    // Per part, in document order: each fill element and the fill it sits in.
+    const seen = new Map();
+    const stack = [];
+    const close = (i, end) => {
+        for (let j = stack.length - 1; j >= i; j--) {
+            const f = stack[j].fill;
+            if (f)
+                f.end = end;
+        }
+        stack.length = i;
+    };
+    TOKEN.lastIndex = 0;
+    let m;
+    while ((m = TOKEN.exec(html))) {
+        if (m[0].startsWith("<!--"))
+            continue;
+        if (m[1]) {
+            const tag = m[1].toLowerCase();
+            for (let i = stack.length - 1; i >= 0; i--) {
+                if (stack[i].tag === tag) {
+                    close(i, TOKEN.lastIndex);
+                    break;
+                }
+            }
+            continue;
+        }
+        const tag = m[2].toLowerCase();
+        const attrs = attributes(m[3] ?? "");
+        let fill = null;
+        const part = attrs["data-part"];
+        const name = attrs["data-fill"];
+        if (part && name && PATH_SEGMENT.test(part)) {
+            fill = { part, fill: name, start: m.index, end: html.length, tagEnd: TOKEN.lastIndex };
+            ranges.push(fill);
+            let slot = seen.get(part);
+            if (!slot && seen.size < MAX_SLOTS) {
+                const outer = [...stack].reverse().find((o) => o.fill)?.fill ?? null;
+                slot = {
+                    fills: [],
+                    defaults: [],
+                    parent: outer ? { part: outer.part, fill: outer.fill } : null,
+                };
+                seen.set(part, slot);
+            }
+            if (slot) {
+                if (attrs["data-part-label"] && !slot.label)
+                    slot.label = attrs["data-part-label"];
+                if (!slot.fills.some((f) => f.name === name)) {
+                    slot.fills.push({
+                        name,
+                        ...(attrs["data-fill-label"] ? { label: attrs["data-fill-label"] } : {}),
+                    });
+                }
+                if ("data-fill-default" in attrs)
+                    slot.defaults.push(name);
+            }
+        }
+        if (VOID.has(tag) || m[4] === "/") {
+            if (fill)
+                fill.end = TOKEN.lastIndex;
+            continue;
+        }
+        if (RAW.has(tag)) {
+            // Skip to the matching close: markup inside script or style is text.
+            const endTag = new RegExp(`</${tag}\\s*>`, "gi");
+            endTag.lastIndex = TOKEN.lastIndex;
+            const e = endTag.exec(html);
+            TOKEN.lastIndex = e ? endTag.lastIndex : html.length;
+            if (fill)
+                fill.end = TOKEN.lastIndex;
+            continue;
+        }
+        stack.push({ tag, fill });
+    }
+    const slots = [];
+    for (const [part, s] of seen) {
+        slots.push({
+            part,
+            ...(s.label ? { label: s.label } : {}),
+            fills: s.fills,
+            default: s.defaults[0] ?? s.fills[0].name,
+            parent: s.parent,
+        });
+    }
+    return { slots, ranges };
+}
+// Each slot is a select knob at its part's path: the fills are its options and
+// the default fill is its value. A knob the agent declares at the same path
+// wins (to relabel the options), so these are merged under declared knobs.
+export function slotKnobs(slots) {
+    const out = {};
+    for (const s of slots) {
+        const config = {
+            type: "select",
+            options: s.fills.map((f) => (f.label ? { value: f.name, label: f.label } : f.name)),
+            value: s.default,
+        };
+        out[s.part] = config;
+    }
+    return out;
+}
+const cssString = (s) => `"${s.replace(/[\\"]/g, (c) => `\\${c}`).replace(/[\n\r<>]/g, (c) => `\\${c.charCodeAt(0).toString(16)} `)}"`;
+// Shows only the chosen fill of each slot, keyed on the `data-k-<part>`
+// attribute the knob runtime keeps on <html>. The chosen fill is never styled:
+// only the others are hidden, so a fill keeps whatever display the agent gave it.
+export function slotCss(slots) {
+    const rules = [];
+    for (const s of slots) {
+        const attr = `data-k-${s.part}`;
+        for (const f of s.fills) {
+            const el = `[data-part=${cssString(s.part)}][data-fill=${cssString(f.name)}]`;
+            const chosen = `[${attr}=${cssString(f.name)}]`;
+            rules.push(f.name === s.default
+                ? `html[${attr}]:not(${chosen}) ${el}{display:none!important}`
+                : `html:not(${chosen}) ${el}{display:none!important}`);
+        }
+    }
+    return rules.join("\n");
+}
+const FILL_ATTRS = /\s(data-fill-label|data-fill-default|data-fill)(?=[\s=/>]|$)(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>`]+))?/g;
+// The screen as chosen: every slot reduced to its chosen fill, the others cut
+// out with whatever they contained, and the fill attributes dropped from the
+// fills that stay. `chosen` maps a slot's part to a fill; a slot it does not
+// name keeps its default.
+export function composeFills(html, chosen) {
+    const { slots, ranges } = scanFills(html);
+    const pick = new Map(slots.map((s) => [s.part, chosen[s.part] ?? s.default]));
+    const cut = ranges.filter((r) => pick.get(r.part) !== r.fill);
+    const kept = ranges.filter((r) => pick.get(r.part) === r.fill);
+    const edits = [];
+    for (const r of cut) {
+        if (cut.some((o) => o !== r && o.start <= r.start && r.end <= o.end))
+            continue;
+        edits.push({ start: r.start, end: r.end, text: "" });
+    }
+    for (const r of kept) {
+        if (cut.some((o) => o.start <= r.start && r.end <= o.end))
+            continue;
+        edits.push({
+            start: r.start,
+            end: r.tagEnd,
+            text: html.slice(r.start, r.tagEnd).replace(FILL_ATTRS, ""),
+        });
+    }
+    edits.sort((a, b) => b.start - a.start);
+    let out = html;
+    for (const e of edits)
+        out = out.slice(0, e.start) + e.text + out.slice(e.end);
+    return out;
+}
+// A post's slots across its html surfaces (the first surface that declares a
+// part wins), cached per surfaces array: a stored post never mutates it.
+const bySurfaces = new WeakMap();
+export function slotsInSurfaces(surfaces) {
+    const hit = bySurfaces.get(surfaces);
+    if (hit)
+        return hit;
+    const out = [];
+    for (const sf of surfaces) {
+        if (sf.kind !== "html")
+            continue;
+        for (const slot of scanFills(sf.html).slots) {
+            if (!out.some((o) => o.part === slot.part))
+                out.push(slot);
+        }
+    }
+    bySurfaces.set(surfaces, out);
+    return out;
+}
+const attrValue = (s) => s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+const FIRST_TAG = /^(?:\s|<!--[\s\S]*?-->)*<([A-Za-z][\w:-]*)((?:\s[^<>]*?)?)(\/?)>/;
+// The replacement must be one element marked as that fill: the marks are added
+// when missing and a contradicting one is refused, so a splice cannot quietly
+// land in another slot.
+function markFill(html, part, fill) {
+    const m = FIRST_TAG.exec(html);
+    if (!m)
+        return { error: `fill "${part}#${fill}" must be html starting with its element` };
+    const attrs = attributes(m[2] ?? "");
+    if (attrs["data-part"] !== undefined && attrs["data-part"] !== part) {
+        return { error: `fill "${part}#${fill}" is marked data-part="${attrs["data-part"]}"` };
+    }
+    if (attrs["data-fill"] !== undefined && attrs["data-fill"] !== fill) {
+        return { error: `fill "${part}#${fill}" is marked data-fill="${attrs["data-fill"]}"` };
+    }
+    const add = (attrs["data-part"] === undefined ? ` data-part="${attrValue(part)}"` : "") +
+        (attrs["data-fill"] === undefined ? ` data-fill="${attrValue(fill)}"` : "");
+    const at = m.index + m[0].indexOf("<") + 1 + m[1].length;
+    return html.slice(0, at) + add + html.slice(at);
+}
+// Replace one fill of a slot, or add it after the slot's last fill, keyed
+// "part#fill". Like spliceParts, every target is located in the original
+// markup and overlapping edits are refused.
+export function spliceFills(surfaces, edits) {
+    const docs = surfaces.flatMap((s, i) => (s.kind === "html" ? [{ i, surface: s }] : []));
+    if (docs.length === 0) {
+        return { ok: false, error: "fills needs an html surface; this variant has none" };
+    }
+    const scans = docs.map((d) => scanAll(d.surface.html).ranges);
+    const plan = new Map();
+    const targets = Object.keys(edits);
+    for (const [n, target] of targets.entries()) {
+        const at = target.indexOf("#");
+        const part = at > 0 ? target.slice(0, at) : "";
+        const fill = at > 0 ? target.slice(at + 1).trim() : "";
+        if (!PATH_SEGMENT.test(part) || !fill) {
+            return {
+                ok: false,
+                error: `fills keys are "part#fill", e.g. "entry#skeleton" (got "${target}")`,
+            };
+        }
+        const where = scans.flatMap((rs, d) => (rs.some((r) => r.part === part) ? [d] : []));
+        if (where.length === 0) {
+            return {
+                ok: false,
+                error: `no fills of "${part}"; mark its alternatives data-part="${part}" data-fill="<name>" with html or parts first`,
+            };
+        }
+        if (where.length > 1) {
+            return {
+                ok: false,
+                error: `fills of "${part}" are in several html surfaces; revise with surfaces`,
+            };
+        }
+        const d = where[0];
+        const own = scans[d].filter((r) => r.part === part);
+        const same = own.filter((r) => r.fill === fill);
+        if (same.length > 1) {
+            return {
+                ok: false,
+                error: `fill "${target}" appears ${same.length} times; revise with html or parts`,
+            };
+        }
+        const text = markFill(edits[target], part, fill);
+        if (typeof text !== "string")
+            return { ok: false, error: text.error };
+        const edit = same.length
+            ? { start: same[0].start, end: same[0].end, text, n }
+            : (() => {
+                const end = Math.max(...own.map((r) => r.end));
+                return { start: end, end, text: `\n${text}`, n };
+            })();
+        const list = plan.get(d) ?? [];
+        const clash = list.find((e) => e.start < edit.end && edit.start < e.end);
+        if (clash) {
+            return { ok: false, error: `fills "${targets[clash.n]}" and "${target}" overlap; send one` };
+        }
+        list.push(edit);
+        plan.set(d, list);
+    }
+    const next = [...surfaces];
+    for (const [d, list] of plan) {
+        const { i, surface } = docs[d];
+        let html = surface.html;
+        // From the end, and same-place additions last-listed first, so they land in listed order.
+        for (const e of list.toSorted((a, b) => b.start - a.start || b.n - a.n)) {
+            html = html.slice(0, e.start) + e.text + html.slice(e.end);
+        }
+        next[i] = { ...surface, html };
+    }
+    return { ok: true, surfaces: next, applied: targets };
+}

package/dist/server/guidance.d.ts

@@ -0,0 +1,23 @@
+export declare const GUIDE_PACKS: readonly ["design-craft"];
+export type GuidePack = (typeof GUIDE_PACKS)[number];
+export declare const RULES_SETTING = "rules";
+export declare const USER_RULES_SETTING = "userRules";
+export declare const MAX_RULES_CHARS = 6000;
+export interface RulesFile {
+    packs: string[];
+    body: string;
+}
+export declare function parseRulesFile(text: string): RulesFile;
+export interface GuidanceInput {
+    packs: Partial<Record<GuidePack, string>>;
+    user: string | null;
+    project: string | null;
+}
+/**
+ * The guidance line and sections for the brief, or "" when only core is on:
+ * a workspace that never wrote a rules file gets the brief it always had.
+ */
+export declare function guidanceSections(input: GuidanceInput): {
+    line: string;
+    body: string;
+};

package/dist/server/guidance.js

@@ -0,0 +1,71 @@
+// Guidance layers on top of the core brief: packs that ship with mockpit (off
+// until a rules file names them), the user's own rules and the project's.
+// Higher wins: project, then the user's, then packs, then core. The brief
+// prints them in that order from the bottom up, so the last word an agent
+// reads is the one that wins.
+//
+// Runtime-agnostic (no node imports): the Worker builds the brief too.
+export const GUIDE_PACKS = ["design-craft"];
+const isGuidePack = (id) => GUIDE_PACKS.includes(id);
+// `rules:<project>` sits beside `design:<project>` and moves with a project
+// rename. The user's own rules are not a project, so their key has no colon:
+// a project named "user" can't collide with it.
+export const RULES_SETTING = "rules";
+export const USER_RULES_SETTING = "userRules";
+// A rules file is read whole into every brief, so it stays a page, not a book.
+export const MAX_RULES_CHARS = 6_000;
+// `---\npacks: [design-craft]\n---` (or `packs: a, b`, or a `- a` list), then
+// markdown. Anything else in the frontmatter is ignored rather than refused:
+// the file is the user's, and a stray key must not cost them their rules.
+export function parseRulesFile(text) {
+    const src = text.replace(/\r\n?/g, "\n");
+    const m = /^---\n([\s\S]*?)\n---[ \t]*(?:\n|$)/.exec(src);
+    if (!m)
+        return { packs: [], body: src.trim() };
+    const packs = [];
+    const lines = m[1].split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const kv = /^packs\s*:\s*(.*)$/.exec(lines[i].trim());
+        if (!kv)
+            continue;
+        const inline = kv[1].trim().replace(/^\[|\]$/g, "");
+        if (inline)
+            packs.push(...inline.split(","));
+        for (let j = i + 1; j < lines.length && /^\s*-\s+/.test(lines[j]); j++) {
+            packs.push(lines[j].replace(/^\s*-\s+/, ""));
+        }
+    }
+    const names = packs.map((p) => p.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+    return { packs: [...new Set(names)], body: src.slice(m[0].length).trim() };
+}
+// The layer files' own `## Rules` / `## Suggestions` sit one level under the
+// layer's heading in the brief.
+const demote = (md) => md.replace(/^(#{1,5}) /gm, "#$1 ");
+/**
+ * The guidance line and sections for the brief, or "" when only core is on:
+ * a workspace that never wrote a rules file gets the brief it always had.
+ */
+export function guidanceSections(input) {
+    const user = input.user ? parseRulesFile(input.user) : null;
+    const project = input.project ? parseRulesFile(input.project) : null;
+    const named = [...new Set([...(user?.packs ?? []), ...(project?.packs ?? [])])];
+    const on = named.filter((p) => isGuidePack(p) && !!input.packs[p]);
+    const unknown = named.filter((p) => !on.includes(p));
+    const layers = [
+        ...on.map((p) => ({ label: p, heading: `Pack: ${p}`, text: input.packs[p].trim() })),
+        ...(user?.body ? [{ label: "your rules", heading: "Your rules", text: user.body }] : []),
+        ...(project?.body
+            ? [{ label: "project", heading: "This project's rules", text: project.body }]
+            : []),
+    ];
+    if (layers.length === 0 && unknown.length === 0)
+        return { line: "", body: "" };
+    const missing = unknown.length
+        ? ` (unknown pack ${unknown.map((p) => `"${p}"`).join(", ")}; packs: ${GUIDE_PACKS.join(", ")})`
+        : "";
+    const line = `Guidance: ${["core", ...layers.map((l) => l.label)].join(" · ")}${missing}. ` +
+        "Higher wins: project, then yours, then packs, then core; the user's own words beat " +
+        "all of them. **Rules** are always followed; **Suggestions** are aimed for.";
+    const body = layers.map((l) => `## ${l.heading}\n\n${demote(l.text)}`).join("\n\n");
+    return { line, body };
+}

package/dist/server/index.js

@@ -1,11 +1,13 @@
 import { serve } from "@hono/node-server";
-import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createApp } from "./app.js";
 import { createNodeExecutor } from "./codeRunner.js";
 import { GUIDE_TOPICS } from "./designGuide.js";
+import { GUIDE_PACKS } from "./guidance.js";
 import { createFileLog } from "./logFile.js";
 import { SqlStore } from "./sqlStore.js";
 import { createSqliteStorage } from "./sqliteStorage.js";
@@ -15,16 +17,30 @@ import { createSqliteStorage } from "./sqliteStorage.js";
 let root = join(dirname(fileURLToPath(import.meta.url)), "..");
 if (basename(root) === "dist")
     root = join(root, "..");
-const [viewerHtml, setupText, topicTexts, pkgJson] = await Promise.all([
+const [viewerHtml, setupText, topicTexts, packTexts, pkgJson] = await Promise.all([
     readFile(join(root, "viewer", "dist", "index.html"), "utf8").catch(() => {
         console.error("viewer build missing — run `npm run build:viewer` first");
         return process.exit(1);
     }),
     readFile(join(root, "guide", "AGENT_SETUP.md"), "utf8"),
     Promise.all(GUIDE_TOPICS.map((id) => readFile(join(root, "guide", "topics", `${id}.md`), "utf8"))),
+    Promise.all(GUIDE_PACKS.map((id) => readFile(join(root, "guide", "packs", `${id}.md`), "utf8"))),
     readFile(join(root, "package.json"), "utf8"),
 ]);
 const topics = Object.fromEntries(GUIDE_TOPICS.map((id, i) => [id, topicTexts[i]]));
+const packs = Object.fromEntries(GUIDE_PACKS.map((id, i) => [id, packTexts[i]]));
+// What renders surface documents: this server's own files and the locked
+// library versions. Hashed whole rather than picked apart, so an edit in dev or
+// an upgrade both reach browsers holding an old document; a change elsewhere
+// in the server only costs one re-fetch per document.
+const serverDir = dirname(fileURLToPath(import.meta.url));
+const renderHash = createHash("sha256");
+for (const name of (await readdir(serverDir)).sort()) {
+    if (/\.(ts|js)$/.test(name))
+        renderHash.update(await readFile(join(serverDir, name)));
+}
+renderHash.update(await readFile(join(root, "package-lock.json")).catch(() => pkgJson));
+const renderRev = renderHash.digest("hex").slice(0, 10);
 const pr = process.env.MOCKPIT_PUBLIC_READ;
 const publicRead = pr === "session" || pr === "full" ? pr : undefined;
 // Storage: SQLite via node:sqlite, the same SqlStore the Cloudflare Durable
@@ -44,17 +60,24 @@ const logPath = logSetting === "off"
     : logSetting || (dbPath === ":memory:" ? undefined : join(dirname(dbPath), "events.jsonl"));
 if (logPath)
     console.log(`mockpit event log: ${logPath}`);
+// The user's own rules live next to the database, so a throwaway or test
+// database never picks up the real ones.
+const rulesPath = dbPath === ":memory:" ? undefined : join(dirname(dbPath), "rules.md");
+const userRules = rulesPath ? () => readFile(rulesPath, "utf8").catch(() => null) : undefined;
 const app = createApp({
     store,
     viewerHtml,
     setupText,
     topics,
+    packs,
+    userRules,
     authToken: process.env.MOCKPIT_TOKEN,
     publicRead,
     // MOCKPIT_VERSION fakes the running version (manual testing of the
     // notice); set it to the empty string to disable the update check
     version: process.env.MOCKPIT_VERSION ?? JSON.parse(pkgJson).version,
     upgradeCommand: "npm install -g mockpit",
+    renderRev,
     // `run` scripts execute in QuickJS inside a worker thread per run.
     executor: createNodeExecutor(),
     log: logPath ? createFileLog(logPath) : undefined,

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) {

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;
@@ -28,6 +31,8 @@ export interface McpFlows {
         session?: unknown;
         project?: unknown;
     }, ctx: FlowContext]>;
+    edit: Flow<[ref: unknown, body: any, ctx: FlowContext]>;
+    editProject: Flow<[name: unknown, body: any, ctx: FlowContext]>;
 }
 export interface McpDeps {
     store: Store;
@@ -49,5 +54,6 @@ export interface McpDeps {
     guide(project: string, topic?: GuideTopic): string | Promise<string>;
 }
 export declare function unwrap(result: FlowResult): unknown;
+export declare function editCall(flows: Pick<McpFlows, "edit" | "editProject">, args: any, ctx: FlowContext, project: string | undefined): Promise<FlowResult>;
 export declare function registerMcp(app: Hono, deps: McpDeps): void;
 export {};

package/dist/server/mcpHttp.js

@@ -11,6 +11,27 @@ export function unwrap(result) {
     }
     return result.body;
 }
+// `edit` is one verb with two shapes: `rename` or `areaOrder` edits the
+// project, anything else edits the mock. Shared by both MCP transports' HTTP
+// side and `run`.
+export function editCall(flows, args, ctx, project) {
+    if (args.rename === undefined && args.areaOrder === undefined) {
+        return flows.edit(args.mock, args, ctx);
+    }
+    if (args.mock !== undefined) {
+        return Promise.resolve({
+            status: 400,
+            body: { error: '"rename" and "areaOrder" edit the project; edit the mock without them' },
+        });
+    }
+    if (!project) {
+        return Promise.resolve({
+            status: 400,
+            body: { error: 'provide "project": the project to edit' },
+        });
+    }
+    return flows.editProject(project, { name: args.rename, areaOrder: args.areaOrder, session: args.session }, ctx);
+}
 export function registerMcp(app, deps) {
     const { flows, store } = deps;
     async function projectOf(args) {
@@ -24,6 +45,15 @@ export function registerMcp(app, deps) {
         const projects = await store.listProjects();
         return projects[0]?.name ?? "workspace";
     }
+    // Only a project the call names, or its session's: a rename never falls back
+    // to whichever project happens to be first.
+    async function namedProject(args) {
+        if (typeof args.project === "string" && args.project)
+            return args.project;
+        if (typeof args.session !== "string")
+            return undefined;
+        return (await store.getSession(args.session))?.project ?? undefined;
+    }
     async function loadImage(ref) {
         const asset = await store.getAsset(ref.id);
         return asset ? { data: asset.data, mimeType: asset.contentType } : null;
@@ -35,6 +65,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, {
@@ -48,6 +81,8 @@ export function registerMcp(app, deps) {
                 return unwrap(await flows.say(args.mock, args, ctx));
             case "export":
                 return unwrap(await flows.exportMock(args.mock, args, ctx));
+            case "edit":
+                return unwrap(await editCall(flows, args, ctx, await namedProject(args)));
             case "upload": {
                 if (typeof args.data !== "string" || args.data.length === 0) {
                     throw new Error("upload needs base64 `data`");