mockpit 0.0.0-stage → 1.0.0

package/dist/server/app.js

@@ -0,0 +1,3112 @@
+import { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import { getCookie, setCookie } from "hono/cookie";
+import { streamSSE } from "hono/streaming";
+import { decodeBase64 } from "./base64.js";
+import { mockDetailView, mockSummaryView, sessionRowView, surfaceRef } from "./apiViews.js";
+import { EventBus } from "./events.js";
+import { GUIDE_TOPICS, isGuideTopic, renderBriefGuide, unknownTopicMessage, } from "./designGuide.js";
+import { buildFeedbackBatches } from "./feedbackBatch.js";
+import { bundledIconSets, expandIcons, iconCount, isIconName, mayHaveIcons, parseIconSet, resolverFor, } from "./icons.js";
+import { checkProjectKit, KIT_IDS, kitSummaries } from "./kits.js";
+import { checkKnobs, checkKnobValues, discreteChoices } from "./knobs.js";
+import { diffParts, partsInSurfaces, spliceParts } from "./parts.js";
+import { postToMarkdown } from "./postMarkdown.js";
+import { addHook, addSubscription, isPushSubscription, listHooks, notify, removeHook, vapidKeys, } from "./push.js";
+import { expandSlots, parseSlotTags } from "./slots.js";
+import { registerMcp } from "./mcpHttp.js";
+import { createRunFlow, DEFAULT_RUN_LIMITS } from "./run.js";
+import { RUN_API } from "./runApi.js";
+import { escapeHtml, renderHtmlPage, renderMermaidPage, renderSandboxedPart, STATIC_ASSET_PREFIX, staticAsset, } from "./surfacePage.js";
+import { DEFAULT_MODE, DEFAULT_THEME_ID, isMode, themeById } from "./themes.js";
+import { BUILTIN_ASK_ID, builtinAsk, DEFAULT_PROJECT, DEFAULT_VARIANT, htmlSurface, isSandboxedSurfaceKind, MAX_ASSET_BYTES, newId, openCount, OTHER_ID, projectFromCwd, reservedAgent, slugify, surfacesByteLength, } from "./types.js";
+import { coerceSurfaces, validateSurfaces, } from "./postSurfaces.js";
+const MAX_SURFACE_BYTES = 2 * 1024 * 1024;
+// A held long-poll (watch, the viewer) re-arms rather than pinning a socket
+// for good; proxies and serverless hosts drop longer requests anyway.
+const MAX_WAIT_SECONDS = 230;
+// Hard ceiling on any request body, applied globally. Every write endpoint
+// reads its body with an unbounded `c.req.json()` (and /mcp likewise), so
+// without this a single oversize POST is an out-of-memory flood — and the local
+// default ships with no auth token, so those endpoints are reachable
+// unauthenticated. Sized to clear the largest legitimate body — a base64 asset
+// uploaded over MCP, ~4/3 of the 5 MiB asset cap — while still bounding a flood.
+// The /api/assets route's own 5 MiB streaming cap is stricter and still applies.
+const MAX_BODY_BYTES = 16 * 1024 * 1024;
+// A comment's text and a surface's title both ride the feedback channel back to
+// the agent in feedback batches, re-sent on every poll — so cap them at the
+// edge to keep one oversize value from bloating the agent's context forever.
+const MAX_COMMENT_TEXT = 8000;
+const MAX_TITLE = 500;
+// Ceiling on concurrently-held SSE + long-poll connections. Both are GETs that
+// pin a connection open (the event stream indefinitely, /api/comments?wait up
+// to MAX_WAIT_SECONDS); on a publicRead workspace they're reachable unauthenticated,
+// so without a cap a flood exhausts sockets. One app instance is one workspace
+// (a single Durable Object), and one workspace is one user — so legitimate
+// concurrent holds are small but not tiny: each open viewer tab holds one SSE,
+// and each active agent holds a long-poll (and possibly its own SSE). A
+// multi-agent session with 5 agents plus a few viewer tabs can legitimately
+// reach ~15. 32 clears that with headroom while still bounding a flood on a
+// no-token local workspace — and a real flood is orders of magnitude bigger, so
+// rejecting at 32 vs 16 makes no difference to flood protection, only to
+// legitimate use. Configurable so deployments can tune it and tests can
+// exercise the cap cheaply.
+const DEFAULT_MAX_HOLD_CONNECTIONS = 32;
+// Asset serving policy: only raster images are served inline; everything else
+// (incl. svg, json, text, the octet-stream catch-all) is an attachment, so a
+// top-level open of /a/:id can never execute an uploaded document as a live
+// same-origin script. <img>/fetch ignore Content-Disposition, so embedding
+// keeps working regardless.
+const INLINE_IMAGE_TYPES = new Set([
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+    "image/avif",
+]);
+const ATTACH_SAFE_TYPES = new Set([
+    "image/svg+xml",
+    "application/json",
+    "application/x-ndjson",
+    "text/plain",
+    "text/csv",
+]);
+function assetServeHeaders(asset) {
+    if (INLINE_IMAGE_TYPES.has(asset.contentType)) {
+        return { contentType: asset.contentType, disposition: "inline" };
+    }
+    const contentType = ATTACH_SAFE_TYPES.has(asset.contentType)
+        ? asset.contentType
+        : "application/octet-stream";
+    const name = (asset.filename || asset.id).replace(/[^\w.-]/g, "_");
+    return { contentType, disposition: `attachment; filename="${name}"` };
+}
+// Pick an AssetKind when the caller didn't specify one.
+function inferAssetKind(contentType) {
+    return contentType.startsWith("image/") ? "image" : "file";
+}
+const isAssetKind = (v) => v === "image" || v === "file";
+// Docs and onboarding snippets are written against the local default; serve
+// them with the real origin so a deployed instance shows copy-pasteable URLs.
+const LOCAL_ORIGIN = "http://localhost:8228";
+// Newer-than for plain x.y.z strings; prerelease suffixes compare as their
+// base version, and garbage compares as "not newer".
+function versionGt(a, b) {
+    const pa = a.split("-")[0].split(".").map(Number);
+    const pb = b.split("-")[0].split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0)
+            return d > 0;
+    }
+    return false;
+}
+// Latest published version from npm, release notes from the matching GitHub
+// release. Notes are garnish: if GitHub is unreachable the version alone
+// still makes a usable notice.
+async function fetchLatestFromRegistry() {
+    const res = await fetch("https://registry.npmjs.org/mockpit/latest");
+    if (!res.ok)
+        return null;
+    const pkg = (await res.json());
+    if (typeof pkg.version !== "string")
+        return null;
+    let notes;
+    try {
+        const gh = await fetch(`https://api.github.com/repos/fabiogaliano/mockpit/releases/tags/v${pkg.version}`, { headers: { "user-agent": "mockpit", accept: "application/vnd.github+json" } });
+        if (gh.ok) {
+            const rel = (await gh.json());
+            if (typeof rel.body === "string")
+                notes = rel.body;
+        }
+    }
+    catch {
+        // ignore — see above
+    }
+    return { version: pkg.version, notes };
+}
+const UPDATE_CHECK_TTL_MS = 6 * 60 * 60 * 1000;
+// In "session" mode only reads addressed by an unguessable id are public: a
+// mock id, a post id (its documents), an asset id, a session's comments/feed.
+// Anything addressed by NAME (projects, mock slugs, the mock list) would let a
+// single shared link enumerate the whole workspace, so it stays private.
+function isPublicReadAllowed(path, mode, query) {
+    if (mode === "full")
+        return true;
+    if (path.startsWith("/project/"))
+        return true;
+    if (path.startsWith("/s/"))
+        return true;
+    if (path.startsWith("/a/"))
+        return true;
+    if (/^\/api\/mocks\/[^/]+(\/export)?$/.test(path)) {
+        return !path.startsWith("/api/mocks/recent") && !query.has("project");
+    }
+    if (path === "/api/comments")
+        return true;
+    if (path === "/api/events")
+        return true;
+    if (path === "/api/theme")
+        return true;
+    if (path === "/api/version")
+        return true;
+    // A project's kits are named by project, so only the bundled list is public.
+    if (path === "/api/kits")
+        return !query.has("project");
+    return false;
+}
+const ok = (body, status = 200) => ({ status, body });
+const fail = (status, error, extra = {}) => ({
+    status,
+    body: { error, ...extra },
+});
+const str = (v, max) => typeof v === "string" && v.trim() ? v.trim().slice(0, max) : undefined;
+const MAX_LABEL = 120;
+const MAX_ASKS = 20;
+const MAX_OPTIONS = 20;
+const MAX_DRAFT_COMMENTS = 50;
+const titleFromSlug = (slug) => slug.replace(/-/g, " ").replace(/^./, (ch) => ch.toUpperCase());
+export function createApp({ store, viewerHtml, setupText, topics = {}, authenticate, authToken, basePath, publicRead, screenshots, version, upgradeCommand, fetchLatestRelease, onEvent, maxHoldConnections = DEFAULT_MAX_HOLD_CONNECTIONS, executor, runLimits, }) {
+    const app = new Hono();
+    // The scripts topic carries the run API from runApi.ts, its one source.
+    if (topics.scripts)
+        topics = {
+            ...topics,
+            scripts: topics.scripts.replace("<!-- run-api -->", `\`\`\`ts\n${RUN_API}\n\`\`\``),
+        };
+    // `?key=` bootstraps cookie auth, so never let a workspace URL disclose that
+    // credential to another origin through an outbound Referer header. Set this
+    // before auth so denied and public routes carry the same policy.
+    // The origin of the most recent request. A surface document bakes its origin
+    // in (CSP, <base>, asset URLs), so the publish-time pre-warm needs one — and a
+    // write arrives over the same origin the viewer is about to read from. It is
+    // only ever a cache-key input: an origin that turns out to be wrong wastes a
+    // warm entry, it can never be served to the wrong caller (renderKey includes it).
+    let lastOrigin = null;
+    app.use("*", (c, next) => {
+        lastOrigin = new URL(c.req.url).origin;
+        c.header("Referrer-Policy", "no-referrer");
+        return next();
+    });
+    const bus = new EventBus();
+    if (onEvent) {
+        bus.subscribe((event) => {
+            try {
+                onEvent(event);
+            }
+            catch (err) {
+                console.warn("[mockpit] onEvent listener failed", err);
+            }
+        });
+    }
+    // Live count of held SSE + long-poll connections, gated by maxHoldConnections.
+    // Each holder increments on entry and releases exactly once via a guarded
+    // release() wired to every exit (stream abort, request abort, normal return).
+    let holdConnections = 0;
+    // Only the viewer holds /api/events (watch long-polls), so an attached SSE
+    // client means someone has the workspace open.
+    let viewerClients = 0;
+    const acquireHold = () => {
+        if (holdConnections >= maxHoldConnections)
+            return false;
+        holdConnections++;
+        return true;
+    };
+    const makeRelease = () => {
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            holdConnections--;
+        };
+    };
+    // Rendered-document cache for /s/:id rich surfaces. Rendering a markdown/code/
+    // diff surface runs shiki / @pierre-diffs SSR, which is non-trivial (a big diff
+    // is tens of ms + tens of KB), so memoize the finished document string. The
+    // key pins everything the output depends on — post id, surface index, the
+    // RESOLVED version number, theme, mode — and a version's content is immutable,
+    // so a hit is always correct (a post edit bumps the version → a new key).
+    // Bounded by BYTES and LRU-evicted: a dropped entry costs a re-render, never
+    // correctness. Bounding the entry COUNT was the wrong axis — a document can
+    // weigh anything from 2 KB to ~900 KB, so 512 entries could mean 450 MB in an
+    // isolate with a 128 MB budget. The DurableObject is single-instance per
+    // workspace, so this in-memory cache is authoritative; a multi-instance deploy
+    // could back it with KV/Cache API behind the same key without changing callers.
+    const MAX_RENDER_CACHE_BYTES = 32 * 1024 * 1024;
+    const renderCache = new Map();
+    let renderCacheBytes = 0;
+    // UTF-16 code units × 2 is the retained JS string size, which is what this
+    // bound is protecting — not the transferred UTF-8 length.
+    const docBytes = (doc) => doc.length * 2;
+    const dropCacheEntry = (key) => {
+        const doc = renderCache.get(key);
+        if (doc === undefined)
+            return;
+        renderCacheBytes -= docBytes(doc);
+        renderCache.delete(key);
+    };
+    const clearRenderCache = () => {
+        renderCache.clear();
+        renderCacheBytes = 0;
+    };
+    // The response headers every surface document carries, on the cache-first
+    // path and the render path alike.
+    //
+    // The `sandbox` CSP sandboxes the document however it is loaded. The viewer
+    // embeds it in an iframe whose `sandbox="allow-scripts"` attribute gives it an
+    // opaque origin, but the document is served from the workspace's own origin —
+    // so a TOP-LEVEL load (a user opening /s/:id in a new tab, an agent-shared
+    // link) would otherwise run the agent's script in the workspace origin, where
+    // it could reach same-origin storage or window.open('/') the real viewer. A
+    // `sandbox` CSP can only be set as a response header (not the meta tag the
+    // page carries), and it forces the same opaque-origin sandbox on a direct
+    // navigation: allow-scripts so the bridge still runs, but no allow-same-origin,
+    // so agent code can never touch the workspace origin. Mirrors the iframe's
+    // sandbox flags.
+    //
+    // Version-pinned + themed requests (what the viewer always sends) are
+    // immutable, so they allow long-lived shared caching; an unpinned direct load
+    // is not.
+    function surfaceDocHeaders(c, immutable) {
+        c.header("X-Content-Type-Options", "nosniff");
+        c.header("Content-Security-Policy", "sandbox allow-scripts");
+        c.header("Cache-Control", immutable ? "public, max-age=31536000, immutable" : "private, no-cache");
+    }
+    function renderCacheHit(key) {
+        const hit = renderCache.get(key);
+        if (hit === undefined)
+            return undefined;
+        // refresh LRU recency
+        renderCache.delete(key);
+        renderCache.set(key, hit);
+        return hit;
+    }
+    async function cachedRender(key, build) {
+        const hit = renderCacheHit(key);
+        if (hit !== undefined)
+            return hit;
+        const doc = await build();
+        renderCache.set(key, doc);
+        renderCacheBytes += docBytes(doc);
+        while (renderCacheBytes > MAX_RENDER_CACHE_BYTES && renderCache.size > 1) {
+            const oldest = renderCache.keys().next().value;
+            if (oldest === undefined)
+                break;
+            dropCacheEntry(oldest);
+        }
+        return doc;
+    }
+    // Last-resort safety net: any handler that throws (rather than returning a
+    // status) becomes a clean JSON 500 instead of leaking a stack or a bare crash.
+    // Validation rejects bad input with 4xx before this, so reaching here means an
+    // unexpected bug — log it so it isn't swallowed silently.
+    app.onError((err, c) => {
+        console.error("mockpit: unhandled error", err);
+        return c.json({ error: "internal error" }, 500);
+    });
+    const normalizeBasePath = (value) => {
+        if (!value || value === "/")
+            return "";
+        const withLeading = value.startsWith("/") ? value : `/${value}`;
+        let end = withLeading.length;
+        while (end > 0 && withLeading.charCodeAt(end - 1) === 47)
+            end--;
+        return withLeading.slice(0, end);
+    };
+    const requestBasePath = (request) => normalizeBasePath(typeof basePath === "function" ? basePath(request) : basePath);
+    // Cached, fail-silent update lookup: being offline or rate-limited must
+    // cost nothing but the absence of the notice. Failures are cached too, so
+    // a dead network doesn't retry on every viewer load.
+    let updateCache = null;
+    async function latestRelease() {
+        if (updateCache && Date.now() - updateCache.at < UPDATE_CHECK_TTL_MS)
+            return updateCache.value;
+        const value = await (fetchLatestRelease ?? fetchLatestFromRegistry)().catch(() => null);
+        updateCache = { at: Date.now(), value };
+        return value;
+    }
+    // --- shared flows (used by both the REST API and the MCP endpoint) ---
+    // User comments the agent has not seen yet ride along on its next write, so
+    // agents hear feedback without blocking on the long-poll. The cursor also
+    // advances past the agent's own comments to keep reads cheap.
+    async function collectFeedback(sessionId) {
+        const session = await store.getSession(sessionId);
+        if (!session)
+            return [];
+        const fresh = await store.listComments({ sessionId, afterSeq: session.agentSeq });
+        if (fresh.length === 0)
+            return [];
+        await store.markAgentSeen(sessionId, fresh[fresh.length - 1].seq);
+        bus.broadcast({ type: "comment-delivered", sessionId, seq: fresh[fresh.length - 1].seq });
+        const feedback = fresh.filter((cm) => cm.author === "user");
+        return feedback.length > 0 ? await buildFeedbackBatches(store, feedback) : [];
+    }
+    // Per-comment delivery state for the viewer: `delivered` once the session's
+    // agentSeq has passed the comment. Computed, never stored.
+    async function withDelivered(comments) {
+        const cursors = new Map();
+        for (const c of comments) {
+            if (!cursors.has(c.sessionId)) {
+                cursors.set(c.sessionId, (await store.getSession(c.sessionId))?.agentSeq ?? 0);
+            }
+        }
+        return comments.map((c) => ({ ...c, delivered: c.seq <= (cursors.get(c.sessionId) ?? 0) }));
+    }
+    // The workspace's light/dark choice. Older workspaces stored a theme id under
+    // `theme`; that registry is gone, so they start from the default mode.
+    async function workspaceMode() {
+        const stored = await store.getSetting("mode");
+        return isMode(stored) ? stored : DEFAULT_MODE;
+    }
+    // A project's imported design system (settings key `design:<project>`), or
+    // null when `mockpit init` has never run for it.
+    async function designFor(project) {
+        const raw = await store.getSetting(`design:${project}`);
+        if (!raw)
+            return null;
+        try {
+            const design = JSON.parse(raw);
+            return {
+                ...design,
+                tailwindCss: typeof design.tailwindCss === "string" ? design.tailwindCss : "",
+                strippedImports: Array.isArray(design.strippedImports) ? design.strippedImports : [],
+                iconSets: Array.isArray(design.iconSets) ? design.iconSets : [],
+                projectKits: Array.isArray(design.projectKits) ? design.projectKits : [],
+                designFiles: design.designFiles ?? null,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    // Parsed installed icon sets by asset id. Asset bytes are immutable (the id
+    // is their hash), so an entry never goes stale; the bound only caps memory.
+    const iconSetCache = new Map();
+    const ICON_SET_CACHE_MAX = 16;
+    async function installedIconSet(assetId) {
+        if (iconSetCache.has(assetId))
+            return iconSetCache.get(assetId);
+        const asset = await store.getAsset(assetId);
+        // A missing asset is not cached: it may be uploaded a moment later.
+        if (!asset)
+            return null;
+        const set = parseIconSet(new TextDecoder().decode(asset.data));
+        if (iconSetCache.size >= ICON_SET_CACHE_MAX) {
+            iconSetCache.delete(iconSetCache.keys().next().value);
+        }
+        iconSetCache.set(assetId, set);
+        return set;
+    }
+    // The project's installed sets first, so installing a set under a bundled
+    // prefix (a newer lucide) overrides the bundled copy.
+    async function iconSetsFor(design) {
+        const out = [];
+        for (const ref of design?.iconSets ?? []) {
+            const set = await installedIconSet(ref.assetId);
+            if (set)
+                out.push({ prefix: ref.prefix, set, source: "installed" });
+        }
+        for (const [prefix, set] of await bundledIconSets()) {
+            if (!out.some((s) => s.prefix === prefix))
+                out.push({ prefix, set, source: "bundled" });
+        }
+        return out;
+    }
+    async function iconResolverFor(design) {
+        const sets = await iconSetsFor(design);
+        return { resolve: resolverFor(sets.map((s) => s.set)), prefixes: sets.map((s) => s.prefix) };
+    }
+    // Unknown icon names in a write's html surfaces, said at write time so the
+    // agent learns without rendering.
+    async function iconWarnings(project, surfaces) {
+        const html = surfaces.flatMap((s) => s.kind === "html" && mayHaveIcons(s.html) ? [s.html] : []);
+        if (html.length === 0)
+            return [];
+        const { resolve, prefixes } = await iconResolverFor(await designFor(project));
+        const unknown = new Set();
+        for (const h of html)
+            for (const u of expandIcons(h, resolve).unknown)
+                unknown.add(u);
+        return [...unknown].map((u) => `unknown icon ${u} (sets: ${prefixes.join(", ")})`);
+    }
+    // An agent asking for instructions must never get an error page, so a store
+    // failure degrades to the brief without project settings.
+    async function briefFor(project) {
+        try {
+            const name = project ?? (await store.listProjects())[0]?.name ?? DEFAULT_PROJECT;
+            return renderBriefGuide(await designFor(name));
+        }
+        catch (err) {
+            console.warn("[mockpit] project design unavailable for the brief", err);
+            return renderBriefGuide(null);
+        }
+    }
+    // Push + webhooks. Detached on purpose: a dead push endpoint must never fail
+    // (or slow) the write that triggered it.
+    function fireNotify(payload) {
+        void notify(store, payload).catch((err) => console.warn("[mockpit] notify failed", err));
+    }
+    const mockUrl = (base, mock, post) => {
+        const url = `${base}/project/${encodeURIComponent(mock.project)}/${encodeURIComponent(mock.slug)}`;
+        if (!post)
+            return url;
+        const q = new URLSearchParams();
+        if (post.state !== null)
+            q.set("state", post.state);
+        q.set("variant", post.variant);
+        return `${url}?${q}`;
+    };
+    // Project resolution for a session: explicit wins, then the cwd's basename,
+    // then the single-workspace fallback.
+    const resolveProject = (project, cwd) => project?.trim() || projectFromCwd(cwd) || DEFAULT_PROJECT;
+    // A mock reference is its id, or its slug within a project. Without a
+    // project, a slug that names exactly one mock in the workspace still resolves —
+    // an agent rarely has more than one repo with the same mock name.
+    async function resolveMock(ref, project, sessionId) {
+        const name = typeof ref === "string" ? ref.trim() : "";
+        if (!name)
+            return fail(400, 'provide a "mock"');
+        const byId = await store.getMock(name);
+        if (byId)
+            return byId;
+        const slug = slugify(name);
+        let proj = typeof project === "string" && project.trim() ? project.trim() : undefined;
+        if (!proj && typeof sessionId === "string") {
+            const session = await store.getSession(sessionId);
+            proj = session?.project ?? undefined;
+        }
+        if (proj) {
+            const mock = await store.findMock(proj, slug);
+            return mock ?? fail(404, `${proj} has no mock "${slug}"`);
+        }
+        const matches = (await store.listMocks()).filter((m) => m.slug === slug);
+        if (matches.length === 1)
+            return matches[0];
+        if (matches.length === 0)
+            return fail(404, `no mock "${slug}"`);
+        return fail(400, `"${slug}" exists in several projects; pass project`, {
+            projects: matches.map((m) => m.project),
+        });
+    }
+    const isResult = (v) => !!v && typeof v === "object" && "status" in v && "body" in v;
+    // A state argument: undefined = not given, null = the single unnamed state.
+    const stateArg = (v) => v === undefined ? undefined : v === null || v === "" ? null : str(v, MAX_LABEL);
+    const variantLabel = (p) => (p.state === null ? p.variant : `${p.state}/${p.variant}`);
+    // Which variant a call means. Explicit wins; one candidate is unambiguous;
+    // several is an error that names them rather than guessing.
+    function chooseVariant(mock, posts, stateIn, variant) {
+        let candidates = posts;
+        if (stateIn !== undefined) {
+            if (stateIn !== null && !mock.states.includes(stateIn)) {
+                return fail(404, `${mock.slug} has no state "${stateIn}"`, { states: mock.states });
+            }
+            candidates = candidates.filter((p) => p.state === stateIn);
+        }
+        if (variant)
+            candidates = candidates.filter((p) => p.variant === variant);
+        if (candidates.length === 1)
+            return candidates[0];
+        if (candidates.length === 0) {
+            return fail(404, `${mock.slug} has no variant ${variant ? `"${variant}"` : ""}`.trim(), {
+                variants: posts.map(variantLabel),
+            });
+        }
+        const live = candidates.filter((p) => p.status !== "archived");
+        if (live.length === 1 && !variant)
+            return live[0];
+        return fail(400, `${mock.slug} has several variants; pass ${variant ? "state" : "variant"}`, {
+            variants: candidates.map(variantLabel),
+        });
+    }
+    // The kit ids a surface of this project may name beyond the bundled ones.
+    const kitScope = async (project) => ({
+        projectKits: ((await designFor(project))?.projectKits ?? []).map((k) => k.id),
+    });
+    async function parseSurfaceInput(body, ctx, scope, base) {
+        if (body.html !== undefined) {
+            if (typeof body.html !== "string" || !body.html.trim()) {
+                return fail(400, 'body must include non-empty "html" string');
+            }
+            const raw = [htmlSurface(body.html, body.kits)];
+            if (!ctx.strict)
+                return coerceSurfaces(raw, scope);
+            const parsed = await validateSurfaces(raw, scope);
+            return parsed.ok ? parsed.surfaces : fail(400, parsed.error, surfaceIssues(parsed));
+        }
+        if (!Array.isArray(body.surfaces))
+            return fail(400, '"surfaces" must be an array');
+        return surfaceList(body.surfaces, ctx, scope, base);
+    }
+    // The full ordered list replaces the variant's surfaces, so one shape covers
+    // add, edit, remove and reorder: an entry that is only `{id}` keeps that
+    // surface, an id with content replaces it in place, an entry without an id is
+    // new, and an id left out is removed.
+    async function surfaceList(raw, ctx, scope, base) {
+        const out = [];
+        const used = new Set();
+        const issues = [];
+        for (const [i, entry] of raw.entries()) {
+            const record = entry && typeof entry === "object" && !Array.isArray(entry)
+                ? entry
+                : null;
+            const id = typeof record?.id === "string" ? record.id : undefined;
+            if (id !== undefined) {
+                if (used.has(id))
+                    return fail(400, `surface "${id}" appears twice in "surfaces"`);
+                used.add(id);
+                const current = base();
+                if (isResult(current))
+                    return current;
+                const kept = current.find((s) => s.id === id);
+                if (!kept) {
+                    return fail(404, `surface "${id}" not found`, { surfaces: current.map(surfaceRef) });
+                }
+                if (record?.kind === undefined) {
+                    out.push(kept);
+                    continue;
+                }
+            }
+            const { id: _id, ...content } = record ?? {};
+            const one = record ? [content] : [entry];
+            if (!ctx.strict) {
+                const [surface] = await coerceSurfaces(one, scope);
+                if (surface)
+                    out.push(id ? { ...surface, id } : surface);
+                continue;
+            }
+            const parsed = await validateSurfaces(one, scope);
+            if (!parsed.ok) {
+                for (const issue of parsed.issues) {
+                    issues.push({
+                        ...issue,
+                        requestPath: issue.requestPath.replace(/^surfaces\[0\]/, `surfaces[${i}]`),
+                    });
+                }
+                continue;
+            }
+            out.push(id ? { ...parsed.surfaces[0], id } : parsed.surfaces[0]);
+        }
+        if (issues.length) {
+            return fail(400, issues.map((x) => `${x.requestPath}: ${x.message}`).join("; "), {
+                code: "surface_validation_failed",
+                issues,
+            });
+        }
+        return out;
+    }
+    const surfaceIssues = (failure) => ({
+        code: failure.code,
+        issues: failure.issues,
+    });
+    function checkSurfaces(surfaces) {
+        if (surfaces.length === 0)
+            return fail(400, "a variant needs at least one surface");
+        if (surfacesByteLength(surfaces) > MAX_SURFACE_BYTES) {
+            return fail(413, `surface exceeds ${MAX_SURFACE_BYTES} bytes`);
+        }
+        return null;
+    }
+    // A page's slot list, with each missing version pinned to the referenced
+    // component's current one (snapshot semantics).
+    async function pageSlots(project, surfaces) {
+        const html = surfaces.find((s) => s.kind === "html");
+        if (!html || html.kind !== "html")
+            return [];
+        const slots = [];
+        for (const tag of parseSlotTags(html.html)) {
+            let version = tag.version;
+            if (version == null)
+                version = (await slotTarget(project, tag.slug, tag.variant))?.version ?? null;
+            if (version != null)
+                slots.push({ slug: tag.slug, variant: tag.variant, version });
+        }
+        return slots;
+    }
+    // A slot names a component mock by slug; it renders that mock's first state.
+    async function slotTarget(project, slug, variant) {
+        const mock = await store.findMock(project, slug);
+        if (!mock)
+            return null;
+        return store.findPost(mock.id, mock.states[0] ?? null, variant);
+    }
+    // Inline each `<mockpit-slot>` with the referenced variant version's first
+    // html surface body. The stored `slots` list (resolved at publish) wins over
+    // a bare tag, so a page keeps rendering the versions it was composed from.
+    async function expandPageHtml(project, post, html) {
+        const pinned = new Map(post.slots.map((s) => [`${s.slug}::${s.variant}`, s.version]));
+        const bodies = new Map();
+        for (const tag of parseSlotTags(html)) {
+            const key = `${tag.slug}::${tag.variant}`;
+            const version = tag.version ?? pinned.get(key) ?? null;
+            const cacheKey = `${key}::${version}`;
+            if (bodies.has(cacheKey))
+                continue;
+            const target = await slotTarget(project, tag.slug, tag.variant);
+            if (!target) {
+                bodies.set(cacheKey, null);
+                continue;
+            }
+            const surfaces = version == null || version === target.version
+                ? target.surfaces
+                : (target.history.find((h) => h.version === version)?.surfaces ?? null);
+            const body = surfaces?.find((s) => s.kind === "html");
+            bodies.set(cacheKey, body && body.kind === "html" ? body.html : null);
+        }
+        return expandSlots(html, ({ slug, variant, version }) => {
+            const key = `${slug}::${variant}`;
+            const pinnedVersion = version ?? pinned.get(key) ?? null;
+            return bodies.get(`${key}::${pinnedVersion}`) ?? null;
+        });
+    }
+    // Knobs with a handful of discrete choices are usually decisions dressed as
+    // controls: the user can't compare options they only see one at a time.
+    function knobNudges(knobs) {
+        const out = [];
+        for (const [path, config] of Object.entries(knobs)) {
+            const n = discreteChoices(config);
+            if (n !== null && n <= 3) {
+                out.push(`knob "${path}" has ${n} discrete options: if each option needs its own render, ask instead (ask with options bound to variants); keep a knob when one render plus a control shows it`);
+            }
+        }
+        return out;
+    }
+    // Ask discipline: two live variants of a state with no ask binding them all
+    // leave the user nothing to answer in one Send, and the agent tends to ask in
+    // chat instead. The nudge carries a ready ask: mock-wide when every state has
+    // the same variant names, else for this state.
+    function unboundVariants(mock, posts, state) {
+        const live = (s) => posts.filter((p) => p.state === s && p.status !== "archived").map((p) => p.variant);
+        const names = live(state);
+        if (names.length < 2)
+            return null;
+        const bound = mock.asks.some((a) => {
+            if (a.scope === "part" || (a.scope === "state" && a.state !== state))
+                return false;
+            const variants = new Set(a.options.map((o) => o.variant));
+            return names.every((n) => variants.has(n));
+        });
+        if (bound)
+            return null;
+        const key = (list) => [...list].sort().join("\n");
+        const states = mock.states.length ? mock.states : [null];
+        const wide = states.every((s) => key(live(s)) === key(names));
+        const options = names.map((v) => ({ label: v, variant: v }));
+        const ask = wide
+            ? { id: BUILTIN_ASK_ID, text: "Which one?", scope: "mock", options }
+            : {
+                id: `${BUILTIN_ASK_ID}-${slugify(state ?? "")}`,
+                text: "Which one?",
+                scope: "state",
+                state,
+                options,
+            };
+        const where = state === null ? mock.slug : `${mock.slug} state "${state}"`;
+        return {
+            nudge: `${where} has ${names.length} variants and no ask binds them: call ask with suggestedAsk (or your own question with options bound to the variants) so the user can choose in one Send; never ask in chat`,
+            ask,
+        };
+    }
+    // The answer to every write: what was published, the parts found per state,
+    // what moved since the previous version, and any feedback waiting.
+    async function writeResult(mock, post, ctx, extra = {}) {
+        const posts = await store.listPosts({ mockId: mock.id });
+        const detail = mockDetailView(mock, posts);
+        const unbound = unboundVariants(mock, posts, post.state);
+        const nudges = [...(extra.nudges ?? []), ...(unbound ? [unbound.nudge] : [])];
+        let partChanges;
+        if (extra.previous) {
+            partChanges = diffParts(partsInSurfaces(extra.previous), partsInSurfaces(post.surfaces));
+        }
+        const warnings = await iconWarnings(mock.project, post.surfaces);
+        const feedback = await collectFeedback(post.sessionId);
+        return ok({
+            mock: {
+                id: mock.id,
+                project: mock.project,
+                slug: mock.slug,
+                title: mock.title,
+                kind: mock.kind,
+                states: mock.states,
+            },
+            post: {
+                id: post.id,
+                state: post.state,
+                variant: post.variant,
+                version: post.version,
+                status: post.status,
+                surfaces: post.surfaces.map(surfaceRef),
+            },
+            sessionId: post.sessionId,
+            url: mockUrl(ctx.base, mock, post),
+            parts: detail.parts,
+            ...(extra.applied ? { applied: extra.applied } : {}),
+            ...(partChanges && (partChanges.vanished.length || partChanges.renamed.length)
+                ? { partChanges }
+                : {}),
+            ...(nudges.length ? { nudges } : {}),
+            ...(unbound ? { suggestedAsk: unbound.ask } : {}),
+            ...(warnings.length ? { warnings } : {}),
+            feedback,
+        }, extra.status ?? 200);
+    }
+    function announcePost(mock, post, created, by = "agent") {
+        bus.broadcast({
+            type: created ? "post-created" : "post-updated",
+            id: post.id,
+            mockId: mock.id,
+            sessionId: post.sessionId,
+            version: post.version,
+            by,
+        });
+        warmPost(post, mock);
+    }
+    // The one write: publish one variant of one state of a mock. An existing
+    // (mock, state, variant) becomes a new version; anything else is created.
+    // Exactly one body: `html`, the full ordered `surfaces` list, or `parts`
+    // spliced into the variant's latest (or `from`) version.
+    async function publishFlow(body, ctx) {
+        if (!body || typeof body !== "object")
+            return fail(400, "invalid JSON body");
+        const slugIn = str(body.mock, MAX_TITLE);
+        if (!slugIn)
+            return fail(400, 'provide "mock": the mock slug, e.g. "writer"');
+        const given = ["html", "surfaces", "parts"].filter((k) => body[k] !== undefined);
+        if (given.length === 0)
+            return fail(400, 'provide "html", "surfaces" or "parts"');
+        if (given.length > 1) {
+            return fail(400, `pass one of "html", "surfaces" or "parts", not ${given.join(" and ")}`);
+        }
+        const partEdits = partEditsArg(body);
+        if (isResult(partEdits))
+            return partEdits;
+        const knobs = checkKnobs(body.knobs);
+        if (!knobs.ok)
+            return fail(400, knobs.error);
+        const variantKnobs = checkKnobs(body.variantKnobs);
+        if (!variantKnobs.ok)
+            return fail(400, variantKnobs.error);
+        const stateIn = stateArg(body.state);
+        const variantIn = str(body.variant, MAX_LABEL);
+        const kind = body.kind === "page" || body.kind === "component" ? body.kind : undefined;
+        const title = str(body.title, MAX_TITLE);
+        const fromN = Number(body.from);
+        const from = Number.isInteger(fromN) && fromN > 0 ? fromN : undefined;
+        const prompt = str(body.prompt, MAX_COMMENT_TEXT);
+        const author = str(body.author, MAX_TITLE);
+        // An existing mock is addressable by id before a session exists.
+        let mock = null;
+        if (typeof body.mock === "string")
+            mock = await store.getMock(body.mock);
+        let session = null;
+        if (typeof body.session === "string" && body.session) {
+            session = await store.getSession(body.session);
+            if (!session)
+                return fail(404, `session "${body.session}" not found`);
+        }
+        const project = mock?.project ??
+            (str(body.project, MAX_TITLE) ||
+                session?.project ||
+                projectFromCwd(session?.cwd) ||
+                resolveProject(undefined, str(body.cwd, 4096)));
+        const slug = mock?.slug ?? slugify(slugIn);
+        mock ??= await store.findMock(project, slug);
+        const posts = mock ? await store.listPosts({ mockId: mock.id }) : [];
+        let state;
+        if (stateIn === undefined || stateIn === null) {
+            if (mock && mock.states.length > 0) {
+                return fail(400, `${slug} has states; pass state`, { states: mock.states });
+            }
+            state = null;
+        }
+        else {
+            if (mock && mock.states.length === 0 && posts.length > 0) {
+                return fail(409, `${slug} is a single-state mock; its variants have no state name. Publish a multi-state design as a new mock and name every state`);
+            }
+            state = stateIn;
+        }
+        const inState = posts.filter((p) => p.state === state);
+        let variant = variantIn;
+        if (!variant) {
+            const live = inState.filter((p) => p.status !== "archived");
+            if (inState.length === 0)
+                variant = DEFAULT_VARIANT;
+            else if (inState.length === 1)
+                variant = inState[0].variant;
+            else if (live.length === 1)
+                variant = live[0].variant;
+            else {
+                return fail(400, `${slug} has several variants; pass variant`, {
+                    variants: inState.map(variantLabel),
+                });
+            }
+        }
+        const target = inState.find((p) => p.variant === variant) ?? null;
+        const missing = () => fail(404, `${slug} has no variant "${variant}"${state === null ? "" : ` in "${state}"`}`, {
+            variants: posts.map(variantLabel),
+        });
+        // What `parts` and kept surface ids refer to: the variant's current
+        // version, or the one `from` names.
+        const base = () => {
+            if (!target)
+                return missing();
+            if (from === undefined || from === target.version)
+                return target.surfaces;
+            return (target.history.find((h) => h.version === from)?.surfaces ??
+                fail(404, `${slug} has no version ${from}`));
+        };
+        let surfaces;
+        let applied;
+        if (partEdits) {
+            const current = base();
+            if (isResult(current))
+                return current;
+            const result = spliceParts(current, partEdits);
+            if (!result.ok)
+                return fail(400, result.error);
+            surfaces = result.surfaces;
+            applied = result.applied;
+        }
+        else {
+            const parsed = await parseSurfaceInput(body, ctx, await kitScope(project), base);
+            if (isResult(parsed))
+                return parsed;
+            surfaces = parsed;
+        }
+        const bad = checkSurfaces(surfaces);
+        if (bad)
+            return bad;
+        const nudges = knobNudges({ ...knobs.value, ...variantKnobs.value });
+        if (!target) {
+            // A new variant: carried by the session the agent is writing from.
+            if (!session) {
+                session = await store.createSession({
+                    agent: str(body.agent, MAX_TITLE) ?? "agent",
+                    title: str(body.sessionTitle, MAX_TITLE),
+                    cwd: str(body.cwd, 4096),
+                    project,
+                });
+                bus.broadcast({ type: "session-created", id: session.id });
+            }
+            if (!mock) {
+                mock = await store.createMock({
+                    project,
+                    slug,
+                    title: title ?? titleFromSlug(slug),
+                    kind: kind ?? "component",
+                    states: state === null ? [] : [state],
+                    knobs: knobs.value,
+                    sessionId: session.id,
+                });
+                bus.broadcast({ type: "mock-created", id: mock.id, project });
+            }
+            const slots = mock.kind === "page" || kind === "page" ? await pageSlots(project, surfaces) : [];
+            const created = await store.createPost({
+                sessionId: session.id,
+                mock: mock.id,
+                state,
+                variant,
+                title: title ?? mock.title,
+                surfaces,
+                ...(Object.keys(variantKnobs.value).length ? { knobs: variantKnobs.value } : {}),
+                slots,
+                from,
+                prompt,
+                author,
+            });
+            if (!created)
+                return fail(404, "session not found");
+            mock = await updateMockAfterWrite(mock, { state, kind, title, knobs: knobs.value, session });
+            announcePost(mock, created, true);
+            if (prompt && ctx.request)
+                notifyPublish(mock, created, prompt, ctx);
+            return writeResult(mock, created, ctx, { nudges, status: 201 });
+        }
+        if (!mock)
+            return missing();
+        // A new version is written by whoever writes it; without an explicit
+        // session the variant's own session carries it.
+        session ??= await store.getSession(target.sessionId);
+        const slots = mock.kind === "page" ? await pageSlots(project, surfaces) : undefined;
+        const updated = await store.updatePost(target.id, {
+            surfaces,
+            title,
+            ...(body.variantKnobs !== undefined ? { knobs: variantKnobs.value } : {}),
+            slots,
+            from,
+            prompt,
+            author,
+        });
+        if (!updated)
+            return fail(404, "variant not found");
+        mock = await updateMockAfterWrite(mock, { state, kind, knobs: knobs.value, session });
+        announcePost(mock, updated, false);
+        if (prompt && ctx.request)
+            notifyPublish(mock, updated, prompt, ctx);
+        return writeResult(mock, updated, ctx, { previous: target.surfaces, applied, nudges });
+    }
+    // `parts`: new outer html per part ("name" or "name#key"), spliced into the
+    // variant's html so a tweak costs the tweak rather than the whole document.
+    function partEditsArg(body) {
+        if (body?.parts === undefined)
+            return undefined;
+        const parts = body.parts;
+        if (!parts || typeof parts !== "object" || Array.isArray(parts)) {
+            return fail(400, '"parts" must be an object: { "<part name>": "<html for that part>" }');
+        }
+        const entries = Object.entries(parts);
+        if (entries.length === 0)
+            return fail(400, '"parts" is empty; name at least one part');
+        if (entries.some(([, html]) => typeof html !== "string")) {
+            return fail(400, 'each "parts" value must be the html string for that part');
+        }
+        return parts;
+    }
+    // A write may add a state, retitle the mock, declare knobs, and makes its
+    // session the one a reply is delivered to.
+    async function updateMockAfterWrite(mock, w) {
+        const states = w.state !== null && !mock.states.includes(w.state) ? [...mock.states, w.state] : undefined;
+        const knobs = Object.keys(w.knobs).length ? { ...mock.knobs, ...w.knobs } : undefined;
+        const updated = await store.updateMock(mock.id, {
+            ...(states ? { states } : {}),
+            ...(w.kind ? { kind: w.kind } : {}),
+            ...(w.title ? { title: w.title } : {}),
+            ...(knobs ? { knobs } : {}),
+            ...(w.session ? { sessionId: w.session.id } : {}),
+        });
+        if (!updated)
+            return mock;
+        bus.broadcast({ type: "mock-updated", id: updated.id, project: updated.project });
+        return updated;
+    }
+    function notifyPublish(mock, post, text, ctx) {
+        fireNotify({
+            event: "publish",
+            project: mock.project,
+            slug: mock.slug,
+            variant: post.variant,
+            version: post.version,
+            text,
+            url: mockUrl(ctx.base, mock, post),
+        });
+    }
+    async function listMocksFlow(query) {
+        const project = str(query.project, MAX_TITLE);
+        const mocks = await store.listMocks(project);
+        const rows = [];
+        const pending = [];
+        for (const m of mocks) {
+            const posts = await store.listPosts({ mockId: m.id });
+            rows.push(mockSummaryView(m, posts));
+            pending.push(pendingOf(m, posts));
+        }
+        const open = rows.reduce((n, r) => n + r.open, 0);
+        return ok({
+            ...(project ? { project } : {}),
+            mocks: rows,
+            open,
+            openMocks: rows.filter((r) => r.open > 0).length,
+            pending,
+        });
+    }
+    // The tuned values of the mock's latest reply: what the user last sent.
+    async function lastTuned(mockId) {
+        const replies = (await store.listComments({ mockId })).filter((c) => c.kind === "reply");
+        return replies[replies.length - 1]?.payload?.tuned ?? {};
+    }
+    async function getMockFlow(ref, query) {
+        const mock = await resolveMock(ref, query.project, query.session);
+        if (isResult(mock))
+            return mock;
+        const posts = await store.listPosts({ mockId: mock.id });
+        return ok({
+            ...mockDetailView(mock, posts, {
+                body: query.body,
+                history: query.history,
+                tuned: await lastTuned(mock.id),
+            }),
+            pending: pendingOf(mock, posts),
+        });
+    }
+    async function exportFlow(ref, query, ctx) {
+        const mock = await resolveMock(ref, query.project);
+        if (isResult(mock))
+            return mock;
+        const posts = await store.listPosts({ mockId: mock.id });
+        const wantedState = stateArg(query.state);
+        const wantedVariant = str(query.variant, MAX_LABEL);
+        const states = (mock.states.length ? mock.states : [null]).filter((s) => wantedState === undefined || s === wantedState);
+        if (states.length === 0)
+            return fail(404, `${mock.slug} has no state "${wantedState}"`);
+        const entries = [];
+        for (const state of states) {
+            const inState = posts.filter((p) => p.state === state);
+            const post = (wantedVariant && inState.find((p) => p.variant === wantedVariant)) ||
+                inState.find((p) => p.status === "accepted") ||
+                inState.find((p) => p.status === "open") ||
+                inState[0];
+            if (!post)
+                continue;
+            if (wantedVariant && post.variant !== wantedVariant)
+                continue;
+            const html = post.surfaces.find((s) => s.kind === "html");
+            entries.push({
+                state,
+                variant: post.variant,
+                postId: post.id,
+                version: post.version,
+                status: post.status,
+                html: html && html.kind === "html" ? html.html : "",
+                markdown: postToMarkdown(post, {
+                    postUrl: `${ctx.base}/s/${post.id}`,
+                    assetBase: ctx.base,
+                }),
+                history: [
+                    ...[...post.history]
+                        .sort((a, b) => a.version - b.version)
+                        .map((h) => ({
+                        version: h.version,
+                        at: h.at,
+                        from: h.from ?? null,
+                        prompt: h.prompt ?? "",
+                    })),
+                    {
+                        version: post.version,
+                        at: post.updatedAt,
+                        from: post.from ?? null,
+                        prompt: post.prompt ?? "",
+                    },
+                ],
+                screenshotUrl: screenshots ? `${ctx.base}/s/${post.id}.png?v=${post.version}` : null,
+            });
+        }
+        if (entries.length === 0) {
+            return fail(404, `${mock.slug} has no variant "${wantedVariant}"`, {
+                variants: posts.map(variantLabel),
+            });
+        }
+        const replies = (await store.listComments({ mockId: mock.id })).filter((c) => c.kind === "reply");
+        return ok({
+            project: mock.project,
+            mock: mock.slug,
+            title: mock.title,
+            kind: mock.kind,
+            states: entries,
+            knobs: mock.knobs,
+            reply: replies[replies.length - 1]?.payload ?? null,
+        });
+    }
+    // --- asks ---
+    function sanitizeAsk(raw, mock, posts, taken) {
+        if (!raw || typeof raw !== "object")
+            return "each ask must be an object";
+        const text = str(raw.text, MAX_COMMENT_TEXT);
+        if (!text)
+            return 'each ask needs "text"';
+        const scope = raw.scope === "state" || raw.scope === "part" ? raw.scope : "mock";
+        const state = str(raw.state, MAX_LABEL);
+        if (scope === "state") {
+            if (!state)
+                return `ask "${text}" has scope "state" but no state`;
+            if (!mock.states.includes(state))
+                return `${mock.slug} has no state "${state}"`;
+        }
+        else if (state && !mock.states.includes(state)) {
+            return `${mock.slug} has no state "${state}"`;
+        }
+        const part = str(raw.part, 200);
+        if (scope === "part" && !part)
+            return `ask "${text}" has scope "part" but no part`;
+        if (!Array.isArray(raw.options) || raw.options.length === 0) {
+            return `ask "${text}" needs options`;
+        }
+        if (raw.options.length > MAX_OPTIONS)
+            return `ask "${text}" has more than ${MAX_OPTIONS} options`;
+        const variants = new Set(posts.map((p) => p.variant));
+        const options = [];
+        // Seeded with the viewer's write-in, so a label "Other" slugs to "other-2".
+        const optionIds = new Set([OTHER_ID]);
+        for (const o of raw.options) {
+            const opt = typeof o === "string" ? { label: o } : o;
+            const label = str(opt?.label, 200);
+            if (!label)
+                return `every option of "${text}" needs a label`;
+            if (str(opt.id, 64) && slugify(str(opt.id, 64)) === OTHER_ID) {
+                return `option id "${OTHER_ID}" is reserved: the viewer adds its own "Other…" write-in to every ask`;
+            }
+            let id = slugify(str(opt.id, 64) ?? label);
+            for (let n = 2; optionIds.has(id); n++)
+                id = `${slugify(str(opt.id, 64) ?? label)}-${n}`;
+            optionIds.add(id);
+            const variant = str(opt.variant, MAX_LABEL);
+            if (variant && !variants.has(variant)) {
+                return `option "${label}" names variant "${variant}", which ${mock.slug} does not have`;
+            }
+            let set;
+            if (opt.set !== undefined) {
+                const checked = checkKnobValues(opt.set, mock, posts, `option "${label}"`);
+                if (!checked.ok)
+                    return checked.error;
+                set = checked.value;
+            }
+            options.push({ id, label, ...(variant ? { variant } : {}), ...(set ? { set } : {}) });
+        }
+        let id = slugify(str(raw.id, 64) ?? text).slice(0, 40);
+        if (!str(raw.id, 64))
+            for (let n = 2; taken.has(id); n++)
+                id = `${slugify(text).slice(0, 36)}-${n}`;
+        return {
+            id,
+            text,
+            scope,
+            ...(state ? { state } : {}),
+            ...(part ? { part } : {}),
+            options,
+            ...(raw.multi === true ? { multi: true } : {}),
+            at: new Date().toISOString(),
+        };
+    }
+    // Ask the user structured questions. An ask whose id matches an existing one
+    // replaces it (and reopens it); anything else is appended.
+    async function askFlow(ref, body, ctx) {
+        if (!body || typeof body !== "object")
+            return fail(400, "invalid JSON body");
+        const resolved = await resolveMock(ref, body.project, body.session);
+        if (isResult(resolved))
+            return resolved;
+        let mock = resolved;
+        const raw = Array.isArray(body.asks) ? body.asks : body.text ? [body] : null;
+        if (!raw || raw.length === 0)
+            return fail(400, 'provide "asks": [{text, options}]');
+        if (raw.length > MAX_ASKS)
+            return fail(400, `at most ${MAX_ASKS} asks per call`);
+        const posts = await store.listPosts({ mockId: mock.id });
+        const asks = [...mock.asks];
+        const taken = new Set(asks.map((a) => a.id));
+        const added = [];
+        for (const entry of raw) {
+            const ask = sanitizeAsk(entry, mock, posts, taken);
+            if (typeof ask === "string")
+                return fail(400, ask);
+            const at = asks.findIndex((a) => a.id === ask.id);
+            if (at >= 0)
+                asks[at] = ask;
+            else
+                asks.push(ask);
+            taken.add(ask.id);
+            added.push(ask);
+        }
+        let sessionId = mock.sessionId;
+        if (typeof body.session === "string" && (await store.getSession(body.session))) {
+            sessionId = body.session;
+        }
+        const updated = await store.updateMock(mock.id, { asks, sessionId });
+        if (!updated)
+            return fail(404, "mock not found");
+        mock = updated;
+        bus.broadcast({ type: "mock-updated", id: mock.id, project: mock.project });
+        // The questions also land in the thread, so the user reads them where they answer.
+        const session = sessionId ? await store.getSession(sessionId) : null;
+        if (session) {
+            const comment = await store.createComment({
+                sessionId: session.id,
+                mockId: mock.id,
+                author: reservedAgent(session.agent),
+                text: added.map((a) => a.text).join("\n"),
+                kind: "ask",
+            });
+            if (comment)
+                announceComment(comment);
+        }
+        fireNotify({
+            event: "ask",
+            project: mock.project,
+            slug: mock.slug,
+            variant: "",
+            version: Math.max(1, ...posts.map((p) => p.version)),
+            text: added.map((a) => a.text).join(" · "),
+            url: mockUrl(ctx.base, mock),
+        });
+        const feedback = session ? await collectFeedback(session.id) : [];
+        return ok({
+            mock: mock.slug,
+            mockId: mock.id,
+            project: mock.project,
+            asks: added,
+            open: openCount(mock, posts),
+            url: mockUrl(ctx.base, mock),
+            feedback,
+        });
+    }
+    // --- drafts and replies (the user's side; viewer origin only) ---
+    function sanitizePartComments(raw, mock) {
+        if (raw === undefined || raw === null)
+            return [];
+        if (!Array.isArray(raw))
+            return '"comments" must be an array';
+        if (raw.length > MAX_DRAFT_COMMENTS)
+            return `at most ${MAX_DRAFT_COMMENTS} comments`;
+        const out = [];
+        for (const c of raw) {
+            const text = str(c?.text, MAX_COMMENT_TEXT);
+            if (!text)
+                return "every comment needs text";
+            const state = stateArg(c.state) ?? null;
+            if (state !== null && !mock.states.includes(state))
+                return `${mock.slug} has no state "${state}"`;
+            const part = str(c.part, 200) ?? null;
+            const a = c.anchor && typeof c.anchor === "object" ? c.anchor : null;
+            const anchor = a ? sanitizePartAnchor(a) : undefined;
+            out.push({ part, state, text, ...(anchor ? { anchor } : {}) });
+        }
+        return out;
+    }
+    function sanitizePartAnchor(a) {
+        const offset = Array.isArray(a.offset) && a.offset.length === 2 && a.offset.every((n) => Number.isFinite(n))
+            ? [Number(a.offset[0]), Number(a.offset[1])]
+            : undefined;
+        const box = Array.isArray(a.box) && a.box.length === 4 && a.box.every((n) => Number.isFinite(n))
+            ? a.box.map(Number)
+            : undefined;
+        const quote = str(a.quote, 200);
+        const selector = str(a.selector, 500);
+        if (!offset && !box && !quote && !selector)
+            return undefined;
+        return {
+            ...(offset ? { offset } : {}),
+            ...(quote ? { quote } : {}),
+            ...(selector ? { selector } : {}),
+            ...(box ? { box } : {}),
+        };
+    }
+    // A stored ask, else the viewer's built-in variant ask under its reserved id.
+    const askById = (mock, posts, id) => mock.asks.find((a) => a.id === id) ?? builtinAsk(mock, posts, id);
+    function sanitizeAnswers(raw, mock, posts) {
+        if (raw === undefined || raw === null)
+            return {};
+        if (typeof raw !== "object" || Array.isArray(raw))
+            return '"answers" must be an object';
+        const out = {};
+        for (const [askId, value] of Object.entries(raw)) {
+            const ask = askById(mock, posts, askId);
+            if (!ask)
+                return `${mock.slug} has no ask "${askId}"`;
+            const ids = Array.isArray(value) ? value : [value];
+            if (ids.length === 0)
+                continue;
+            if (!ask.multi && ids.length > 1)
+                return `ask "${askId}" takes one answer`;
+            for (const id of ids) {
+                if (typeof id !== "string" || !ask.options.some((o) => o.id === id)) {
+                    return `ask "${askId}" has no option "${String(id)}"`;
+                }
+            }
+            out[askId] = ask.multi ? ids : ids[0];
+        }
+        return out;
+    }
+    // askId → text, for the write-ins and the notes: known asks only, text capped
+    // like a comment, blanks dropped.
+    function sanitizeAskTexts(raw, mock, posts, key) {
+        if (raw === undefined || raw === null)
+            return {};
+        if (typeof raw !== "object" || Array.isArray(raw))
+            return `"${key}" must be an object`;
+        const out = {};
+        for (const [askId, value] of Object.entries(raw)) {
+            if (!askById(mock, posts, askId))
+                return `${mock.slug} has no ask "${askId}"`;
+            if (value !== undefined && value !== null && typeof value !== "string") {
+                return `${key} "${askId}" must be text`;
+            }
+            const text = str(value, MAX_COMMENT_TEXT);
+            if (text)
+                out[askId] = text;
+        }
+        return out;
+    }
+    function sanitizeMix(raw, posts) {
+        if (raw === undefined || raw === null)
+            return {};
+        if (typeof raw !== "object" || Array.isArray(raw))
+            return '"mix" must be an object';
+        const variants = new Set(posts.map((p) => p.variant));
+        const out = {};
+        for (const [part, variant] of Object.entries(raw)) {
+            if (!part || part.length > 200)
+                return "mix keys are part names";
+            if (typeof variant !== "string" || !variants.has(variant)) {
+                return `mix "${part}" names a variant that does not exist`;
+            }
+            out[part] = variant;
+        }
+        return out;
+    }
+    // A draft, validated against the mock as it is now: unknown asks, options,
+    // variants, knob paths or out-of-range values are refused, never stored.
+    function sanitizeDraft(raw, mock, posts, base) {
+        const pick = (key) => (raw?.[key] !== undefined ? raw[key] : base?.[key]);
+        const answers = sanitizeAnswers(pick("answers"), mock, posts);
+        if (typeof answers === "string")
+            return answers;
+        const mix = sanitizeMix(pick("mix"), posts);
+        if (typeof mix === "string")
+            return mix;
+        const tuned = checkKnobValues(pick("tuned"), mock, posts, "tuned");
+        if (!tuned.ok)
+            return tuned.error;
+        const comments = sanitizePartComments(pick("comments"), mock);
+        if (typeof comments === "string")
+            return comments;
+        const others = sanitizeAskTexts(pick("others"), mock, posts, "others");
+        if (typeof others === "string")
+            return others;
+        const notes = sanitizeAskTexts(pick("notes"), mock, posts, "notes");
+        if (typeof notes === "string")
+            return notes;
+        for (const askId of Object.keys(others)) {
+            const ask = askById(mock, posts, askId);
+            if (!ask?.multi && answers[askId] !== undefined)
+                return `ask "${askId}" takes one answer`;
+        }
+        const versionN = Number(pick("version"));
+        const version = Number.isInteger(versionN) && versionN > 0
+            ? versionN
+            : Math.max(1, ...posts.map((p) => p.version));
+        return {
+            version,
+            answers,
+            mix,
+            tuned: tuned.value,
+            comments,
+            others,
+            notes,
+            updatedAt: new Date().toISOString(),
+        };
+    }
+    const viewerOnly = () => fail(403, "only the viewer can do this");
+    async function getDraftFlow(ref, ctx) {
+        if (!ctx.viewer)
+            return viewerOnly();
+        const mock = await resolveMock(ref);
+        if (isResult(mock))
+            return mock;
+        return ok({ draft: mock.draft });
+    }
+    async function putDraftFlow(ref, body, ctx) {
+        if (!ctx.viewer)
+            return viewerOnly();
+        if (!body || typeof body !== "object")
+            return fail(400, "invalid JSON body");
+        const mock = await resolveMock(ref);
+        if (isResult(mock))
+            return mock;
+        const posts = await store.listPosts({ mockId: mock.id });
+        const draft = sanitizeDraft(body, mock, posts, null);
+        if (typeof draft === "string")
+            return fail(400, draft);
+        await store.putDraft(mock.id, draft);
+        bus.broadcast({ type: "draft-updated", mockId: mock.id });
+        return ok({ draft });
+    }
+    async function deleteDraftFlow(ref, ctx) {
+        if (!ctx.viewer)
+            return viewerOnly();
+        const mock = await resolveMock(ref);
+        if (isResult(mock))
+            return mock;
+        await store.putDraft(mock.id, null);
+        bus.broadcast({ type: "draft-updated", mockId: mock.id });
+        return ok({ draft: null });
+    }
+    function sanitizeDecision(raw, mock, posts) {
+        if (raw === undefined || raw === null)
+            return undefined;
+        const kind = raw.kind;
+        if (kind !== "accept" && kind !== "revise" && kind !== "drop") {
+            return 'decision.kind must be "accept", "revise" or "drop"';
+        }
+        const chosen = chooseVariant(mock, posts, stateArg(raw.state), str(raw.variant, MAX_LABEL));
+        if (isResult(chosen))
+            return chosen.body.error;
+        return { kind, state: chosen.state, variant: chosen.variant };
+    }
+    // Which variants a reply accepts and archives. A variant-bound answer accepts
+    // the chosen variant(s) in every state the ask covers and archives their
+    // siblings there; a part-scoped pick is a mix, not a verdict. The built-in
+    // variant asks flip the same way, per state.
+    function replyFlips(mock, posts, answers, decision) {
+        const accept = new Set();
+        const archive = new Set();
+        const settle = (inState, chosen) => {
+            if (!inState.some((p) => chosen.has(p.variant)))
+                return;
+            for (const p of inState) {
+                if (chosen.has(p.variant))
+                    accept.add(p.id);
+                else if (p.status !== "archived")
+                    archive.add(p.id);
+            }
+        };
+        const builtins = Object.keys(answers)
+            .filter((id) => !mock.asks.some((a) => a.id === id))
+            .flatMap((id) => builtinAsk(mock, posts, id) ?? []);
+        for (const ask of [...mock.asks, ...builtins]) {
+            const answer = answers[ask.id];
+            if (answer === undefined || ask.scope === "part")
+                continue;
+            const ids = Array.isArray(answer) ? answer : [answer];
+            const chosen = new Set(ask.options.filter((o) => ids.includes(o.id) && o.variant).map((o) => o.variant));
+            if (chosen.size === 0)
+                continue;
+            const states = ask.scope === "state" ? [ask.state ?? null] : mock.states.length ? mock.states : [null];
+            for (const state of states)
+                settle(posts.filter((p) => p.state === state), chosen);
+        }
+        if (decision?.kind === "accept") {
+            settle(posts.filter((p) => p.state === decision.state), new Set([decision.variant]));
+        }
+        else if (decision?.kind === "drop") {
+            const post = posts.find((p) => p.state === decision.state && p.variant === decision.variant);
+            if (post)
+                archive.add(post.id);
+        }
+        for (const id of accept)
+            archive.delete(id);
+        return { accept, archive };
+    }
+    // An ask as a reply leaves it. A pick or a write-in replaces whatever was
+    // answered before; a note alone keeps that answer and adds to it.
+    function sentAsk(a, draft) {
+        const answer = draft.answers[a.id];
+        const other = draft.others?.[a.id];
+        const note = draft.notes?.[a.id];
+        if (answer === undefined && other === undefined && note === undefined)
+            return a;
+        const next = { ...a };
+        if (answer !== undefined || other !== undefined) {
+            delete next.answer;
+            delete next.other;
+            if (answer !== undefined)
+                next.answer = answer;
+            if (other !== undefined)
+                next.other = other;
+        }
+        if (note !== undefined)
+            next.note = note;
+        return next;
+    }
+    // Send: the user's one batched answer becomes one kind:"reply" comment on the
+    // mock's session, delivered through the same cursor as everything else. The
+    // draft is cleared and statuses flip in the same store transaction.
+    async function replyFlow(ref, body, ctx) {
+        if (!ctx.viewer)
+            return viewerOnly();
+        const mock = await resolveMock(ref);
+        if (isResult(mock))
+            return mock;
+        const posts = await store.listPosts({ mockId: mock.id });
+        const draft = sanitizeDraft(body ?? {}, mock, posts, mock.draft);
+        if (typeof draft === "string")
+            return fail(400, draft);
+        const text = str(body?.text, MAX_COMMENT_TEXT);
+        const decision = sanitizeDecision(body?.decision, mock, posts);
+        if (typeof decision === "string")
+            return fail(400, decision);
+        const empty = !text &&
+            !decision &&
+            !Object.keys(draft.answers).length &&
+            !Object.keys(draft.mix).length &&
+            !Object.keys(draft.tuned).length &&
+            !draft.comments.length &&
+            !Object.keys(draft.others ?? {}).length &&
+            !Object.keys(draft.notes ?? {}).length;
+        if (empty)
+            return fail(400, "nothing to send");
+        const latest = [...posts].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))[0];
+        const sessionId = mock.sessionId ?? latest?.sessionId;
+        if (!sessionId)
+            return fail(409, `${mock.slug} has no agent session to reply to`);
+        const payload = {
+            mockId: mock.id,
+            version: draft.version,
+            answers: draft.answers,
+            mix: draft.mix,
+            tuned: draft.tuned,
+            comments: draft.comments,
+            ...(Object.keys(draft.others ?? {}).length ? { others: draft.others } : {}),
+            ...(Object.keys(draft.notes ?? {}).length ? { notes: draft.notes } : {}),
+            ...(text ? { text } : {}),
+            ...(decision ? { decision } : {}),
+        };
+        const asks = mock.asks.map((a) => sentAsk(a, draft));
+        const flips = replyFlips(mock, posts, draft.answers, decision);
+        const comment = await store.commitReply({
+            mockId: mock.id,
+            sessionId,
+            text: text ?? "",
+            payload,
+            asks,
+            accept: [...flips.accept],
+            archive: [...flips.archive],
+        });
+        if (!comment)
+            return fail(409, `${mock.slug} has no agent session to reply to`);
+        announceComment(comment);
+        bus.broadcast({ type: "mock-updated", id: mock.id, project: mock.project });
+        bus.broadcast({ type: "draft-updated", mockId: mock.id });
+        const after = await store.listPosts({ mockId: mock.id });
+        for (const p of after) {
+            if (flips.accept.has(p.id) || flips.archive.has(p.id)) {
+                bus.broadcast({
+                    type: "post-updated",
+                    id: p.id,
+                    mockId: mock.id,
+                    sessionId: p.sessionId,
+                    version: p.version,
+                    by: "user",
+                });
+            }
+        }
+        fireNotify({
+            event: "decision",
+            project: mock.project,
+            slug: mock.slug,
+            variant: decision?.variant ?? "",
+            version: draft.version,
+            text: text || decision?.kind || "reply",
+            url: mockUrl(ctx.base, mock),
+        });
+        const [delivered] = await withDelivered([comment]);
+        return ok({
+            reply: delivered,
+            accepted: after
+                .filter((p) => flips.accept.has(p.id))
+                .map((p) => ({ state: p.state, variant: p.variant })),
+            archived: after
+                .filter((p) => flips.archive.has(p.id))
+                .map((p) => ({ state: p.state, variant: p.variant })),
+        }, 201);
+    }
+    async function restoreFlow(ref, body) {
+        const mock = await resolveMock(ref, body?.project);
+        if (isResult(mock))
+            return mock;
+        const posts = await store.listPosts({ mockId: mock.id });
+        const chosen = chooseVariant(mock, posts, stateArg(body?.state), str(body?.variant, MAX_LABEL));
+        if (isResult(chosen))
+            return chosen;
+        const updated = await store.setPostStatus(chosen.id, "open");
+        if (!updated)
+            return fail(404, "variant not found");
+        bus.broadcast({
+            type: "post-updated",
+            id: updated.id,
+            mockId: mock.id,
+            sessionId: updated.sessionId,
+            version: updated.version,
+            by: "user",
+        });
+        return ok({ state: updated.state, variant: updated.variant, status: updated.status });
+    }
+    // D8 "restore as vN": the user brings an older version back as the newest
+    // one. Distinct from restoreFlow, which un-archives a variant. Viewer-only
+    // because the version is authored by the user; an agent restoring publishes.
+    async function restoreVersionFlow(ref, postId, body, ctx) {
+        if (!ctx.viewer)
+            return viewerOnly();
+        const mock = await resolveMock(ref);
+        if (isResult(mock))
+            return mock;
+        const post = await store.getPost(postId);
+        if (!post || post.mock !== mock.id)
+            return fail(404, `${mock.slug} has no variant "${postId}"`);
+        const version = Number(body?.version);
+        if (!Number.isInteger(version) || version < 1) {
+            return fail(400, '"version" must be a positive integer');
+        }
+        if (version === post.version)
+            return fail(409, `v${version} is already the current version`);
+        const old = post.history.find((h) => h.version === version);
+        if (!old)
+            return fail(404, `v${version} is not available`);
+        const updated = await store.updatePost(post.id, {
+            surfaces: old.surfaces,
+            title: old.title,
+            from: version,
+            prompt: `restored v${version}`,
+            author: "user",
+        });
+        if (!updated)
+            return fail(404, "variant not found");
+        const touched = (await store.updateMock(mock.id, {})) ?? mock;
+        bus.broadcast({ type: "mock-updated", id: touched.id, project: touched.project });
+        announcePost(touched, updated, false, "user");
+        return ok({
+            state: updated.state,
+            variant: updated.variant,
+            version: updated.version,
+            from: version,
+        });
+    }
+    async function removeMockFlow(ref, query) {
+        const mock = await resolveMock(ref, query.project);
+        if (isResult(mock))
+            return mock;
+        await store.removeMock(mock.id);
+        bus.broadcast({ type: "mock-deleted", id: mock.id, project: mock.project });
+        return ok({ ok: true });
+    }
+    // --- comments ---
+    function numberInRange(value, min, max) {
+        const n = Number(value);
+        return Number.isFinite(n) && n >= min && n <= max ? n : null;
+    }
+    function sanitizeCommentAnchor(raw, mock, post) {
+        if (!raw || typeof raw !== "object")
+            return undefined;
+        const input = raw;
+        if (input.kind === "part") {
+            const part = str(input.part, 200);
+            if (!part)
+                return undefined;
+            const state = stateArg(input.state) ?? post?.state ?? null;
+            if (state !== null && !mock.states.includes(state))
+                return undefined;
+            return { kind: "part", part, state, ...sanitizePartAnchor(input) };
+        }
+        if (!post)
+            return undefined;
+        const kind = input.kind === "rect" || input.kind === "lineRange" ? input.kind : "point";
+        let surfaceIndex = Number(input.surfaceIndex);
+        if (!Number.isInteger(surfaceIndex) ||
+            surfaceIndex < 0 ||
+            surfaceIndex >= post.surfaces.length) {
+            const surfaceId = typeof input.surfaceId === "string" ? input.surfaceId : undefined;
+            surfaceIndex = post.surfaces.findIndex((s) => s.id === surfaceId);
+        }
+        if (surfaceIndex < 0 || surfaceIndex >= post.surfaces.length)
+            return undefined;
+        const surface = post.surfaces[surfaceIndex];
+        const base = {
+            surfaceIndex,
+            ...(surface.id && { surfaceId: surface.id }),
+            surfaceKind: surface.kind,
+            // The server pins anchors to the current stored version instead of trusting
+            // the client-supplied value.
+            postVersion: post.version,
+        };
+        if (kind === "lineRange") {
+            const startLine = Number(input.startLine);
+            const endLine = Number(input.endLine);
+            if (!Number.isInteger(startLine) || !Number.isInteger(endLine) || startLine < 1) {
+                return undefined;
+            }
+            return {
+                kind,
+                ...base,
+                startLine,
+                endLine: Math.max(startLine, endLine),
+                ...(typeof input.file === "string" && { file: input.file.slice(0, MAX_TITLE) }),
+            };
+        }
+        const x = numberInRange(input.x, 0, 1);
+        const y = numberInRange(input.y, 0, 1);
+        if (x == null || y == null)
+            return undefined;
+        if (kind === "rect") {
+            const w = numberInRange(input.w, 0, 1);
+            const h = numberInRange(input.h, 0, 1);
+            if (w == null || h == null)
+                return undefined;
+            return { kind, ...base, x, y, w, h };
+        }
+        return { kind: "point", ...base, x, y };
+    }
+    // Viewport presets the stage lays out at; anything else is dropped rather
+    // than echoed back to the agent as a made-up width.
+    const VIEWPORTS = new Set([390, 820, 1280]);
+    const sanitizeViewport = (raw) => {
+        const n = Number(raw);
+        return VIEWPORTS.has(n) ? n : null;
+    };
+    const sanitizePostVersion = (raw, post) => {
+        const n = Number(raw);
+        return Number.isInteger(n) && n >= 1 && n <= post.version ? n : post.version;
+    };
+    // Markers are DATA: every field is re-derived or range-checked here, so
+    // whatever the overlay (or a forged request) sends, the agent only ever
+    // receives a bounded shape it can render as text.
+    const MAX_ANCHORS = 20;
+    const MAX_ANCHOR_TEXT = 200;
+    function sanitizeAnchors(raw, post, viewport) {
+        if (!post || !Array.isArray(raw))
+            return [];
+        const out = [];
+        for (const entry of raw.slice(0, MAX_ANCHORS)) {
+            if (!entry || typeof entry !== "object")
+                continue;
+            const a = entry;
+            const shape = a.shape === "rect" || a.shape === "circle" ? a.shape : "pin";
+            const box = Array.isArray(a.box) ? a.box.map((n) => numberInRange(n, 0, 1)) : [];
+            const need = shape === "pin" ? 2 : 4;
+            if (box.length < need || box.slice(0, need).some((n) => n == null))
+                continue;
+            let surfaceIndex = Number(a.surfaceIndex);
+            if (!Number.isInteger(surfaceIndex) ||
+                surfaceIndex < 0 ||
+                surfaceIndex >= post.surfaces.length) {
+                surfaceIndex = 0;
+            }
+            const ref = typeof a.ref === "string" && /^@\d{1,3}$/.test(a.ref) ? a.ref : `@${out.length + 1}`;
+            out.push({
+                ref,
+                shape,
+                box: box.slice(0, need),
+                surfaceIndex,
+                postVersion: sanitizePostVersion(a.postVersion, post),
+                ...(typeof a.path === "string" && { path: a.path.slice(0, MAX_ANCHOR_TEXT) }),
+                ...(typeof a.text === "string" && { text: a.text.slice(0, MAX_ANCHOR_TEXT) }),
+                ...(viewport === null ? {} : { viewport }),
+            });
+        }
+        return out;
+    }
+    function announceComment(comment) {
+        bus.broadcast({
+            type: "comment-created",
+            id: comment.id,
+            sessionId: comment.sessionId,
+            mockId: comment.mockId,
+            postId: comment.postId,
+            seq: comment.seq,
+        });
+    }
+    // Where a thread comment lands: a mock, optionally one variant of it, and the
+    // session whose stream carries it.
+    async function commentTarget(body) {
+        let post = null;
+        let mock = null;
+        if (typeof body.post === "string" && body.post) {
+            post = await store.getPost(body.post);
+            if (!post)
+                return fail(404, "post not found");
+            mock = await store.getMock(post.mock);
+        }
+        else if (body.mock !== undefined) {
+            const resolved = await resolveMock(body.mock, body.project, body.session);
+            if (isResult(resolved))
+                return resolved;
+            mock = resolved;
+            if (body.variant !== undefined || body.state !== undefined) {
+                const posts = await store.listPosts({ mockId: mock.id });
+                const chosen = chooseVariant(mock, posts, stateArg(body.state), str(body.variant, MAX_LABEL));
+                if (isResult(chosen))
+                    return chosen;
+                post = chosen;
+            }
+        }
+        else {
+            return fail(400, 'provide "mock" (or "post")');
+        }
+        if (!mock)
+            return fail(404, "mock not found");
+        let session = null;
+        if (typeof body.session === "string" && body.session) {
+            session = await store.getSession(body.session);
+            if (!session)
+                return fail(404, `session "${body.session}" not found`);
+        }
+        if (!session) {
+            const sid = mock.sessionId ?? post?.sessionId;
+            session = sid ? await store.getSession(sid) : null;
+        }
+        if (!session)
+            return fail(409, `${mock.slug} has no agent session`);
+        return { mock, post, session };
+    }
+    // The user's comment in a thread: the trusted viewer's verb only. Sandboxed
+    // surfaces have opaque origins, so their bridge is stamped "surface" by the
+    // viewer rather than by contained code. An agent writes with say.
+    async function commentFlow(body, ctx) {
+        if (!ctx.viewer)
+            return fail(403, "only the viewer can do this; an agent posts with say");
+        if (!body || typeof body !== "object")
+            return fail(400, "invalid JSON body");
+        const text = str(body.text, MAX_COMMENT_TEXT);
+        if (!text)
+            return fail(400, 'provide non-empty "text"');
+        const target = await commentTarget(body);
+        if (isResult(target))
+            return target;
+        const { mock, post, session } = target;
+        const viewport = sanitizeViewport(body.viewport);
+        const comment = await store.createComment({
+            sessionId: session.id,
+            mockId: mock.id,
+            postId: post?.id ?? null,
+            author: body.author === "surface" ? "surface" : "user",
+            text,
+            anchor: sanitizeCommentAnchor(body.anchor, mock, post),
+            kind: "comment",
+            anchors: sanitizeAnchors(body.anchors, post, viewport),
+            postVersion: post ? sanitizePostVersion(body.postVersion, post) : null,
+            viewport,
+        });
+        if (!comment)
+            return fail(404, "session not found");
+        announceComment(comment);
+        const [delivered] = await withDelivered([comment]);
+        return ok(delivered, 201);
+    }
+    // The agent's plain-text message in a mock's thread. Stored as text and
+    // rendered as a text node, never as HTML. A write, so feedback rides along.
+    async function sayFlow(ref, body) {
+        if (!body || typeof body !== "object")
+            return fail(400, "invalid JSON body");
+        const text = typeof body.message === "string" ? str(body.message, MAX_COMMENT_TEXT) : undefined;
+        if (!text)
+            return fail(400, 'provide non-empty "message" text');
+        const target = await commentTarget({ ...body, mock: ref, post: undefined });
+        if (isResult(target))
+            return target;
+        const { mock, post, session } = target;
+        const comment = await store.createComment({
+            sessionId: session.id,
+            mockId: mock.id,
+            postId: post?.id ?? null,
+            author: reservedAgent(session.agent),
+            text,
+            kind: "comment",
+            anchors: [],
+            postVersion: post ? post.version : null,
+            viewport: null,
+        });
+        if (!comment)
+            return fail(404, "session not found");
+        announceComment(comment);
+        return ok({ feedback: await collectFeedback(comment.sessionId) }, 201);
+    }
+    // Long-poll: resolves as soon as a matching comment lands, or at timeout.
+    async function waitForComments(q, signal) {
+        // An author=user session wait with no explicit cursor resumes from the
+        // session's agentSeq — "where the agent left off" lives server-side so the
+        // CLI, both MCP transports, and piggyback share one exactly-once stream.
+        let afterSeq = q.afterSeq;
+        if (afterSeq === undefined && q.author === "user" && q.sessionId) {
+            afterSeq = (await store.getSession(q.sessionId))?.agentSeq;
+        }
+        const query = { sessionId: q.sessionId, mockId: q.mockId, postId: q.postId, afterSeq };
+        const matches = (list) => q.author ? list.filter((cm) => cm.author === q.author) : list;
+        const wait = Math.min(Math.max(q.waitSeconds, 0), MAX_WAIT_SECONDS);
+        let all = await store.listComments(query);
+        let comments = matches(all);
+        if (comments.length === 0 && wait > 0) {
+            await new Promise((resolve) => {
+                const timer = setTimeout(done, wait * 1000);
+                const unsubscribe = bus.subscribe((event) => {
+                    if (event.type !== "comment-created")
+                        return;
+                    if (q.sessionId && event.sessionId !== q.sessionId)
+                        return;
+                    if (q.mockId && event.mockId !== q.mockId)
+                        return;
+                    if (q.postId && event.postId !== q.postId)
+                        return;
+                    done();
+                });
+                const onAbort = () => done();
+                let settled = false;
+                signal?.addEventListener("abort", onAbort, { once: true });
+                if (signal?.aborted)
+                    done();
+                function done() {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    unsubscribe();
+                    signal?.removeEventListener("abort", onAbort);
+                    resolve();
+                }
+            });
+            // A caller that gave up can't receive this batch, so delivering it would
+            // advance the cursor past feedback no agent ever saw.
+            if (signal?.aborted)
+                return { comments: [], lastSeq: afterSeq ?? 0 };
+            all = await store.listComments(query);
+            comments = matches(all);
+        }
+        // The cursor advances past every comment in the window — not just the
+        // filtered ones — so the next call doesn't re-read the agent's own comments.
+        const lastSeq = all.length > 0 ? all[all.length - 1].seq : (afterSeq ?? 0);
+        // An author=user query is the agent listening (the viewer never filters by
+        // author) — what it receives here must not be re-delivered as piggyback.
+        if (q.agent && q.author === "user" && q.sessionId && all.length > 0) {
+            await store.markAgentSeen(q.sessionId, lastSeq);
+            bus.broadcast({ type: "comment-delivered", sessionId: q.sessionId, seq: lastSeq });
+        }
+        return { comments, lastSeq };
+    }
+    // The watch long-poll's answer: comments plus the batched feedback built
+    // from them.
+    async function listenFlow(q, signal) {
+        const result = await waitForComments({ ...q, agent: true }, signal);
+        const feedback = await buildFeedbackBatches(store, result.comments);
+        return ok({ ...result, feedback });
+    }
+    // What the user is doing right now, per mock: derived from the SSE registry
+    // and the server-side draft, never stored. It is why an empty `feedback` still
+    // tells the agent something ("2 of 3 answered", or nobody is looking).
+    const pendingOf = (mock, posts) => ({
+        mock: mock.slug,
+        viewerOpen: viewerClients > 0,
+        draft: mock.draft
+            ? {
+                answered: Object.keys(mock.draft.answers).length,
+                of: openCount(mock, posts),
+                comments: mock.draft.comments.length,
+                touchedAt: mock.draft.updatedAt,
+            }
+            : null,
+    });
+    // The feedback verb: never blocks. Takes what the session has not heard yet
+    // (the same cursor as piggyback and watch) plus `pending` for the project.
+    async function feedbackFlow(query) {
+        if (typeof query.session !== "string" || !query.session) {
+            return fail(400, 'provide "session": the session id a write returned');
+        }
+        const session = await store.getSession(query.session);
+        if (!session)
+            return fail(404, `session "${query.session}" not found`);
+        const { comments } = await waitForComments({
+            sessionId: session.id,
+            author: "user",
+            waitSeconds: 0,
+            agent: true,
+        });
+        const project = str(query.project, MAX_TITLE) ?? session.project ?? undefined;
+        return ok({
+            feedback: await buildFeedbackBatches(store, comments),
+            pending: await Promise.all((await store.listMocks(project)).map(async (m) => pendingOf(m, await store.listPosts({ mockId: m.id })))),
+        });
+    }
+    // Store an uploaded blob. An explicit session is validated and a missing one
+    // is auto-created so an upload can precede the first publish. The asset's
+    // data is dropped from the result (it's bytes).
+    async function uploadAsset(input) {
+        if (input.data.byteLength === 0)
+            return { error: "empty upload", status: 400 };
+        if (input.data.byteLength > MAX_ASSET_BYTES) {
+            return { error: `asset exceeds ${MAX_ASSET_BYTES} bytes`, status: 413 };
+        }
+        let sessionId = input.session;
+        if (sessionId && !(await store.getSession(sessionId))) {
+            return { error: `session "${sessionId}" not found`, status: 404 };
+        }
+        if (!sessionId) {
+            const session = await store.createSession({ agent: input.agent ?? "agent" });
+            bus.broadcast({ type: "session-created", id: session.id });
+            sessionId = session.id;
+        }
+        const asset = await store.putAsset({
+            sessionId,
+            kind: input.kind ?? inferAssetKind(input.contentType),
+            contentType: input.contentType || "application/octet-stream",
+            filename: input.filename,
+            data: input.data,
+        });
+        if (!asset)
+            return { error: "session not found", status: 404 };
+        const { data: _data, ...meta } = asset;
+        return { asset: meta };
+    }
+    // --- auth ---
+    const isAuthenticated = (c) => {
+        if (!authToken)
+            return true;
+        if (c.req.header("authorization") === `Bearer ${authToken}`)
+            return true;
+        if (getCookie(c, "mockpit_key") === authToken)
+            return true;
+        return c.req.query("key") === authToken;
+    };
+    const isUnauthenticatedSessionRead = (c) => publicRead === "session" && !isAuthenticated(c);
+    app.use("*", async (c, next) => {
+        const path = new URL(c.req.url).pathname;
+        // Content-hashed static assets (the surface bridge script and the static
+        // stylesheets) are served unauthenticated on purpose: they are our own code,
+        // carry no workspace data, and the sandboxed frames that load them run at an
+        // opaque origin, so their subresource requests carry no SameSite cookie and
+        // could not authenticate even on a tokened workspace.
+        if (path.startsWith(STATIC_ASSET_PREFIX))
+            return next();
+        if (authenticate) {
+            const result = await authenticate(c.req.raw);
+            if (result === true)
+                return next();
+            if (result instanceof Response)
+                return result;
+            if (path.startsWith("/api") || path === "/mcp") {
+                return c.json({ error: "unauthorized" }, 401);
+            }
+            return c.text("unauthorized", 401);
+        }
+        if (!authToken)
+            return next();
+        if (path === "/guide" || path === "/setup" || path === "/agent-howto")
+            return next();
+        if (path.startsWith(STATIC_ASSET_PREFIX))
+            return next();
+        const key = c.req.query("key");
+        if (key === authToken) {
+            setCookie(c, "mockpit_key", authToken, {
+                httpOnly: true,
+                sameSite: "Lax",
+                secure: new URL(c.req.url).protocol === "https:",
+                maxAge: 60 * 60 * 24 * 90,
+                path: "/",
+            });
+            return next();
+        }
+        if (publicRead &&
+            c.req.method === "GET" &&
+            isPublicReadAllowed(path, publicRead, new URL(c.req.url).searchParams)) {
+            return next();
+        }
+        if (isAuthenticated(c))
+            return next();
+        if (path.startsWith("/api") || path === "/mcp") {
+            return c.json({ error: "unauthorized — send Authorization: Bearer <token>" }, 401);
+        }
+        return c.text("unauthorized — open this page as /?key=<your token>", 401);
+    });
+    // Cap every request body. Runs after auth, so an unauthenticated request on a
+    // token-protected workspace is rejected (401) before its body is ever read; on a
+    // no-token workspace it still bounds the body. bodyLimit short-circuits on an
+    // oversize Content-Length and otherwise streams-and-aborts at the cap, so a
+    // chunked body (no Content-Length) can't slip past either. /api/assets is
+    // exempt here because it applies its own, stricter cap (limitAssetBody below).
+    const limitBody = bodyLimit({
+        maxSize: MAX_BODY_BYTES,
+        onError: (c) => c.json({ error: "request body too large" }, 413),
+    });
+    app.use("*", (c, next) => (c.req.path === "/api/assets" ? next() : limitBody(c, next)));
+    // The asset route's own (tighter) body cap. Keeps the asset limit and its
+    // wording, and bounds the upload before it is read — bodyLimit refuses an
+    // oversize Content-Length outright and aborts a chunked stream at the cap.
+    const limitAssetBody = bodyLimit({
+        maxSize: MAX_ASSET_BYTES,
+        onError: (c) => c.json({ error: `asset exceeds ${MAX_ASSET_BYTES} bytes` }, 413),
+    });
+    const withOrigin = (text, c) => text.replaceAll(LOCAL_ORIGIN, new URL(c.req.url).origin);
+    const injectHead = (text, head) => {
+        const headClose = text.lastIndexOf("</head>");
+        return headClose >= 0
+            ? `${text.slice(0, headClose)}${head}${text.slice(headClose)}`
+            : `${head}${text}`;
+    };
+    const withDocumentTitle = (text, title) => {
+        if (!title)
+            return text;
+        const escaped = escapeHtml(title);
+        const titleTag = `<title>${escaped}</title>`;
+        const titleStart = text.indexOf("<title>");
+        if (titleStart < 0)
+            return injectHead(text, titleTag);
+        const titleEnd = text.indexOf("</title>", titleStart + "<title>".length);
+        if (titleEnd < 0)
+            return injectHead(text, titleTag);
+        return `${text.slice(0, titleStart)}${titleTag}${text.slice(titleEnd + "</title>".length)}`;
+    };
+    const withViewerConfig = (text, request, isReadonly, pageTitle) => {
+        const config = [
+            `window.__MOCKPIT_BASE_PATH__=${JSON.stringify(requestBasePath(request))};`,
+            pageTitle ? `window.__MOCKPIT_PAGE_TITLE__=${JSON.stringify(pageTitle)};` : "",
+            isReadonly ? "window.__MOCKPIT_READONLY__=true;" : "",
+            isReadonly && publicRead
+                ? `window.__MOCKPIT_PUBLIC_READ__=${JSON.stringify(publicRead)};`
+                : "",
+            screenshots ? "window.__MOCKPIT_SCREENSHOTS__=true;" : "",
+        ].join("");
+        return injectHead(text, `<script>${config}</script>`);
+    };
+    // --- viewer pages ---
+    // Link previews for a mock page: the first open variant's first surface,
+    // with every pixel-affecting input pinned in the image URL so the Worker can
+    // cache it at the edge.
+    const mockPreviewHead = (mock, post, request, mode, rendererGeneration) => {
+        const origin = new URL(request.url).origin;
+        const publicBasePath = requestBasePath(request);
+        const canonical = `${origin}${publicBasePath}/project/${encodeURIComponent(mock.project)}/${encodeURIComponent(mock.slug)}`;
+        const imageUrl = new URL(`${origin}${publicBasePath}/s/${post.id}.png`);
+        imageUrl.searchParams.set("card", "1");
+        imageUrl.searchParams.set("theme", DEFAULT_THEME_ID);
+        imageUrl.searchParams.set("mode", mode);
+        imageUrl.searchParams.set("v", String(post.version));
+        imageUrl.searchParams.set("g", rendererGeneration);
+        const image = imageUrl.toString();
+        const title = escapeHtml(mock.title);
+        const description = "A https://mockpit.sh mock";
+        return [
+            `<link rel="canonical" href="${escapeHtml(canonical)}">`,
+            `<meta property="og:type" content="website">`,
+            `<meta property="og:title" content="${title}">`,
+            `<meta property="og:description" content="${description}">`,
+            `<meta property="og:url" content="${escapeHtml(canonical)}">`,
+            `<meta property="og:image" content="${escapeHtml(image)}">`,
+            `<meta property="og:image:width" content="1200">`,
+            `<meta property="og:image:height" content="630">`,
+            `<meta name="twitter:card" content="summary_large_image">`,
+            `<meta name="twitter:title" content="${title}">`,
+            `<meta name="twitter:description" content="${description}">`,
+            `<meta name="twitter:image" content="${escapeHtml(image)}">`,
+        ].join("\n");
+    };
+    const configuredViewerHtml = async (c, opts = {}) => {
+        // The viewer HTML is the trusted app origin — it shares that origin with the
+        // authenticated API and the comment→agent channel, so a cross-origin page
+        // that frames it could clickjack actions or the prompt-injection channel.
+        // Refuse cross-origin framing (same-origin embedding still allowed). The
+        // sandboxed surface documents at /s/:id are *meant* to be framed and carry
+        // their own `sandbox` CSP header instead, so they never pass through here.
+        c.header("Content-Security-Policy", "frame-ancestors 'self'");
+        const html = withDocumentTitle(withViewerConfig(withOrigin(viewerHtml, { req: { url: c.req.url } }), c.req.raw, !!publicRead && !isAuthenticated(c), opts.title), opts.title);
+        if (!opts.preview)
+            return html;
+        const { mock, post } = opts.preview;
+        return injectHead(html, mockPreviewHead(mock, post, c.req.raw, await workspaceMode(), version ?? "dev"));
+    };
+    app.get("/", async (c) => c.html(await configuredViewerHtml(c)));
+    // The engine reads the project/mock out of the URL itself; these render the
+    // same shell as "/".
+    app.get("/project/:name", async (c) => c.html(await configuredViewerHtml(c, { title: c.req.param("name") })));
+    app.get("/project/:name/:slug", async (c) => {
+        const mock = await store.findMock(c.req.param("name"), c.req.param("slug"));
+        if (!mock)
+            return c.html(await configuredViewerHtml(c, { title: c.req.param("name") }));
+        const posts = await store.listPosts({ mockId: mock.id });
+        const post = posts.find((p) => p.status !== "archived") ?? posts[0];
+        return c.html(await configuredViewerHtml(c, {
+            title: mock.title,
+            ...(post ? { preview: { mock, post } } : {}),
+        }));
+    });
+    // --- REST plumbing for the shared flows ---
+    const flowCtx = (c, strict = true) => ({
+        base: `${new URL(c.req.url).origin}${requestBasePath(c.req.raw)}`,
+        // The browser sets Fetch Metadata on same-origin requests; only the trusted
+        // viewer may act as the user (drafts, replies, user-authored comments).
+        viewer: c.req.header("sec-fetch-site") === "same-origin",
+        strict,
+        request: c.req.raw,
+        signal: c.req.raw.signal,
+    });
+    const send = (c, result) => c.json(result.body, result.status);
+    const jsonBody = (c) => c.req.json().catch(() => null);
+    const flag = (c, key) => c.req.query(key) === "1";
+    // --- sessions ---
+    app.get("/api/sessions", async (c) => {
+        const [sessions, counts] = await Promise.all([
+            store.listSessions(),
+            store.countPostsBySession(),
+        ]);
+        return c.json(sessions.map((s) => sessionRowView(s, counts.get(s.id) ?? 0)));
+    });
+    app.get("/api/sessions/:id", async (c) => {
+        const session = await store.getSession(c.req.param("id"));
+        if (!session)
+            return c.json({ error: "session not found" }, 404);
+        const posts = await store.listPosts({ sessionId: session.id });
+        return c.json(sessionRowView(session, posts.length));
+    });
+    app.post("/api/sessions", async (c) => {
+        const body = (await jsonBody(c)) ?? {};
+        const cwd = str(body.cwd, 4096);
+        const key = str(body.key, MAX_TITLE);
+        const existing = key ? await store.getSessionByKey(key) : null;
+        if (existing)
+            return c.json(existing, 200);
+        const session = await store.createSession({
+            agent: str(body.agent, MAX_TITLE) ?? "agent",
+            title: str(body.title, MAX_TITLE),
+            cwd,
+            // Resolved once here so every mock this session publishes lands in the
+            // same project.
+            project: resolveProject(str(body.project, MAX_TITLE), cwd),
+            key,
+        });
+        bus.broadcast({ type: "session-created", id: session.id });
+        return c.json(session, 201);
+    });
+    app.patch("/api/sessions/:id", async (c) => {
+        const body = await jsonBody(c);
+        if (!body || typeof body.title !== "string") {
+            return c.json({ error: 'body must include "title" string' }, 400);
+        }
+        const session = await store.renameSession(c.req.param("id"), body.title.slice(0, MAX_TITLE));
+        if (!session)
+            return c.json({ error: "session not found" }, 404);
+        bus.broadcast({ type: "session-updated", id: session.id });
+        return c.json(session);
+    });
+    app.delete("/api/sessions/:id", async (c) => {
+        const id = c.req.param("id");
+        if (!(await store.removeSession(id)))
+            return c.json({ error: "session not found" }, 404);
+        bus.broadcast({ type: "session-deleted", id });
+        return c.json({ ok: true });
+    });
+    // --- projects and mocks ---
+    app.get("/api/projects", async (c) => c.json(await store.listProjects()));
+    app.get("/api/mocks", async (c) => send(c, await listMocksFlow({ project: c.req.query("project") })));
+    app.post("/api/mocks", async (c) => send(c, await publishFlow(await jsonBody(c), flowCtx(c))));
+    // A session-scoped public read may only address a mock by its unguessable id.
+    const guardPublicMock = async (c) => {
+        if (!isUnauthenticatedSessionRead(c))
+            return null;
+        return (await store.getMock(c.req.param("id") ?? ""))
+            ? null
+            : c.json({ error: "mock not found" }, 404);
+    };
+    app.get("/api/mocks/:id", async (c) => {
+        const denied = await guardPublicMock(c);
+        if (denied)
+            return denied;
+        return send(c, await getMockFlow(c.req.param("id"), {
+            project: c.req.query("project"),
+            body: flag(c, "body"),
+            history: flag(c, "history"),
+        }));
+    });
+    app.get("/api/mocks/:id/export", async (c) => {
+        const denied = await guardPublicMock(c);
+        if (denied)
+            return denied;
+        return send(c, await exportFlow(c.req.param("id"), {
+            project: c.req.query("project"),
+            state: c.req.query("state"),
+            variant: c.req.query("variant"),
+        }, flowCtx(c)));
+    });
+    app.delete("/api/mocks/:id", async (c) => send(c, await removeMockFlow(c.req.param("id"), { project: c.req.query("project") })));
+    app.post("/api/mocks/:id/asks", async (c) => send(c, await askFlow(c.req.param("id"), await jsonBody(c), flowCtx(c))));
+    app.get("/api/mocks/:id/draft", async (c) => send(c, await getDraftFlow(c.req.param("id"), flowCtx(c))));
+    app.put("/api/mocks/:id/draft", async (c) => send(c, await putDraftFlow(c.req.param("id"), await jsonBody(c), flowCtx(c))));
+    app.delete("/api/mocks/:id/draft", async (c) => send(c, await deleteDraftFlow(c.req.param("id"), flowCtx(c))));
+    app.post("/api/mocks/:id/reply", async (c) => send(c, await replyFlow(c.req.param("id"), await jsonBody(c), flowCtx(c))));
+    app.post("/api/mocks/:id/restore", async (c) => send(c, await restoreFlow(c.req.param("id"), await jsonBody(c))));
+    app.post("/api/mocks/:id/variants/:postId/restore", async (c) => send(c, await restoreVersionFlow(c.req.param("id"), c.req.param("postId"), await jsonBody(c), flowCtx(c))));
+    app.post("/api/mocks/:id/say", async (c) => send(c, await sayFlow(c.req.param("id"), await jsonBody(c))));
+    app.get("/api/feedback", async (c) => send(c, await feedbackFlow({ session: c.req.query("session"), project: c.req.query("project") })));
+    // --- comments ---
+    app.post("/api/comments", async (c) => send(c, await commentFlow(await jsonBody(c), flowCtx(c))));
+    app.delete("/api/comments/:id", async (c) => {
+        const comment = await store.removeComment(c.req.param("id"));
+        if (!comment)
+            return c.json({ error: "comment not found" }, 404);
+        bus.broadcast({ type: "comment-deleted", id: comment.id, sessionId: comment.sessionId });
+        return c.json({ ok: true });
+    });
+    // The viewer's update notice: running version vs latest published release.
+    app.get("/api/version", async (c) => {
+        if (!version)
+            return c.json({ current: null, latest: null, updateAvailable: false });
+        const latest = await latestRelease();
+        const updateAvailable = latest !== null && versionGt(latest.version, version);
+        return c.json({
+            current: version,
+            latest: latest?.version ?? null,
+            updateAvailable,
+            upgradeCommand: updateAvailable ? (upgradeCommand ?? null) : null,
+            notes: updateAvailable ? (latest?.notes ?? null) : null,
+        });
+    });
+    // Long-poll friendly: ?wait=N holds the request open up to N seconds until
+    // a matching comment arrives. Plumbing for `mockpit watch` and the viewer;
+    // agents read with GET /api/feedback, which never blocks.
+    // A wait counts against the connection cap (it pins a socket just like SSE);
+    // an instant ?wait=0 read does not.
+    app.get("/api/comments", async (c) => {
+        const sessionId = c.req.query("session");
+        const mockId = c.req.query("mock");
+        const postId = c.req.query("post");
+        if (isUnauthenticatedSessionRead(c)) {
+            if (!sessionId && !mockId && !postId) {
+                return c.json({ error: "session, mock or post required" }, 401);
+            }
+            if (sessionId && !(await store.getSession(sessionId))) {
+                return c.json({ error: "session not found" }, 404);
+            }
+            if (mockId && !(await store.getMock(mockId)))
+                return c.json({ error: "mock not found" }, 404);
+            if (postId && !(await store.getPost(postId)))
+                return c.json({ error: "post not found" }, 404);
+        }
+        const waitSeconds = Number(c.req.query("wait") ?? 0) || 0;
+        const author = c.req.query("author");
+        const after = c.req.query("after");
+        const query = {
+            sessionId,
+            mockId,
+            postId,
+            author,
+            afterSeq: after ? Number(after) : undefined,
+            waitSeconds,
+        };
+        // An `author=user` read (or any wait) is the agent listening; anything else
+        // is the viewer reading a thread, which gets per-comment delivery state.
+        // Only an authenticated caller can be the agent: on a public-read workspace
+        // an anonymous reader must never advance the feedback cursor, or the agent
+        // would silently lose the comments that reader "took".
+        const isAgentRead = isAuthenticated(c) && (author === "user" || waitSeconds > 0);
+        query.agent = isAgentRead;
+        const respond = async (signal) => {
+            if (isAgentRead)
+                return send(c, await listenFlow(query, signal));
+            const result = await waitForComments(query, signal);
+            return c.json({ ...result, comments: await withDelivered(result.comments) });
+        };
+        if (waitSeconds <= 0)
+            return respond();
+        if (!acquireHold())
+            return c.json({ error: "too many concurrent connections" }, 503);
+        const release = makeRelease();
+        // If the client disconnects mid-wait, release the slot promptly.
+        c.req.raw.signal.addEventListener("abort", release, { once: true });
+        try {
+            return await respond(c.req.raw.signal);
+        }
+        finally {
+            release();
+        }
+    });
+    // Content-hashed bridge/token assets the surface documents reference, so
+    // every surface doesn't re-inline the same ~11 KB. Without this route the
+    // in-frame bridge never loads and iframes never report their height.
+    app.get("/asset/:file", (c) => {
+        const asset = staticAsset(`/asset/${c.req.param("file")}`);
+        if (!asset)
+            return c.text("Not found", 404);
+        c.header("Content-Type", asset.contentType);
+        c.header("Cache-Control", "public, max-age=31536000, immutable");
+        return c.body(asset.body);
+    });
+    app.get("/guide", (c) => c.text(withOrigin(topics.html ?? "", c)));
+    app.get("/setup", (c) => c.text(withOrigin(setupText, c)));
+    // The brief without `?topic=`, one reference topic with it. Unknown topics
+    // are a 400 that names the real ones, so an agent can correct itself.
+    app.get("/agent-howto", async (c) => {
+        const topic = c.req.query("topic");
+        if (topic === undefined)
+            return c.text(withOrigin(await briefFor(c.req.query("project")), c));
+        if (!isGuideTopic(topic))
+            return c.json({ error: unknownTopicMessage(topic), topics: GUIDE_TOPICS }, 400);
+        return c.text(withOrigin(topics[topic] ?? "", c));
+    });
+    // Opt-in html kits available on this workspace (id, label, summary, classes) —
+    // for discovery (`mockpit kits`); the CSS/JS payloads are server-only. With
+    // `?project=`, that project's own kits follow the bundled ones.
+    app.get("/api/kits", async (c) => {
+        const project = c.req.query("project");
+        return c.json(kitSummaries(project ? ((await designFor(project))?.projectKits ?? []) : []));
+    });
+    // --- theme: one palette, so the workspace setting is just its mode ---
+    app.get("/api/theme", async (c) => c.json({ mode: await workspaceMode() }));
+    app.put("/api/theme", async (c) => {
+        const body = await c.req.json().catch(() => null);
+        const mode = body?.mode;
+        if (!isMode(mode))
+            return c.json({ error: 'mode must be "dark" or "light"' }, 400);
+        await store.setSetting("mode", mode);
+        bus.broadcast({ type: "theme-changed", mode });
+        return c.json({ mode });
+    });
+    // The project's design system, imported by `mockpit init` and injected into
+    // every html surface of the project (see renderHtmlPage).
+    app.get("/api/projects/:name/design", async (c) => c.json(await designFor(c.req.param("name"))));
+    app.put("/api/projects/:name/design", async (c) => {
+        const body = await c.req.json().catch(() => null);
+        if (!body || typeof body !== "object")
+            return c.json({ error: "invalid JSON body" }, 400);
+        const project = c.req.param("name");
+        // `mockpit init` re-detects the repo and PUTs without iconSets; that must
+        // not uninstall what `mockpit icons add` installed.
+        const previous = await designFor(project);
+        let iconSets = previous?.iconSets ?? [];
+        if (body.iconSets !== undefined) {
+            const checked = await checkIconSets(body.iconSets);
+            if (typeof checked === "string")
+                return c.json({ error: checked }, 400);
+            iconSets = checked;
+        }
+        // Same rule as iconSets: a PUT that omits projectKits keeps them.
+        let projectKits = previous?.projectKits ?? [];
+        if (body.projectKits !== undefined) {
+            const checked = checkProjectKits(body.projectKits);
+            if (typeof checked === "string")
+                return c.json({ error: checked }, 400);
+            projectKits = checked;
+        }
+        const kitIds = ["tailwind", "none", ...KIT_IDS, ...projectKits.map((k) => k.id)];
+        const kit = body.kit === undefined || body.kit === null ? "none" : body.kit;
+        if (typeof kit !== "string" || !kitIds.includes(kit))
+            return c.json({ error: `unknown kit "${String(kit)}" — known: ${kitIds.join(", ")}` }, 400);
+        const designFiles = checkDesignFiles(body.designFiles);
+        if (typeof designFiles === "string")
+            return c.json({ error: designFiles }, 400);
+        const design = {
+            detected: body.detected && typeof body.detected === "object"
+                ? {
+                    tailwind: body.detected.tailwind === true,
+                    shadcn: body.detected.shadcn === true,
+                    cssVars: Number(body.detected.cssVars) || 0,
+                    fonts: Array.isArray(body.detected.fonts)
+                        ? body.detected.fonts.filter((f) => typeof f === "string").slice(0, 20)
+                        : [],
+                }
+                : null,
+            palette: body.palette && typeof body.palette === "object" && body.palette.light && body.palette.dark
+                ? body.palette
+                : null,
+            kit,
+            cssVars: typeof body.cssVars === "string" ? body.cssVars.slice(0, 64_000) : "",
+            // A cut stylesheet would not compile, so an oversized one is dropped
+            // whole and the frame falls back to `cssVars`.
+            tailwindCss: typeof body.tailwindCss === "string" && body.tailwindCss.length <= 128_000
+                ? body.tailwindCss
+                : "",
+            strippedImports: Array.isArray(body.strippedImports)
+                ? body.strippedImports
+                    .filter((s) => typeof s === "string")
+                    .map((s) => s.slice(0, 200))
+                    .slice(0, 50)
+                : [],
+            iconSets,
+            projectKits,
+            designFiles,
+            updatedAt: new Date().toISOString(),
+        };
+        return c.json(await saveDesign(project, design));
+    });
+    async function saveDesign(project, design) {
+        await store.setSetting(`design:${project}`, JSON.stringify(design));
+        // Every rendered surface bakes the design into its document string, so a
+        // design change invalidates them all.
+        clearRenderCache();
+        bus.broadcast({ type: "theme-changed", mode: await workspaceMode() });
+        return design;
+    }
+    const MAX_PROJECT_KITS = 16;
+    function checkProjectKits(raw) {
+        if (!Array.isArray(raw))
+            return "projectKits must be an array";
+        if (raw.length > MAX_PROJECT_KITS)
+            return `at most ${MAX_PROJECT_KITS} project kits`;
+        const kits = [];
+        for (const item of raw) {
+            const kit = checkProjectKit(item);
+            if (typeof kit === "string")
+                return kit;
+            if (kits.some((k) => k.id === kit.id))
+                return `kit "${kit.id}" is listed twice`;
+            kits.push(kit);
+        }
+        return kits;
+    }
+    const emptyDesign = () => ({
+        detected: null,
+        palette: null,
+        kit: "none",
+        cssVars: "",
+        tailwindCss: "",
+        strippedImports: [],
+        iconSets: [],
+        projectKits: [],
+        updatedAt: new Date().toISOString(),
+    });
+    // Add or replace one project kit (`mockpit kit add`). A project that never ran
+    // init gets a design holding just the kit.
+    app.put("/api/projects/:name/kits/:id", async (c) => {
+        const body = await c.req.json().catch(() => null);
+        if (!body || typeof body !== "object")
+            return c.json({ error: "invalid JSON body" }, 400);
+        const project = c.req.param("name");
+        const kit = checkProjectKit({ ...body, id: c.req.param("id") });
+        if (typeof kit === "string")
+            return c.json({ error: kit }, 400);
+        const design = (await designFor(project)) ?? emptyDesign();
+        const others = design.projectKits.filter((k) => k.id !== kit.id);
+        if (others.length >= MAX_PROJECT_KITS)
+            return c.json({ error: `at most ${MAX_PROJECT_KITS} project kits` }, 400);
+        const saved = await saveDesign(project, {
+            ...design,
+            projectKits: [...others, kit],
+            updatedAt: new Date().toISOString(),
+        });
+        return c.json(saved);
+    });
+    // Removing the project's default kit falls back to no kit rather than leaving
+    // design.kit naming something that no longer resolves.
+    app.delete("/api/projects/:name/kits/:id", async (c) => {
+        const project = c.req.param("name");
+        const id = c.req.param("id");
+        const design = await designFor(project);
+        if (!design?.projectKits.some((k) => k.id === id))
+            return c.json({ error: `${project} has no kit "${id}"` }, 404);
+        const saved = await saveDesign(project, {
+            ...design,
+            kit: design.kit === id ? "none" : design.kit,
+            projectKits: design.projectKits.filter((k) => k.id !== id),
+            updatedAt: new Date().toISOString(),
+        });
+        return c.json(saved);
+    });
+    // Every set an html surface of this project can name, installed first.
+    app.get("/api/projects/:name/icons", async (c) => {
+        const sets = await iconSetsFor(await designFor(c.req.param("name")));
+        return c.json({
+            sets: sets.map((s) => ({ prefix: s.prefix, count: iconCount(s.set), source: s.source })),
+        });
+    });
+    // The repo's design files as init read them: every map and list is cut to
+    // the reader's own caps, then the whole is refused past 32k so one project
+    // cannot bloat every brief and every settings read.
+    const DESIGN_FILES_MAX = 32_000;
+    const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+    function checkDesignFiles(raw) {
+        if (raw === undefined || raw === null)
+            return null;
+        if (!isRecord(raw))
+            return "designFiles must be an object";
+        const str = (v, max) => (typeof v === "string" ? v.slice(0, max) : "");
+        const strs = (v, n, max) => Array.isArray(v)
+            ? v
+                .filter((s) => typeof s === "string")
+                .map((s) => s.slice(0, max))
+                .slice(0, n)
+            : [];
+        const flat = (v, n) => Object.fromEntries(Object.entries(isRecord(v) ? v : {})
+            .filter((e) => typeof e[1] === "string")
+            .slice(0, n)
+            .map(([k, x]) => [k.slice(0, 80), x.slice(0, 120)]));
+        const nested = (v, n) => Object.fromEntries(Object.entries(isRecord(v) ? v : {})
+            .filter(([, x]) => isRecord(x))
+            .slice(0, n)
+            .map(([k, x]) => [k.slice(0, 80), flat(x, 12)]));
+        const out = {};
+        const md = raw.designMd;
+        if (isRecord(md)) {
+            out.designMd = {
+                name: str(md.name, 120),
+                colors: flat(md.colors, 100),
+                typography: nested(md.typography, 40),
+                rounded: flat(md.rounded, 30),
+                spacing: flat(md.spacing, 30),
+                components: nested(md.components, 60),
+                headings: strs(md.headings, 20, 120),
+                dos: str(md.dos, 1_500),
+            };
+        }
+        const tokens = raw.tokens;
+        if (isRecord(tokens)) {
+            out.tokens = {
+                files: strs(tokens.files, 20, 200),
+                count: Math.max(0, Math.floor(Number(tokens.count) || 0)),
+                cssVars: tokens.cssVars === true,
+                values: flat(tokens.values, 400),
+            };
+        }
+        const shadcn = raw.shadcn;
+        if (isRecord(shadcn)) {
+            out.shadcn = {
+                style: str(shadcn.style, 60),
+                baseColor: str(shadcn.baseColor, 60),
+                iconLibrary: str(shadcn.iconLibrary, 60),
+                components: strs(shadcn.components, 80, 60),
+            };
+        }
+        const size = JSON.stringify(out).length;
+        if (size > DESIGN_FILES_MAX) {
+            return `designFiles is ${size} characters serialized; at most ${DESIGN_FILES_MAX}`;
+        }
+        return Object.keys(out).length ? out : null;
+    }
+    // The installed sets a design PUT names: each must be an uploaded Iconify
+    // JSON set whose prefix matches, so a typo fails here rather than as blank
+    // icons on every render. The count is read off the set, not trusted.
+    const MAX_ICON_SETS = 32;
+    async function checkIconSets(raw) {
+        if (!Array.isArray(raw))
+            return "iconSets must be an array of {prefix, assetId}";
+        if (raw.length > MAX_ICON_SETS)
+            return `at most ${MAX_ICON_SETS} icon sets`;
+        const byPrefix = new Map();
+        for (const entry of raw) {
+            const prefix = entry?.prefix;
+            const assetId = entry?.assetId;
+            if (!isIconName(prefix) || typeof assetId !== "string" || !assetId) {
+                return "each icon set needs a prefix (lowercase, e.g. lucide) and an assetId";
+            }
+            const set = await installedIconSet(assetId);
+            if (!set)
+                return `icon set ${prefix}: asset ${assetId} is not an Iconify JSON set`;
+            if (set.prefix !== prefix) {
+                return `icon set ${prefix}: asset ${assetId} holds the ${set.prefix} set`;
+            }
+            byPrefix.set(prefix, { prefix, assetId, count: iconCount(set) });
+        }
+        return [...byPrefix.values()];
+    }
+    // --- push and webhooks ---
+    app.get("/api/push/vapid", async (c) => c.json({ publicKey: (await vapidKeys(store)).publicKey }));
+    app.post("/api/push/subscribe", async (c) => {
+        const body = await c.req.json().catch(() => null);
+        const subscription = body?.subscription ?? body;
+        if (!isPushSubscription(subscription)) {
+            return c.json({ error: "invalid push subscription" }, 400);
+        }
+        await addSubscription(store, subscription);
+        return c.body(null, 204);
+    });
+    app.get("/api/hooks", async (c) => c.json(await listHooks(store)));
+    app.post("/api/hooks", async (c) => {
+        const body = await c.req.json().catch(() => null);
+        const url = typeof body?.url === "string" ? body.url : "";
+        if (!/^https?:\/\//.test(url))
+            return c.json({ error: 'body must include an http(s) "url"' }, 400);
+        const events = (Array.isArray(body.events) ? body.events : []).filter((e) => e === "ask" || e === "publish" || e === "decision");
+        if (events.length === 0) {
+            return c.json({ error: '"events" must list "ask", "publish" and/or "decision"' }, 400);
+        }
+        const hook = { id: newId(), url, events };
+        await addHook(store, hook);
+        return c.json({ id: hook.id }, 201);
+    });
+    app.delete("/api/hooks/:id", async (c) => {
+        if (!(await removeHook(store, c.req.param("id")))) {
+            return c.json({ error: "hook not found" }, 404);
+        }
+        return c.json({ ok: true });
+    });
+    // --- rendering ---
+    // Serves one surface of a post as a themed, sandboxed document. The viewer
+    // points an iframe here for every surface kind that becomes HTML — html surfaces
+    // (author markup) and the rich kinds (markdown/code/diff/terminal rendered
+    // server-side; mermaid as a self-rendering CDN doc). Image/json surfaces
+    // are data the viewer renders natively (text nodes / <img> / JSX), so they
+    // never reach here.
+    // Everything a rendered document depends on. The resolved version makes a
+    // version's content immutable, and `origin` is in the key because it is baked
+    // into the document (CSP, <base>, asset URLs) — a pre-warm triggered by an
+    // agent publishing over one origin must never be served to a viewer on another.
+    // `knobs` is the canonical (validated, path-sorted) JSON of `?k=`, so two
+    // spellings of the same values share an entry.
+    const renderKey = (o) => `${o.postId}:${o.idx}:${o.version}:${o.mode ?? "os"}:${o.origin}:${o.knobs ?? ""}`;
+    // The document itself. Shared by the GET below and the publish-time pre-warm,
+    // so both produce byte-identical output for one key.
+    async function buildSurfaceDoc(args) {
+        const { surface, mode, origin } = args;
+        const theme = themeById(DEFAULT_THEME_ID);
+        const themeId = theme.id;
+        if (surface.kind === "html") {
+            // A page mock composes published components by reference; the tags
+            // are expanded here, server-side, so the whole page is still ONE
+            // sandboxed document rather than nested frames.
+            const html = args.mock?.kind === "page"
+                ? await expandPageHtml(args.mock.project, args.post, surface.html)
+                : surface.html;
+            return renderHtmlPage({
+                title: args.title,
+                html,
+                origin,
+                theme,
+                mode,
+                kits: surface.kits,
+                design: args.design,
+                version: args.version,
+                knobs: args.knobs,
+                resolveIcon: mayHaveIcons(html) ? (await iconResolverFor(args.design)).resolve : undefined,
+            });
+        }
+        if (surface.kind === "mermaid") {
+            return renderMermaidPage({ mermaid: surface.mermaid, origin, theme, mode });
+        }
+        // Load the rich renderers on first use, not at module load. richRender.ts
+        // pulls in shiki, @pierre/diffs, markdown-it and ansi_up — measured at ~48 MB
+        // of RSS and ~240 ms of import time (`npm run bench:all`, process suite), which
+        // every server paid at boot whether or not it ever rendered a rich surface.
+        // Deferring it past the html and mermaid branches above means an html-only
+        // workspace never loads any of it.
+        //
+        // The runtime's module cache makes every later call cheap, so there's no memo
+        // here to keep in sync. On the Worker the module is already inside the
+        // deployed bundle — the import defers evaluating it, not fetching it — so this
+        // needs no network at runtime. test/workerIntegration covers that on real
+        // workerd, because a dynamic import resolving differently there is exactly the
+        // way this optimization could break in production and nowhere else.
+        const { renderCode, renderDiff, renderMarkdown, renderTerminal } = await import("./richRender.js");
+        const rendered = surface.kind === "markdown"
+            ? await renderMarkdown(surface, { theme: themeId, mode })
+            : surface.kind === "code"
+                ? await renderCode(surface, { theme: themeId, mode })
+                : surface.kind === "terminal"
+                    ? renderTerminal(surface)
+                    : await renderDiff(surface, { theme: themeId, mode }).catch((e) => ({
+                        body: `<div class="rich-error">Couldn’t render diff — ${escapeHtml(e instanceof Error ? e.message : "render error")}</div>`,
+                        css: `.rich-error{color:var(--danger);font:13px/1.5 ui-monospace,monospace;padding:8px 12px;}`,
+                    }));
+        return renderSandboxedPart({ body: rendered.body, css: rendered.css, origin, theme, mode });
+    }
+    // Render the current version of a post into the cache, off the write path.
+    // The first thing the viewer does after a publish is load an iframe per
+    // surface; warming both schemes of the workspace theme turns that cold render
+    // (up to a second for a large code surface) into a cache hit. Detached on
+    // purpose: a render failure must never fail — or delay — the write. (The DO
+    // stays alive for the duration; there is no ExecutionContext to hand this to.)
+    const PREWARM_SURFACE_LIMIT = 4;
+    function warmPost(post, mock) {
+        const origin = lastOrigin;
+        if (!origin)
+            return;
+        void (async () => {
+            const design = await designFor(mock.project);
+            let warmed = 0;
+            for (const [idx, surface] of post.surfaces.entries()) {
+                if (warmed >= PREWARM_SURFACE_LIMIT)
+                    break;
+                if (!isSandboxedSurfaceKind(surface.kind))
+                    continue;
+                warmed++;
+                for (const mode of ["light", "dark"]) {
+                    const key = renderKey({ postId: post.id, idx, version: post.version, mode, origin });
+                    if (renderCache.has(key))
+                        continue;
+                    await cachedRender(key, () => buildSurfaceDoc({
+                        post,
+                        mock,
+                        surface,
+                        title: post.title,
+                        version: post.version,
+                        mode,
+                        origin,
+                        design,
+                    }));
+                }
+            }
+        })().catch((err) => console.warn("[mockpit] render pre-warm failed", err));
+    }
+    // `?k=` arrives URL-encoded; past this it is not a set of knob values.
+    const MAX_KNOB_QUERY = 8 * 1024;
+    const renderPostPage = async (c) => {
+        const surfaceParam = c.req.query("surface") ?? "0";
+        const ver = c.req.query("ver");
+        const modeParam = c.req.query("mode");
+        const mode = modeParam === "light" || modeParam === "dark" ? modeParam : undefined;
+        const kParam = c.req.query("k");
+        const origin = new URL(c.req.url).origin;
+        // Cache-first. A hit needs nothing from the post row, and the row is the
+        // expensive part of this route (surfaces + every retained version). Only a
+        // version-pinned request can take this path: without `ver` the current
+        // version — and so the key — is unknown until the row is read. A `?k=`
+        // request never does: its values are checked against the mock's knobs,
+        // which can change under a pinned version.
+        const pinned = Number(ver);
+        if (Number.isInteger(pinned) && pinned > 0 && kParam === undefined) {
+            const hit = renderCacheHit(renderKey({
+                postId: c.req.param("id"),
+                idx: Number(surfaceParam),
+                version: pinned,
+                mode,
+                origin,
+            }));
+            if (hit !== undefined) {
+                surfaceDocHeaders(c, true);
+                return c.html(hit);
+            }
+        }
+        const post = await store.getPost(c.req.param("id"));
+        if (!post)
+            return c.text("Post not found", 404);
+        const mock = await store.getMock(post.mock);
+        let title = post.title;
+        let surfaces = post.surfaces;
+        let version = post.version;
+        if (ver && Number(ver) !== post.version) {
+            const old = post.history.find((h) => h.version === Number(ver));
+            if (!old)
+                return c.text(`Version ${ver} not available`, 404);
+            title = old.title;
+            surfaces = old.surfaces;
+            version = old.version;
+        }
+        const idx = Number(surfaceParam ?? 0);
+        const surface = surfaces[idx];
+        // Only the kinds that become HTML are served here. Image/json render
+        // natively in the viewer and must not be reachable as a document.
+        if (!surface || !isSandboxedSurfaceKind(surface.kind)) {
+            return c.text("No renderable surface at that index", 404);
+        }
+        // Knob values are agent/user data: only values the mock (or this variant's
+        // per-part overrides) declares, within their schema, ever reach the document.
+        let knobs;
+        let knobsKey;
+        if (kParam !== undefined) {
+            const bad = (error) => {
+                surfaceDocHeaders(c, false);
+                return c.text(error, 400);
+            };
+            if (kParam.length > MAX_KNOB_QUERY)
+                return bad("k is too long");
+            let raw;
+            try {
+                raw = JSON.parse(kParam);
+            }
+            catch {
+                return bad("k must be URL-encoded JSON of {path: value}");
+            }
+            const checked = checkKnobValues(raw, mock ?? { knobs: {} }, [post], "k");
+            if (!checked.ok)
+                return bad(checked.error);
+            const paths = Object.keys(checked.value).sort();
+            if (paths.length > 0 && surface.kind === "html") {
+                knobs = Object.fromEntries(paths.map((p) => [p, checked.value[p]]));
+                knobsKey = JSON.stringify(knobs);
+            }
+        }
+        // Every input is in the URL (the palette is fixed, the mode is a query
+        // param), so a version-pinned document never changes.
+        surfaceDocHeaders(c, ver != null);
+        // Cache the finished document under the same key the pre-warm uses; the
+        // resolved `version` makes it immutable, so a hit is always correct.
+        // A page's slots are pinned at publish, so they are a function of
+        // (id, version) too and need no separate key component.
+        const cacheKey = renderKey({ postId: post.id, idx, version, mode, origin, knobs: knobsKey });
+        const design = mock ? await designFor(mock.project) : null;
+        const doc = await cachedRender(cacheKey, async () => buildSurfaceDoc({ post, mock, surface, title, version, mode, origin, design, knobs }));
+        return c.html(doc);
+    };
+    app.get("/s/:id", renderPostPage);
+    // --- assets (agent-uploaded images and files) ---
+    // Accepts raw bytes (the asset's own Content-Type, metadata via query) or a
+    // JSON envelope { data: base64, contentType, ... } — so curl --data-binary
+    // and a JSON client both work, and MCP can ride base64. The body is read once
+    // and only treated as an envelope when it is application/json carrying a
+    // base64 `data` string; a raw JSON asset (no top-level `data`) stays raw.
+    app.post("/api/assets", limitAssetBody, async (c) => {
+        const mime = (c.req.header("content-type") ?? "").split(";")[0].trim().toLowerCase();
+        // limitAssetBody has already bounded the body to MAX_ASSET_BYTES, so this
+        // read is safe. The post-decode cap in uploadAsset still applies (a base64
+        // envelope decodes to ~3/4), enforcing the true asset limit on the bytes.
+        const buf = new Uint8Array(await c.req.arrayBuffer());
+        let envelope = null;
+        if (mime === "application/json") {
+            try {
+                const j = JSON.parse(new TextDecoder().decode(buf));
+                if (j && typeof j.data === "string")
+                    envelope = j;
+            }
+            catch {
+                // not an envelope — fall through to the raw path
+            }
+        }
+        const kindQ = c.req.query("kind");
+        let body;
+        try {
+            body = envelope
+                ? {
+                    data: decodeBase64(envelope.data),
+                    contentType: typeof envelope.contentType === "string"
+                        ? envelope.contentType
+                        : "application/octet-stream",
+                    filename: typeof envelope.filename === "string" ? envelope.filename : undefined,
+                    kind: isAssetKind(envelope.kind) ? envelope.kind : undefined,
+                    session: typeof envelope.session === "string" ? envelope.session : undefined,
+                    agent: typeof envelope.agent === "string" ? envelope.agent : undefined,
+                }
+                : {
+                    data: buf,
+                    contentType: mime || "application/octet-stream",
+                    filename: c.req.query("filename"),
+                    kind: isAssetKind(kindQ) ? kindQ : undefined,
+                    session: c.req.query("session"),
+                    agent: c.req.query("agent"),
+                };
+        }
+        catch (err) {
+            return c.json({ error: err instanceof Error ? err.message : "invalid upload" }, 400);
+        }
+        const result = await uploadAsset(body);
+        if ("error" in result)
+            return c.json({ error: result.error }, result.status);
+        const origin = new URL(c.req.url).origin;
+        const publicBasePath = requestBasePath(c.req.raw);
+        const assetPath = encodeURIComponent(result.asset.id);
+        return c.json({ ...result.asset, url: `${origin}${publicBasePath}/a/${assetPath}` }, 201);
+    });
+    app.get("/a/:id", async (c) => {
+        const id = c.req.param("id");
+        let asset = await store.getAsset(id);
+        // Optimistic uploads: an agent can derive an asset's URL from its content
+        // hash and publish a surface referencing it before (or while) the bytes are
+        // uploaded. Rather than 404 in that window, briefly wait for the bytes —
+        // but only when a live surface actually points at this id, so unknown ids
+        // still fail fast.
+        if (!asset && (await store.isAssetReferenced(id))) {
+            for (let i = 0; i < 20 && !asset; i++) {
+                await new Promise((resolve) => setTimeout(resolve, 150));
+                asset = await store.getAsset(id);
+            }
+        }
+        if (!asset)
+            return c.text("Asset not found", 404);
+        await store.touchAsset(asset.id);
+        const { contentType, disposition } = assetServeHeaders(asset);
+        c.header("Content-Type", contentType);
+        c.header("Content-Disposition", disposition);
+        c.header("X-Content-Type-Options", "nosniff");
+        // Short revalidating cache (not immutable) so touch-on-serve keeps firing
+        // and the LRU clock reflects real views; asset ids are unique anyway.
+        c.header("Cache-Control", "private, max-age=60");
+        return c.body(asset.data);
+    });
+    // --- live feed ---
+    app.get("/api/events", async (c) => {
+        const sessionId = c.req.query("session");
+        const mockId = c.req.query("mock");
+        if (isUnauthenticatedSessionRead(c)) {
+            if (!sessionId && !mockId)
+                return c.json({ error: "session or mock required" }, 401);
+            if (sessionId && !(await store.getSession(sessionId))) {
+                return c.json({ error: "session not found" }, 404);
+            }
+            if (mockId && !(await store.getMock(mockId))) {
+                return c.json({ error: "mock not found" }, 404);
+            }
+        }
+        if (!acquireHold())
+            return c.json({ error: "too many concurrent connections" }, 503);
+        viewerClients++;
+        let attached = true;
+        const releaseHold = makeRelease();
+        const release = () => {
+            if (attached)
+                viewerClients--;
+            attached = false;
+            releaseHold();
+        };
+        // Safety net: if the client disconnects before the stream callback opens,
+        // the request abort still releases the slot. close() below is guarded so a
+        // later abort firing release again is a no-op.
+        c.req.raw.signal.addEventListener("abort", release, { once: true });
+        const eventSessionId = (event) => {
+            if ("sessionId" in event)
+                return event.sessionId;
+            if (event.type === "session-created" ||
+                event.type === "session-updated" ||
+                event.type === "session-deleted") {
+                return event.id;
+            }
+            return undefined;
+        };
+        const eventMockId = (event) => {
+            if ("mockId" in event)
+                return event.mockId;
+            if (event.type === "mock-created" ||
+                event.type === "mock-updated" ||
+                event.type === "mock-deleted") {
+                return event.id;
+            }
+            return undefined;
+        };
+        return streamSSE(c, async (stream) => {
+            const queue = [];
+            let wake = null;
+            const unsubscribe = bus.subscribe((event) => {
+                if (sessionId && eventSessionId(event) !== sessionId)
+                    return;
+                if (mockId && eventMockId(event) !== mockId)
+                    return;
+                queue.push(event);
+                wake?.();
+            });
+            let open = true;
+            let closed = false;
+            const close = () => {
+                if (closed)
+                    return;
+                closed = true;
+                open = false;
+                unsubscribe();
+                wake?.();
+                release();
+            };
+            stream.onAbort(close);
+            c.req.raw.signal.addEventListener("abort", close, { once: true });
+            try {
+                await stream.writeSSE({ event: "hello", data: "{}" });
+                while (open) {
+                    while (queue.length > 0) {
+                        await stream.writeSSE({ data: JSON.stringify(queue.shift()) });
+                    }
+                    let pingTimer = null;
+                    await Promise.race([
+                        new Promise((resolve) => {
+                            wake = resolve;
+                        }),
+                        new Promise((resolve) => {
+                            pingTimer = setTimeout(resolve, 15000);
+                        }),
+                    ]);
+                    wake = null;
+                    if (pingTimer)
+                        clearTimeout(pingTimer);
+                    if (open && queue.length === 0) {
+                        await stream.writeSSE({ event: "ping", data: "{}" });
+                    }
+                }
+            }
+            finally {
+                close();
+            }
+        });
+    });
+    // --- MCP over streamable HTTP (works locally and deployed) ---
+    const mcpFlows = {
+        publish: (body, ctx) => publishFlow(body, ctx),
+        list: (query) => listMocksFlow(query),
+        get: (ref, query) => getMockFlow(ref, query),
+        ask: (ref, body, ctx) => askFlow(ref, body, ctx),
+        exportMock: (ref, query, ctx) => exportFlow(ref, query, ctx),
+        say: (ref, body) => sayFlow(ref, body),
+        feedback: (query) => feedbackFlow(query),
+    };
+    const guide = (project, topic) => topic ? (topics[topic] ?? "") : briefFor(project);
+    // --- run: an agent script over the same flows (server/run.ts) ---
+    const runFlow = createRunFlow({
+        store,
+        executor,
+        limits: { ...DEFAULT_RUN_LIMITS, ...runLimits },
+        flows: mcpFlows,
+        guide,
+        uploadAsset,
+        async createSession({ agent, project }) {
+            const session = await store.createSession({ agent, project: resolveProject(project) });
+            bus.broadcast({ type: "session-created", id: session.id });
+            return session.id;
+        },
+    });
+    // Never the viewer's verb: a script acts as the agent whatever origin sent it.
+    app.post("/api/run", async (c) => send(c, await runFlow(await jsonBody(c), flowCtx(c, false))));
+    registerMcp(app, {
+        store,
+        basePath: requestBasePath,
+        flows: mcpFlows,
+        run: runFlow,
+        uploadAsset,
+        // Every feature works on every tier: a remote MCP agent needs the project's
+        // real palette and kit, and the topics, as much as a shell one does.
+        guide,
+    });
+    return app;
+}