@cueloop/client 0.1.0-alpha.7 → 0.1.0-alpha.9

package/src/App.tsx

@@ -1,44 +1,43 @@
 /**
- * The cueloop TUI (#22): Ledger IA reduced to its terminal shape - header,
- * center artifact pane (projection renderer), right review rail, footer hint
- * bar. Thin renderer over daemon state: every mutation round-trips through
- * DaemonClient; local state is view state only (cursor, span, overlays).
+ * The cueloop TUI (#22, #71): header, plan sheet (sheet header + inline
+ * compose + selectable lines) or diff pane, right review rail, footer hint
+ * bar. Thin renderer over the review-session controller: daemon IO and the
+ * mutation verbs live in session-controller.ts, the keyboard grammar in
+ * keymap.ts; local state is view state only (cursor, selection, overlays).
+ *
+ * The plan review grammar: selection is the entry primitive (mouse drag or
+ * keyboard span on one native renderer selection), compose happens inline
+ * under the anchor, annotation text lives in the rail while the document
+ * keeps only the kind-colored highlight, and the rail edits what the
+ * document selects - one selected id drives both sides.
  */
 
-import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { useKeyboard } from "@opentui/react";
-import { DaemonClient } from "@cueloop/daemon/client";
-import {
-  cutBlock,
-  makeAnchor,
-  restoreBlock,
-  restoreLine,
-  type Annotation,
-  type ReviewSession,
-  type VerdictKind,
-} from "@cueloop/schema";
+import React, { useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { useKeyboard, useRenderer } from "@opentui/react";
+import type { ScrollBoxRenderable, TextRenderable } from "@opentui/core";
+import { type Annotation, type ReviewSession, type VerdictKind } from "@cueloop/schema";
 import {
   blockRuns,
-  buildDisplay,
+  composeBoxHeight,
   displayText,
   marksByDisplay,
-  nextWorkBlock,
   overlayMarks,
+  revisionDelta,
   spanKey,
   startSpan,
   wrapRuns,
   type DisplayBlock,
+  type Mark,
   type SpanState,
   type StyleRun,
 } from "./view";
-import { diffRows, diffRowAnchor, diffRowLocation, type DiffRow } from "./view-diff";
-import { editInEditor } from "./editor";
+import { type DiffRow } from "./view-diff";
 import { DARK as T } from "./theme";
 import { highlightCode, type CodeToken } from "./syntax";
-import { DEFAULT_KEYS, actionFor, loadConfig, persistAutoClose, type AutoClose } from "./config";
-import { focusHerdrPane, returnPaneFor } from "./herdr";
-import { Registry, type Exporter } from "@cueloop/extension-api";
-import { createObsidianExtension, shouldExport, type ObsidianConfig } from "@cueloop/integration-obsidian";
+import { DEFAULT_KEYS, loadConfig } from "./config";
+import { returnPaneFor } from "./herdr";
+import { createReviewController } from "./session-controller";
+import { reduceKey, type Intent, type KeyState } from "./keymap";
 
 export interface AppProps {
   home?: string;
@@ -55,10 +54,10 @@ type Mode =
   | { m: "normal" }
   | { m: "span"; span: SpanState }
   | { m: "compose"; kind: "comment" | "suggestion"; dispIdx: number; start: number; end: number; text: string }
+  | { m: "railEdit"; id: string; text: string }
   | { m: "submit"; verdict: VerdictKind; summary: string };
 
-/** Verbs that write session state; an observer never reaches their handlers. */
-const MUTATING_ACTIONS = new Set(["comment", "suggest", "cut", "edit", "delete_annotation", "submit"]);
+type RailTab = "review" | "agent";
 
 const VERDICTS: VerdictKind[] = ["comment", "approve", "request_changes"];
 const VERDICT_LABEL: Record<VerdictKind, string> = {
@@ -67,353 +66,342 @@ const VERDICT_LABEL: Record<VerdictKind, string> = {
   request_changes: "Request changes",
 };
 
+/** One rendered plan line, registered for the native selection primitive. */
+interface PlanLineRef {
+  renderable: TextRenderable;
+  dispIdx: number;
+  lineIndex: number;
+  /** Block-text offset of the line's first positioned run; null for pure-del lines. */
+  lineStart: number | null;
+  /** Screen columns before the run text (cursor glyph + list marker). */
+  prefixColumns: number;
+  /** Length of the positioned run text in this line. */
+  textLength: number;
+}
+
+/** Rail card height (3 text rows + 1 margin), for reveal-scroll math. */
+const RAIL_CARD_HEIGHT = 4;
+
 export function App({ home, sessionId, readOnly = false, onExit }: AppProps): React.ReactNode {
-  const clientRef = useRef<DaemonClient | null>(null);
-  const [error, setError] = useState<string | null>(null);
-  const [inbox, setInbox] = useState<ReviewSession[] | null>(null);
-  const [session, setSession] = useState<ReviewSession | null>(null);
+  const controller = useMemo(
+    () => createReviewController({ home, sessionId, readOnly, onExit }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [home, sessionId],
+  );
+  useEffect(() => {
+    controller.connect();
+    return () => controller.close();
+  }, [controller]);
+  const { session, inbox, status, error, completion, editOrphanCount } = useSyncExternalStore(
+    controller.subscribe,
+    controller.getSnapshot,
+    controller.getSnapshot,
+  );
+  const renderer = useRenderer();
+
+  // ── view state ──────────────────────────────
   const [cursor, setCursor] = useState(0);
   const [inboxCursor, setInboxCursor] = useState(0);
   const [mode, setMode] = useState<Mode>({ m: "normal" });
   const [focusedAnn, setFocusedAnn] = useState<string | undefined>(undefined);
-  const [status, setStatus] = useState("");
-  /**
-   * Post-submit lifecycle (a review pane should hand you back to the agent,
-   * not linger): idle → prompt (auto-close off: offer the choice) or
-   * counting (configured delay) → exit. esc dismisses to the resolved view.
-   */
-  const [completion, setCompletion] = useState<
-    { phase: "idle" } | { phase: "prompt" } | { phase: "counting"; remaining: number } | { phase: "dismissed" }
-  >({ phase: "idle" });
-  const autoCloseRef = useRef<AutoClose>("off");
-  /** Close the review and, inside herdr, bounce focus back to the agent. */
-  const finishReview = useCallback(() => {
-    const pane = returnPaneFor(session?.artifact.meta.herdrPane);
-    if (pane) focusHerdrPane(pane);
-    onExit?.(0);
-  }, [session, onExit]);
+  const [railTab, setRailTab] = useState<RailTab>("review");
+  // ~2s focus pulse on the document highlight when a rail card is activated
+  const [pulseAnn, setPulseAnn] = useState<string | null>(null);
+  const pulseTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
   // live mirror of overlay input text: refs commit synchronously, so the
   // RETURN handler never reads a stale value mid-typing
   const liveInput = useRef("");
+  // rendered plan lines, for driving and reading the native selection
+  const lineRefs = useRef(new Map<string, PlanLineRef>());
+  const docScrollRef = useRef<ScrollBoxRenderable | null>(null);
+  const railScrollRef = useRef<ScrollBoxRenderable | null>(null);
   // keymap from layered config; theme overrides land on the shared tokens
   const keysRef = useRef(DEFAULT_KEYS);
-  const obsidianRef = useRef<ObsidianConfig | null>(null);
-  const exportersRef = useRef<Map<string, Exporter>>(new Map());
   useEffect(() => {
     const cfg = loadConfig({ repoRoot: session?.workspace.repoRoot });
     keysRef.current = cfg.keys;
-    autoCloseRef.current = cfg.ui.autoClose;
     Object.assign(T, cfg.theme);
-    obsidianRef.current = cfg.integrations.obsidian;
-    // bundled integrations register through the public extension API
-    const registry = new Registry();
-    void registry.load("obsidian", createObsidianExtension(cfg.integrations.obsidian)).then((rec) => {
-      exportersRef.current = rec.exporters;
-    });
-  }, [session?.workspace.repoRoot]);
-
-  // ── daemon wiring ───────────────────────────
-  useEffect(() => {
-    let closed = false;
-    void (async () => {
-      try {
-        const client = await DaemonClient.connect({ home, autostart: true });
-        if (closed) return void client.close();
-        clientRef.current = client;
-        client.onEvent((e) => {
-          // another controller/observer changed state: re-fetch
-          if (session && e.sessionId === session.id) void refreshSession(e.sessionId);
-          if (!sessionId) void refreshInbox();
-        });
-        await client.subscribe();
-        if (sessionId) {
-          setSession(await client.sessionGet(sessionId));
-        } else {
-          setInbox(await client.sessionList({ status: "pending" }));
-        }
-      } catch (err) {
-        setError(err instanceof Error ? err.message : String(err));
-      }
-    })();
-    return () => {
-      closed = true;
-      clientRef.current?.close();
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [home, sessionId]);
-
-  const refreshSession = useCallback(async (id: string) => {
-    const c = clientRef.current;
-    if (c) setSession(await c.sessionGet(id));
-  }, []);
-  const refreshInbox = useCallback(async () => {
-    const c = clientRef.current;
-    if (c) setInbox(await c.sessionList({ status: "pending" }));
-  }, []);
+    controller.applyConfig(cfg);
+  }, [session?.workspace.repoRoot, controller]);
+  useEffect(
+    () => () => {
+      if (pulseTimer.current) clearTimeout(pulseTimer.current);
+    },
+    [],
+  );
 
   // ── derived view model ──────────────────────
-  const working = session ? (session.workingCopy ?? session.artifact.content) : "";
-  const display = useMemo(
-    () => (session ? buildDisplay(session.artifact.content, session.workingCopy) : []),
-    [session],
-  );
+  const display = controller.display();
+  const rows = controller.rows();
   const marks = useMemo(
-    () => (session ? marksByDisplay(session.annotations, display, focusedAnn) : new Map()),
-    [session, display, focusedAnn],
+    () => (session ? marksByDisplay(session.annotations, display, pulseAnn ?? undefined) : new Map<number, Mark[]>()),
+    [session, display, pulseAnn],
   );
+  /** Annotation ids whose anchor resolved against the working copy. */
+  const resolvedIds = useMemo(() => {
+    const ids = new Set<string>();
+    for (const blockMarks of marks.values()) {
+      for (const mark of blockMarks) if (mark.annotationId) ids.add(mark.annotationId);
+    }
+    return ids;
+  }, [marks]);
   const resolved = session?.status === "resolved";
   const isDiff = session?.artifact.type === "diff";
-  const rows = useMemo(() => (session && isDiff ? diffRows(session.artifact.content) : []), [session, isDiff]);
-
-  const apply = useCallback((p: Promise<ReviewSession>) => {
-    p.then(setSession).catch((e: unknown) => setStatus(String(e instanceof Error ? e.message : e)));
-  }, []);
-
-  // ── verbs ───────────────────────────────────
-  const verbCut = useCallback(() => {
-    if (!session || resolved) return;
-    const d = display[cursor];
-    if (!d) return;
-    const c = clientRef.current!;
-    if (d.type === "del") {
-      const line = restoreLine(nextWorkBlock(display, cursor), working.split("\n").length);
-      // restoreBlock returns undefined when the block structure round-trips
-      // to the submitted revision - the working copy is gone
-      const restored = restoreBlock(session.artifact.content, working, d.base!, line);
-      apply(c.sessionSetWorkingCopy(session.id, restored));
-      setStatus("cut restored");
-    } else if (d.work) {
-      apply(c.sessionSetWorkingCopy(session.id, cutBlock(working, d.work)));
-      setStatus("block cut - it serializes into the diff");
-    }
-  }, [session, resolved, display, cursor, working, apply]);
-
-  const verbEdit = useCallback(() => {
-    if (!session || resolved) return;
-    try {
-      const result = editInEditor(working, "plan.md");
-      if (result.changed) {
-        apply(clientRef.current!.sessionSetWorkingCopy(session.id, result.content));
-        setStatus("edits tracked - one diff");
-      } else setStatus("no changes");
-    } catch (err) {
-      setStatus(err instanceof Error ? err.message : String(err));
-    }
-  }, [session, resolved, working, apply]);
-
-  const saveCompose = useCallback(
-    (m: Extract<Mode, { m: "compose" }>, liveText: string) => {
-      if (!session || !liveText.trim()) return setMode({ m: "normal" });
-      let anchor;
-      if (session.artifact.type === "diff") {
-        anchor = { ...diffRowAnchor(rows, m.dispIdx), blockIndex: m.dispIdx };
-      } else {
-        const workBlocks = display.filter((d) => d.work).map((d) => d.work!);
-        const workIdx = display.slice(0, m.dispIdx + 1).filter((d) => d.work).length - 1;
-        anchor = makeAnchor(workBlocks, workIdx, m.start, m.end);
-      }
-      apply(
-        clientRef.current!.sessionAnnotate(session.id, {
-          id: `a_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 5)}`,
-          kind: m.kind,
-          anchor,
-          body: liveText.trim(),
-        }),
-      );
-      setMode({ m: "normal" });
-      setStatus(m.kind === "suggestion" ? "suggestion added - the agent applies it" : "comment added");
-    },
-    [session, display, rows, apply],
-  );
 
-  const submit = useCallback(
-    (verdict: VerdictKind, summary: string) => {
-      if (!session) return;
-      clientRef.current!
-        .sessionResolve(session.id, verdict, summary)
-        .then((resolved) => {
-          setSession(resolved);
-          setStatus(`review submitted - ${verdict.replace("_", " ")}`);
-          // notes-vault export: guarded by config, default is manual (no-op)
-          const obsidian = obsidianRef.current;
-          const exporter = exportersRef.current.get("obsidian");
-          if (obsidian && exporter && shouldExport(obsidian.exportOn, verdict)) {
-            void exporter(resolved).then((r) => {
-              setStatus(r.success && r.path ? `exported to ${r.path}` : `export failed: ${r.error ?? "unknown"}`);
-            });
-          }
-          // hand the reviewer back to the agent: prompt or count down per config;
-          // inside herdr with a known return pane, closing is the default
-          const delay = autoCloseRef.current;
-          const returns = returnPaneFor(resolved.artifact.meta.herdrPane) !== undefined;
-          if (delay === 0) finishReview();
-          else if (typeof delay === "number") setCompletion({ phase: "counting", remaining: delay });
-          else if (returns) setCompletion({ phase: "counting", remaining: 3 });
-          else setCompletion({ phase: "prompt" });
-        })
-        .catch((e: unknown) => setStatus(String(e instanceof Error ? e.message : e)));
-      setMode({ m: "normal" });
-    },
-    [session, finishReview],
-  );
+  // ── the native selection: keyboard driver ───
+  const lineRefFor = (dispIdx: number, offset: number): PlanLineRef | null => {
+    for (const meta of lineRefs.current.values()) {
+      if (meta.dispIdx !== dispIdx || meta.lineStart === null) continue;
+      if (offset >= meta.lineStart && offset < meta.lineStart + meta.textLength) return meta;
+    }
+    return null;
+  };
 
+  /** Anchor/extend the renderer's native selection from keyboard span offsets. */
+  const driveNativeSelection = (span: SpanState): void => {
+    if (!renderer) return;
+    const startMeta = lineRefFor(span.dispIdx, span.start);
+    const endMeta = lineRefFor(span.dispIdx, span.end - 1);
+    if (!startMeta || !endMeta) return;
+    const startColumn = startMeta.prefixColumns + (span.start - startMeta.lineStart!);
+    const endColumn = endMeta.prefixColumns + (span.end - 1 - endMeta.lineStart!);
+    renderer.startSelection(startMeta.renderable, startMeta.renderable.x + startColumn, startMeta.renderable.y);
+    renderer.updateSelection(endMeta.renderable, endMeta.renderable.x + endColumn + 1, endMeta.renderable.y);
+  };
+  // driving needs committed layout, so it runs after render; any transition
+  // out of span mode clears the renderer selection (compose paints its own
+  // mark, and a mouse drag never changes the mode, so it survives)
   useEffect(() => {
-    if (completion.phase !== "counting") return;
-    if (completion.remaining <= 0) return void finishReview();
-    const timer = setTimeout(
-      () => setCompletion((c) => (c.phase === "counting" ? { phase: "counting", remaining: c.remaining - 1 } : c)),
-      1000,
-    );
-    return () => clearTimeout(timer);
-  }, [completion, finishReview]);
+    if (mode.m === "span") driveNativeSelection(mode.span);
+    else renderer?.clearSelection();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [mode]);
 
-  // ── keyboard grammar ────────────────────────
-  useKeyboard((key) => {
-    const name = key.name;
-    // compose/submit overlays own the keys via focused inputs; only escape here
-    if (mode.m === "compose" || mode.m === "submit") {
-      if (name === "escape") setMode({ m: "normal" });
-      else if (name === "return" || name === "enter") {
-        if (mode.m === "compose") saveCompose(mode, liveInput.current);
-        else submit(mode.verdict, liveInput.current);
-      } else if (mode.m === "submit" && (name === "left" || name === "right")) {
-        const dir = name === "left" ? -1 : 1;
-        const idx = (VERDICTS.indexOf(mode.verdict) + dir + VERDICTS.length) % VERDICTS.length;
-        setMode({ ...mode, verdict: VERDICTS[idx]! });
-      }
-      return;
-    }
-    if (completion.phase === "prompt" || completion.phase === "counting") {
-      if (name === "return" || name === "enter" || name === "q") return finishReview();
-      if (name === "a" && completion.phase === "prompt") {
-        // opt in: close in 3s from now on, persisted to the user config
-        try {
-          persistAutoClose(3);
-        } catch {
-          // a read-only config dir must not block closing the review
-        }
-        autoCloseRef.current = 3;
-        return setCompletion({ phase: "counting", remaining: 3 });
-      }
-      if (name === "escape") return setCompletion({ phase: "dismissed" });
-      return;
-    }
-    const action = actionFor(keysRef.current, name, !!key.shift);
-    if (action === "quit") return onExit?.(0);
-    if (readOnly && action && MUTATING_ACTIONS.has(action)) return setStatus("observer - read-only");
-
-    // inbox mode
-    if (!session) {
-      if (!inbox?.length) return;
-      if (name === "j" || name === "down") setInboxCursor((c) => Math.min(inbox.length - 1, c + 1));
-      else if (name === "k" || name === "up") setInboxCursor((c) => Math.max(0, c - 1));
-      else if (name === "return" || name === "enter") {
-        const s = inbox[inboxCursor];
-        if (s) setSession(s);
-      }
-      return;
+  /**
+   * Read the native selection (mouse drag) back as a block range. The quote
+   * anchors in the FIRST selected block - quote anchors resolve within one
+   * block. Columns map 1:1 onto text offsets except inside word-diffed mod
+   * blocks, where inline del runs shift the screen columns.
+   */
+  const readNativeSelection = (): { dispIdx: number; start: number; end: number } | null => {
+    if (!renderer?.hasSelection) return null;
+    const ordered = [...lineRefs.current.values()].sort(
+      (a, b) => a.dispIdx - b.dispIdx || a.lineIndex - b.lineIndex,
+    );
+    let found: { dispIdx: number; start: number; end: number } | null = null;
+    for (const meta of ordered) {
+      if (meta.lineStart === null) continue;
+      const selection = meta.renderable.getSelection();
+      if (!selection || selection.end <= selection.start) continue;
+      const startInText = Math.min(meta.textLength, Math.max(0, selection.start - meta.prefixColumns));
+      const endInText = Math.min(meta.textLength, Math.max(0, selection.end - meta.prefixColumns));
+      if (endInText <= startInText) continue;
+      const blockStart = meta.lineStart + startInText;
+      const blockEnd = meta.lineStart + endInText;
+      if (!found) found = { dispIdx: meta.dispIdx, start: blockStart, end: blockEnd };
+      else if (found.dispIdx === meta.dispIdx) found.end = Math.max(found.end, blockEnd);
     }
+    return found;
+  };
 
-    if (session.artifact.type === "diff") {
-      if (action === "down") setCursor((c) => Math.min(rows.length - 1, c + 1));
-      else if (action === "up") setCursor((c) => Math.max(0, c - 1));
-      else if (action === "top") setCursor(0);
-      else if (action === "bottom") setCursor(rows.length - 1);
-      else if (action === "comment") {
-        if (resolved) return setStatus("review submitted - read-only");
-        const row = rows[cursor];
-        if (!row || row.t === "file" || row.t === "hunk") return setStatus("move to a code line to comment");
-        liveInput.current = "";
-        setMode({ m: "compose", kind: "comment", dispIdx: cursor, start: 0, end: row.text.length, text: "" });
-      } else if (action === "next_annotation" || action === "prev_annotation") {
-        const anns = session.annotations;
-        if (!anns.length) return setStatus("no annotations");
-        const idx = anns.findIndex((a) => a.id === focusedAnn);
-        const next = idx === -1 ? 0 : (idx + (action === "next_annotation" ? 1 : -1) + anns.length) % anns.length;
-        setFocusedAnn(anns[next]!.id);
-      } else if (action === "delete_annotation") {
-        if (resolved || !focusedAnn) return;
-        apply(clientRef.current!.sessionRemoveAnnotation(session.id, focusedAnn));
-        setFocusedAnn(undefined);
-      } else if (action === "submit") {
-        if (!resolved) {
-          liveInput.current = "";
-          setMode({ m: "submit", verdict: defaultVerdict(session), summary: "" });
-        }
-      } else if (action === "span" || action === "cut" || action === "edit" || action === "suggest") {
-        setStatus("plan-only verb - diff review uses c on a line");
+  // ── selection symmetry: one selected id, both sides ──
+  const pulse = (id: string): void => {
+    setPulseAnn(id);
+    if (pulseTimer.current) clearTimeout(pulseTimer.current);
+    pulseTimer.current = setTimeout(() => setPulseAnn(null), 2000);
+  };
+
+  const revealRailCard = (annotationId: string): void => {
+    const index = session?.annotations.findIndex((annotation) => annotation.id === annotationId) ?? -1;
+    if (index >= 0) railScrollRef.current?.scrollTo(Math.max(0, index * RAIL_CARD_HEIGHT - 1));
+  };
+
+  /** Card activation scrolls the document to the anchor and pulses it. */
+  const revealAnchor = (annotationId: string): void => {
+    for (const [dispIdx, blockMarks] of marks) {
+      if (!blockMarks.some((mark) => mark.annotationId === annotationId)) continue;
+      setCursor(dispIdx);
+      try {
+        docScrollRef.current?.scrollChildIntoView(`plan-block-${dispIdx}`);
+      } catch {
+        // reveal is best-effort; selection state is already correct
       }
       return;
     }
+  };
+
+  const selectCardFromDocument = (annotationId: string): void => {
+    setFocusedAnn(annotationId);
+    revealRailCard(annotationId);
+  };
 
-    const vis = display;
-    if (mode.m === "span") {
-      if (name === "escape") return setMode({ m: "normal" });
-      if (["l", "h", "w", "b", "$", "0"].includes(name)) {
-        return setMode({ m: "span", span: spanKey(mode.span, name, displayText(vis[mode.span.dispIdx]!)) });
+  const selectCardFromRail = (annotationId: string): void => {
+    setFocusedAnn(annotationId);
+    pulse(annotationId);
+    revealAnchor(annotationId);
+  };
+
+  const openCardEdit = (annotationId: string): void => {
+    if (readOnly) return controller.setStatus("observer - read-only");
+    if (resolved) return controller.setStatus("review submitted - read-only");
+    const annotation = session?.annotations.find((candidate) => candidate.id === annotationId);
+    if (!annotation) return;
+    liveInput.current = annotation.body;
+    setMode({ m: "railEdit", id: annotation.id, text: annotation.body });
+  };
+
+  // ── keyboard grammar: build state, reduce, dispatch ──
+  const dispatch = (intent: Intent): void => {
+    switch (intent.t) {
+      case "exit":
+        return void onExit?.(0);
+      case "status":
+        return controller.setStatus(intent.msg);
+      case "move": {
+        const len = isDiff ? rows.length : display.length;
+        if (intent.to === "down") setCursor((c) => Math.min(len - 1, c + 1));
+        else if (intent.to === "up") setCursor((c) => Math.max(0, c - 1));
+        else if (intent.to === "top") setCursor(0);
+        else setCursor(len - 1);
+        return;
       }
-      if (name === "c" || name === "s") {
-        if (readOnly) return setStatus("observer - read-only");
-        liveInput.current = "";
-        return setMode({
-          m: "compose",
-          kind: name === "s" ? "suggestion" : "comment",
-          dispIdx: mode.span.dispIdx,
-          start: mode.span.start,
-          end: mode.span.end,
-          text: "",
-        });
+      case "inboxMove": {
+        const len = inbox?.length ?? 0;
+        setInboxCursor((c) => (intent.to === "down" ? Math.min(len - 1, c + 1) : Math.max(0, c - 1)));
+        return;
       }
-      return;
-    }
-
-    // normal mode
-    if (action === "down") setCursor((c) => Math.min(vis.length - 1, c + 1));
-    else if (action === "up") setCursor((c) => Math.max(0, c - 1));
-    else if (action === "top") setCursor(0);
-    else if (action === "bottom") setCursor(vis.length - 1);
-    else if (action === "span") {
-      const d = vis[cursor];
-      if (d?.work) {
+      case "openSession": {
+        const s = inbox?.[inboxCursor];
+        if (s) controller.open(s.id);
+        return;
+      }
+      case "startSpan": {
+        const d = display[cursor];
+        if (!d?.work) return;
         const span = startSpan(cursor, displayText(d));
         if (span) setMode({ m: "span", span });
+        return;
       }
-    } else if (action === "comment" || action === "suggest") {
-      if (resolved) return setStatus("review submitted - read-only");
-      const d = vis[cursor];
-      if (!d?.work) return setStatus("text is cut - restore it first");
-      liveInput.current = "";
-      setMode({
-        m: "compose",
-        kind: action === "suggest" ? "suggestion" : "comment",
-        dispIdx: cursor,
-        start: 0,
-        end: displayText(d).length,
-        text: "",
-      });
-    } else if (action === "cut") {
-      if (resolved) return setStatus("review submitted - read-only");
-      verbCut();
-    } else if (action === "edit") {
-      if (resolved) return setStatus("review submitted - read-only");
-      verbEdit();
-    } else if (action === "next_annotation" || action === "prev_annotation") {
-      const anns = session.annotations;
-      if (!anns.length) return setStatus("no annotations");
-      const idx = anns.findIndex((a) => a.id === focusedAnn);
-      const next = idx === -1 ? 0 : (idx + (action === "next_annotation" ? 1 : -1) + anns.length) % anns.length;
-      setFocusedAnn(anns[next]!.id);
-    } else if (action === "delete_annotation") {
-      if (resolved || !focusedAnn) return;
-      apply(clientRef.current!.sessionRemoveAnnotation(session.id, focusedAnn));
-      setFocusedAnn(undefined);
-      setStatus("annotation deleted");
-    } else if (action === "submit") {
-      if (!resolved) {
+      case "spanKey":
+        if (mode.m === "span") {
+          const span = spanKey(mode.span, intent.name, displayText(display[mode.span.dispIdx]!));
+          setMode({ m: "span", span });
+          driveNativeSelection(span);
+        }
+        return;
+      case "openCompose": {
         liveInput.current = "";
-        setMode({ m: "submit", verdict: defaultVerdict(session), summary: "" });
+        if (intent.from === "span" && mode.m === "span") {
+          setMode({
+            m: "compose",
+            kind: intent.kind,
+            dispIdx: mode.span.dispIdx,
+            start: mode.span.start,
+            end: mode.span.end,
+            text: "",
+          });
+        } else if (isDiff) {
+          const row = rows[cursor];
+          if (row) setMode({ m: "compose", kind: intent.kind, dispIdx: cursor, start: 0, end: row.text.length, text: "" });
+        } else {
+          // a mouse drag leaves a native selection; it wins over the cursor block
+          const native = readNativeSelection();
+          if (native) {
+            setMode({ m: "compose", kind: intent.kind, ...native, text: "" });
+          } else {
+            const d = display[cursor];
+            if (d) setMode({ m: "compose", kind: intent.kind, dispIdx: cursor, start: 0, end: displayText(d).length, text: "" });
+          }
+        }
+        return;
       }
+      case "openSubmit":
+        if (!session) return;
+        liveInput.current = "";
+        return void setMode({ m: "submit", verdict: defaultVerdict(session), summary: "" });
+      case "cut":
+        return controller.cut(cursor);
+      case "edit":
+        return controller.edit();
+      case "editCard":
+        if (focusedAnn) openCardEdit(focusedAnn);
+        return;
+      case "nextAnn":
+      case "prevAnn": {
+        const anns = session?.annotations ?? [];
+        if (!anns.length) return;
+        const idx = anns.findIndex((a) => a.id === focusedAnn);
+        const next = idx === -1 ? 0 : (idx + (intent.t === "nextAnn" ? 1 : -1) + anns.length) % anns.length;
+        return void selectCardFromDocument(anns[next]!.id);
+      }
+      case "removeAnnotation":
+        if (focusedAnn) {
+          controller.removeAnnotation(focusedAnn);
+          setFocusedAnn(undefined);
+        }
+        return;
+      case "deselect":
+        renderer?.clearSelection();
+        setFocusedAnn(undefined);
+        setPulseAnn(null);
+        return;
+      case "closeOverlay":
+        return void setMode({ m: "normal" });
+      case "saveCompose": {
+        const body = liveInput.current.trim();
+        if (mode.m === "railEdit") {
+          if (session && body) controller.updateAnnotation(mode.id, body);
+          return void setMode({ m: "normal" });
+        }
+        if (mode.m !== "compose") return;
+        if (session && body) {
+          const annotationId = controller.annotate(mode.kind, mode.dispIdx, mode.start, mode.end, body);
+          if (annotationId) setFocusedAnn(annotationId);
+        }
+        return void setMode({ m: "normal" });
+      }
+      case "submitVerdict":
+        if (mode.m === "submit") controller.submit(mode.verdict, liveInput.current);
+        return void setMode({ m: "normal" });
+      case "cycleVerdict": {
+        if (mode.m !== "submit") return;
+        const idx = (VERDICTS.indexOf(mode.verdict) + intent.dir + VERDICTS.length) % VERDICTS.length;
+        return void setMode({ ...mode, verdict: VERDICTS[idx]! });
+      }
+      case "finishReview":
+        return controller.finishReview();
+      case "optInAutoClose":
+        return controller.optInAutoClose();
+      case "dismissCompletion":
+        return controller.dismissCompletion();
     }
+  };
+
+  useKeyboard((key) => {
+    const state: KeyState = {
+      keys: keysRef.current,
+      readOnly,
+      overlay:
+        mode.m === "compose" || mode.m === "railEdit"
+          ? "compose"
+          : mode.m === "submit"
+            ? "submit"
+            : completion.phase === "prompt"
+              ? "completion-prompt"
+              : completion.phase === "counting"
+                ? "completion-counting"
+                : "none",
+      view: !session ? "inbox" : isDiff ? "diff" : "plan",
+      spanMode: mode.m === "span",
+      resolved: !!resolved,
+      hasInboxItems: !!inbox?.length,
+      annotationCount: session?.annotations.length ?? 0,
+      hasFocusedAnnotation: focusedAnn !== undefined,
+      cursorAnnotatable: isDiff
+        ? rows[cursor] !== undefined && rows[cursor]!.t !== "file" && rows[cursor]!.t !== "hunk"
+        : !!display[cursor]?.work,
+    };
+    for (const intent of reduceKey(state, { name: key.name, shift: !!key.shift })) dispatch(intent);
   });
 
   // ── render ──────────────────────────────────
@@ -435,6 +423,41 @@ export function App({ home, sessionId, readOnly = false, onExit }: AppProps): Re
     );
   }
 
+  const composeState =
+    mode.m === "compose" && !isDiff
+      ? {
+          kind: mode.kind,
+          dispIdx: mode.dispIdx,
+          quote: displayText(display[mode.dispIdx]!).slice(mode.start, mode.end),
+          text: mode.text,
+          onInput: (text: string) => {
+            liveInput.current = text;
+            setMode({ ...mode, text });
+          },
+          onSave: () => dispatch({ t: "saveCompose" }),
+          onCancel: () => dispatch({ t: "closeOverlay" }),
+        }
+      : null;
+
+  const registerLine = (key: string, renderable: TextRenderable | null, meta: Omit<PlanLineRef, "renderable">): void => {
+    if (renderable) lineRefs.current.set(key, { renderable, ...meta });
+    else lineRefs.current.delete(key);
+  };
+
+  const onLineActivate = (dispIdx: number): void => {
+    // releasing a drag-selection lands here too; a live selection is not a click
+    if (renderer?.hasSelection) return;
+    setCursor(dispIdx);
+    const annotationId = marks.get(dispIdx)?.[0]?.annotationId;
+    if (annotationId) selectCardFromDocument(annotationId);
+  };
+
+  const onEditRequest = (): void => {
+    if (readOnly) return controller.setStatus("observer - read-only");
+    if (resolved) return controller.setStatus("review submitted - read-only");
+    controller.edit();
+  };
+
   return (
     <box style={{ flexDirection: "column", width: "100%", height: "100%", backgroundColor: T.bg }}>
       <box style={{ height: 1, backgroundColor: T.panel, paddingLeft: 1, flexDirection: "row" }}>
@@ -450,12 +473,48 @@ export function App({ home, sessionId, readOnly = false, onExit }: AppProps): Re
         {isDiff ? (
           <DiffPane rows={rows} cursor={cursor} annotations={s.annotations} focusedAnn={focusedAnn} />
         ) : (
-          <PlanPane display={display} marks={marks} cursor={cursor} mode={mode} />
+          <PlanPane
+            display={display}
+            marks={marks}
+            cursor={cursor}
+            mode={mode}
+            session={s}
+            editOrphanCount={editOrphanCount}
+            compose={composeState}
+            registerLine={registerLine}
+            onLineActivate={onLineActivate}
+            onEditRequest={onEditRequest}
+            docScrollRef={docScrollRef}
+          />
         )}
-        <Rail session={s} focusedAnn={focusedAnn} pendingCount={pendingCount} />
+        <Rail
+          session={s}
+          selectedId={focusedAnn}
+          resolvedIds={isDiff ? null : resolvedIds}
+          railTab={railTab}
+          pendingCount={pendingCount}
+          cardEdit={
+            mode.m === "railEdit"
+              ? {
+                  id: mode.id,
+                  text: mode.text,
+                  onInput: (text: string) => {
+                    liveInput.current = text;
+                    setMode({ m: "railEdit", id: mode.id, text });
+                  },
+                  onSave: () => dispatch({ t: "saveCompose" }),
+                  onCancel: () => dispatch({ t: "closeOverlay" }),
+                }
+              : null
+          }
+          onTab={setRailTab}
+          onSelectCard={selectCardFromRail}
+          onActivateCard={openCardEdit}
+          railScrollRef={railScrollRef}
+        />
       </box>
-      {mode.m === "compose" ? (
-        <ComposeBar mode={mode} quote={isDiff ? (rows[mode.dispIdx]?.text ?? "") : displayText(display[mode.dispIdx]!).slice(mode.start, mode.end)} onChange={(text) => { liveInput.current = text; setMode({ ...mode, text }); }} />
+      {mode.m === "compose" && isDiff ? (
+        <ComposeBar mode={mode} quote={rows[mode.dispIdx]?.text ?? ""} onChange={(text) => { liveInput.current = text; setMode({ ...mode, text }); }} />
       ) : mode.m === "submit" ? (
         <SubmitBar mode={mode} pendingCount={pendingCount} onChange={(summary) => { liveInput.current = summary; setMode({ ...mode, summary }); }} />
       ) : (
@@ -465,7 +524,11 @@ export function App({ home, sessionId, readOnly = false, onExit }: AppProps): Re
               ? "observer - read-only · j/k move · n/p annotations · q quit"
               : mode.m === "span"
                 ? "span · l/h grow/shrink · w/b slide · $ end · c comment · s suggest · esc"
-                : "j/k move · v span · c comment · s suggest · x cut · e edit · n/p annotations · ⏎ submit · q quit"}
+                : mode.m === "compose" || mode.m === "railEdit"
+                  ? "typing · ⏎ save · esc cancel"
+                  : focusedAnn !== undefined
+                    ? "card · e edit · x Cut · n/p cards · esc deselect · ⏎ submit"
+                    : "j/k move · v span · drag selects · c comment · s suggest · x cut · e edit · n/p annotations · ⏎ submit · q quit"}
           </text>
         </box>
       )}
@@ -475,44 +538,83 @@ export function App({ home, sessionId, readOnly = false, onExit }: AppProps): Re
 
 // ── panes ─────────────────────────────────────
 
+interface ComposeState {
+  kind: "comment" | "suggestion";
+  dispIdx: number;
+  quote: string;
+  text: string;
+  onInput: (text: string) => void;
+  onSave: () => void;
+  onCancel: () => void;
+}
+
 function PlanPane({
   display,
   marks,
   cursor,
   mode,
+  session,
+  editOrphanCount,
+  compose,
+  registerLine,
+  onLineActivate,
+  onEditRequest,
+  docScrollRef,
 }: {
   display: DisplayBlock[];
-  marks: Map<number, { start: number; end: number; role: StyleRun["role"]; annotationId?: string }[]>;
+  marks: Map<number, Mark[]>;
   cursor: number;
   mode: Mode;
+  session: ReviewSession;
+  editOrphanCount: number;
+  compose: ComposeState | null;
+  registerLine: (key: string, renderable: TextRenderable | null, meta: Omit<PlanLineRef, "renderable">) => void;
+  onLineActivate: (dispIdx: number) => void;
+  onEditRequest: () => void;
+  docScrollRef: React.RefObject<ScrollBoxRenderable | null>;
 }): React.ReactNode {
   const width = 76;
-  return (
-    <scrollbox style={{ flexGrow: 1, paddingLeft: 2, paddingTop: 1 }} focused={false}>
-      {display.map((d, i) => {
-        const isCursor = i === cursor;
-        const gap = topGap(display[i - 1], d);
-        if (d.kind === "code") {
-          return (
-            <CodeBlock
-              key={i}
-              block={d}
-              isCursor={isCursor}
-              gap={gap}
-              annotated={(marks.get(i) ?? []).length > 0}
-            />
-          );
-        }
-        const blockMarks = [...(marks.get(i) ?? [])];
-        if (mode.m === "span" && mode.span.dispIdx === i) {
-          blockMarks.push({ start: mode.span.start, end: mode.span.end, role: "kspan" });
-        }
-        const runs = overlayMarks(blockRuns(d, true), blockMarks);
-        const lines = wrapRuns(runs, width - marker(d).length);
-        return (
-          <box key={i} style={{ flexDirection: "column", marginTop: gap }}>
-            {lines.map((line, li) => (
-              <text key={li} bg={isCursor ? T.cursorBg : undefined}>
+  const children: React.ReactNode[] = [];
+  for (let i = 0; i < display.length; i++) {
+    const d = display[i]!;
+    const isCursor = i === cursor;
+    const gap = topGap(display[i - 1], d);
+    if (d.kind === "code") {
+      children.push(
+        <CodeBlock key={i} id={`plan-block-${i}`} block={d} isCursor={isCursor} gap={gap} annotated={(marks.get(i) ?? []).length > 0} />,
+      );
+    } else {
+      const blockMarks = [...(marks.get(i) ?? [])];
+      if (mode.m === "span" && mode.span.dispIdx === i) {
+        blockMarks.push({ start: mode.span.start, end: mode.span.end, role: "kspan" });
+      }
+      // the compose anchor stays painted selection-style while the box is open
+      if (mode.m === "compose" && mode.dispIdx === i) {
+        blockMarks.push({ start: mode.start, end: mode.end, role: "kspan" });
+      }
+      const runs = overlayMarks(blockRuns(d, true), blockMarks);
+      const lines = wrapRuns(runs, width - marker(d).length);
+      const prefixColumns = 2 + marker(d).length;
+      children.push(
+        <box key={i} id={`plan-block-${i}`} style={{ flexDirection: "column", marginTop: gap }}>
+          {lines.map((line, li) => {
+            const positioned = line.filter((run) => run.start !== null);
+            const lineStart = positioned.length ? positioned[0]!.start : null;
+            const lastPositioned = positioned[positioned.length - 1];
+            const textLength =
+              lineStart !== null && lastPositioned ? lastPositioned.start! + lastPositioned.text.length - lineStart : 0;
+            return (
+              <text
+                key={li}
+                bg={isCursor ? T.cursorBg : undefined}
+                selectable
+                selectionBg={T.accent}
+                selectionFg={T.accentInk}
+                ref={(renderable: TextRenderable | null) =>
+                  registerLine(`${i}:${li}`, renderable, { dispIdx: i, lineIndex: li, lineStart, prefixColumns, textLength })
+                }
+                onMouseUp={() => onLineActivate(i)}
+              >
                 <span fg={isCursor ? T.accent : T.textDim}>{li === 0 ? cursorGlyph(isCursor) : "  "}</span>
                 <span fg={T.textDim}>{li === 0 ? marker(d) : " ".repeat(marker(d).length)}</span>
                 {line.map((r, ri) => (
@@ -522,20 +624,70 @@ function PlanPane({
                 ))}
                 {li === 0 && d.type !== "same" ? <span fg={tagColor(d)}> [{tagLabel(d)}]</span> : null}
               </text>
-            ))}
-          </box>
-        );
-      })}
-    </scrollbox>
+            );
+          })}
+        </box>,
+      );
+    }
+    if (compose && compose.dispIdx === i) {
+      children.push(
+        <AnnotationCard
+          key={`compose-${i}`}
+          kind={compose.kind}
+          quote={compose.quote}
+          draft={{ text: compose.text, onInput: compose.onInput, onSave: compose.onSave, onCancel: compose.onCancel }}
+        />,
+      );
+    }
+  }
+  return (
+    <box style={{ flexGrow: 1, flexDirection: "column" }}>
+      <SheetHeader session={session} onEditRequest={onEditRequest} />
+      {editOrphanCount > 0 ? (
+        <box style={{ height: 1, backgroundColor: T.markCommentBg, paddingLeft: 2 }}>
+          <text fg={T.red}>
+            {editOrphanCount} annotation{editOrphanCount === 1 ? "" : "s"} no longer match - the passage was removed.
+          </text>
+        </box>
+      ) : null}
+      <scrollbox ref={docScrollRef} style={{ flexGrow: 1, paddingLeft: 2, paddingTop: 1 }} focused={false}>
+        {children}
+      </scrollbox>
+    </box>
+  );
+}
+
+/** Sheet chrome: submitted-by + revision delta left, the Edit word-button right. */
+function SheetHeader({ session, onEditRequest }: { session: ReviewSession; onEditRequest: () => void }): React.ReactNode {
+  const revisionCount = session.revisions.length;
+  const previous = revisionCount > 1 ? session.revisions[revisionCount - 2] : undefined;
+  const delta = previous ? revisionDelta(previous.content, session.artifact.content) : null;
+  return (
+    <box style={{ height: 1, flexDirection: "row", paddingLeft: 2, paddingRight: 1 }}>
+      <text fg={T.textDim}>
+        submitted by <span fg={T.textMuted}>{session.artifact.meta.agent ?? "unknown"}</span> · revision {revisionCount}
+        {delta ? (
+          <span fg={T.green}>
+            {" "}· v{revisionCount - 1}→v{revisionCount} +{delta.added} -{delta.removed}
+          </span>
+        ) : null}
+      </text>
+      <box style={{ flexGrow: 1 }} />
+      <box onMouseUp={onEditRequest}>
+        <text fg={T.textDim}> Edit </text>
+      </box>
+    </box>
   );
 }
 
 function CodeBlock({
+  id,
   block,
   isCursor,
   gap,
   annotated,
 }: {
+  id: string;
   block: DisplayBlock;
   isCursor: boolean;
   gap: number;
@@ -556,7 +708,7 @@ function CodeBlock({
   }, [content, lang]);
   const lines: CodeToken[][] = tokens ?? content.split("\n").map((l) => [{ content: l }]);
   return (
-    <box style={{ flexDirection: "column", marginTop: gap }}>
+    <box id={id} style={{ flexDirection: "column", marginTop: gap }}>
       <text>
         <span fg={isCursor ? T.accent : T.textDim}>{cursorGlyph(isCursor)}</span>
         <span fg={T.textDim}>{lang ?? "code"}</span>
@@ -600,47 +752,193 @@ function topGap(prev: DisplayBlock | undefined, cur: DisplayBlock): number {
   return tightPair ? 0 : 1;
 }
 
+// ── the rail ──────────────────────────────────
+
+interface CardEditState {
+  id: string;
+  text: string;
+  onInput: (text: string) => void;
+  onSave: () => void;
+  onCancel: () => void;
+}
+
 function Rail({
   session,
-  focusedAnn,
+  selectedId,
+  resolvedIds,
+  railTab,
   pendingCount,
+  cardEdit,
+  onTab,
+  onSelectCard,
+  onActivateCard,
+  railScrollRef,
 }: {
   session: ReviewSession;
-  focusedAnn?: string;
+  selectedId?: string;
+  /** Ids whose anchor resolved; null = orphan display off (diff view). */
+  resolvedIds: Set<string> | null;
+  railTab: RailTab;
   pendingCount: number;
+  cardEdit: CardEditState | null;
+  onTab: (tab: RailTab) => void;
+  onSelectCard: (id: string) => void;
+  onActivateCard: (id: string) => void;
+  railScrollRef: React.RefObject<ScrollBoxRenderable | null>;
 }): React.ReactNode {
   return (
     <box style={{ width: 34, backgroundColor: T.panel, flexDirection: "column", paddingLeft: 1, paddingTop: 1 }}>
-      <text fg={T.textDim}>REVIEW ({pendingCount})</text>
-      <text fg={T.textDim}>{session.workingCopy !== undefined ? "± plan edits → one diff" : "  no direct edits"}</text>
+      <box style={{ height: 1, flexDirection: "row" }}>
+        <box onMouseUp={() => onTab("review")}>
+          <text fg={railTab === "review" ? T.accent : T.textDim}>Review ({pendingCount})</text>
+        </box>
+        <text fg={T.textDim}>{"   "}</text>
+        <box onMouseUp={() => onTab("agent")}>
+          <text fg={railTab === "agent" ? T.accent : T.textDim}>Agent</text>
+        </box>
+      </box>
       <text> </text>
-      {session.annotations.length === 0 ? (
-        <text fg={T.textDim}>no annotations yet</text>
+      {railTab === "agent" ? (
+        <AgentTab session={session} />
       ) : (
-        session.annotations.map((a) => <AnnCard key={a.id} a={a} focused={a.id === focusedAnn} />)
+        <>
+          {session.workingCopy !== undefined ? <text fg={T.textDim}>± plan edits → one diff</text> : null}
+          {session.annotations.length === 0 ? (
+            <text fg={T.textDim}>no annotations yet</text>
+          ) : (
+            <scrollbox ref={railScrollRef} style={{ flexGrow: 1 }} focused={false}>
+              {session.annotations.map((annotation) => (
+                <AnnotationCard
+                  key={annotation.id}
+                  kind={annotation.kind}
+                  quote={annotation.anchor.quote}
+                  saved={{
+                    body: annotation.body,
+                    selected: annotation.id === selectedId,
+                    orphan: resolvedIds !== null && !resolvedIds.has(annotation.id),
+                    blocking: annotationBlocking(annotation),
+                    editing:
+                      cardEdit && cardEdit.id === annotation.id
+                        ? { text: cardEdit.text, onInput: cardEdit.onInput, onSave: cardEdit.onSave, onCancel: cardEdit.onCancel }
+                        : null,
+                    onMouseUp: () =>
+                      annotation.id === selectedId ? onActivateCard(annotation.id) : onSelectCard(annotation.id),
+                  }}
+                />
+              ))}
+            </scrollbox>
+          )}
+          <box style={{ flexGrow: 1 }} />
+          <text fg={session.status === "resolved" ? T.green : T.accent}>
+            {session.status === "resolved" ? `resolved: ${session.verdict!.kind.replace("_", " ")}` : `Submit review (${pendingCount}) ⏎`}
+          </text>
+        </>
       )}
-      <box style={{ flexGrow: 1 }} />
-      <text fg={session.status === "resolved" ? T.green : T.accent}>
-        {session.status === "resolved" ? `resolved: ${session.verdict!.kind.replace("_", " ")}` : `Submit review (${pendingCount}) ⏎`}
-      </text>
     </box>
   );
 }
 
-function AnnCard({ a, focused }: { a: Annotation; focused: boolean }): React.ReactNode {
-  const color = a.kind === "suggestion" ? T.green : T.accent;
+/** Agent tab: who submitted, where the session stands, which revision. */
+function AgentTab({ session }: { session: ReviewSession }): React.ReactNode {
+  return (
+    <box style={{ flexDirection: "column", flexGrow: 1 }}>
+      <text fg={T.textMuted}>{session.artifact.meta.agent ?? "unknown"}</text>
+      <text fg={T.textDim}>status: {session.status}</text>
+      <text fg={T.textDim}>revision {session.revisions.length}</text>
+    </box>
+  );
+}
+
+/**
+ * The composer and the rail card are one component in two modes: draft props
+ * attached (bordered box inline in the document flow) or saved props attached
+ * (rail card, optionally editing its body in place). Compose, saved, and
+ * re-edit all share this rendering path.
+ */
+function AnnotationCard({
+  kind,
+  quote,
+  draft,
+  saved,
+}: {
+  kind: string;
+  quote: string;
+  draft?: { text: string; onInput: (text: string) => void; onSave: () => void; onCancel: () => void };
+  saved?: {
+    body: string;
+    selected: boolean;
+    orphan: boolean;
+    blocking: boolean;
+    editing: { text: string; onInput: (text: string) => void; onSave: () => void; onCancel: () => void } | null;
+    onMouseUp: () => void;
+  };
+}): React.ReactNode {
+  const color = kind === "suggestion" ? T.green : T.accent;
+  if (draft) {
+    const verb = kind === "suggestion" ? "suggest replacement for" : "comment on";
+    return (
+      <box
+        style={{
+          height: composeBoxHeight(),
+          marginLeft: 2,
+          marginRight: 2,
+          border: true,
+          borderStyle: "rounded",
+          borderColor: color,
+          backgroundColor: T.elevated,
+          flexDirection: "column",
+          paddingLeft: 1,
+        }}
+        title={` ${verb} "${truncate(quote, 40)}" `}
+      >
+        <input focused value={draft.text} onInput={draft.onInput} placeholder="write a note..." />
+        <SaveCancelRow onSave={draft.onSave} onCancel={draft.onCancel} />
+      </box>
+    );
+  }
+  const card = saved!;
   return (
-    <box style={{ flexDirection: "column", marginBottom: 1 }}>
-      <text fg={focused ? T.text : color}>
-        {focused ? "▸ " : "  "}
-        {a.kind.toUpperCase()}
+    <box
+      style={{ flexDirection: "column", marginBottom: 1, backgroundColor: card.selected ? T.elevated : undefined }}
+      onMouseUp={card.onMouseUp}
+    >
+      <text fg={card.selected ? T.text : color}>
+        {card.selected ? "▸ " : "  "}
+        {kind.toUpperCase()}
+        {card.blocking ? <span fg={T.red}> · BLOCKING</span> : null}
+        <span fg={T.textDim}>{card.orphan ? " · ORPHANED" : " · pending"}</span>
       </text>
-      <text fg={T.textDim}>  “{truncate(a.anchor.quote, 26)}”</text>
-      <text fg={T.textMuted}>  {truncate(a.body, 28)}</text>
+      <text fg={T.textDim}>  "{truncate(quote, 26)}"</text>
+      {card.editing ? (
+        <>
+          <input focused value={card.editing.text} onInput={card.editing.onInput} />
+          <SaveCancelRow onSave={card.editing.onSave} onCancel={card.editing.onCancel} />
+        </>
+      ) : (
+        <text fg={card.orphan ? T.textDim : T.textMuted}>  {truncate(card.body, 28)}</text>
+      )}
+    </box>
+  );
+}
+
+function SaveCancelRow({ onSave, onCancel }: { onSave: () => void; onCancel: () => void }): React.ReactNode {
+  return (
+    <box style={{ flexDirection: "row", height: 1 }}>
+      <box style={{ backgroundColor: T.accent, marginRight: 2 }} onMouseUp={onSave}>
+        <text fg={T.accentInk}> Save ⏎ </text>
+      </box>
+      <box onMouseUp={onCancel}>
+        <text fg={T.textDim}> Cancel esc </text>
+      </box>
     </box>
   );
 }
 
+/** Forward-compatible: open annotation kinds may carry a blocking flag. */
+function annotationBlocking(annotation: Annotation): boolean {
+  return (annotation as Annotation & { blocking?: boolean }).blocking === true;
+}
+
 function Inbox({ inbox, cursor }: { inbox: ReviewSession[]; cursor: number }): React.ReactNode {
   return (
     <box style={{ flexDirection: "column", width: "100%", height: "100%", backgroundColor: T.bg, padding: 1 }}>
@@ -662,6 +960,7 @@ function Inbox({ inbox, cursor }: { inbox: ReviewSession[]; cursor: number }): R
   );
 }
 
+/** Bottom compose bar - the diff view still composes here. */
 function ComposeBar({
   mode,
   quote,