@erdemtuna/doc-review 0.10.0 → 0.11.0

package/lib/chrome-client.js

@@ -5,23 +5,27 @@
  * postMessage, because the artifact iframe lives on the other loopback
  * hostname: a separate origin that can never reach this page or its token.
  */
-import { tidyMiddle } from "./anchor-text.js";
-import { clearOwned, createCommentUi, migrateCommentUi, mutationIsCurrent, ownConfirmation, ownEdit, ownMenu, newestComments, pageUrl, reconcileCommentUi, replacePage, } from "./chrome-session.js";
+import { clearOwned, commentControlId as controlId, createCommentUi, migrateCommentUi, mutationIsCurrent, ownConfirmation, ownEdit, newestComments, pageUrl, reconcileCommentUi, replacePage, } from "./chrome-session.js";
 import { sanitizeClientRects, sanitizeClipRect, sanitizeRelation } from "./comment-target.js";
 import { externalHref } from "./editing.js";
 import { framePolicy } from "./frame-policy.js";
 import { createIcon } from "./icons.js";
-import { createComparisonView } from "./comparison-view.js";
-import { createExecutionControls } from "./execution-client.js";
+import { executionPresentation } from "./execution-client.js";
+import { createToolbarController } from "./toolbar-controller.js";
+import { createRecoveryController } from "./recovery-controller.js";
+import { createCommentsController } from "./comments-controller.js";
+import { createComposerDraft, createContextualController } from "./contextual-controller.js";
 import { alignedCardPosition, placeContextualSurface, visibleViewport } from "./positioning.js";
 import { normalizeReviewMode, reviewConfiguration } from "./review-mode.js";
-import { createCaptureRequests, captureError, sameRender, draftCount, excerpt, changeKind, pendingCaptureTarget, comparisonFreshness } from "./history-client.js";
-import { createCaptureCoordinator, createHistoryController, historyPresentation, requireCaptureSuccess } from "./history-coordinator.js";
+import { createCaptureRequests, captureError, sameRender, draftCount, pendingCaptureTarget } from "./history-client.js";
+import { createCaptureCoordinator, createHistoryController, requireCaptureSuccess } from "./history-coordinator.js";
 import { createReviewApi, decodePage } from "./chrome-api.js";
 import { createFrameHost } from "./frame-host.js";
 import { createFrameController } from "./frame-controller.js";
 import { createSaveController } from "./save-controller.js";
 import { createFeedbackController } from "./feedback-controller.js";
+import { createFeedbackPanelController, createNoteDraft } from "./feedback-panel-controller.js";
+import { createChangesController } from "./changes-controller.js";
 import { createReviewController } from "./review-controller.js";
 const $ = (id) => document.getElementById(id);
 const ARTIFACT_HOST = location.hostname === "127.0.0.1" ? "localhost" : "127.0.0.1";
@@ -57,6 +61,7 @@ const state = {
     token: document.body.dataset.token,
     page: null,
     compose: null,
+    composerDraft: createComposerDraft(),
     composeLifecycle: "closed",
     composePlacement: "hidden",
     target: null,
@@ -68,16 +73,21 @@ const state = {
     savePolicy: "writable",
     modeApplying: false,
     modeMenuOpen: false,
+    restoreModeFocus: false,
+    theme: "light",
     drawerOpen: false,
     agent: "idle",
     orphans: new Set(),
     pollCommand: "",
-    editsExpanded: false,
+    noteDraft: createNoteDraft(),
     others: [],
     scroll: { x: 0, y: 0 },
     comparing: false,
     executionPreference: null,
     ended: false,
+    reloadVisible: false,
+    reloadMessage: "",
+    reloadFailed: false,
 };
 const diagnostic = (event, detail = {}) => {
     console.info("[doc-review]", { event, ...detail });
@@ -95,13 +105,10 @@ function advancePageEpoch(reason) {
 function commentById(id) {
     return state.page?.comments?.find((comment) => comment.id === id) || null;
 }
-function domId(value) {
-    return String(value).replace(/[^a-zA-Z0-9_-]/g, (char) => `-${char.codePointAt(0).toString(16)}-`);
-}
-function controlId(commentId, surface, action) {
-    return `comment-${surface}-${domId(commentId)}-${action}`;
-}
 function requestControlFocus(id) {
+    if (state.drawerOpen && document.getElementById(id)?.closest("#cards")) {
+        commentsRuntime.commands.setSectionOpen(true);
+    }
     requestedFocus = id;
 }
 function editTextarea(commentId) {
@@ -126,7 +133,12 @@ function restoreTransientFocus(editWasFocused = false) {
     const shouldFocusEdit = editWasFocused || editFocusRequested;
     afterPaint(() => {
         if (focusId) {
-            document.getElementById(focusId)?.focus();
+            const target = document.getElementById(focusId);
+            if (target?.closest("[hidden], [inert]")) {
+                $(state.comparing ? "latestVersion" : state.drawerOpen ? "commentsSection" : "commentsButton").focus();
+            }
+            else
+                target?.focus();
             return;
         }
         const edit = state.commentUi.edit;
@@ -138,16 +150,14 @@ function restoreTransientFocus(editWasFocused = false) {
             return;
         }
         editFocusRequested = false;
+        // A mounted React editor already owns its live selection; delayed focus must not reset it.
+        if (document.activeElement === input)
+            return;
         input.focus();
         input.setSelectionRange(edit.selectionStart, edit.selectionEnd);
     });
 }
 function moveTransientSurface(surface) {
-    const menu = state.commentUi.menu;
-    if (menu) {
-        menu.surface = surface;
-        menu.triggerId = controlId(menu.commentId, surface, "more");
-    }
     if (state.commentUi.confirmation)
         state.commentUi.confirmation.surface = surface;
 }
@@ -166,29 +176,24 @@ function installStaticIcons() {
     document.querySelectorAll("[data-icon]").forEach((container) => {
         replaceIcon(container, container.dataset.icon);
     });
-    replaceIcon($("modeChevron"), "chevronDown");
-    replaceIcon($("composeClose"), "x");
-    replaceIcon($("drawerClose"), "x");
 }
 function openModeMenu() {
     if (state.modeMenuOpen)
         return;
+    recoveryRuntime.commands.setMenuOpen(false, { restoreFocus: false });
     state.modeMenuOpen = true;
-    $("modeMenu").hidden = false;
-    $("modeButton").setAttribute("aria-expanded", "true");
+    state.restoreModeFocus = true;
+    toolbarRuntime.publish();
     toFrame({ type: "eh:modeMenuState", open: true });
-    $("modeMenu").querySelector(`[data-mode="${state.reviewMode}"]`)?.focus();
 }
 function closeModeMenu(reason = "dismissed", { restoreFocus = false } = {}) {
     if (!state.modeMenuOpen)
         return false;
     state.modeMenuOpen = false;
-    $("modeMenu").hidden = true;
-    $("modeButton").setAttribute("aria-expanded", "false");
+    state.restoreModeFocus = restoreFocus;
+    toolbarRuntime.publish();
     toFrame({ type: "eh:modeMenuState", open: false });
     diagnostic("mode-menu-close", { reason });
-    if (restoreFocus)
-        $("modeButton").focus();
     return true;
 }
 function openDrawer() {
@@ -209,7 +214,6 @@ function closeDrawer() {
     state.drawerOpen = false;
     const transientOwner = state.commentUi.edit?.commentId ||
         state.commentUi.confirmation?.commentId ||
-        state.commentUi.menu?.commentId ||
         null;
     if (transientOwner && commentById(transientOwner)) {
         state.activeSavedCommentId = transientOwner;
@@ -229,9 +233,7 @@ function setComposeLifecycle(next, reason) {
         return;
     const from = state.composeLifecycle;
     state.composeLifecycle = next;
-    const submitting = next === "submitting";
-    $("composeCancel").disabled = submitting;
-    $("composeClose").disabled = submitting;
+    contextualRuntime.publish();
     diagnostic("composer-lifecycle-transition", { from, to: next, reason });
 }
 function setComposePlacement(next) {
@@ -239,6 +241,7 @@ function setComposePlacement(next) {
         return;
     const from = state.composePlacement;
     state.composePlacement = next;
+    contextualRuntime.publish();
     diagnostic("placement-transition", { from, to: next });
 }
 /**
@@ -275,8 +278,10 @@ const frameController = createFrameController({
         saveController.baseline(null);
     },
     failed(message) {
-        $("reloadNotice").hidden = false;
-        $("reloadMessage").textContent = `${message} Reload keeps your comment drafts.`;
+        state.reloadVisible = true;
+        state.reloadFailed = true;
+        state.reloadMessage = `${message} Reload keeps your comment drafts.`;
+        recoveryRuntime.publish();
         toast(message);
     },
 });
@@ -295,12 +300,12 @@ const feedbackController = createFeedbackController({
     sourceHash: () => frameController.state.sourceHash, save: saveController,
     policy: () => state.savePolicy, request: api,
     capture: () => captureStablePage({ timeout: 500 }), refresh: () => refreshHistory(),
-    note: () => $("note").value,
-    clearNote(sent) { if ($("note").value === sent)
-        $("note").value = ""; },
+    note: () => state.noteDraft.text,
+    clearNote(sent) {
+        if (state.noteDraft.text === sent && !state.noteDraft.composing)
+            Object.assign(state.noteDraft, createNoteDraft());
+    },
     pauseCapture() {
-        if ($("captureWarning"))
-            $("captureWarning").hidden = true;
         captureCoordinator.reset();
         manualCaptureController?.abort();
     },
@@ -340,14 +345,19 @@ reviewController.own(() => frameController.dispose());
 reviewController.own(() => saveController.dispose());
 reviewController.own(() => feedbackController.dispose());
 reviewController.own(() => transport.dispose());
-const executionControls = createExecutionControls({
-    api,
+export const recoveryRuntime = createRecoveryController({
+    request: api,
     sessionId: state.sessionId,
-    elements: {
-        static: $("executionStatic"), auto: $("executionAuto"), status: $("executionStatus"),
-        details: $("executionDetails"), menu: $("reviewDetails"),
-        editDescription: $("modeMenu").querySelector('[data-mode="edit"] small'),
-    },
+    read: () => ({
+        page: state.page, rendered: frameHost.visibleExecution, identity: frameController.identity(),
+        comparing: state.comparing, ended: state.ended, loading: frameController.loading,
+        pendingReload: frameController.state.pendingReload || !!frameHost.previous,
+        frameError: frameController.state.phase.kind === "failed" ? frameController.state.phase.message : null,
+        reload: {
+            visible: state.reloadVisible, message: state.reloadMessage,
+            error: state.reloadFailed || saveController.state.conflict,
+        },
+    }),
     changed(page) {
         if (!page || page.key !== frameController.state.key)
             return;
@@ -360,7 +370,148 @@ const executionControls = createExecutionControls({
         state.savePolicy = reviewConfiguration(state.page, state.reviewMode).savePolicy;
         render();
     },
-    failed(error) { toast(error.message || String(error)); },
+    failed: toast,
+    menuChanged(open) {
+        if (open) {
+            closeModeMenu("recovery-menu");
+        }
+        toFrame({ type: "eh:modeMenuState", open });
+    },
+    reload: () => reloadLatest({ explicit: true }),
+    keepCurrent() {
+        state.reloadVisible = false;
+        announce("Keeping the current page. Return to Review to reload when ready.");
+    },
+});
+reviewController.own(() => recoveryRuntime.dispose());
+function pendingFeedbackCount() {
+    return (state.page?.comments?.length || 0) + (state.page?.edits?.length || 0) +
+        (state.others || []).reduce((sum, other) => sum + other.count, 0);
+}
+export const toolbarRuntime = createToolbarController(() => ({
+    comparing: state.comparing,
+    mode: normalizeReviewMode(state.reviewMode),
+    modeDisabled: state.modeApplying || state.comparing || feedbackController.sending || !frameController.state.execution,
+    modeMenuOpen: state.modeMenuOpen,
+    restoreModeFocus: state.restoreModeFocus,
+    editDescription: executionPresentation(state.page, frameHost.visibleExecution).editDescription,
+    drawerOpen: state.drawerOpen,
+    feedbackCount: pendingFeedbackCount(),
+    theme: state.theme === "dark" ? "dark" : "light",
+    ended: state.ended,
+}), {
+    setComparing: setHistoryView,
+    setMode: (mode) => { void setReviewMode(mode); },
+    setModeMenu: (open) => {
+        if (open)
+            openModeMenu();
+        else
+            closeModeMenu("dismissed", { restoreFocus: true });
+    },
+    openComments: openDrawer,
+    toggleTheme,
+});
+reviewController.own(() => toolbarRuntime.dispose());
+export const commentsRuntime = createCommentsController({
+    read: () => ({
+        open: state.drawerOpen, ended: state.ended, comparing: state.comparing,
+        hasPage: !!state.page, composeOpen: !!state.compose,
+        error: frameController.state.phase.kind === "failed" ? frameController.state.phase.message : null,
+        comments: state.page?.comments || [], others: state.others || [],
+        activeId: state.activeSavedCommentId, orphans: state.orphans, ui: state.commentUi,
+    }),
+    close: closeDrawer,
+    activate: setActive,
+    edit: (id, surface) => startCommentEdit(commentById(id), surface),
+    save: saveCommentEdit,
+    cancelEdit: cancelCommentEdit,
+    confirm: confirmCommentDelete,
+    dismiss: () => dismissActiveComment("close", { restoreFocus: true }),
+    cancelDelete: cancelDeleteConfirmation,
+    remove: deleteComment,
+    async navigate(key) {
+        try {
+            await reviewController.navigate({ key });
+        }
+        catch (err) {
+            toast(`${err.message}. Stay on this page and retry.`);
+        }
+    },
+});
+reviewController.own(() => commentsRuntime.dispose());
+export const contextualRuntime = createContextualController({
+    read: () => ({
+        open: !!state.compose, disabled: state.ended || state.comparing,
+        submitting: state.composeLifecycle === "submitting",
+        kind: state.compose?.kind || "selection", quote: state.compose?.quote || "",
+        placement: state.composePlacement, draft: state.composerDraft,
+    }),
+    submit: commitCompose, cancel: cancelCompose,
+    reveal() {
+        if (!state.compose || state.compose.unresolved)
+            return;
+        diagnostic("reveal-target-requested");
+        toFrame({ type: "eh:revealTarget", targetGeneration: state.compose.generation });
+    },
+    focus() { $("compose").classList.remove("pass-through"); },
+    measure: scheduleContextualPosition,
+});
+reviewController.own(() => contextualRuntime.dispose());
+export const feedbackRuntime = createFeedbackPanelController({
+    read: () => ({
+        note: state.noteDraft, ended: state.ended,
+        available: !!state.page && !frameController.loading && !state.comparing,
+        identity: JSON.stringify([frameController.state.key, frameController.state.renderId, frameController.state.generation, state.pageEpoch, frameController.state.pendingReload]),
+        source: frameController.state.sourceHash,
+        edits: state.page?.edits || [],
+        total: pendingFeedbackCount(),
+        drafts: draftCount(state), agent: state.agent,
+        prompt: handoffPrompt(state.pollCommand || state.page?.pollCommand),
+        filename: state.page?.filename || "", kind: state.page?.kind || "", markdown: !!state.page?.markdown,
+        save: saveController.getSnapshot(), delivery: feedbackController.getSnapshot(),
+    }),
+    send: () => feedbackController.send(),
+    async flush(action) {
+        if (action === "revert") {
+            // Revert owns save ordering and can discard edits that failed to persist.
+            await frameController.flush(true);
+        }
+        else {
+            await flushFrame({ strict: true });
+            await saveController.settled();
+        }
+    },
+    revert: () => saveController.revert(),
+    async end() {
+        await api(`/api/session/${state.sessionId}/end`, { method: "POST" });
+        showEnded();
+    },
+    copy: (text) => navigator.clipboard.writeText(text),
+    failed: toast,
+});
+reviewController.own(() => feedbackRuntime.dispose());
+reviewController.own(frameController.subscribe(() => feedbackRuntime.publish()));
+let contextualFrame = null;
+function scheduleContextualPosition() {
+    if (contextualFrame !== null || uiLifetime.signal.aborted)
+        return;
+    contextualFrame = requestAnimationFrame(() => {
+        contextualFrame = null;
+        if (uiLifetime.signal.aborted)
+            return;
+        positionCompose();
+        positionAlignedCard();
+    });
+}
+const contextualObserver = new ResizeObserver(scheduleContextualPosition);
+for (const host of [$("compose"), $("alignedCard"), $("noticesRoot"), document.querySelector(".document-host")]) {
+    contextualObserver.observe(host);
+}
+reviewController.own(() => {
+    contextualObserver.disconnect();
+    if (contextualFrame !== null)
+        cancelAnimationFrame(contextualFrame);
+    contextualFrame = null;
 });
 const toolbar = document.querySelector(".toolbar");
 const toolbarObserver = new ResizeObserver(() => {
@@ -369,11 +520,9 @@ const toolbarObserver = new ResizeObserver(() => {
 toolbarObserver.observe(toolbar);
 reviewController.own(() => toolbarObserver.disconnect());
 function renderExecution() {
-    executionControls.render(state.page, frameHost.visibleExecution, {
-        pendingReload: frameController.state.pendingReload || !!frameHost.previous,
-        loading: frameController.loading,
-        error: frameController.state.phase.kind === "failed" ? frameController.state.phase.message : null,
-    });
+    recoveryRuntime.publish();
+    toolbarRuntime.publish();
+    commentsRuntime.publish();
 }
 const persistEdit = (key, payload) => saveController.persistEdit(key, payload);
 const settleEditPersistence = (key) => saveController.settleEdits(key);
@@ -422,7 +571,7 @@ function configureFrame() {
 }
 async function setReviewMode(nextMode) {
     const next = normalizeReviewMode(nextMode);
-    closeModeMenu("selection");
+    closeModeMenu("selection", { restoreFocus: true });
     if (next === state.reviewMode || state.modeApplying)
         return;
     state.modeApplying = true;
@@ -454,6 +603,8 @@ async function setReviewMode(nextMode) {
 }
 async function loadPage(key, { reload = true } = {}) {
     const returning = state.page;
+    state.reloadVisible = false;
+    state.reloadFailed = false;
     advancePageEpoch(returning ? "navigation" : "reload");
     const generation = beginFrameTransition(key);
     frameController.resetRetries();
@@ -466,6 +617,7 @@ async function loadPage(key, { reload = true } = {}) {
     frameController.setPolicy(framePolicy(state.page, ARTIFACT_ORIGIN));
     state.orphans = new Set();
     state.compose = null;
+    state.composerDraft = createComposerDraft();
     setComposeLifecycle("closed", "page-change");
     setComposePlacement("hidden");
     state.target = null;
@@ -486,26 +638,17 @@ async function loadPage(key, { reload = true } = {}) {
         toast(`${edits} ${edits === 1 ? "edit is" : "edits are"} queued for the agent to apply to the source`);
     }
 }
-// -------------------------------------------------------------------- clock
-function ago(ts) {
-    const secs = Math.max(0, Math.round((Date.now() - ts) / 1000));
-    if (secs < 45)
-        return "just now";
-    const mins = Math.round(secs / 60);
-    if (mins < 60)
-        return `${mins}m`;
-    const hours = Math.round(mins / 60);
-    if (hours < 24)
-        return `${hours}h`;
-    return `${Math.round(hours / 24)}d`;
-}
 // -------------------------------------------------------------------- render
 function render() {
     if (state.ended)
         return;
+    toolbarRuntime.publish();
     const page = state.page;
-    if (!page)
+    if (!page) {
+        commentsRuntime.publish();
+        contextualRuntime.publish();
         return;
+    }
     // Source updates cannot change the policy of a frame awaiting draft-safe reload.
     if (frameController.state.execution)
         Object.assign(page, frameController.state.execution);
@@ -515,150 +658,18 @@ function render() {
     syncFrameInteraction();
     const editWasFocused = skipEditCaptureOnce ? false : captureEditState();
     skipEditCaptureOnce = false;
+    commentsRuntime.publish();
     document.title = page.filename || 'doc-review';
-    const comments = newestComments(page.comments);
-    const edits = page.edits || [];
-    $("count").textContent = String(comments.length);
-    $("toolbarCount").textContent = String(comments.length);
-    $("empty").hidden = comments.length > 0 || !!state.compose;
-    $("modeLabel").textContent = state.reviewMode === "edit" ? "Edit" : "View";
-    replaceIcon($("modeIcon"), state.reviewMode === "edit" ? "pencil" : "eye");
-    $("modeButton").disabled = state.modeApplying || state.comparing || feedbackController.sending || !frameController.state.execution;
-    for (const item of $("modeMenu").querySelectorAll("[data-mode]")) {
-        const checked = item.dataset.mode === state.reviewMode;
-        item.setAttribute("aria-checked", String(checked));
-        const check = item.querySelector(".menu-check");
-        check.textContent = "";
-        if (checked)
-            check.append(createIcon("check"));
-    }
-    $("drawer").classList.toggle("open", state.drawerOpen);
-    $("drawer").setAttribute("aria-hidden", String(!state.drawerOpen));
-    $("commentsButton").setAttribute("aria-expanded", String(state.drawerOpen));
-    $("drawerBackdrop").hidden = !state.drawerOpen;
-    // --- compose
-    const composeWrap = $("compose");
-    if (state.compose) {
-        composeWrap.hidden = false;
-        $("composeKind").textContent = state.compose.kind === "element" ? "Element" : "Selection";
-        $("composeQuote").textContent = tidyMiddle(state.compose.quote, 260);
-        afterPaint(positionCompose);
-    }
-    else {
-        composeWrap.hidden = true;
-        $("composeText").value = "";
-        $("composeError").hidden = true;
-    }
-    // --- comment cards
-    const list = $("cards");
-    list.textContent = "";
-    for (const comment of comments) {
-        list.append(renderCommentCard(comment, "drawer"));
-    }
-    renderAlignedCard(comments);
-    // --- your edits
-    const box = $("editsBox");
-    box.hidden = edits.length === 0;
-    if (edits.length) {
-        $("editCount").textContent = String(edits.length);
-        const rows = $("editList");
-        rows.textContent = "";
-        const LIMIT = 5;
-        const shown = state.editsExpanded ? edits : edits.slice(0, LIMIT);
-        for (const edit of shown) {
-            const row = document.createElement("div");
-            row.className = `edit-row${edit.kind === "deleted" ? " deleted" : ""}`;
-            const pip = document.createElement("span");
-            pip.className = "pip";
-            const label = document.createElement("span");
-            label.className = "label";
-            label.textContent = edit.label;
-            const kind = document.createElement("span");
-            kind.className = "kind";
-            kind.textContent = edit.kind;
-            row.append(pip, label, kind);
-            rows.append(row);
-        }
-        if (edits.length > LIMIT) {
-            const more = document.createElement("button");
-            more.type = "button";
-            more.className = "edit-more";
-            more.textContent = state.editsExpanded ? "Show fewer" : `${edits.length - LIMIT} more…`;
-            more.addEventListener("click", () => {
-                state.editsExpanded = !state.editsExpanded;
-                render();
-            });
-            rows.append(more);
-        }
-        renderSave();
-    }
-    // --- pages you left feedback on but are not looking at
-    const others = state.others || [];
-    const othersBox = $("othersBox");
-    othersBox.hidden = others.length === 0;
-    if (others.length) {
-        $("othersCount").textContent = String(others.length);
-        const list = $("othersList");
-        list.textContent = "";
-        for (const other of others) {
-            const row = document.createElement("button");
-            row.type = "button";
-            row.className = "edit-row other-row";
-            const label = document.createElement("span");
-            label.className = "label";
-            label.textContent = other.filename;
-            const count = document.createElement("span");
-            count.className = "kind";
-            count.textContent = String(other.count);
-            row.append(label, count);
-            row.addEventListener("click", async () => {
-                try {
-                    await reviewController.navigate({ key: other.key });
-                }
-                catch (err) {
-                    toast(`${err.message}. Stay on this page and retry.`);
-                }
-            });
-            list.append(row);
-        }
-    }
-    // --- send
-    const otherTotal = others.reduce((sum, o) => sum + o.count, 0);
-    const total = comments.length + edits.length + otherTotal;
-    // An overall note is sendable on its own — the server already accepts
-    // note-only batches; the button must not stay dead while one is typed.
-    const hasNote = $("note").value.trim().length > 0;
-    const send = $("send");
-    const delivered = state.agent === "working";
-    const stranded = state.agent === "stranded";
-    const busy = delivered || stranded || feedbackController.sent;
-    send.disabled = (total === 0 && !hasNote) || busy || feedbackController.sending;
-    send.textContent = feedbackController.sending ? "Sending feedback…" : delivered
-        ? "Feedback delivered"
-        : stranded
-            ? "Sent — agent is not listening"
-            : feedbackController.sent
-                ? "Sent — waiting for agent"
-                : total
-                    ? `Send ${total} to agent`
-                    : hasNote
-                        ? "Send note to agent"
-                        : "Nothing to send yet";
-    // After sending, say what happens next. If nothing is polling, the loop would
-    // otherwise dead-end silently, so hand over the exact command to run.
-    $("agentLine").hidden = !delivered;
-    $("agentText").textContent = "Feedback delivered — page reloads when fixes land";
-    // Server-authoritative, so it survives a browser refresh.
-    $("handoff").hidden = !stranded;
-    if (stranded)
-        $("handoffCmd").textContent = handoffPrompt(state.pollCommand || page.pollCommand);
-    const excluded = draftCount(state);
-    $("draftWarning").hidden = excluded === 0;
-    $("draftWarning").textContent = `${excluded} open ${excluded === 1 ? "draft is" : "drafts are"} not included. Save comments explicitly before sending.`;
+    // Stable outer hosts are the bounded geometry adapter; React owns their controls.
+    $("compose").hidden = !state.compose;
+    contextualRuntime.publish();
+    scheduleContextualPosition();
+    feedbackRuntime.publish();
     restoreTransientFocus(editWasFocused);
 }
 function positionCompose() {
     if (!state.compose || state.composeLifecycle === "closed") {
+        $("compose").hidden = true;
         setComposePlacement("hidden");
         return;
     }
@@ -667,7 +678,9 @@ function positionCompose() {
         surface.hidden = false;
         surface.classList.add("sheet");
         surface.classList.remove("edge-top", "edge-bottom");
-        $("composeDirection").hidden = true;
+        surface.style.left = "";
+        surface.style.top = "";
+        surface.style.width = "";
         setComposePlacement("sheet");
         return;
     }
@@ -688,13 +701,6 @@ function positionCompose() {
     surface.classList.toggle("edge-top", placement.kind === "edge-top");
     surface.classList.toggle("edge-bottom", placement.kind === "edge-bottom");
     setComposePlacement(placement.kind);
-    const edge = placement.kind === "edge-top" || placement.kind === "edge-bottom";
-    $("composeDirection").hidden = !edge;
-    $("composeDirectionText").textContent = placement.kind === "edge-top"
-        ? "Selection is above"
-        : placement.kind === "edge-bottom"
-            ? "Selection is below"
-            : "";
     surface.hidden = placement.kind === "hidden";
     if (placement.kind !== "sheet" && placement.kind !== "hidden") {
         surface.style.left = `${placement.left}px`;
@@ -707,273 +713,15 @@ function positionCompose() {
         surface.style.width = "";
     }
 }
-function makeAction(label, className = "card-action") {
-    const button = document.createElement("button");
-    button.type = "button";
-    button.className = className;
-    button.textContent = label;
-    return button;
-}
-function makeWho(comment, surface) {
-    const who = document.createElement("span");
-    who.className = "who";
-    who.append("You");
-    if (surface === "drawer") {
-        const sep = document.createElement("span");
-        sep.className = "sep";
-        sep.textContent = "·";
-        const when = document.createElement("span");
-        when.className = "when";
-        when.textContent = ago(comment.updatedAt || comment.createdAt);
-        who.append(sep, when);
-    }
-    if (comment.correction) {
-        const badge = document.createElement("span");
-        badge.className = "badge correction";
-        badge.textContent = "correction";
-        who.append(badge);
-    }
-    else if (comment.updatedAt) {
-        const badge = document.createElement("span");
-        badge.className = "badge";
-        badge.textContent = "edited";
-        who.append(badge);
-    }
-    if (state.orphans.has(comment.id)) {
-        const badge = document.createElement("span");
-        badge.className = "badge";
-        badge.textContent = "orphaned";
-        who.append(badge);
-    }
-    return who;
-}
-function commentUiKind(commentId) {
-    if (state.commentUi.edit?.commentId === commentId)
-        return "edit";
-    if (state.commentUi.confirmation?.commentId === commentId)
-        return "confirmation";
-    if (state.commentUi.menu?.commentId === commentId)
-        return "menu";
-    return "normal";
-}
-function renderMore(comment, surface, open, disabled = false) {
-    const triggerId = controlId(comment.id, surface, "more");
-    const menuId = controlId(comment.id, surface, "menu");
-    const trigger = makeAction("More", "card-action more-trigger");
-    trigger.id = triggerId;
-    trigger.setAttribute("aria-haspopup", "menu");
-    trigger.setAttribute("aria-expanded", String(open));
-    trigger.setAttribute("aria-controls", menuId);
-    trigger.disabled = disabled;
-    trigger.prepend(createIcon("moreHorizontal", { size: 14 }));
-    trigger.addEventListener("click", (event) => {
-        event.stopPropagation();
-        if (open) {
-            closeCommentMenu({ restoreFocus: true });
-        }
-        else {
-            if (!ownMenu(state.commentUi, comment.id, surface, triggerId)) {
-                focusCurrentCommentEdit();
-                return;
-            }
-            toFrame({ type: "eh:modeMenuState", open: true });
-            requestControlFocus(controlId(comment.id, surface, "delete-item"));
-            render();
-        }
-    });
-    return trigger;
-}
-function renderCommentCard(comment, surface) {
-    const card = document.createElement(surface === "aligned" ? "article" : "div");
-    if (surface === "drawer") {
-        card.className = `comment${state.activeSavedCommentId === comment.id ? " active" : ""}`;
-    }
-    card.dataset.id = comment.id;
-    card.dataset.surface = surface;
-    const kind = commentUiKind(comment.id);
-    const editOwnedElsewhere = !!(state.commentUi.edit &&
-        state.commentUi.edit.commentId !== comment.id);
-    const head = document.createElement("div");
-    head.className = "comment-head";
-    head.append(makeWho(comment, surface));
-    if (kind === "normal") {
-        if (surface === "drawer") {
-            const jump = makeAction("Jump to");
-            jump.disabled = editOwnedElsewhere;
-            jump.addEventListener("click", (event) => {
-                event.stopPropagation();
-                setActive(comment.id, true);
-            });
-            head.append(jump);
-        }
-        const edit = makeAction("Edit");
-        edit.id = controlId(comment.id, surface, "edit");
-        edit.setAttribute("aria-label", "Edit comment");
-        edit.disabled = editOwnedElsewhere;
-        edit.addEventListener("click", (event) => {
-            event.stopPropagation();
-            startCommentEdit(comment, surface);
-        });
-        head.append(edit);
-        if (surface === "aligned") {
-            const close = makeAction("Close");
-            close.setAttribute("aria-label", "Close comment card");
-            close.addEventListener("click", (event) => {
-                event.stopPropagation();
-                dismissActiveComment("close", { restoreFocus: true });
-            });
-            head.append(close);
-        }
-        head.append(renderMore(comment, surface, false, editOwnedElsewhere));
-    }
-    else if (kind === "menu") {
-        head.append(renderMore(comment, surface, true));
-    }
-    const quote = document.createElement("p");
-    quote.className = "quote";
-    quote.textContent = tidyMiddle(comment.quote, 140);
-    card.append(head, quote);
-    if (kind === "edit") {
-        const edit = state.commentUi.edit;
-        const input = document.createElement("textarea");
-        input.className = "body-edit";
-        input.rows = 3;
-        input.value = edit.draft;
-        input.readOnly = edit.status === "saving";
-        input.dataset.commentEdit = comment.id;
-        input.setAttribute("aria-label", "Edit comment text");
-        input.addEventListener("input", () => {
-            edit.draft = input.value;
-            edit.selectionStart = input.selectionStart;
-            edit.selectionEnd = input.selectionEnd;
-            edit.validation = "";
-        });
-        const rememberSelection = () => {
-            edit.selectionStart = input.selectionStart;
-            edit.selectionEnd = input.selectionEnd;
-        };
-        input.addEventListener("select", rememberSelection);
-        input.addEventListener("keyup", rememberSelection);
-        input.addEventListener("click", (event) => {
-            event.stopPropagation();
-            rememberSelection();
-        });
-        input.addEventListener("compositionstart", () => {
-            edit.composing = true;
-        });
-        input.addEventListener("compositionend", () => {
-            edit.composing = false;
-            rememberSelection();
-        });
-        input.addEventListener("keydown", (event) => {
-            event.stopPropagation();
-            rememberSelection();
-            if (event.key === "Enter" && !event.shiftKey) {
-                if (edit.composing || event.isComposing)
-                    return;
-                event.preventDefault();
-                void saveCommentEdit();
-            }
-            else if (event.key === "Escape") {
-                event.preventDefault();
-                cancelCommentEdit();
-            }
-        });
-        card.append(input);
-        const helper = document.createElement("p");
-        helper.className = "edit-help";
-        helper.textContent = "Enter to save · Shift+Enter for new line";
-        card.append(helper);
-        if (edit.validation) {
-            const validation = document.createElement("p");
-            validation.className = "comment-validation";
-            validation.setAttribute("role", "alert");
-            validation.textContent = edit.validation;
-            card.append(validation);
-        }
-        const actions = document.createElement("div");
-        actions.className = "comment-edit-actions";
-        const save = makeAction(edit.status === "saving" ? "Saving…" : "Save", "btn-primary");
-        save.disabled = edit.status === "saving";
-        save.addEventListener("click", (event) => {
-            event.stopPropagation();
-            void saveCommentEdit();
-        });
-        const cancel = makeAction("Cancel", "btn-ghost");
-        cancel.disabled = edit.status === "saving";
-        cancel.addEventListener("click", (event) => {
-            event.stopPropagation();
-            cancelCommentEdit();
-        });
-        actions.append(save, cancel);
-        card.append(actions);
-    }
-    else if (kind === "confirmation") {
-        const confirmation = state.commentUi.confirmation;
-        const prompt = document.createElement("p");
-        prompt.className = "delete-prompt";
-        prompt.textContent = "Delete this comment?";
-        const actions = document.createElement("div");
-        actions.className = "delete-actions";
-        const cancel = makeAction("Cancel", "btn-ghost");
-        cancel.disabled = confirmation.status === "deleting";
-        cancel.addEventListener("click", (event) => {
-            event.stopPropagation();
-            cancelDeleteConfirmation();
-        });
-        const remove = makeAction(confirmation.status === "deleting" ? "Deleting…" : "Delete", "btn-danger");
-        remove.id = controlId(comment.id, surface, "confirm-delete");
-        remove.disabled = confirmation.status === "deleting";
-        remove.addEventListener("click", (event) => {
-            event.stopPropagation();
-            void deleteComment(comment.id);
-        });
-        actions.append(cancel, remove);
-        card.append(prompt, actions);
-    }
-    else {
-        const body = document.createElement("p");
-        body.className = "body";
-        body.textContent = comment.feedback;
-        body.title = "Click to edit";
-        if (!editOwnedElsewhere) {
-            body.addEventListener("click", (event) => {
-                event.stopPropagation();
-                startCommentEdit(comment, surface);
-            });
-        }
-        card.append(body);
-    }
-    if (kind === "menu") {
-        const menu = document.createElement("div");
-        menu.id = controlId(comment.id, surface, "menu");
-        menu.className = "comment-menu";
-        menu.setAttribute("role", "menu");
-        menu.setAttribute("aria-labelledby", controlId(comment.id, surface, "more"));
-        const remove = makeAction("Delete", "comment-menu-item");
-        remove.id = controlId(comment.id, surface, "delete-item");
-        remove.setAttribute("role", "menuitem");
-        remove.prepend(createIcon("trash", { size: 14 }));
-        remove.addEventListener("click", (event) => {
-            event.stopPropagation();
-            toFrame({ type: "eh:modeMenuState", open: false });
-            if (!ownConfirmation(state.commentUi, comment.id, surface)) {
-                focusCurrentCommentEdit();
-                return;
-            }
-            requestControlFocus(controlId(comment.id, surface, "confirm-delete"));
-            render();
-        });
-        menu.append(remove);
-        card.append(menu);
-    }
-    if (surface === "drawer") {
-        card.addEventListener("click", () => {
-            if (kind === "normal" && !editOwnedElsewhere)
-                setActive(comment.id, false);
-        });
+function confirmCommentDelete(id, surface) {
+    if (!commentById(id))
+        return;
+    if (!ownConfirmation(state.commentUi, id, surface)) {
+        focusCurrentCommentEdit();
+        return;
     }
-    return card;
+    requestControlFocus(controlId(id, surface, "confirm-delete"));
+    render();
 }
 function positionAlignedCard() {
     const host = $("alignedCard");
@@ -987,6 +735,8 @@ function positionAlignedCard() {
     const position = alignedCardPosition(geometry.rects, {
         frameRect: frameHost.current.getBoundingClientRect(),
         viewport,
+        width: host.offsetWidth || 300,
+        height: host.offsetHeight || 180,
     });
     if (!position) {
         host.hidden = true;
@@ -997,19 +747,6 @@ function positionAlignedCard() {
     host.hidden = false;
     return true;
 }
-function renderAlignedCard(comments) {
-    const host = $("alignedCard");
-    host.textContent = "";
-    const comment = comments.find((item) => item.id === state.activeSavedCommentId);
-    if (!comment) {
-        host.hidden = true;
-        return;
-    }
-    const card = renderCommentCard(comment, "aligned");
-    while (card.firstChild)
-        host.append(card.firstChild);
-    positionAlignedCard();
-}
 async function deleteComment(id) {
     if (deleteFlights.has(id))
         return deleteFlights.get(id);
@@ -1019,6 +756,7 @@ async function deleteComment(id) {
     confirmation.status = "deleting";
     render();
     const startEpoch = state.pageEpoch;
+    const index = newestComments(state.page.comments).findIndex((comment) => comment.id === id);
     const flight = (async () => {
         try {
             const result = await api(`/api/page/${frameController.state.key}/comment/${id}`, { method: "DELETE" });
@@ -1029,6 +767,11 @@ async function deleteComment(id) {
             state.activeGeometry.delete(id);
             if (state.activeSavedCommentId === id)
                 state.activeSavedCommentId = null;
+            if (state.drawerOpen) {
+                const remaining = newestComments(state.page.comments);
+                const next = remaining[Math.min(index, remaining.length - 1)];
+                requestControlFocus(next ? controlId(next.id, "drawer", "delete") : "commentsSection");
+            }
             render();
             return true;
         }
@@ -1052,7 +795,7 @@ function cancelDeleteConfirmation() {
     const confirmation = state.commentUi.confirmation;
     if (!confirmation || confirmation.status === "deleting")
         return false;
-    const triggerId = controlId(confirmation.commentId, confirmation.surface, "more");
+    const triggerId = controlId(confirmation.commentId, confirmation.surface, "delete");
     clearOwned(state.commentUi, "confirmation");
     requestControlFocus(triggerId);
     render();
@@ -1144,6 +887,8 @@ async function executeCommentPatch(edit, startEpoch) {
         }
         reconcilePage(result.page, { reason: "mutation" });
         clearOwned(state.commentUi, "edit");
+        if (state.drawerOpen)
+            requestControlFocus(controlId(replacement?.id || id, "drawer", "edit"));
         if (result.delivery === "updated-pending") {
             toast("Updated the feedback waiting for your agent");
         }
@@ -1176,37 +921,7 @@ async function executeCommentPatch(edit, startEpoch) {
     }
 }
 function renderSave() {
-    const line = $("saveLine");
-    if (saveController.state.conflict) {
-        line.className = "save-line failed";
-        $("saveText").textContent = "Source changed — reload latest before saving. Your page edits remain in this tab.";
-        return;
-    }
-    if (state.page && state.page.kind === "url") {
-        line.className = "save-line dynamic";
-        $("saveText").textContent = "Localhost page — your direct edits go to the agent for source updates";
-        return;
-    }
-    if (state.page && state.page.markdown) {
-        line.className = "save-line dynamic";
-        $("saveText").textContent = "Markdown source — edits go to the agent as feedback";
-        return;
-    }
-    if (saveController.state.dynamic) {
-        // The page's own scripts render it, so writing the live DOM back would
-        // corrupt the file. Edits still reach the agent as feedback.
-        line.className = "save-line dynamic";
-        $("saveText").textContent = "Live page — edits go to the agent, the file is left alone";
-        return;
-    }
-    line.className = `save-line ${saveController.state.status === "saving" ? "saving" : saveController.state.status === "failed" ? "failed" : ""}`;
-    const name = state.page ? state.page.filename : "";
-    if (saveController.state.status === "saving")
-        $("saveText").textContent = `Saving to ${name}…`;
-    else if (saveController.state.status === "failed")
-        $("saveText").textContent = "Couldn't save — retry before sending";
-    else
-        $("saveText").textContent = saveController.state.savedAt ? `Saved to ${name} · ${saveController.state.savedAt}` : `Saved to ${name}`;
+    feedbackRuntime.publish();
 }
 function toast(message) {
     const el = document.createElement("div");
@@ -1216,6 +931,8 @@ function toast(message) {
     afterDelay(() => el.remove(), 3200);
 }
 function setActive(id, scroll) {
+    if (id && state.drawerOpen)
+        commentsRuntime.commands.setSectionOpen(true);
     state.activeSavedCommentId = id;
     toFrame({ type: "eh:activate", id, scroll: !!scroll });
     render();
@@ -1236,13 +953,15 @@ function dismissActiveComment(reason, { restoreFocus = false } = {}) {
 }
 // ------------------------------------------------------------------ compose
 async function openCompose(detail) {
+    const identity = currentRender();
+    const pageKey = frameController.state.key;
     if (state.compose && state.compose.generation === detail.generation) {
         if (state.composeLifecycle === "closed")
             setComposeLifecycle("open", "accepted");
         $("composeText").focus();
         return true;
     }
-    if (state.compose && $("composeText").value.trim()) {
+    if (state.compose && state.composerDraft.text.trim()) {
         const submitted = await commitCompose();
         if (!submitted) {
             diagnostic("comment-retarget-blocked", { reason: "submit-failed" });
@@ -1252,12 +971,12 @@ async function openCompose(detail) {
     else if (state.compose) {
         cancelCompose({ restoreFocus: false, preserveRetarget: true });
     }
+    if (state.ended || pageKey !== frameController.state.key || !sameRender(identity, currentRender()))
+        return false;
     dismissActiveComment("composer-open");
     state.compose = detail;
+    state.composerDraft = createComposerDraft();
     setComposeLifecycle("open", "accepted");
-    $("composeText").value = "";
-    $("composeError").hidden = true;
-    $("composeAddLabel").textContent = "Comment";
     render();
     afterPaint(() => {
         positionCompose();
@@ -1272,6 +991,7 @@ function cancelCompose({ restoreFocus = true, preserveRetarget = false } = {}) {
     const generation = state.compose.generation;
     const discardThroughGeneration = Math.max(generation, Number(state.compose.rejectedTargetGeneration) || generation);
     state.compose = null;
+    state.composerDraft = createComposerDraft();
     setComposeLifecycle("closed", "cancel");
     setComposePlacement("hidden");
     toFrame({
@@ -1297,26 +1017,40 @@ function commitCompose() {
 }
 async function executeComposeSubmit() {
     const compose = state.compose;
-    const feedback = $("composeText").value.trim();
-    if (!compose || !feedback)
+    const draft = state.composerDraft;
+    const feedback = draft.text.trim();
+    if (!compose || !feedback || draft.composing || state.ended)
         return false;
-    const button = $("composeAdd");
-    button.disabled = true;
+    const startEpoch = state.pageEpoch;
+    const identity = currentRender();
+    const targetGeneration = compose.generation;
+    const current = () => !state.ended && state.compose === compose && state.composerDraft === draft;
+    draft.error = "";
     setComposeLifecycle("submitting", "submit");
     diagnostic("comment-submit-executed");
-    $("composeError").hidden = true;
     try {
-        const result = await api(`/api/page/${frameController.state.key}/comment`, {
+        const result = await api(`/api/page/${identity.key}/comment`, {
             method: "POST",
             body: JSON.stringify({ kind: compose.kind, quote: compose.quote, anchor: compose.unresolved ? null : compose.anchor, feedback }),
         });
-        toFrame({
-            type: "eh:commit",
-            id: result.comment.id,
-            targetGeneration: compose.generation,
-            restoreFocus: true,
-        });
+        if (!current())
+            return false;
+        if (startEpoch !== state.pageEpoch || !sameRender(identity, currentRender())) {
+            draft.error = "The page changed while this comment was saving. Your draft is preserved; check the comments before retrying.";
+            draft.retry = true;
+            setComposeLifecycle("open", "stale-submit");
+            render();
+            return false;
+        }
+        if (!compose.unresolved)
+            toFrame({
+                type: "eh:commit",
+                id: result.comment.id,
+                targetGeneration,
+                restoreFocus: true,
+            });
         state.compose = null;
+        state.composerDraft = createComposerDraft();
         setComposeLifecycle("closed", "submitted");
         setComposePlacement("hidden");
         state.page = result.page;
@@ -1326,24 +1060,22 @@ async function executeComposeSubmit() {
         return true;
     }
     catch (err) {
-        $("composeError").textContent = `${err.message}. Retry or cancel.`;
-        $("composeError").hidden = false;
-        $("composeAddLabel").textContent = "Retry";
+        if (!current())
+            return false;
+        draft.error = `${err.message}. Retry or cancel.`;
+        draft.retry = true;
         diagnostic("comment-request-failure", { status: err.status || 0 });
         announce("Comment could not be saved. Your draft is still here.");
         setComposeLifecycle("open", "submit-failed");
+        render();
         $("compose").classList.remove("pass-through");
         afterPaint(() => $("composeText").focus());
         return false;
     }
-    finally {
-        button.disabled = false;
-    }
 }
 // ------------------------------------------------------------ review history
 const currentRender = () => frameController.identity();
 const captures = createCaptureRequests({ send: toFrame, current: currentRender });
-const comparisonView = createComparisonView($("changeDetail"));
 const historyUrl = (suffix = "") => `/api/session/${state.sessionId}/history${suffix}`;
 const historyController = createHistoryController({
     request: (suffix) => api(historyUrl(suffix)), changed: renderHistory, refreshed: scheduleResultCapture,
@@ -1371,164 +1103,42 @@ function selectedTarget() {
     const targets = roundTargets(history.round);
     return targets.find((target) => target.key === history.targetKey) || targets[0] || null;
 }
-function targetComparison(target) { return target?.comparison || {}; }
-function comparisonItems() {
-    const comparison = targetComparison(selectedTarget());
-    const value = history.mode === "source" ? comparison.source : comparison.content;
-    return value?.changes || value?.items || (history.mode === "content" ? comparison.changes || comparison.items : []) || [];
-}
 const refreshHistory = () => state.ended ? Promise.resolve(false) : historyController.refresh();
+export const changesRuntime = createChangesController({
+    read: () => ({
+        history, ended: state.ended, comparing: state.comparing, sending: feedbackController.sending,
+        current: {
+            key: frameController.state.key, kind: state.page?.kind,
+            ready: !frameController.loading && !!frameController.state.readyAt,
+            pendingReload: frameController.state.pendingReload,
+            dirty: saveController.state.dirty || saveController.state.conflict,
+            sourceHash: frameController.state.sourceHash || saveController.state.baseHash,
+            sessionId: state.sessionId, generation: frameController.state.generation,
+        },
+    }),
+    selectRound: (id) => historyController.selectRound(id),
+    selectTarget: (key) => historyController.selectTarget(key),
+    selectMode(mode) {
+        history.preferredMode = mode;
+        history.mode = mode;
+        history.index = 0;
+        renderHistory();
+    },
+    selectIndex(index) { history.index = index; renderHistory(); },
+    capture: () => captureResult(history.round, selectedTarget()),
+    finish: () => finishCapture(),
+    refresh: refreshHistory,
+    failed: toast,
+});
+reviewController.own(() => changesRuntime.dispose());
+reviewController.own(frameController.subscribe(() => changesRuntime.publish()));
+reviewController.own(saveController.subscribe(() => changesRuntime.publish()));
+reviewController.own(feedbackController.subscribe(() => changesRuntime.publish()));
 function renderHistory() {
     if (state.ended)
         return;
     syncFrameInteraction();
-    const focusedMode = document.activeElement?.dataset.comparisonMode;
-    const picker = $("roundPicker");
-    picker.replaceChildren();
-    for (const [index, round] of history.rounds.entries()) {
-        const option = document.createElement("option");
-        option.value = roundId(round);
-        option.textContent = `Round ${round.ordinal || round.number || history.rounds.length - index} · ${round.captureStatus === "ready" ? "completed" : round.captureStatus || round.status || round.feedbackStatus || "pending"}`;
-        picker.append(option);
-    }
-    picker.value = history.selectedId || "";
-    picker.disabled = !history.rounds.length;
-    const targets = roundTargets(history.round);
-    const target = selectedTarget();
-    if (history.round)
-        history.targetKey = target?.key || null;
-    $("historyTarget").replaceChildren();
-    for (const item of targets) {
-        const option = document.createElement("option");
-        option.value = item.key;
-        option.textContent = item.filename || item.label || item.key;
-        $("historyTarget").append(option);
-    }
-    $("historyTarget").value = history.targetKey || "";
-    $("historyTargetLabel").hidden = targets.length < 2;
-    const comparison = targetComparison(target);
-    const failedCapture = history.failures.get(`${roundId(history.round)}:${target?.key}`);
-    const presentation = historyPresentation({ ...history, target, comparison, failure: failedCapture });
-    const modes = presentation.modes;
-    history.mode = modes.includes(history.preferredMode) ? history.preferredMode : modes[0] || "content";
-    const displayedComparison = comparison[history.mode] || {};
-    $("historyUnavailable").replaceChildren();
-    for (const mode of ["content", "source"]) {
-        const representation = comparison[mode];
-        if (representation && representation.available === false) {
-            const reason = document.createElement("p");
-            reason.textContent = `${mode === "content" ? "Content" : "Source"} comparison unavailable: ${representation.reason || "This representation could not be compared."}`;
-            $("historyUnavailable").append(reason);
-        }
-    }
-    $("historyUnavailable").hidden = !$("historyUnavailable").childElementCount;
-    $("historyTiming").replaceChildren();
-    for (const [label, timestamp] of [
-        ["Before captured", displayedComparison.beforeCapturedAt],
-        ["Agent acknowledged", history.round?.acknowledgedAt],
-        ["After captured", displayedComparison.afterCapturedAt],
-    ]) {
-        const row = document.createElement("div");
-        const term = document.createElement("dt");
-        term.textContent = label;
-        const value = document.createElement("dd");
-        const date = timestamp == null ? null : new Date(timestamp);
-        value.textContent = date && Number.isFinite(date.getTime()) ? date.toLocaleString() : "Not available";
-        row.append(term, value);
-        $("historyTiming").append(row);
-    }
-    $("historyTiming").hidden = !history.round;
-    const afterAt = displayedComparison.afterCapturedAt == null ? NaN : new Date(displayedComparison.afterCapturedAt).getTime();
-    const acknowledgedAt = history.round?.acknowledgedAt == null ? NaN : new Date(history.round.acknowledgedAt).getTime();
-    const delay = afterAt - acknowledgedAt;
-    $("historyCaptureDelay").hidden = !Number.isFinite(delay);
-    $("historyCaptureDelay").textContent = delay >= 0
-        ? `Result captured ${Math.round(delay / 1000)} seconds after acknowledgment—not at the acknowledgment instant. A delayed capture can include later changes.`
-        : "This result snapshot predates acknowledgment. It is not proof of the page state at acknowledgment.";
-    $("historyCurrentStatus").hidden = !target?.resultRevisionId && !displayedComparison.afterCapturedAt;
-    $("historyCurrentStatus").textContent = comparisonFreshness(displayedComparison, target?.key, {
-        key: frameController.state.key, kind: state.page?.kind, ready: !frameController.loading && !!frameController.state.readyAt,
-        pendingReload: frameController.state.pendingReload, dirty: saveController.state.dirty || saveController.state.conflict,
-        sourceHash: frameController.state.sourceHash || saveController.state.baseHash,
-        sessionId: state.sessionId, generation: frameController.state.generation,
-    });
-    const viewComparison = history.mode === "content" ? displayedComparison.viewComparison : null;
-    $("historyViewCoverage").hidden = !viewComparison?.message;
-    $("historyViewCoverage").textContent = viewComparison?.message || "";
-    $("historyViewCoverage").dataset.status = viewComparison?.status || "";
-    $("comparisonModes").replaceChildren();
-    for (const mode of modes) {
-        const button = makeAction(mode === "source" ? "Source" : "Content", "btn-ghost");
-        button.dataset.comparisonMode = mode;
-        button.setAttribute("aria-pressed", String(history.mode === mode));
-        button.addEventListener("click", () => {
-            history.preferredMode = mode;
-            history.mode = mode;
-            history.index = 0;
-            renderHistory();
-            $("comparisonModes").querySelector(`[data-comparison-mode="${mode}"]`)?.focus({ preventScroll: true });
-        });
-        $("comparisonModes").append(button);
-    }
-    if (focusedMode)
-        $("comparisonModes").querySelector(`[data-comparison-mode="${focusedMode}"]`)?.focus({ preventScroll: true });
-    if ($("historyStatus").textContent !== presentation.message)
-        $("historyStatus").textContent = presentation.message;
-    $("historyStatus").dataset.state = presentation.state;
-    const detail = history.error?.message || failedCapture || target?.capture?.error;
-    $("historyError").hidden = !detail;
-    $("historyError").textContent = detail || "";
-    const captureAllowed = target && !target.resultRevisionId && target.capture?.status !== "unavailable" && history.round?.feedbackStatus === "acknowledged";
-    $("captureResult").hidden = !captureAllowed;
-    $("captureResult").disabled = history.captureBusy || history.finalizing || target?.key !== frameController.state.key || frameController.loading;
-    $("captureResult").textContent = history.captureBusy ? "Capturing result…" : "Capture result";
-    const canFinalize = target && !target.resultRevisionId && history.round?.feedbackStatus === "acknowledged" &&
-        ["pending", "failed"].includes(target.capture?.status || target.captureStatus || "pending");
-    $("finishCapture").hidden = !canFinalize;
-    $("finishCaptureHelp").hidden = !canFinalize;
-    $("finishCapture").disabled = history.finalizing || history.captureBusy;
-    $("finishCapture").setAttribute("aria-describedby", "finishCaptureHelp");
-    $("finishCapture").textContent = history.finalizing ? "Finishing…" : "Finish with available snapshots";
-    const items = comparisonItems();
-    const limitations = [...new Set([
-            ...(comparison.content?.limitations || []),
-            ...(comparison.source?.limitations || []),
-        ])];
-    $("historyLimitations").hidden = limitations.length === 0;
-    $("historyLimitationsList").replaceChildren();
-    for (const limitation of limitations) {
-        const line = document.createElement("li");
-        line.textContent = String(limitation).replaceAll("-", " ").replaceAll("_", " ");
-        $("historyLimitationsList").append(line);
-    }
-    const counts = displayedComparison.counts;
-    $("historyCounts").textContent = modes.length && counts
-        ? `${counts.added} Added · ${counts.modified} Modified · ${counts.removed} Removed`
-        : "";
-    $("historyCounts").hidden = !counts;
-    history.index = Math.max(0, Math.min(history.index, items.length - 1));
-    $("changeDetail").hidden = !modes.length;
-    const comparisonHeader = $("historyPanel").querySelector(".comparison-header");
-    if (comparisonHeader)
-        comparisonHeader.hidden = !modes.length;
-    if (modes.length) {
-        comparisonView.render({ ...displayedComparison, changes: items }, {
-            mode: history.mode, key: `${history.selectedId}:${history.targetKey}`,
-        });
-        comparisonView.select(history.index);
-    }
-    $("changeJump").replaceChildren();
-    for (const [index, item] of items.entries()) {
-        const option = document.createElement("option");
-        option.value = index;
-        option.textContent = `${index + 1}. ${changeKind(item)} · ${tidyMiddle(item.label || excerpt(item.after) || excerpt(item.before) || "Structure", 65)}`;
-        $("changeJump").append(option);
-    }
-    $("changeJump").value = String(history.index);
-    $("changeNavigation").hidden = items.length < 2;
-    $("previousChange").disabled = history.index === 0;
-    $("nextChange").disabled = history.index >= items.length - 1;
-    $("changePosition").textContent = `${items.length ? history.index + 1 : 0} of ${items.length}`;
+    changesRuntime.publish();
 }
 async function captureResult(round, target, automatic = false, signal) {
     if (history.captureBusy || !round || target?.key !== frameController.state.key)
@@ -1583,8 +1193,7 @@ async function captureResult(round, target, automatic = false, signal) {
                     diagnostic("capture-failure-report-failed", { message: reportError.message });
             });
         }
-        $("historyError").hidden = false;
-        $("historyError").textContent = `${err.message} Use Capture result to retry; existing captures are unchanged.`;
+        history.failures.set(`${roundId(round)}:${target.key}`, `${err.message} Use Capture result to retry; existing captures are unchanged.`);
         if (automatic)
             throw err;
     }
@@ -1602,35 +1211,21 @@ function scheduleResultCapture() {
 function setHistoryView(comparing) {
     captureEditState();
     state.comparing = comparing;
+    changesRuntime.publish();
     closeModeMenu("history-switch");
     document.body.classList.toggle("comparing", comparing);
     syncFrameInteraction();
     frameHost.current.setAttribute("aria-hidden", String(comparing));
     $("historyPanel").hidden = !comparing;
-    $("latestVersion").setAttribute("aria-pressed", String(!comparing));
-    $("seeChanges").setAttribute("aria-pressed", String(comparing));
     if (!comparing && frameController.state.pendingReload)
-        $("reloadNotice").hidden = false;
+        state.reloadVisible = true;
     if (comparing) {
         closeDrawer();
         void refreshHistory();
     }
     render();
 }
-listen($("latestVersion"), "click", () => setHistoryView(false));
-listen($("seeChanges"), "click", () => setHistoryView(true));
-listen($("roundPicker"), "change", () => void historyController.selectRound($("roundPicker").value));
-listen($("historyTarget"), "change", () => void historyController.selectTarget($("historyTarget").value));
-function jumpToChange(index) {
-    history.index = index;
-    renderHistory();
-    comparisonView.select(history.index, { scroll: true });
-}
-listen($("previousChange"), "click", () => jumpToChange(history.index - 1));
-listen($("nextChange"), "click", () => jumpToChange(history.index + 1));
-listen($("changeJump"), "change", (event) => jumpToChange(Number(event.target.value)));
-listen($("captureResult"), "click", () => void captureResult(history.round, selectedTarget()));
-listen($("finishCapture"), "click", async () => {
+async function finishCapture() {
     const target = selectedTarget();
     const round = history.round;
     if (!target || !round || history.finalizing || history.captureBusy)
@@ -1638,23 +1233,23 @@ listen($("finishCapture"), "click", async () => {
     history.finalizing = true;
     renderHistory();
     try {
-        await api(historyUrl(`/${roundId(round)}/capture`), {
+        const result = await api(historyUrl(`/${roundId(round)}/capture`), {
             method: "POST",
             body: JSON.stringify({ key: target.key, manual: true, finalUnavailable: true }),
         });
+        requireCaptureSuccess(result, target.key);
         history.failures.delete(`${roundId(round)}:${target.key}`);
         await refreshHistory();
         announce("Finished with available snapshots. Missing Content remains unavailable.");
     }
     catch (err) {
-        $("historyError").hidden = false;
-        $("historyError").textContent = `${err.message} The capture is still open; you can retry.`;
+        history.failures.set(`${roundId(round)}:${target.key}`, `${err.message} The capture is still open; you can retry.`);
     }
     finally {
         history.finalizing = false;
         renderHistory();
     }
-});
+}
 // -------------------------------------------------------------------- saving
 const saveNow = (html) => saveController.save(html);
 // ------------------------------------------------------------ frame messages
@@ -1776,7 +1371,7 @@ listen(window, "message", async (event) => {
                 state.compose.relation = geometry.relation;
                 state.compose.clip = geometry.clip;
                 state.compose.horizontal = geometry.horizontal ?? state.compose.horizontal;
-                positionCompose();
+                scheduleContextualPosition();
             }
             break;
         case "eh:commentGeometry": {
@@ -1796,7 +1391,7 @@ listen(window, "message", async (event) => {
                 visible: msg.visible !== false && rects.length > 0,
             });
             if (state.activeSavedCommentId === id) {
-                positionAlignedCard();
+                scheduleContextualPosition();
                 restoreTransientFocus(false);
             }
             break;
@@ -1809,10 +1404,10 @@ listen(window, "message", async (event) => {
             break;
         case "eh:interaction":
             closeModeMenu("frame-interaction");
-            closeCommentMenu();
+            recoveryRuntime.commands.setMenuOpen(false, { restoreFocus: false });
             break;
         case "eh:dismiss":
-            if (!$("composeText").value.trim())
+            if (!state.composerDraft.text.trim())
                 cancelCompose();
             break;
         case "eh:activate":
@@ -1920,118 +1515,18 @@ listen(window, "message", async (event) => {
     }
 });
 // --------------------------------------------------------------- UI wiring
-let composeComposing = false;
-listen($("composeAdd"), "click", commitCompose);
-listen($("composeCancel"), "click", cancelCompose);
-listen($("composeClose"), "click", cancelCompose);
-listen($("composeReveal"), "click", () => {
-    if (!state.compose)
-        return;
-    diagnostic("reveal-target-requested");
-    toFrame({ type: "eh:revealTarget", targetGeneration: state.compose.generation });
-});
-listen($("compose"), "mousedown", (event) => {
-    if (event.target.closest("button"))
-        return;
-    if (event.target !== $("composeText"))
-        $("composeText").focus();
-});
-listen($("composeText"), "compositionstart", () => {
-    composeComposing = true;
-});
-listen($("composeText"), "compositionend", () => {
-    composeComposing = false;
-});
-listen($("composeText"), "keydown", (event) => {
-    if (event.key === "Enter") {
-        event.stopPropagation();
-        if (composeComposing || event.isComposing || event.shiftKey)
-            return;
-        event.preventDefault();
-        void commitCompose();
-    }
-    if (event.key === "Escape") {
-        event.stopPropagation();
-        event.preventDefault();
-        cancelCompose();
-    }
-});
-listen($("modeButton"), "click", () => {
-    if ($("modeMenu").hidden)
-        openModeMenu();
-    else
-        closeModeMenu("trigger", { restoreFocus: true });
-});
-listen($("modeMenu"), "click", (event) => {
-    const item = event.target.closest("[data-mode]");
-    if (item)
-        void setReviewMode(item.dataset.mode);
-});
-listen($("modeMenu"), "keydown", (event) => {
-    const items = [...$("modeMenu").querySelectorAll("[data-mode]")];
-    const current = items.indexOf(document.activeElement);
-    if (event.key === "ArrowDown" || event.key === "ArrowUp") {
-        event.preventDefault();
-        const delta = event.key === "ArrowDown" ? 1 : -1;
-        items[(current + delta + items.length) % items.length].focus();
-    }
-    else if (event.key === "Escape") {
-        event.preventDefault();
-        event.stopPropagation();
-        closeModeMenu("escape", { restoreFocus: true });
-    }
-});
-listen($("commentsButton"), "click", openDrawer);
-listen($("drawerClose"), "click", closeDrawer);
-listen($("drawerBackdrop"), "click", closeDrawer);
-const dismissModeMenuOutside = (event) => {
-    if (!state.modeMenuOpen || event.target.closest(".mode-control"))
-        return;
-    closeModeMenu(event.type === "focusin" ? "parent-focus" : "parent-pointer");
-};
-listen(document, "pointerdown", dismissModeMenuOutside, true);
-listen(document, "focusin", dismissModeMenuOutside, true);
-function closeCommentMenu({ restoreFocus = false } = {}) {
-    const menu = state.commentUi.menu;
-    if (!menu)
-        return false;
-    clearOwned(state.commentUi, "menu");
-    toFrame({ type: "eh:modeMenuState", open: false });
-    if (restoreFocus)
-        requestControlFocus(menu.triggerId);
-    render();
-    return true;
-}
-const dismissCommentMenuOutside = (event) => {
-    const menu = state.commentUi.menu;
-    if (!menu)
-        return;
-    const menuElement = document.getElementById(controlId(menu.commentId, menu.surface, "menu"));
-    const trigger = document.getElementById(menu.triggerId);
-    if (menuElement?.contains(event.target) || trigger?.contains(event.target))
-        return;
-    closeCommentMenu();
-};
-listen(document, "pointerdown", dismissCommentMenuOutside, true);
-listen(document, "focusin", dismissCommentMenuOutside, true);
-const sendFeedback = () => feedbackController.send();
-listen($("send"), "click", () => void sendFeedback());
-listen($("revert"), "click", async () => {
-    const count = state.page.edits.length;
-    if (!window.confirm(`Discard all ${count} of your edits?`))
-        return;
-    try {
-        await saveController.revert();
-    }
-    catch (err) {
-        toast(err.message);
-    }
-});
 /** The session is over: freeze the page and say so. Feedback is already safe. */
 function showEnded() {
     if (document.querySelector(".ended"))
         return;
     state.ended = true;
+    state.modeMenuOpen = false;
+    toolbarRuntime.publish();
+    recoveryRuntime.publish();
+    commentsRuntime.publish();
+    contextualRuntime.publish();
+    feedbackRuntime.publish();
+    changesRuntime.publish();
     captureCoordinator.stop();
     manualCaptureController?.abort();
     captures.cancel("Review ended");
@@ -2046,60 +1541,25 @@ function showEnded() {
     overlay.append(title, line);
     document.body.append(overlay);
 }
-listen($("endReview"), "click", async () => {
-    const page = state.page;
-    const otherTotal = (state.others || []).reduce((sum, o) => sum + o.count, 0);
-    const unsent = page ? (page.comments || []).length + (page.edits || []).length + otherTotal : 0;
-    const message = unsent
-        ? `End this review? ${unsent} unsent ${unsent === 1 ? "item" : "items"} will be kept for next time.`
-        : "End this review? The waiting agent will be told to stop polling.";
-    if (!window.confirm(message))
-        return;
-    try {
-        // Ship anything still sitting in the SDK's debounce windows first.
-        await flushFrame();
-        await api(`/api/session/${state.sessionId}/end`, { method: "POST" });
-        showEnded();
-    }
-    catch (err) {
-        toast(err.message);
-    }
-});
-listen($("handoffCopy"), "click", async (event) => {
-    const button = event.currentTarget;
-    try {
-        await navigator.clipboard.writeText($("handoffCmd").textContent);
-        button.textContent = "Copied";
-        afterDelay(() => {
-            button.textContent = "Copy prompt";
-        }, 1600);
-    }
-    catch {
-        toast("Couldn't copy — select the prompt and copy it manually");
-    }
-});
-listen($("note"), "input", (event) => {
-    const el = event.target;
-    el.style.height = "auto";
-    el.style.height = `${Math.min(el.scrollHeight + 2, window.innerHeight * 0.4)}px`;
-    render(); // keep the send button in step with note-only feedback
-});
-listen($("theme"), "click", () => {
+function toggleTheme() {
     const dark = document.documentElement.dataset.theme !== "dark";
     applyTheme(dark);
     try {
         localStorage.setItem("doc-review:theme", dark ? "dark" : "light");
     }
-    catch { }
-});
+    catch (error) {
+        diagnostic("theme-preference-save-failed", { message: error.message });
+        announce("Theme changed for this review, but the preference could not be saved.");
+    }
+}
 function applyTheme(dark) {
     document.documentElement.dataset.theme = dark ? "dark" : "light";
-    const button = $("theme");
-    button.title = dark ? "Switch chrome to light" : "Switch chrome to dark";
-    button.setAttribute("aria-label", button.title);
-    replaceIcon(button, dark ? "sun" : "moon");
+    state.theme = dark ? "dark" : "light";
+    toolbarRuntime.publish();
 }
 listen(document, "keydown", (event) => {
+    if (event.defaultPrevented || feedbackRuntime.getSnapshot().dialog)
+        return;
     const meta = event.metaKey || event.ctrlKey;
     // ⌘S is reassurance only: flush pending keystrokes, never a state change.
     if (meta && event.key.toLowerCase() === "s") {
@@ -2108,25 +1568,11 @@ listen(document, "keydown", (event) => {
         renderSave();
         return;
     }
-    if (event.key === "Tab" && state.commentUi.menu) {
-        closeCommentMenu();
-        return;
-    }
     if (event.key !== "Escape")
         return;
-    const recoveryMenu = event.target.closest?.("#reviewDetails");
-    if (recoveryMenu) {
-        recoveryMenu.open = false;
-        recoveryMenu.querySelector("summary")?.focus({ preventScroll: true });
-        event.preventDefault();
-        event.stopPropagation();
-        return;
-    }
     let handled = false;
     if (state.commentUi.confirmation)
         handled = cancelDeleteConfirmation();
-    else if (state.commentUi.menu)
-        handled = closeCommentMenu({ restoreFocus: true });
     else if (state.commentUi.edit)
         handled = cancelCommentEdit();
     else if (state.compose)
@@ -2148,8 +1594,9 @@ listen(document, "keydown", (event) => {
 function holdReload() {
     frameController.holdReload();
     saveController.hold();
-    $("reloadNotice").hidden = false;
-    $("reloadMessage").textContent = saveController.state.dirty || saveController.state.conflict
+    state.reloadVisible = true;
+    state.reloadFailed = false;
+    state.reloadMessage = saveController.state.dirty || saveController.state.conflict
         ? "The source changed. This page has unsaved edits; reload discards those page edits, but keeps open comment drafts. Stale edits will not overwrite the new source."
         : "The source changed. Reload keeps your comment drafts as unresolved excerpts so they cannot attach to the wrong content.";
     captureCoordinator.reset();
@@ -2175,9 +1622,9 @@ async function reloadLatest({ explicit = false } = {}) {
     }
     const generation = beginFrameTransition();
     frameController.resetRetries();
+    state.reloadVisible = false;
     frameController.startReload();
     saveController.reset();
-    $("reloadNotice").hidden = true;
     try {
         const page = await api(pageUrl(key, state.sessionId), undefined, decodePage);
         if (frameController.state.key !== key || frameController.state.generation !== generation)
@@ -2186,13 +1633,10 @@ async function reloadLatest({ explicit = false } = {}) {
         // Keep parent-owned drafts rather than replacing their text on a source update.
         replacePage(state, page);
         saveController.reset();
-        render();
         if (state.compose) {
-            $("compose").hidden = false;
-            $("compose").classList.add("sheet");
-            $("composeError").hidden = false;
-            $("composeError").textContent = "The source changed. This draft keeps its original excerpt; cancel it to select a new target.";
+            state.composerDraft.error = "The source changed. This draft keeps its original excerpt; cancel it to select a new target.";
         }
+        render();
         await registerFrame(key, generation);
     }
     catch (err) {
@@ -2200,10 +1644,8 @@ async function reloadLatest({ explicit = false } = {}) {
             failFrame(err.message);
     }
 }
-listen($("safeReload"), "click", () => void reloadLatest({ explicit: true }));
-listen($("keepCurrent"), "click", () => { $("reloadNotice").hidden = true; announce("Keeping the current page. Return to Latest version to reload when ready."); });
 listen(window, "beforeunload", (event) => {
-    if (!saveController.state.dirty && !draftCount(state, $("note").value) && !saveController.queued(frameController.state.key))
+    if (!saveController.state.dirty && !draftCount(state, state.noteDraft.text) && !saveController.queued(frameController.state.key))
         return;
     event.preventDefault();
     event.returnValue = "";
@@ -2212,6 +1654,12 @@ listen(window, "pagehide", (event) => {
     if (event.persisted)
         return;
     state.ended = true;
+    state.modeMenuOpen = false;
+    toolbarRuntime.publish();
+    recoveryRuntime.publish();
+    commentsRuntime.publish();
+    contextualRuntime.publish();
+    changesRuntime.publish();
     captureCoordinator.stop();
     manualCaptureController?.abort();
     captures.cancel("Review closed");
@@ -2225,7 +1673,10 @@ const connect = () => reviewController.connect();
     try {
         applyTheme(localStorage.getItem("doc-review:theme") === "dark");
     }
-    catch { }
+    catch (error) {
+        applyTheme(false);
+        diagnostic("theme-preference-read-failed", { message: error.message });
+    }
     const bootstrap = await api(`/api/session/${state.sessionId}/page`);
     if (bootstrap && bootstrap.page)
         state.pollCommand = bootstrap.page.pollCommand;
@@ -2238,18 +1689,12 @@ const connect = () => reviewController.connect();
 })().catch((error) => {
     failFrame(`Review could not start: ${error.message}`);
 });
-listen(window, "resize", () => {
-    positionCompose();
-    if (state.activeSavedCommentId)
-        positionAlignedCard();
-});
+listen(window, "resize", scheduleContextualPosition);
 if (window.visualViewport) {
-    listen(window.visualViewport, "resize", positionCompose);
-    listen(window.visualViewport, "scroll", positionCompose);
+    listen(window.visualViewport, "resize", scheduleContextualPosition);
+    listen(window.visualViewport, "scroll", scheduleContextualPosition);
 }
 reviewController.own(frameHost.onFocus(() => {
-    closeCommentMenu();
     if (state.compose)
         $("compose").classList.add("pass-through");
 }));
-listen($("compose"), "focusin", () => $("compose").classList.remove("pass-through"));