mockpit 1.2.0 → 1.3.0

package/dist/server/app.js

@@ -5,7 +5,7 @@ import { streamSSE } from "hono/streaming";
 import { ICON_SIZES, ICON_SVG, themeColor, webManifest } from "./appIcon.js";
 import { ICON_PNG_BASE64 } from "./appIconPng.js";
 import { decodeBase64 } from "./base64.js";
-import { mockDetailView, mockSummaryView, sessionRowView, surfaceRef } from "./apiViews.js";
+import { mockDetailView, treeNodeView, mockSummaryView, sessionRowView, surfaceRef, } from "./apiViews.js";
 import { askNudges } from "./askNudges.js";
 import { EventBus } from "./events.js";
 import { GUIDE_TOPICS, isGuideTopic, renderBriefGuide, unknownTopicMessage, } from "./designGuide.js";
@@ -13,19 +13,22 @@ import { buildFeedbackBatches } from "./feedbackBatch.js";
 import { HANDOFF_NOTE, handoffReady, supersedes } from "./handoff.js";
 import { bundledIconSets, expandIcons, iconCount, isIconName, mayHaveIcons, parseIconSet, resolverFor, } from "./icons.js";
 import { checkProjectKit, KIT_IDS, kitSummaries } from "./kits.js";
+import { chosenFills, decisionsFor, settledValues } from "./decisions.js";
+import { composeFills, slotsInSurfaces, spliceFills } from "./fills.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 { embedsKey, expandHtml, hasEmbedTags, parseEmbedTags, } from "./embeds.js";
 import { registerMcp } from "./mcpHttp.js";
 import { createRunFlow, DEFAULT_RUN_LIMITS } from "./run.js";
 import { logMiddleware, writeLog } from "./eventLog.js";
 import { RUN_API } from "./runApi.js";
-import { escapeHtml, renderHtmlPage, renderMermaidPage, renderSandboxedPart, STATIC_ASSET_PREFIX, staticAsset, } from "./surfacePage.js";
+import { escapeHtml, renderHtmlPage, renderMermaidPage, knobAttributes, renderSandboxedPart, STATIC_ASSET_PREFIX, staticAsset, } from "./surfacePage.js";
 import { DEFAULT_MODE, DEFAULT_THEME_ID, isMode, themeById } from "./themes.js";
-import { builtinAsk, DEFAULT_PROJECT, DEFAULT_VARIANT, htmlSurface, isSandboxedSurfaceKind, ATTACHABLE_IMAGE_TYPES, MAX_ASK_IMAGES, MAX_ASSET_BYTES, newId, openCount, OTHER_ID, REACTIONS, projectFromCwd, reservedAgent, slugify, surfacesByteLength, } from "./types.js";
+import { askAnswered, builtinAsk, builtinAskIds, DEFAULT_PROJECT, DEFAULT_VARIANT, htmlSurface, isSandboxedSurfaceKind, ATTACHABLE_IMAGE_TYPES, MAX_ASK_IMAGES, MAX_ASSET_BYTES, inUseVersion, isLive, optionState, newId, openAsks, openCount, OTHER_ID, REACTIONS, projectFromCwd, postAtVersion, versionAt, reservedAgent, sameScreen, slugify, surfacesByteLength, } from "./types.js";
 import { coerceSurfaces, validateSurfaces, } from "./postSurfaces.js";
+import { isViewerRequest } from "./viewerRequest.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.
@@ -165,8 +168,14 @@ const fail = (status, error, extra = {}) => ({
     status,
     body: { error, ...extra },
 });
+const MAX_NOTE = 400;
+const MAX_WIDTHS = 4;
+const MIN_WIDTH = 280;
+const MAX_WIDTH = 2560;
 const str = (v, max) => typeof v === "string" && v.trim() ? v.trim().slice(0, max) : undefined;
 const MAX_LABEL = 120;
+const MAX_FLOWS = 50;
+const MAX_FLOW_STEPS = 100;
 const MAX_ASKS = 20;
 const MAX_OPTIONS = 20;
 const MAX_DRAFT_COMMENTS = 50;
@@ -177,7 +186,7 @@ const APP_FILES = new Set([
     ...ICON_SIZES.map((s) => `/icon-${s}.png`),
 ]);
 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, log, }) {
+export function createApp({ store, viewerHtml, setupText, topics = {}, authenticate, authToken, basePath, publicRead, screenshots, version, upgradeCommand, renderRev, fetchLatestRelease, onEvent, maxHoldConnections = DEFAULT_MAX_HOLD_CONNECTIONS, executor, runLimits, log, }) {
     const app = new Hono();
     // The scripts topic carries the run API from runApi.ts, its one source.
     if (topics.scripts)
@@ -195,7 +204,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     // 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;
+        lastOrigin = requestOrigin(c.req.raw);
         c.header("Referrer-Policy", "no-referrer");
         return next();
     });
@@ -285,7 +294,8 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     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");
+        const current = !renderRev || c.req.query("r") === renderRev;
+        c.header("Cache-Control", immutable && current ? "public, max-age=31536000, immutable" : "private, no-cache");
     }
     function renderCacheHit(key) {
         const hit = renderCache.get(key);
@@ -329,6 +339,19 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         return withLeading.slice(0, end);
     };
     const requestBasePath = (request) => normalizeBasePath(typeof basePath === "function" ? basePath(request) : basePath);
+    // Behind a TLS-terminating proxy (tailscale serve, a tunnel) the request
+    // reaches us as http while the browser is on https. A surface bakes this
+    // origin into its script URLs and CSP, and an http script inside an https
+    // page is blocked as mixed content: the frame then never runs its bridge, so
+    // live knobs and part reports silently stop. Trusting the header is safe
+    // here: it only shapes the caller's own response.
+    const requestOrigin = (request) => {
+        const url = new URL(request.url);
+        const proto = request.headers.get("x-forwarded-proto")?.split(",")[0]?.trim();
+        if (proto === "https" || proto === "http")
+            url.protocol = `${proto}:`;
+        return url.origin;
+    };
     // 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.
@@ -588,7 +611,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                 variants: posts.map(variantLabel),
             });
         }
-        const live = candidates.filter((p) => p.status !== "archived");
+        const live = candidates.filter((p) => isLive(p.status));
         if (live.length === 1 && !variant)
             return live[0];
         return fail(400, `${mock.slug} has several variants; pass ${variant ? "state" : "variant"}`, {
@@ -683,57 +706,126 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         }
         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) {
+    // The component post an embed shows: the named variant of its first state,
+    // else the accepted one there, else "default", else the first live one.
+    async function embedTarget(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);
+        const state = mock.states[0] ?? null;
+        if (variant)
+            return store.findPost(mock.id, state, variant);
+        const inState = (await store.listPosts({ mockId: mock.id })).filter((p) => p.state === state);
+        return (inState.find((p) => p.status === "accepted") ??
+            inState.find((p) => p.variant === DEFAULT_VARIANT && isLive(p.status)) ??
+            inState.find((p) => isLive(p.status)) ??
+            inState[0] ??
+            null);
+    }
+    // Resolves tags to bodies: the tag's version if it pins one, else a peek
+    // (`overrides`, slug → version) the viewer asked for, else the latest. The
+    // body shows the component as decided: its slots composed to the fills its
+    // settled values chose, its other settled values on the wrapper.
+    function embedResolver(project, overrides = {}) {
+        return async (tag) => {
+            const post = await embedTarget(project, tag.slug, tag.variant);
+            if (!post)
+                return null;
+            const version = tag.version ?? overrides[tag.slug] ?? inUseVersion(post);
+            const surfaces = version === post.version
+                ? post.surfaces
+                : post.history.find((h) => h.version === version)?.surfaces;
+            const body = surfaces?.find((x) => x.kind === "html");
+            if (!surfaces || !body || body.kind !== "html")
+                return null;
+            const mock = await store.getMock(post.mock);
+            const settled = mock
+                ? settledValues(await replyPayloads(mock.id), mock, await store.listPosts({ mockId: mock.id }))
+                : {};
+            const slots = slotsInSurfaces(surfaces);
+            const fills = new Set(slots.map((sl) => sl.part));
+            const rest = Object.fromEntries(Object.entries(settled).filter(([p]) => !fills.has(p)));
+            return {
+                variant: post.variant,
+                version,
+                html: slots.length ? composeFills(body.html, chosenFills(slots, settled)) : body.html,
+                attrs: knobAttributes(rest).attrs,
+                ...(Object.keys(settled).length ? { stamp: JSON.stringify(settled) } : {}),
+            };
+        };
+    }
+    // A surface's html with its embeds expanded, and what they resolved to.
+    async function composedHtml(project, slug, html, overrides) {
+        if (!hasEmbedTags(html))
+            return { html, used: [], stamps: [], cycle: null };
+        return expandHtml(html, embedResolver(project, overrides), [slug]);
+    }
+    // The component versions a publish renders with, recorded on the version;
+    // an embed chain that loops back to this mock is refused.
+    async function publishEmbeds(project, slug, surfaces) {
+        const html = surfaces.find((x) => x.kind === "html");
+        if (!html || html.kind !== "html")
+            return [];
+        const { used, cycle } = await composedHtml(project, slug, html.html);
+        if (cycle) {
+            return fail(400, `embeds loop back on themselves: ${cycle.join(" → ")}`, { cycle });
+        }
+        return used;
+    }
+    // What the variants of a mock show through their embeds now: per post, the
+    // resolved list (nested included) with each component's versions, and the
+    // key that changes when any of them does.
+    async function embedViews(mock, posts) {
+        const out = new Map();
+        for (const post of posts) {
+            const html = post.surfaces.find((x) => x.kind === "html");
+            if (!html || html.kind !== "html" || !hasEmbedTags(html.html))
                 continue;
+            const composed = await composedHtml(mock.project, mock.slug, html.html);
+            const { used } = composed;
+            const list = [];
+            for (const e of used) {
+                const target = await embedTarget(mock.project, e.slug, e.variant);
+                const versions = target
+                    ? [target.version, ...target.history.map((h) => h.version)].sort((a, b) => b - a)
+                    : [e.version];
+                list.push({ ...e, latest: target?.version ?? e.version, versions });
             }
-            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);
+            out.set(post.id, { key: embedsKey(composed), list });
         }
-        return expandSlots(html, ({ slug, variant, version }) => {
-            const key = `${slug}::${variant}`;
-            const pinnedVersion = version ?? pinned.get(key) ?? null;
-            return bodies.get(`${key}::${pinnedVersion}`) ?? null;
-        });
+        return out;
+    }
+    // The mocks whose html embeds this slug, directly or through other
+    // components: they render differently once it changes.
+    async function embeddersOf(project, slug) {
+        const mocks = await store.listMocks(project);
+        const tagsOf = new Map();
+        for (const m of mocks) {
+            const slugs = new Set();
+            for (const p of await store.listPosts({ mockId: m.id })) {
+                for (const x of p.surfaces) {
+                    if (x.kind === "html")
+                        for (const t of parseEmbedTags(x.html))
+                            slugs.add(t.slug);
+                }
+            }
+            tagsOf.set(m.id, slugs);
+        }
+        const reached = new Set([slug]);
+        const out = [];
+        for (let grew = true; grew;) {
+            grew = false;
+            for (const m of mocks) {
+                if (reached.has(m.slug))
+                    continue;
+                if ([...(tagsOf.get(m.id) ?? [])].some((s) => reached.has(s))) {
+                    reached.add(m.slug);
+                    out.push(m);
+                    grew = true;
+                }
+            }
+        }
+        return out;
     }
     // 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.
@@ -752,7 +844,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     // 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 live = (s) => posts.filter((p) => p.state === s && isLive(p.status)).map((p) => p.variant);
         const names = live(state);
         if (names.length < 2)
             return null;
@@ -821,7 +913,27 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         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] : [])];
+        // A slot no ask sets is a decision nobody was asked; hand over the ask.
+        const slots = slotsInSurfaces(post.surfaces);
+        const setPaths = new Set(mock.asks.flatMap((a) => a.options.flatMap((o) => Object.keys(o.set ?? {}))));
+        const slotAsks = slots
+            .filter((sl) => !setPaths.has(sl.part))
+            .map((sl) => ({
+            id: sl.part,
+            text: `Which ${sl.label ?? sl.part}?`,
+            scope: "part",
+            part: sl.part,
+            options: sl.fills.map((f) => ({ label: f.label ?? f.name, set: { [sl.part]: f.name } })),
+        }));
+        const nudges = [
+            ...(extra.nudges ?? []),
+            ...(unbound ? [unbound.nudge] : []),
+            ...(slotAsks.length
+                ? [
+                    `${slotAsks.map((a) => `slot "${a.part}"`).join(", ")} ${slotAsks.length === 1 ? "has" : "have"} fills and no ask sets ${slotAsks.length === 1 ? "it" : "them"}: send suggestedSlotAsks with ask (reword the text in the user's terms)`,
+                ]
+                : []),
+        ];
         let partChanges;
         if (extra.previous) {
             partChanges = diffParts(partsInSurfaces(extra.previous), partsInSurfaces(post.surfaces));
@@ -848,13 +960,16 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             sessionId: post.sessionId,
             url: mockUrl(ctx.base, mock, post),
             parts: detail.parts,
+            ...(slots.length ? { slots } : {}),
             ...(extra.applied ? { applied: extra.applied } : {}),
             ...(partChanges && (partChanges.vanished.length || partChanges.renamed.length)
                 ? { partChanges }
                 : {}),
             ...(nudges.length ? { nudges } : {}),
             ...(unbound ? { suggestedAsk: unbound.ask } : {}),
+            ...(slotAsks.length ? { suggestedSlotAsks: slotAsks } : {}),
             ...(warnings.length ? { warnings } : {}),
+            ...(extra.flow ? { flow: extra.flow } : {}),
             feedback,
         }, extra.status ?? 200);
     }
@@ -868,26 +983,46 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             by,
         });
         warmPost(post, mock);
+        void announceEmbedders(mock).catch((err) => console.warn("[mockpit] embedders", err));
+    }
+    // A component's new version changes every mock that shows it: their views
+    // carry a new embeds key, so open viewers refetch and reload those frames.
+    async function announceEmbedders(mock) {
+        for (const m of await embeddersOf(mock.project, mock.slug)) {
+            bus.broadcast({ type: "mock-updated", id: m.id, project: m.project });
+        }
     }
     // 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.
+    // Exactly one body: `html`, the full ordered `surfaces` list, or `parts` or
+    // `fills` 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"');
+        const given = ["html", "surfaces", "parts", "fills"].filter((k) => body[k] !== undefined);
+        const forkIn = forkArg(body.fork);
+        if (isResult(forkIn))
+            return forkIn;
+        const flowIn = flowArg(body);
+        if (isResult(flowIn))
+            return flowIn;
+        // `flow` alone places an existing screen in a flow without a new version.
+        const flowOnly = given.length === 0 && !forkIn && !!flowIn;
+        if (given.length === 0 && !forkIn && !flowIn) {
+            return fail(400, 'provide "html", "surfaces", "parts" or "fills" (or "fork" alone)');
+        }
         if (given.length > 1) {
-            return fail(400, `pass one of "html", "surfaces" or "parts", not ${given.join(" and ")}`);
+            return fail(400, `pass one of "html", "surfaces", "parts" or "fills", not ${given.join(" and ")}`);
         }
-        const partEdits = partEditsArg(body);
+        const partEdits = editsArg(body, "parts");
         if (isResult(partEdits))
             return partEdits;
+        const fillEdits = editsArg(body, "fills");
+        if (isResult(fillEdits))
+            return fillEdits;
         const knobs = checkKnobs(body.knobs);
         if (!knobs.ok)
             return fail(400, knobs.error);
@@ -902,6 +1037,10 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         const from = Number.isInteger(fromN) && fromN > 0 ? fromN : undefined;
         const prompt = str(body.prompt, MAX_COMMENT_TEXT);
         const author = str(body.author, MAX_TITLE);
+        const note = body.note === undefined ? undefined : (str(body.note, MAX_NOTE) ?? "");
+        const widths = widthsArg(body.widths);
+        if (isResult(widths))
+            return widths;
         // An existing mock is addressable by id before a session exists.
         let mock = null;
         if (typeof body.mock === "string")
@@ -936,13 +1075,15 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         const inState = posts.filter((p) => p.state === state);
         let variant = variantIn;
         if (!variant) {
-            const live = inState.filter((p) => p.status !== "archived");
+            const live = inState.filter((p) => isLive(p.status));
             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 if (flowOnly)
+                variant = (live[0] ?? inState[0]).variant;
             else {
                 return fail(400, `${slug} has several variants; pass variant`, {
                     variants: inState.map(variantLabel),
@@ -953,9 +1094,53 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         const missing = () => fail(404, `${slug} has no variant "${variant}"${state === null ? "" : ` in "${state}"`}`, {
             variants: posts.map(variantLabel),
         });
+        const screen = { mock: slug, state };
+        if (flowIn) {
+            const full = await flowFull(project, flowIn.name, screen, flowIn.step);
+            if (full)
+                return full;
+        }
+        if (flowOnly) {
+            if (!mock || inState.length === 0) {
+                return fail(404, `${slug} has no ${state === null ? "design" : `state "${state}"`} yet: publish it with "flow" to place it`);
+            }
+            if (!target)
+                return missing();
+            const flow = await placeFlow(project, flowIn.name, screen, flowIn.step);
+            bus.broadcast({ type: "mock-updated", id: mock.id, project });
+            return writeResult(mock, target, ctx, { writer: session, flow });
+        }
+        // A fork starts a new variant from a sibling's version: that version's
+        // surfaces are what `parts`, `fills` and kept surface ids refer to.
+        let fork = null;
+        if (forkIn) {
+            if (target) {
+                return fail(409, `${variant} already exists; fork names a new variant to start`);
+            }
+            const source = inState.find((p) => p.variant === forkIn.variant);
+            if (!source) {
+                return fail(404, `no variant "${forkIn.variant}" to fork in this state`, {
+                    variants: inState.map(variantLabel),
+                });
+            }
+            const version = forkIn.version ?? source.version;
+            const surfacesAt = version === source.version
+                ? source.surfaces
+                : source.history.find((h) => h.version === version)?.surfaces;
+            if (!surfacesAt)
+                return fail(404, `${source.variant} has no version ${version}`);
+            fork = {
+                ref: { variant: source.variant, version },
+                surfaces: surfacesAt,
+                ...(source.knobs ? { knobs: source.knobs } : {}),
+                ...(source.note ? { note: source.note } : {}),
+            };
+        }
         // What `parts` and kept surface ids refer to: the variant's current
         // version, or the one `from` names.
         const base = () => {
+            if (fork)
+                return fork.surfaces;
             if (!target)
                 return missing();
             if (from === undefined || from === target.version)
@@ -965,11 +1150,16 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         };
         let surfaces;
         let applied;
-        if (partEdits) {
+        if (fork && given.length === 0) {
+            surfaces = fork.surfaces;
+        }
+        else if (partEdits || fillEdits) {
             const current = base();
             if (isResult(current))
                 return current;
-            const result = spliceParts(current, partEdits);
+            const result = partEdits
+                ? spliceParts(current, partEdits)
+                : spliceFills(current, fillEdits);
             if (!result.ok)
                 return fail(400, result.error);
             surfaces = result.surfaces;
@@ -985,6 +1175,9 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         if (bad)
             return bad;
         const nudges = knobNudges({ ...knobs.value, ...variantKnobs.value });
+        const embeds = await publishEmbeds(project, slug, surfaces);
+        if (isResult(embeds))
+            return embeds;
         if (!target) {
             // A new variant: carried by the session the agent is writing from.
             if (!session) {
@@ -1004,11 +1197,11 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                     kind: kind ?? "component",
                     states: state === null ? [] : [state],
                     knobs: knobs.value,
+                    ...(widths ? { widths } : {}),
                     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,
@@ -1016,38 +1209,53 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                 variant,
                 title: title ?? mock.title,
                 surfaces,
-                ...(Object.keys(variantKnobs.value).length ? { knobs: variantKnobs.value } : {}),
-                slots,
+                ...(Object.keys(variantKnobs.value).length
+                    ? { knobs: variantKnobs.value }
+                    : fork?.knobs
+                        ? { knobs: fork.knobs }
+                        : {}),
+                ...(note ? { note } : note === undefined && fork?.note ? { note: fork.note } : {}),
+                embeds,
+                ...(fork ? { forkedFrom: fork.ref } : {}),
                 from,
                 prompt,
                 author,
             });
             if (!created)
                 return fail(404, "session not found");
-            mock = await updateMockAfterWrite(mock, { state, kind, title, knobs: knobs.value, session });
+            mock = await updateMockAfterWrite(mock, {
+                state,
+                kind,
+                title,
+                knobs: knobs.value,
+                widths,
+                session,
+            });
+            const flow = flowIn ? await placeFlow(project, flowIn.name, screen, flowIn.step) : undefined;
             announcePost(mock, created, true);
             if (prompt && ctx.request)
                 notifyPublish(mock, created, prompt, ctx);
-            return writeResult(mock, created, ctx, { nudges, status: 201 });
+            return writeResult(mock, created, ctx, { nudges, status: 201, flow });
         }
         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,
+            ...(note !== undefined ? { note } : {}),
+            embeds,
             from,
             prompt,
             author,
         });
         if (!updated)
             return fail(404, "variant not found");
-        mock = await updateMockAfterWrite(mock, { state, kind, knobs: knobs.value, session });
+        const flow = flowIn ? await placeFlow(project, flowIn.name, screen, flowIn.step) : undefined;
+        mock = await updateMockAfterWrite(mock, { state, kind, knobs: knobs.value, widths, session });
         announcePost(mock, updated, false);
         if (prompt && ctx.request)
             notifyPublish(mock, updated, prompt, ctx);
@@ -1056,24 +1264,121 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             applied,
             nudges,
             writer: session,
+            flow,
         });
     }
+    // `flow` names a flow; `step` is the 1-based place of this screen in it
+    // (moving it if it is there already), 0 takes the screen out, and without
+    // `step` a screen not yet in the flow joins at its end.
+    function flowArg(body) {
+        const stepIn = body.step;
+        if (body.flow === undefined || body.flow === null) {
+            return stepIn === undefined || stepIn === null
+                ? undefined
+                : fail(400, '"step" needs "flow": the flow\'s name, e.g. "Morning"');
+        }
+        const name = str(body.flow, MAX_LABEL);
+        if (!name)
+            return fail(400, '"flow" must be the flow\'s name, e.g. "Morning"');
+        if (stepIn === undefined || stepIn === null)
+            return { name };
+        const step = Number(stepIn);
+        if (!Number.isInteger(step) || step < 0) {
+            return fail(400, '"step" must be the 1-based place in the flow, or 0 to take it out');
+        }
+        return { name, step };
+    }
+    // Checked before anything is written, so a full flow leaves no new version behind.
+    async function flowFull(project, name, screen, step) {
+        if (step === 0)
+            return null;
+        const flows = await store.listFlows(project);
+        const flow = flows.find((f) => f.name === name);
+        if (!flow && flows.length >= MAX_FLOWS) {
+            return fail(400, `${project} already has ${MAX_FLOWS} flows; reuse one`);
+        }
+        if (flow &&
+            flow.steps.length >= MAX_FLOW_STEPS &&
+            !flow.steps.some((x) => sameScreen(x, screen))) {
+            return fail(400, `flow "${name}" already has ${MAX_FLOW_STEPS} steps`);
+        }
+        return null;
+    }
+    async function placeFlow(project, name, screen, step) {
+        let at = step;
+        if (at === undefined) {
+            const flow = (await store.listFlows(project)).find((f) => f.name === name);
+            const i = flow ? flow.steps.findIndex((x) => sameScreen(x, screen)) : -1;
+            at = i >= 0 ? i + 1 : MAX_FLOW_STEPS + 1;
+        }
+        const flow = await store.placeFlowStep(project, name, screen, at);
+        return { name, steps: flow?.steps ?? [] };
+    }
+    // The project's flows as `read` returns them: only steps whose screen exists.
+    async function flowsView(project, mocks) {
+        const bySlug = new Map(mocks.map((m) => [m.slug, m]));
+        const exists = (x) => {
+            const m = bySlug.get(x.mock);
+            return !!m && (x.state === null ? m.states.length === 0 : m.states.includes(x.state));
+        };
+        return (await store.listFlows(project))
+            .map((f) => ({ name: f.name, steps: f.steps.filter(exists) }))
+            .filter((f) => f.steps.length > 0);
+    }
+    // `fork`: "variant" or "variant@N", the sibling version a new variant starts
+    // from.
+    function forkArg(v) {
+        if (v === undefined || v === null || v === "")
+            return undefined;
+        const bad = '"fork" must be "<variant>" or "<variant>@<version>", e.g. "quiet@2"';
+        if (typeof v !== "string")
+            return fail(400, bad);
+        const m = /^(.+?)(?:@(\d+))?$/.exec(v.trim());
+        const variant = m && str(m[1], MAX_LABEL);
+        if (!variant)
+            return fail(400, bad);
+        const version = m[2] === undefined ? undefined : Number(m[2]);
+        if (version !== undefined && version < 1)
+            return fail(400, bad);
+        return version === undefined ? { variant } : { variant, version };
+    }
+    // `widths`: the device widths the mock is judged at, in the agent's order;
+    // [] hands the choice back to the viewer.
+    function widthsArg(v) {
+        if (v === undefined)
+            return undefined;
+        const bad = `"widths" must be up to ${MAX_WIDTHS} integer px widths between ${MIN_WIDTH} and ${MAX_WIDTH}, e.g. [390, 1280]`;
+        if (!Array.isArray(v) || v.length > MAX_WIDTHS)
+            return fail(400, bad);
+        const out = [];
+        for (const w of v) {
+            if (!Number.isInteger(w) || w < MIN_WIDTH || w > MAX_WIDTH)
+                return fail(400, bad);
+            if (!out.includes(w))
+                out.push(w);
+        }
+        return out;
+    }
     // `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)
+    // `fills`: the same per slot alternative ("part#fill"), replaced or added.
+    function editsArg(body, key) {
+        if (body?.[key] === 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 edits = body[key];
+        const shape = key === "parts"
+            ? '{ "<part name>": "<html for that part>" }'
+            : '{ "<part>#<fill>": "<html for that fill>" }';
+        if (!edits || typeof edits !== "object" || Array.isArray(edits)) {
+            return fail(400, `"${key}" must be an object: ${shape}`);
         }
-        const entries = Object.entries(parts);
+        const entries = Object.entries(edits);
         if (entries.length === 0)
-            return fail(400, '"parts" is empty; name at least one part');
+            return fail(400, `"${key}" is empty; name at least one ${key.slice(0, -1)}`);
         if (entries.some(([, html]) => typeof html !== "string")) {
-            return fail(400, 'each "parts" value must be the html string for that part');
+            return fail(400, `each "${key}" value must be the html string for that ${key.slice(0, -1)}`);
         }
-        return parts;
+        return edits;
     }
     // A write may add a state, retitle the mock, declare knobs, and makes its
     // session the one a reply is delivered to.
@@ -1085,6 +1390,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             ...(w.kind ? { kind: w.kind } : {}),
             ...(w.title ? { title: w.title } : {}),
             ...(knobs ? { knobs } : {}),
+            ...(w.widths ? { widths: w.widths } : {}),
             ...(w.session ? { sessionId: w.session.id } : {}),
         });
         if (!updated)
@@ -1115,17 +1421,56 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         }
         const open = rows.reduce((n, r) => n + r.open, 0);
         return ok({
-            ...(project ? { project } : {}),
+            ...(project ? { project, flows: await flowsView(project, mocks) } : {}),
             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 ?? {};
+    // The project as a tree: every mock with its variants per state (status,
+    // lineage, what its embeds resolve to) and the components it embeds and is
+    // embedded in, and the declared flows. What the viewer's Home and an agent's
+    // `read --tree` lay out.
+    async function treeFlow(query) {
+        const project = str(query.project, MAX_TITLE);
+        if (!project)
+            return fail(400, 'provide "project"');
+        const mocks = await store.listMocks(project);
+        const nodes = [];
+        const pending = [];
+        for (const m of mocks) {
+            const posts = await store.listPosts({ mockId: m.id });
+            const embeds = await embedViews(m, posts);
+            const uses = new Set();
+            for (const p of posts) {
+                if (!isLive(p.status))
+                    continue;
+                for (const x of p.surfaces) {
+                    if (x.kind === "html")
+                        for (const t of parseEmbedTags(x.html))
+                            uses.add(t.slug);
+                }
+            }
+            nodes.push(treeNodeView(m, posts, {
+                settled: settledValues(await replyPayloads(m.id), m, posts),
+                uses: [...uses],
+                embeds,
+            }));
+            pending.push(pendingOf(m, posts));
+        }
+        const bySlug = new Map(nodes.map((n) => [n.slug, n]));
+        for (const n of nodes) {
+            n.uses = n.uses.filter((s) => bySlug.has(s));
+            for (const s of n.uses)
+                bySlug.get(s).usedIn.push(n.slug);
+        }
+        return ok({ project, tree: nodes, flows: await flowsView(project, mocks), pending });
+    }
+    async function replyPayloads(mockId) {
+        return (await store.listComments({ mockId }))
+            .filter((c) => c.kind === "reply" && c.payload)
+            .map((c) => c.payload);
     }
     async function getMockFlow(ref, query) {
         const mock = await resolveMock(ref, query.project, query.session);
@@ -1136,7 +1481,8 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             ...mockDetailView(mock, posts, {
                 body: query.body,
                 history: query.history,
-                tuned: await lastTuned(mock.id),
+                settled: settledValues(await replyPayloads(mock.id), mock, posts),
+                embeds: await embedViews(mock, posts),
             }),
             pending: pendingOf(mock, posts),
         });
@@ -1151,31 +1497,45 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         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 replies = await replyPayloads(mock.id);
+        const lastReply = replies[replies.length - 1] ?? null;
+        const settled = settledValues(replies, mock, posts);
         const entries = [];
         for (const state of states) {
             const inState = posts.filter((p) => p.state === state);
-            const post = (wantedVariant && inState.find((p) => p.variant === wantedVariant)) ||
+            const found = (wantedVariant && inState.find((p) => p.variant === wantedVariant)) ||
                 inState.find((p) => p.status === "accepted") ||
                 inState.find((p) => p.status === "open") ||
                 inState[0];
-            if (!post)
+            if (!found)
                 continue;
-            if (wantedVariant && post.variant !== wantedVariant)
+            if (wantedVariant && found.variant !== wantedVariant)
                 continue;
+            const post = postAtVersion(found, inUseVersion(found)) ?? found;
             const html = post.surfaces.find((s) => s.kind === "html");
+            // With slots, the screen as decided: only the chosen fills, by every
+            // value sent so far (defaults before any reply). The authored markup with
+            // every fill stays available as `source`.
+            const slots = slotsInSurfaces(post.surfaces);
+            const raw = html && html.kind === "html" ? html.html : "";
+            const composed = slots.length ? composeFills(raw, chosenFills(slots, settled)) : raw;
             entries.push({
                 state,
                 variant: post.variant,
                 postId: post.id,
                 version: post.version,
+                // The agent's newer versions wait until the user puts one in use.
+                ...(found.version !== post.version ? { latest: found.version } : {}),
                 status: post.status,
-                html: html && html.kind === "html" ? html.html : "",
+                html: composed,
+                ...(slots.length ? { source: raw } : {}),
                 markdown: postToMarkdown(post, {
                     postUrl: `${ctx.base}/s/${post.id}`,
                     assetBase: ctx.base,
                 }),
                 history: [
-                    ...[...post.history]
+                    ...[...found.history]
+                        .filter((h) => !(found.hiddenVersions ?? []).includes(h.version))
                         .sort((a, b) => a.version - b.version)
                         .map((h) => ({
                         version: h.version,
@@ -1184,10 +1544,10 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                         prompt: h.prompt ?? "",
                     })),
                     {
-                        version: post.version,
-                        at: post.updatedAt,
-                        from: post.from ?? null,
-                        prompt: post.prompt ?? "",
+                        version: found.version,
+                        at: found.updatedAt,
+                        from: found.from ?? null,
+                        prompt: found.prompt ?? "",
                     },
                 ],
                 screenshotUrl: screenshots ? `${ctx.base}/s/${post.id}.png?v=${post.version}` : null,
@@ -1198,7 +1558,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                 variants: posts.map(variantLabel),
             });
         }
-        const replies = (await store.listComments({ mockId: mock.id })).filter((c) => c.kind === "reply");
+        const decisions = lastReply ? decisionsFor(mock, posts, lastReply) : null;
         return ok({
             project: mock.project,
             mock: mock.slug,
@@ -1206,7 +1566,9 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             kind: mock.kind,
             states: entries,
             knobs: mock.knobs,
-            reply: replies[replies.length - 1]?.payload ?? null,
+            settled,
+            reply: lastReply,
+            ...(decisions ? { decisions } : {}),
         });
     }
     // --- asks ---
@@ -1262,12 +1624,25 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                     return checked.error;
                 set = checked.value;
             }
+            if (opt.version !== undefined) {
+                const pinned = versionOption(opt.version, label, variant, { scope, state }, mock, posts);
+                if (typeof pinned === "string")
+                    return pinned;
+                options.push({ id, label, ...pinned, ...(set ? { set } : {}) });
+                continue;
+            }
             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}`;
+        const after = raw.after === undefined ? undefined : str(raw.after, 64);
+        if (raw.after !== undefined) {
+            if (!after || after === id || !taken.has(after)) {
+                return `ask "${text}": after must name an earlier ask's id (asked before it or earlier in this call)`;
+            }
+        }
         return {
             id,
             text,
@@ -1276,9 +1651,49 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             ...(part ? { part } : {}),
             options,
             ...(raw.multi === true ? { multi: true } : {}),
+            ...(after ? { after } : {}),
             at: new Date().toISOString(),
         };
     }
+    // A version option names one visible version of one variant in the ask's
+    // state (`optionState`); the variant may be left out when that state has
+    // only one, or one accepted.
+    function versionOption(raw, label, variant, ask, mock, posts) {
+        const version = Number(raw);
+        if (!Number.isInteger(version) || version < 1) {
+            return `option "${label}": version must be a positive integer`;
+        }
+        if (ask.scope === "part") {
+            return `option "${label}" names a version, which puts it in use: ask with scope "state" or "mock", not "part"`;
+        }
+        if (ask.state === undefined && mock.states.length > 1) {
+            return `option "${label}" names a version: give the ask a state (${mock.slug} has ${mock.states.map((x) => `"${x}"`).join(", ")})`;
+        }
+        const state = optionState(ask, mock);
+        const inState = posts.filter((p) => p.state === state);
+        const accepted = inState.filter((p) => p.status === "accepted");
+        const post = variant
+            ? inState.find((p) => p.variant === variant)
+            : inState.length === 1
+                ? inState[0]
+                : accepted.length === 1
+                    ? accepted[0]
+                    : undefined;
+        const where = state === null ? mock.slug : `"${state}"`;
+        if (!post) {
+            return variant
+                ? `option "${label}" names variant "${variant}", which ${where} does not have`
+                : `option "${label}" names version ${version} but ${where} has several variants (${inState.map((p) => p.variant).join(", ")}): name one`;
+        }
+        const hidden = new Set(post.hiddenVersions ?? []);
+        const visible = [post.version, ...post.history.map((h) => h.version)]
+            .filter((v) => !hidden.has(v))
+            .sort((a, b) => a - b);
+        if (!visible.includes(version)) {
+            return `option "${label}" names ${post.variant} v${version}${hidden.has(version) ? ", which is hidden" : ""}; ${post.variant} has ${visible.map((v) => `v${v}`).join(", ")}`;
+        }
+        return { variant: post.variant, version };
+    }
     // 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) {
@@ -1297,11 +1712,18 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         const asks = [...mock.asks];
         const taken = new Set(asks.map((a) => a.id));
         const added = [];
+        const skipped = [];
         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);
+            // The user closed this one as not worth answering; asking it again is
+            // exactly the noise they resolved away. Only their Reopen revives it.
+            if (at >= 0 && asks[at].dismissed) {
+                skipped.push(ask.id);
+                continue;
+            }
             if (at >= 0)
                 asks[at] = ask;
             else
@@ -1309,11 +1731,31 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             taken.add(ask.id);
             added.push(ask);
         }
+        const skippedNudges = skipped.map((id) => `ask "${id}": the user dismissed it when they resolved ${mock.slug}; not asked again. Don't re-ask it.`);
+        if (!added.length) {
+            return ok({
+                mock: mock.slug,
+                mockId: mock.id,
+                project: mock.project,
+                asks: [],
+                skipped,
+                open: openCount(mock, posts),
+                url: mockUrl(ctx.base, mock),
+                nudges: skippedNudges,
+                feedback: mock.sessionId ? await collectFeedback(mock.sessionId, ctx.base) : [],
+            });
+        }
         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 });
+        // A new question on a resolved mock brings it back to the open list, or it
+        // would wait where the user no longer looks.
+        const updated = await store.updateMock(mock.id, {
+            asks,
+            sessionId,
+            ...(mock.resolvedAt ? { resolvedAt: null } : {}),
+        });
         if (!updated)
             return fail(404, "mock not found");
         mock = updated;
@@ -1341,12 +1783,13 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             url: mockUrl(ctx.base, mock),
         });
         const feedback = session ? await collectFeedback(session.id, ctx.base) : [];
-        const nudges = askNudges(added, mock.asks);
+        const nudges = [...skippedNudges, ...askNudges(added, mock.asks)];
         return ok({
             mock: mock.slug,
             mockId: mock.id,
             project: mock.project,
             asks: added,
+            ...(skipped.length ? { skipped } : {}),
             open: openCount(mock, posts),
             url: mockUrl(ctx.base, mock),
             ...(nudges.length ? { nudges } : {}),
@@ -1619,18 +2062,30 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     // 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();
+    // variant asks flip the same way, per state. Each accepted variant is put in
+    // use at the version the reply was made on (`version`, a mock version), not
+    // whatever the agent published since — or, for a version option, at its version.
+    function replyFlips(mock, posts, answers, decision, version) {
+        const accept = new Map();
         const archive = new Set();
-        const settle = (inState, chosen) => {
+        const drop = new Set();
+        const settle = (inState, chosen, pins) => {
             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);
+                if (!chosen.has(p.variant)) {
+                    if (isLive(p.status))
+                        archive.add(p.id);
+                    continue;
+                }
+                const pin = pins?.get(p.variant);
+                // A version option outranks a looser pick of the same variant (the
+                // built-in Which one?, a Look) in the same reply.
+                if (pin === undefined && accept.has(p.id))
+                    continue;
+                // A pinned version history retention has since dropped falls back to
+                // what the stage showed, rather than pinning one nothing can render.
+                accept.set(p.id, pin !== undefined && postAtVersion(p, pin) ? pin : versionAt(p, version));
             }
         };
         const builtins = Object.keys(answers)
@@ -1641,7 +2096,13 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             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));
+            const picked = ask.options.filter((o) => ids.includes(o.id) && o.variant);
+            const pinned = picked.filter((o) => o.version !== undefined);
+            if (pinned.length) {
+                const state = optionState(ask, mock);
+                settle(posts.filter((p) => p.state === state), new Set(pinned.map((o) => o.variant)), new Map(pinned.map((o) => [o.variant, o.version])));
+            }
+            const chosen = new Set(picked.filter((o) => o.version === undefined).map((o) => o.variant));
             if (chosen.size === 0)
                 continue;
             const states = ask.scope === "state" ? [ask.state ?? null] : mock.states.length ? mock.states : [null];
@@ -1654,11 +2115,15 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         else if (decision?.kind === "drop") {
             const post = posts.find((p) => p.state === decision.state && p.variant === decision.variant);
             if (post)
-                archive.add(post.id);
+                drop.add(post.id);
+        }
+        for (const id of accept.keys()) {
+            archive.delete(id);
+            drop.delete(id);
         }
-        for (const id of accept)
+        for (const id of drop)
             archive.delete(id);
-        return { accept, archive };
+        return { accept, archive, drop };
     }
     // 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.
@@ -1669,6 +2134,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         if (answer === undefined && other === undefined && note === undefined)
             return a;
         const next = { ...a };
+        delete next.dismissed;
         if (answer !== undefined || other !== undefined) {
             delete next.answer;
             delete next.other;
@@ -1733,27 +2199,33 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             ...(draft.otherImages ? { otherImages: draft.otherImages } : {}),
             ...(draft.noteImages ? { noteImages: draft.noteImages } : {}),
             ...(text ? { text } : {}),
-            ...(decision ? { decision } : {}),
         };
         const asks = mock.asks.map((a) => sentAsk(a, draft));
-        const flips = replyFlips(mock, posts, draft.answers, decision);
+        const flips = replyFlips(mock, posts, draft.answers, decision, draft.version);
+        if (decision) {
+            const target = posts.find((p) => p.state === decision.state && p.variant === decision.variant);
+            const pinned = decision.kind === "accept" && target ? flips.accept.get(target.id) : undefined;
+            payload.decision = pinned === undefined ? decision : { ...decision, version: pinned };
+        }
         const comment = await store.commitReply({
             mockId: mock.id,
             sessionId,
             text: text ?? "",
             payload,
             asks,
-            accept: [...flips.accept],
+            accept: [...flips.accept].map(([id, version]) => ({ id, version })),
             archive: [...flips.archive],
+            drop: [...flips.drop],
         });
         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 });
+        void announceEmbedders(mock).catch((err) => console.warn("[mockpit] embedders", err));
         const after = await store.listPosts({ mockId: mock.id });
         for (const p of after) {
-            if (flips.accept.has(p.id) || flips.archive.has(p.id)) {
+            if (flips.accept.has(p.id) || flips.archive.has(p.id) || flips.drop.has(p.id)) {
                 bus.broadcast({
                     type: "post-updated",
                     id: p.id,
@@ -1778,12 +2250,216 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             reply: delivered,
             accepted: after
                 .filter((p) => flips.accept.has(p.id))
-                .map((p) => ({ state: p.state, variant: p.variant })),
+                .map((p) => ({ state: p.state, variant: p.variant, version: inUseVersion(p) })),
             archived: after
                 .filter((p) => flips.archive.has(p.id))
                 .map((p) => ({ state: p.state, variant: p.variant })),
+            dropped: after
+                .filter((p) => flips.drop.has(p.id))
+                .map((p) => ({ state: p.state, variant: p.variant })),
+        }, 201);
+    }
+    // "Use this": the user puts one exact version of a variant in use. It is an
+    // accept, so it archives the variant's live siblings in that state and
+    // reaches the agent once, as a reply carrying the decision, through the same
+    // cursor as a Send; the user's unsent draft is left for their next Send.
+    async function useFlow(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 chosen = chooseVariant(mock, posts, stateArg(body?.state), str(body?.variant, MAX_LABEL));
+        if (isResult(chosen))
+            return chosen;
+        const version = Number(body?.version);
+        if (!Number.isInteger(version) || version < 1) {
+            return fail(400, '"version" must be a positive integer');
+        }
+        if (!postAtVersion(chosen, version)) {
+            return fail(404, `${chosen.variant} has no version ${version}`, {
+                versions: [chosen.version, ...chosen.history.map((h) => h.version)],
+            });
+        }
+        const inUse = { state: chosen.state, variant: chosen.variant, version };
+        if (chosen.status === "accepted" && chosen.acceptedVersion === version) {
+            return ok({ reply: null, inUse, archived: [] });
+        }
+        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 archive = posts.filter((p) => p.state === chosen.state && p.id !== chosen.id && isLive(p.status));
+        const comment = await store.commitReply({
+            mockId: mock.id,
+            sessionId,
+            text: "",
+            payload: {
+                mockId: mock.id,
+                version,
+                answers: {},
+                mix: {},
+                tuned: {},
+                comments: [],
+                decision: { kind: "accept", ...inUse },
+            },
+            asks: mock.asks,
+            accept: [{ id: chosen.id, version }],
+            archive: archive.map((p) => p.id),
+            keepDraft: true,
+        });
+        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 });
+        void announceEmbedders(mock).catch((err) => console.warn("[mockpit] embedders", err));
+        for (const p of [chosen, ...archive]) {
+            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: chosen.variant,
+            version,
+            text: "accept",
+            url: mockUrl(ctx.base, mock),
+        });
+        const [delivered] = await withDelivered([comment]);
+        return ok({
+            reply: delivered,
+            inUse,
+            archived: archive.map((p) => ({ state: p.state, variant: p.variant })),
         }, 201);
     }
+    // The user hides one version of a variant from the history, or brings it
+    // back. Hidden, never removed: replies and embeds may point at it, so it still
+    // renders by URL. The version in use can't be hidden, nor a state's last.
+    async function hideFlow(ref, body, ctx) {
+        if (!ctx.viewer)
+            return viewerOnly();
+        const mock = await resolveMock(ref);
+        if (isResult(mock))
+            return mock;
+        if (typeof body?.hidden !== "boolean")
+            return fail(400, '"hidden" must be true or false');
+        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 version = Number(body?.version);
+        if (!Number.isInteger(version) || version < 1) {
+            return fail(400, '"version" must be a positive integer');
+        }
+        if (!postAtVersion(chosen, version)) {
+            return fail(404, `${chosen.variant} has no version ${version}`);
+        }
+        if (body.hidden) {
+            if (chosen.status === "accepted" && inUseVersion(chosen) === version) {
+                return fail(409, `v${version} of ${chosen.variant} is in use; use another version first`);
+            }
+            const visible = posts
+                .filter((p) => p.state === chosen.state)
+                .flatMap((p) => [p.version, ...p.history.map((h) => h.version)].map((v) => [p, v]))
+                .filter(([p, v]) => !(p.hiddenVersions ?? []).includes(v));
+            if (visible.length === 1 && visible[0][0].id === chosen.id && visible[0][1] === version) {
+                return fail(409, "the last visible version can't be hidden");
+            }
+        }
+        const updated = await store.setVersionHidden(chosen.id, version, body.hidden);
+        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,
+            version,
+            hidden: body.hidden,
+        });
+    }
+    // The user closes a mock from the project list: its open asks are dismissed
+    // unanswered, an unsent draft goes with them, and the agent hears it once,
+    // as a resolution through the same cursor as a Send.
+    async function resolveFlow(ref, ctx) {
+        if (!ctx.viewer)
+            return viewerOnly();
+        const mock = await resolveMock(ref);
+        if (isResult(mock))
+            return mock;
+        const posts = await store.listPosts({ mockId: mock.id });
+        if (mock.resolvedAt)
+            return ok({ mock: mockSummaryView(mock, posts), dismissed: [] });
+        const dismissed = [...openAsks(mock).map((a) => a.id), ...builtinAskIds(mock, posts, mock.id)];
+        const asks = mock.asks.map((a) => (askAnswered(a) ? a : { ...a, dismissed: true }));
+        const at = new Date().toISOString();
+        const latest = [...posts].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))[0];
+        const sessionId = mock.sessionId ?? latest?.sessionId;
+        const session = sessionId ? await store.getSession(sessionId) : null;
+        const comment = session
+            ? await store.commitReply({
+                mockId: mock.id,
+                sessionId: session.id,
+                text: "",
+                payload: {
+                    mockId: mock.id,
+                    version: Math.max(1, ...posts.map((p) => p.version)),
+                    answers: {},
+                    mix: {},
+                    tuned: {},
+                    comments: [],
+                    resolved: { dismissed },
+                },
+                asks,
+                accept: [],
+                archive: [],
+                resolvedAt: at,
+            })
+            : null;
+        if (comment)
+            announceComment(comment);
+        else {
+            // No agent to tell: the mock still leaves the open list.
+            await store.updateMock(mock.id, { asks, resolvedAt: at });
+            await store.putDraft(mock.id, null);
+        }
+        bus.broadcast({ type: "mock-updated", id: mock.id, project: mock.project });
+        bus.broadcast({ type: "draft-updated", mockId: mock.id });
+        const after = (await store.getMock(mock.id)) ?? mock;
+        return ok({ mock: mockSummaryView(after, posts), dismissed });
+    }
+    // Back from Resolved: the asks it dismissed are open again. The agent was
+    // told they were dismissed; answers given now reach it as a normal Send.
+    async function reopenFlow(ref, ctx) {
+        if (!ctx.viewer)
+            return viewerOnly();
+        const mock = await resolveMock(ref);
+        if (isResult(mock))
+            return mock;
+        const posts = await store.listPosts({ mockId: mock.id });
+        if (!mock.resolvedAt)
+            return ok({ mock: mockSummaryView(mock, posts) });
+        const asks = mock.asks.map(({ dismissed: _, ...a }) => a);
+        const updated = await store.updateMock(mock.id, { asks, resolvedAt: null });
+        if (!updated)
+            return fail(404, "mock not found");
+        bus.broadcast({ type: "mock-updated", id: mock.id, project: mock.project });
+        return ok({ mock: mockSummaryView(updated, posts) });
+    }
     async function restoreFlow(ref, body) {
         const mock = await resolveMock(ref, body?.project);
         if (isResult(mock))
@@ -1805,6 +2481,34 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         });
         return ok({ state: updated.state, variant: updated.variant, status: updated.status });
     }
+    // The user stars (or unstars) a variant: a favourite to come back to, which
+    // decides nothing. Viewer-only; the agent reads it as `starred`.
+    async function starFlow(ref, body, ctx) {
+        if (!ctx.viewer)
+            return viewerOnly();
+        const mock = await resolveMock(ref);
+        if (isResult(mock))
+            return mock;
+        if (typeof body?.starred !== "boolean")
+            return fail(400, '"starred" must be true or false');
+        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.setPostStarred(chosen.id, body.starred);
+        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",
+        });
+        bus.broadcast({ type: "mock-updated", id: mock.id, project: mock.project });
+        return ok({ state: updated.state, variant: updated.variant, starred: !!updated.starred });
+    }
     // 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.
@@ -2178,6 +2882,8 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     // tells the agent something ("2 of 3 answered", or nobody is looking).
     const pendingOf = (mock, posts) => ({
         mock: mock.slug,
+        // Closed by the user: nothing there is waiting on them, or on you.
+        ...(mock.resolvedAt ? { resolved: true } : {}),
         viewerOpen: viewing.has(mock.id),
         draft: mock.draft
             ? {
@@ -2336,7 +3042,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         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 withOrigin = (text, c) => text.replaceAll(LOCAL_ORIGIN, requestOrigin(c.req.raw));
     const injectHead = (text, head) => {
         const headClose = text.lastIndexOf("</head>");
         return headClose >= 0
@@ -2365,6 +3071,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                 ? `window.__MOCKPIT_PUBLIC_READ__=${JSON.stringify(publicRead)};`
                 : "",
             screenshots ? "window.__MOCKPIT_SCREENSHOTS__=true;" : "",
+            renderRev ? `window.__MOCKPIT_RENDER_REV__=${JSON.stringify(renderRev)};` : "",
         ].join("");
         return injectHead(text, `<script>${config}</script>`);
     };
@@ -2388,7 +3095,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     // 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 origin = requestOrigin(request);
         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`);
@@ -2423,7 +3130,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         // 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 = withAppHead(c.req.raw, await workspaceMode())(withDocumentTitle(withViewerConfig(withOrigin(viewerHtml, { req: { url: c.req.url } }), c.req.raw, !!publicRead && !isAuthenticated(c), opts.title), opts.title));
+        const html = withAppHead(c.req.raw, await workspaceMode())(withDocumentTitle(withViewerConfig(withOrigin(viewerHtml, c), c.req.raw, !!publicRead && !isAuthenticated(c), opts.title), opts.title));
         if (!opts.preview)
             return html;
         const { mock, post } = opts.preview;
@@ -2467,7 +3174,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         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];
+        const post = posts.find((p) => isLive(p.status)) ?? posts[0];
         return c.html(await configuredViewerHtml(c, {
             title: mock.title,
             ...(post ? { preview: { mock, post } } : {}),
@@ -2475,10 +3182,10 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     });
     // --- 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",
+        base: `${requestOrigin(c.req.raw)}${requestBasePath(c.req.raw)}`,
+        // Only the trusted viewer may act as the user (drafts, replies,
+        // user-authored comments); server/viewerRequest.ts says how it is known.
+        viewer: isViewerRequest(c.req.raw),
         strict,
         request: c.req.raw,
         signal: c.req.raw.signal,
@@ -2579,6 +3286,11 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     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/use", async (c) => send(c, await useFlow(c.req.param("id"), await jsonBody(c), flowCtx(c))));
+    app.post("/api/mocks/:id/hide", async (c) => send(c, await hideFlow(c.req.param("id"), await jsonBody(c), flowCtx(c))));
+    app.post("/api/mocks/:id/resolve", async (c) => send(c, await resolveFlow(c.req.param("id"), flowCtx(c))));
+    app.post("/api/mocks/:id/reopen", async (c) => send(c, await reopenFlow(c.req.param("id"), flowCtx(c))));
+    app.post("/api/mocks/:id/star", async (c) => send(c, await starFlow(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), flowCtx(c))));
@@ -2708,6 +3420,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     });
     // 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/tree", async (c) => send(c, await treeFlow({ project: c.req.param("name") })));
     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);
@@ -2986,7 +3699,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     // 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 ?? ""}`;
+    const renderKey = (o) => `${o.postId}:${o.idx}:${o.version}:${o.mode ?? "os"}:${o.origin}:${o.knobs ?? ""}:${o.embeds ?? ""}`;
     // 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) {
@@ -2994,12 +3707,10 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         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;
+            // Embedded components are expanded server-side (the caller passes the
+            // expansion), so the whole page is still ONE sandboxed document rather
+            // than nested frames.
+            const html = args.composed ?? surface.html;
             return renderHtmlPage({
                 title: args.title,
                 html,
@@ -3062,8 +3773,18 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                 if (!isSandboxedSurfaceKind(surface.kind))
                     continue;
                 warmed++;
+                const composed = surface.kind === "html" && hasEmbedTags(surface.html)
+                    ? await composedHtml(mock.project, mock.slug, surface.html)
+                    : null;
                 for (const mode of ["light", "dark"]) {
-                    const key = renderKey({ postId: post.id, idx, version: post.version, mode, origin });
+                    const key = renderKey({
+                        postId: post.id,
+                        idx,
+                        version: post.version,
+                        mode,
+                        origin,
+                        embeds: composed ? embedsKey(composed) : undefined,
+                    });
                     if (renderCache.has(key))
                         continue;
                     await cachedRender(key, () => buildSurfaceDoc({
@@ -3075,6 +3796,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                         mode,
                         origin,
                         design,
+                        composed: composed?.html,
                     }));
                 }
             }
@@ -3088,7 +3810,11 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         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;
+        // `e`: the embeds key the caller saw (cache identity); `embed`: a peek at
+        // older component versions, JSON {slug: version}.
+        const eParam = c.req.query("e");
+        const embedParam = c.req.query("embed");
+        const origin = requestOrigin(c.req.raw);
         // 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
@@ -3096,13 +3822,16 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         // 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) {
+        // A document with embeds is stored only under the key its resolved embeds
+        // give, so a hit here was rendered with exactly the `e` this URL names.
+        if (Number.isInteger(pinned) && pinned > 0 && kParam === undefined && !embedParam) {
             const hit = renderCacheHit(renderKey({
                 postId: c.req.param("id"),
                 idx: Number(surfaceParam),
                 version: pinned,
                 mode,
                 origin,
+                embeds: eParam,
             }));
             if (hit !== undefined) {
                 surfaceDocHeaders(c, true);
@@ -3158,16 +3887,59 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                 knobsKey = JSON.stringify(knobs);
             }
         }
+        let composed = null;
+        if (surface.kind === "html" && hasEmbedTags(surface.html) && mock) {
+            let overrides;
+            if (embedParam !== undefined) {
+                let raw;
+                try {
+                    raw = JSON.parse(embedParam);
+                }
+                catch {
+                    raw = null;
+                }
+                const ok = raw !== null &&
+                    typeof raw === "object" &&
+                    !Array.isArray(raw) &&
+                    Object.values(raw).every((v) => Number.isInteger(v) && v > 0);
+                if (!ok || embedParam.length > MAX_KNOB_QUERY) {
+                    surfaceDocHeaders(c, false);
+                    return c.text("embed must be URL-encoded JSON of {slug: version}", 400);
+                }
+                overrides = raw;
+            }
+            composed = await composedHtml(mock.project, mock.slug, surface.html, overrides);
+        }
+        const eKey = composed ? embedsKey(composed) : undefined;
         // 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);
+        // param), so a version-pinned document never changes, unless it follows a
+        // component's latest version and the URL does not name that state (`e`).
+        surfaceDocHeaders(c, ver != null && (eKey === undefined || eKey === eParam));
         // 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 });
+        // resolved `version` and embeds key make it immutable, so a hit is always
+        // correct.
+        const cacheKey = renderKey({
+            postId: post.id,
+            idx,
+            version,
+            mode,
+            origin,
+            knobs: knobsKey,
+            embeds: eKey,
+        });
         const design = mock ? await designFor(mock.project) : null;
-        const doc = await cachedRender(cacheKey, async () => buildSurfaceDoc({ post, mock, surface, title, version, mode, origin, design, knobs }));
+        const doc = await cachedRender(cacheKey, async () => buildSurfaceDoc({
+            post,
+            mock,
+            surface,
+            title,
+            version,
+            mode,
+            origin,
+            design,
+            knobs,
+            composed: composed?.html,
+        }));
         return c.html(doc);
     };
     app.get("/s/:id", renderPostPage);
@@ -3228,7 +4000,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         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 origin = requestOrigin(c.req.raw);
         const publicBasePath = requestBasePath(c.req.raw);
         const assetPath = encodeURIComponent(result.asset.id);
         return c.json({ ...result.asset, url: `${origin}${publicBasePath}/a/${assetPath}` }, 201);
@@ -3382,6 +4154,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     const mcpFlows = {
         publish: (body, ctx) => publishFlow(body, ctx),
         list: (query) => listMocksFlow(query),
+        tree: (query) => treeFlow(query),
         get: (ref, query) => getMockFlow(ref, query),
         ask: (ref, body, ctx) => askFlow(ref, body, ctx),
         exportMock: (ref, query, ctx) => exportFlow(ref, query, ctx),