mockpit 1.1.0 → 1.3.0

package/dist/server/app.js

@@ -2,26 +2,33 @@ import { Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
 import { getCookie, setCookie } from "hono/cookie";
 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";
 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 { 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 { 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.
@@ -161,13 +168,25 @@ 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;
+const APP_FILES = new Set([
+    "/manifest.webmanifest",
+    "/icon.svg",
+    "/apple-touch-icon.png",
+    ...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)
@@ -185,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();
     });
@@ -275,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);
@@ -319,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.
@@ -331,31 +364,93 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         return value;
     }
     // --- shared flows (used by both the REST API and the MCP endpoint) ---
+    // Sessions with an author=user long-poll held open right now: a waiting
+    // `mockpit watch` is a live agent, whatever its agentActiveAt says.
+    const listening = new Map();
     // 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) {
+    async function collectFeedback(sessionId, base) {
+        // Touch before reading the cursor: a taker's handOff checks agentActiveAt,
+        // so it can't move this cursor under a read already in flight.
+        await store.touchAgent(sessionId);
         const session = await store.getSession(sessionId);
         if (!session)
             return [];
+        const handedOff = await takeOrphaned(session);
         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 });
+        if (fresh.length > 0) {
+            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) : [];
+        return feedbackWithHandoffs(feedback, handedOff, base);
+    }
+    async function feedbackWithHandoffs(own, handedOff, base) {
+        const mine = own.length > 0 ? await buildFeedbackBatches(store, own, base) : [];
+        if (handedOff.length === 0)
+            return mine;
+        const theirs = await buildFeedbackBatches(store, handedOff, base);
+        return [...mine, ...theirs.map((b) => ({ ...b, handoff: HANDOFF_NOTE }))];
+    }
+    // The user comments still owed to sessions `taker` supersedes (handoff.ts),
+    // taken for `taker`: each owner's cursor moves past them in one conditional
+    // write, so delivery stays exactly-once across sessions.
+    async function takeOrphaned(taker) {
+        if (!taker.project)
+            return [];
+        const now = Date.now();
+        const taken = [];
+        for (const owner of await store.listSessions(taker.project)) {
+            if (!supersedes(taker, owner, listening.has(owner.id)))
+                continue;
+            const owed = await store.listComments({ sessionId: owner.id, afterSeq: owner.agentSeq });
+            // Seq order is time order, so the ready comments are a prefix; stop at the
+            // first one still inside its grace and leave the rest owed.
+            let upto = owner.agentSeq;
+            const take = [];
+            for (const c of owed) {
+                if (c.author === "user" && !handoffReady(c, owner, taker, now))
+                    break;
+                upto = c.seq;
+                if (c.author === "user")
+                    take.push(c);
+            }
+            if (take.length === 0)
+                continue;
+            if (!(await store.handOff(owner.id, owner, upto)))
+                continue;
+            bus.broadcast({ type: "comment-delivered", sessionId: owner.id, seq: upto });
+            taken.push(...take);
+        }
+        return taken;
     }
     // Per-comment delivery state for the viewer: `delivered` once the session's
-    // agentSeq has passed the comment. Computed, never stored.
+    // agentSeq has passed the comment. Computed, never stored. `ownerGone` marks
+    // an undelivered user comment whose session a newer one already supersedes,
+    // so the Thread can say the next agent here will get it.
     async function withDelivered(comments) {
-        const cursors = new Map();
+        const sessions = new Map();
         for (const c of comments) {
-            if (!cursors.has(c.sessionId)) {
-                cursors.set(c.sessionId, (await store.getSession(c.sessionId))?.agentSeq ?? 0);
+            if (!sessions.has(c.sessionId))
+                sessions.set(c.sessionId, await store.getSession(c.sessionId));
+        }
+        const gone = new Map();
+        const ownerGone = async (owner) => {
+            if (!gone.has(owner.id)) {
+                const peers = owner.project ? await store.listSessions(owner.project) : [];
+                gone.set(owner.id, peers.some((t) => supersedes(t, owner, listening.has(owner.id))));
             }
+            return gone.get(owner.id);
+        };
+        const out = [];
+        for (const c of comments) {
+            const owner = sessions.get(c.sessionId);
+            const delivered = c.seq <= (owner?.agentSeq ?? 0);
+            const waiting = !delivered && !!owner && c.author === "user" && (await ownerGone(owner));
+            out.push({ ...c, delivered, ...(waiting ? { ownerGone: true } : {}) });
         }
-        return comments.map((c) => ({ ...c, delivered: c.seq <= (cursors.get(c.sessionId) ?? 0) }));
+        return out;
     }
     // 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.
@@ -516,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"}`, {
@@ -611,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.
@@ -669,8 +833,8 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         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`);
+            if (n !== null && n >= 2 && n <= 3) {
+                out.push(`knob "${path}": a 2–3 option knob is a choice. Ask with options that \`set\` it.`);
             }
         }
         return out;
@@ -680,50 +844,102 @@ 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;
+        const applies = (a) => a.scope !== "part" && !(a.scope === "state" && a.state !== state);
         const bound = mock.asks.some((a) => {
-            if (a.scope === "part" || (a.scope === "state" && a.state !== state))
+            if (!applies(a))
                 return false;
             const variants = new Set(a.options.map((o) => o.variant));
             return names.every((n) => variants.has(n));
         });
         if (bound)
             return null;
+        const where = state === null ? mock.slug : `${mock.slug} state "${state}"`;
         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));
+        // An ask that already picks between some of these variants is the question:
+        // a second, generic "Which one?" would make the user choose the look twice.
+        // A mock-wide one only fits while every state has the same variants; else a
+        // variant only some states have would leave the others no real choice.
+        const existing = mock.asks.find((a) => applies(a) && a.options.some((o) => o.variant) && (a.scope === "state" || wide));
+        if (existing) {
+            const have = new Set(existing.options.map((o) => o.variant));
+            const missing = names.filter((n) => !have.has(n));
+            const ask = {
+                id: existing.id,
+                text: existing.text,
+                scope: existing.scope,
+                ...(existing.state ? { state: existing.state } : {}),
+                ...(existing.multi ? { multi: true } : {}),
+                options: [
+                    ...existing.options.map((o) => ({
+                        id: o.id,
+                        label: o.label,
+                        ...(o.variant ? { variant: o.variant } : {}),
+                        ...(o.set ? { set: o.set } : {}),
+                    })),
+                    ...missing.map((v) => ({ label: v, variant: v })),
+                ],
+            };
+            return {
+                nudge: `${where}: bind ${missing.map((m) => `"${m}"`).join(", ")} to your existing ask "${existing.id}": call ask with suggestedAsk. Never ask in chat.`,
+                ask,
+            };
+        }
         const options = names.map((v) => ({ label: v, variant: v }));
+        // Not the built-in's reserved id: a stored ask under it would collide with the
+        // built-in the viewer synthesizes once a new variant goes unbound. Nor any id
+        // already taken, which sending this would silently replace.
+        const base = wide ? "look" : `look-${slugify(state ?? "")}`;
+        let id = base;
+        for (let n = 2; mock.asks.some((a) => a.id === id); n++)
+            id = `${base}-${n}`;
         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}"`;
+            ? { id, text: "Which one?", scope: "mock", options }
+            : { id, text: "Which one?", scope: "state", state, options };
         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`,
+            nudge: `${where} has ${names.length} variants and no ask binds them: call ask with suggestedAsk. 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.
+    // what moved since the previous version, and any feedback waiting — for the
+    // session that wrote, which on a new version may not be the variant's own.
     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] : [])];
+        // 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));
         }
         const warnings = await iconWarnings(mock.project, post.surfaces);
-        const feedback = await collectFeedback(post.sessionId);
+        const feedback = await collectFeedback(extra.writer?.id ?? post.sessionId, ctx.base);
         return ok({
             mock: {
                 id: mock.id,
@@ -744,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);
     }
@@ -764,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);
@@ -798,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")
@@ -832,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),
@@ -849,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)
@@ -861,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;
@@ -881,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) {
@@ -900,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,
@@ -912,59 +1209,176 @@ 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);
-        return writeResult(mock, updated, ctx, { previous: target.surfaces, applied, nudges });
+        return writeResult(mock, updated, ctx, {
+            previous: target.surfaces,
+            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.
@@ -976,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)
@@ -1006,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);
@@ -1027,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),
         });
@@ -1042,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,
@@ -1075,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,
@@ -1089,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,
@@ -1097,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 ---
@@ -1153,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,
@@ -1167,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) {
@@ -1188,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
@@ -1200,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;
@@ -1231,19 +1782,22 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             text: added.map((a) => a.text).join(" · "),
             url: mockUrl(ctx.base, mock),
         });
-        const feedback = session ? await collectFeedback(session.id) : [];
+        const feedback = session ? await collectFeedback(session.id, ctx.base) : [];
+        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 } : {}),
             feedback,
         });
     }
     // --- drafts and replies (the user's side; viewer origin only) ---
-    function sanitizePartComments(raw, mock) {
+    function sanitizePartComments(raw, mock, posts) {
         if (raw === undefined || raw === null)
             return [];
         if (!Array.isArray(raw))
@@ -1252,16 +1806,39 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             return `at most ${MAX_DRAFT_COMMENTS} comments`;
         const out = [];
         for (const c of raw) {
+            const reaction = c?.reaction;
+            if (reaction !== undefined && !REACTIONS.includes(reaction))
+                return `reaction must be one of ${REACTIONS.join(", ")}`;
             const text = str(c?.text, MAX_COMMENT_TEXT);
-            if (!text)
+            if (!text && !reaction)
                 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 variant = str(c.variant, 200);
+            if (variant && !posts.some((p) => p.variant === variant && p.state === state))
+                return `${mock.slug} has no variant "${variant}"${state ? ` in "${state}"` : ""}`;
             const a = c.anchor && typeof c.anchor === "object" ? c.anchor : null;
             const anchor = a ? sanitizePartAnchor(a) : undefined;
-            out.push({ part, state, text, ...(anchor ? { anchor } : {}) });
+            const next = {
+                part,
+                state,
+                text: text ?? "",
+                ...(anchor ? { anchor } : {}),
+                ...(reaction ? { reaction: reaction } : {}),
+                ...(variant ? { variant } : {}),
+            };
+            // One reaction per target: a later tap on the same part replaces the earlier one.
+            if (reaction) {
+                const same = out.findIndex((o) => o.reaction &&
+                    o.part === part &&
+                    o.state === state &&
+                    (o.variant ?? null) === (variant ?? null));
+                if (same >= 0)
+                    out.splice(same, 1);
+            }
+            out.push(next);
         }
         return out;
     }
@@ -1274,6 +1851,9 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             : undefined;
         const quote = str(a.quote, 200);
         const selector = str(a.selector, 500);
+        const width = typeof a.width === "number" && Number.isFinite(a.width) && a.width >= 1 && a.width <= 10000
+            ? Math.round(a.width)
+            : undefined;
         if (!offset && !box && !quote && !selector)
             return undefined;
         return {
@@ -1281,6 +1861,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             ...(quote ? { quote } : {}),
             ...(selector ? { selector } : {}),
             ...(box ? { box } : {}),
+            ...(width ? { width } : {}),
         };
     }
     // A stored ask, else the viewer's built-in variant ask under its reserved id.
@@ -1329,6 +1910,37 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         }
         return out;
     }
+    // askId → attached image ids: known asks, ids of stored raster images only,
+    // deduped and capped, empty lists dropped.
+    async function sanitizeAskImages(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 (!Array.isArray(value) || value.some((id) => typeof id !== "string")) {
+                return `${key} "${askId}" must be a list of asset ids`;
+            }
+            const ids = [...new Set(value)];
+            if (ids.length > MAX_ASK_IMAGES) {
+                return `${key} "${askId}" takes at most ${MAX_ASK_IMAGES} images`;
+            }
+            for (const id of ids) {
+                const asset = await store.getAsset(id);
+                if (!asset)
+                    return `asset "${id}" not found`;
+                if (!ATTACHABLE_IMAGE_TYPES.has(asset.contentType)) {
+                    return `asset "${id}" is not an attachable image`;
+                }
+            }
+            if (ids.length)
+                out[askId] = ids;
+        }
+        return out;
+    }
     function sanitizeMix(raw, posts) {
         if (raw === undefined || raw === null)
             return {};
@@ -1348,7 +1960,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     }
     // 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) {
+    async 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")
@@ -1359,7 +1971,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         const tuned = checkKnobValues(pick("tuned"), mock, posts, "tuned");
         if (!tuned.ok)
             return tuned.error;
-        const comments = sanitizePartComments(pick("comments"), mock);
+        const comments = sanitizePartComments(pick("comments"), mock, posts);
         if (typeof comments === "string")
             return comments;
         const others = sanitizeAskTexts(pick("others"), mock, posts, "others");
@@ -1368,6 +1980,16 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         const notes = sanitizeAskTexts(pick("notes"), mock, posts, "notes");
         if (typeof notes === "string")
             return notes;
+        const otherImages = await sanitizeAskImages(pick("otherImages"), mock, posts, "otherImages");
+        if (typeof otherImages === "string")
+            return otherImages;
+        const noteImages = await sanitizeAskImages(pick("noteImages"), mock, posts, "noteImages");
+        if (typeof noteImages === "string")
+            return noteImages;
+        for (const askId of Object.keys(otherImages))
+            others[askId] ??= "";
+        for (const askId of Object.keys(noteImages))
+            notes[askId] ??= "";
         for (const askId of Object.keys(others)) {
             const ask = askById(mock, posts, askId);
             if (!ask?.multi && answers[askId] !== undefined)
@@ -1385,6 +2007,8 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             comments,
             others,
             notes,
+            ...(Object.keys(otherImages).length ? { otherImages } : {}),
+            ...(Object.keys(noteImages).length ? { noteImages } : {}),
             updatedAt: new Date().toISOString(),
         };
     }
@@ -1406,7 +2030,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         if (isResult(mock))
             return mock;
         const posts = await store.listPosts({ mockId: mock.id });
-        const draft = sanitizeDraft(body, mock, posts, null);
+        const draft = await sanitizeDraft(body, mock, posts, null);
         if (typeof draft === "string")
             return fail(400, draft);
         await store.putDraft(mock.id, draft);
@@ -1438,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)
@@ -1460,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];
@@ -1473,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)
+        for (const id of accept.keys()) {
             archive.delete(id);
-        return { accept, archive };
+            drop.delete(id);
+        }
+        for (const id of drop)
+            archive.delete(id);
+        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.
@@ -1488,16 +2134,26 @@ 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;
+            delete next.otherImages;
             if (answer !== undefined)
                 next.answer = answer;
             if (other !== undefined)
                 next.other = other;
+            const images = draft.otherImages?.[a.id];
+            if (other !== undefined && images)
+                next.otherImages = images;
         }
-        if (note !== undefined)
+        if (note !== undefined) {
             next.note = note;
+            delete next.noteImages;
+            const images = draft.noteImages?.[a.id];
+            if (images)
+                next.noteImages = images;
+        }
         return next;
     }
     // Send: the user's one batched answer becomes one kind:"reply" comment on the
@@ -1510,7 +2166,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         if (isResult(mock))
             return mock;
         const posts = await store.listPosts({ mockId: mock.id });
-        const draft = sanitizeDraft(body ?? {}, mock, posts, mock.draft);
+        const draft = await sanitizeDraft(body ?? {}, mock, posts, mock.draft);
         if (typeof draft === "string")
             return fail(400, draft);
         const text = str(body?.text, MAX_COMMENT_TEXT);
@@ -1540,28 +2196,36 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             comments: draft.comments,
             ...(Object.keys(draft.others ?? {}).length ? { others: draft.others } : {}),
             ...(Object.keys(draft.notes ?? {}).length ? { notes: draft.notes } : {}),
+            ...(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,
@@ -1586,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))
@@ -1613,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.
@@ -1865,7 +2761,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     }
     // 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) {
+    async function sayFlow(ref, body, ctx) {
         if (!body || typeof body !== "object")
             return fail(400, "invalid JSON body");
         const text = typeof body.message === "string" ? str(body.message, MAX_COMMENT_TEXT) : undefined;
@@ -1889,10 +2785,15 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         if (!comment)
             return fail(404, "session not found");
         announceComment(comment);
-        return ok({ feedback: await collectFeedback(comment.sessionId) }, 201);
+        return ok({ feedback: await collectFeedback(comment.sessionId, ctx.base) }, 201);
     }
     // Long-poll: resolves as soon as a matching comment lands, or at timeout.
     async function waitForComments(q, signal) {
+        // The agent listening for its feedback: it is alive, and it may take
+        // replies owed to a session it superseded (handoff.ts).
+        const listener = q.agent && q.author === "user" ? q.sessionId : undefined;
+        if (listener)
+            await store.touchAgent(listener);
         // 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.
@@ -1900,12 +2801,19 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         if (afterSeq === undefined && q.author === "user" && q.sessionId) {
             afterSeq = (await store.getSession(q.sessionId))?.agentSeq;
         }
+        const takeOrphanedFor = async (id) => {
+            const taker = id ? await store.getSession(id) : null;
+            return taker ? await takeOrphaned(taker) : [];
+        };
+        let handedOff = await takeOrphanedFor(listener);
         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) {
+        if (comments.length === 0 && handedOff.length === 0 && wait > 0) {
+            if (listener)
+                listening.set(listener, (listening.get(listener) ?? 0) + 1);
             await new Promise((resolve) => {
                 const timer = setTimeout(done, wait * 1000);
                 const unsubscribe = bus.subscribe((event) => {
@@ -1934,10 +2842,20 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                     resolve();
                 }
             });
+            if (listener) {
+                const n = (listening.get(listener) ?? 1) - 1;
+                if (n > 0)
+                    listening.set(listener, n);
+                else
+                    listening.delete(listener);
+            }
             // 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 };
+                return { comments: [], lastSeq: afterSeq ?? 0, handedOff: [] };
+            if (listener)
+                await store.touchAgent(listener);
+            handedOff = await takeOrphanedFor(listener);
             all = await store.listComments(query);
             comments = matches(all);
         }
@@ -1950,13 +2868,13 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             await store.markAgentSeen(q.sessionId, lastSeq);
             bus.broadcast({ type: "comment-delivered", sessionId: q.sessionId, seq: lastSeq });
         }
-        return { comments, lastSeq };
+        return { comments, lastSeq, handedOff };
     }
     // 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);
+    async function listenFlow(q, base, signal) {
+        const { handedOff, ...result } = await waitForComments({ ...q, agent: true }, signal);
+        const feedback = await feedbackWithHandoffs(result.comments, handedOff, base);
         return ok({ ...result, feedback });
     }
     // What the user is doing right now, per mock: derived from the SSE registry
@@ -1964,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
             ? {
@@ -1976,14 +2896,14 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     });
     // 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) {
+    async function feedbackFlow(query, ctx) {
         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({
+        const { comments, handedOff } = await waitForComments({
             sessionId: session.id,
             author: "user",
             waitSeconds: 0,
@@ -1991,13 +2911,14 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         });
         const project = str(query.project, MAX_TITLE) ?? session.project ?? undefined;
         return ok({
-            feedback: await buildFeedbackBatches(store, comments),
+            feedback: await feedbackWithHandoffs(comments, handedOff, ctx.base),
             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).
+    // is auto-created so an upload can precede the first publish. An image the
+    // user attaches names its mock instead, and belongs to the session that mock
+    // replies to. 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 };
@@ -2005,6 +2926,19 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             return { error: `asset exceeds ${MAX_ASSET_BYTES} bytes`, status: 413 };
         }
         let sessionId = input.session;
+        if (input.mock !== undefined) {
+            if (!ATTACHABLE_IMAGE_TYPES.has(input.contentType)) {
+                return { error: "attach a png, jpeg, webp or gif image", status: 415 };
+            }
+            const mock = await store.getMock(input.mock);
+            if (!mock)
+                return { error: `mock "${input.mock}" not found`, status: 404 };
+            const posts = await store.listPosts({ mockId: mock.id });
+            const latest = [...posts].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))[0];
+            sessionId = mock.sessionId ?? latest?.sessionId;
+            if (!sessionId)
+                return { error: `${mock.slug} has no agent session`, status: 409 };
+        }
         if (sessionId && !(await store.getSession(sessionId))) {
             return { error: `session "${sessionId}" not found`, status: 404 };
         }
@@ -2062,6 +2996,11 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             return next();
         if (path.startsWith(STATIC_ASSET_PREFIX))
             return next();
+        // The installable-app files carry no workspace data, and a browser may
+        // fetch them without the cookie; the manifest adds the key only for a
+        // caller that already holds it.
+        if (APP_FILES.has(path))
+            return next();
         const key = c.req.query("key");
         if (key === authToken) {
             setCookie(c, "mockpit_key", authToken, {
@@ -2103,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
@@ -2132,15 +3071,31 @@ 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>`);
     };
+    // The tags that make the viewer installable to a home screen. `use-credentials`
+    // sends the cookie with the manifest fetch, which browsers otherwise omit.
+    const withAppHead = (request, mode) => (text) => {
+        const base = escapeHtml(requestBasePath(request));
+        return injectHead(text, [
+            `<link rel="manifest" href="${base}/manifest.webmanifest" crossorigin="use-credentials">`,
+            `<link rel="icon" href="${base}/icon.svg" type="image/svg+xml">`,
+            `<link rel="apple-touch-icon" href="${base}/apple-touch-icon.png">`,
+            `<meta name="theme-color" content="${themeColor(mode)}">`,
+            `<meta name="mobile-web-app-capable" content="yes">`,
+            `<meta name="apple-mobile-web-app-capable" content="yes">`,
+            `<meta name="apple-mobile-web-app-title" content="mockpit">`,
+            `<meta name="apple-mobile-web-app-status-bar-style" content="default">`,
+        ].join("\n"));
+    };
     // --- 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 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`);
@@ -2175,13 +3130,42 @@ 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 = 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;
         return injectHead(html, mockPreviewHead(mock, post, c.req.raw, await workspaceMode(), version ?? "dev"));
     };
     app.get("/", async (c) => c.html(await configuredViewerHtml(c)));
+    // --- the installable app: manifest and icons ---
+    app.get("/manifest.webmanifest", async (c) => {
+        // A tokened workspace bakes the key into start_url for a caller that holds
+        // it (the viewer links the manifest with credentials), so a home-screen
+        // launch, which may not share the browser's cookies, signs itself in.
+        const keyed = !!authToken && isAuthenticated(c);
+        const manifest = webManifest(await workspaceMode(), keyed ? `./?key=${encodeURIComponent(authToken)}` : "./");
+        c.header("Content-Type", "application/manifest+json; charset=utf-8");
+        c.header("X-Content-Type-Options", "nosniff");
+        c.header("Cache-Control", keyed ? "private, no-store" : "no-cache");
+        return c.body(JSON.stringify(manifest));
+    });
+    app.get("/icon.svg", (c) => {
+        c.header("Content-Type", "image/svg+xml");
+        // Our own art, but SVG is a document: opened top-level it runs at this origin.
+        c.header("Content-Security-Policy", "default-src 'none'; style-src 'unsafe-inline'; sandbox");
+        c.header("X-Content-Type-Options", "nosniff");
+        c.header("Cache-Control", "public, max-age=86400");
+        return c.body(ICON_SVG);
+    });
+    const iconPng = (size) => (c) => {
+        c.header("Content-Type", "image/png");
+        c.header("X-Content-Type-Options", "nosniff");
+        c.header("Cache-Control", "public, max-age=86400");
+        return c.body(decodeBase64(ICON_PNG_BASE64[size]).buffer);
+    };
+    for (const size of ICON_SIZES)
+        app.get(`/icon-${size}.png`, iconPng(size));
+    app.get("/apple-touch-icon.png", iconPng(180));
     // 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") })));
@@ -2190,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 } } : {}),
@@ -2198,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,
@@ -2229,8 +3213,11 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         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);
+        if (existing) {
+            // A resumed conversation is that agent back, not a new one superseding it.
+            await store.touchAgent(existing.id);
+            return c.json((await store.getSession(existing.id)) ?? existing, 200);
+        }
         const session = await store.createSession({
             agent: str(body.agent, MAX_TITLE) ?? "agent",
             title: str(body.title, MAX_TITLE),
@@ -2299,10 +3286,15 @@ 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))));
-    app.get("/api/feedback", async (c) => send(c, await feedbackFlow({ session: c.req.query("session"), project: c.req.query("project") })));
+    app.post("/api/mocks/:id/say", async (c) => send(c, await sayFlow(c.req.param("id"), await jsonBody(c), flowCtx(c))));
+    app.get("/api/feedback", async (c) => send(c, await feedbackFlow({ session: c.req.query("session"), project: c.req.query("project") }, flowCtx(c))));
     // --- comments ---
     app.post("/api/comments", async (c) => send(c, await commentFlow(await jsonBody(c), flowCtx(c))));
     app.delete("/api/comments/:id", async (c) => {
@@ -2367,8 +3359,8 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         query.agent = isAgentRead;
         const respond = async (signal) => {
             if (isAgentRead)
-                return send(c, await listenFlow(query, signal));
-            const result = await waitForComments(query, signal);
+                return send(c, await listenFlow(query, flowCtx(c).base, signal));
+            const { handedOff: _none, ...result } = await waitForComments(query, signal);
             return c.json({ ...result, comments: await withDelivered(result.comments) });
         };
         if (waitSeconds <= 0)
@@ -2428,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);
@@ -2706,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) {
@@ -2714,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,
@@ -2782,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({
@@ -2795,6 +3796,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                         mode,
                         origin,
                         design,
+                        composed: composed?.html,
                     }));
                 }
             }
@@ -2808,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
@@ -2816,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);
@@ -2878,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);
@@ -2935,15 +3987,20 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                     kind: isAssetKind(kindQ) ? kindQ : undefined,
                     session: c.req.query("session"),
                     agent: c.req.query("agent"),
+                    mock: c.req.query("mock"),
                 };
         }
         catch (err) {
             return c.json({ error: err instanceof Error ? err.message : "invalid upload" }, 400);
         }
+        // An attachment on a mock is the user's, so only the viewer may make one.
+        if (body.mock !== undefined && !flowCtx(c).viewer) {
+            return c.json({ error: "only the viewer can attach images to a mock" }, 403);
+        }
         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);
@@ -3097,11 +4154,12 @@ 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),
-        say: (ref, body) => sayFlow(ref, body),
-        feedback: (query) => feedbackFlow(query),
+        say: (ref, body, ctx) => sayFlow(ref, body, ctx),
+        feedback: (query, ctx) => feedbackFlow(query, ctx),
     };
     const guide = (project, topic) => topic ? (topics[topic] ?? "") : briefFor(project);
     // --- run: an agent script over the same flows (server/run.ts) ---