@cueloop/client 0.1.0-alpha.0 → 0.1.0-alpha.10

package/src/App.submit-confirm.test.tsx

@@ -0,0 +1,183 @@
+/**
+ * The rail submit confirm (tier 2): pressing submit expands the rail's
+ * Submit button into a bordered confirm card - counts, verdict selector,
+ * summary input, word-buttons. Char-frame assertions over the real App
+ * and an in-process daemon, like App.test.tsx.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import React from "react";
+import { testRender } from "@opentui/react/test-utils";
+import { DaemonServer } from "@cueloop/daemon";
+import { makeAnchor, parseBlocks, type ReviewSession } from "@cueloop/schema";
+import { App } from "./App";
+
+const PLAN = `# Migration Plan
+
+## Context
+
+The daemon persists sessions to disk atomically.
+
+## Steps
+
+- move the store
+- add recovery
+`;
+
+let home: string;
+let server: DaemonServer;
+let session: ReviewSession;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-confirm-"));
+  server = new DaemonServer({ home, idleExitMs: 0 });
+  server.start();
+  session = server.core.sessionCreate({
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: "plan", content: PLAN, meta: { title: "Migration Plan", planPath: "plan.md" } },
+  });
+});
+afterEach(() => {
+  server.stop();
+  rmSync(home, { recursive: true, force: true });
+});
+
+async function renderApp(options: { readOnly?: boolean } = {}) {
+  const setup = await testRender(<App home={home} sessionId={session.id} readOnly={options.readOnly ?? false} />, {
+    width: 120,
+    height: 32,
+  });
+  for (let i = 0; i < 40 && !setup.captureCharFrame().includes("cueloop"); i++) {
+    await Bun.sleep(25);
+    await setup.renderOnce();
+  }
+  await setup.renderOnce();
+  return setup;
+}
+
+type Setup = Awaited<ReturnType<typeof renderApp>>;
+
+async function press(setup: Setup, k: string): Promise<void> {
+  if (k === "enter") setup.mockInput.pressKey("RETURN");
+  else if (k === "escape") {
+    setup.mockInput.pressKey("ESCAPE");
+    // a bare ESC byte is an ambiguous sequence prefix; the parser settles late
+    await Bun.sleep(120);
+  } else if (k === "left") setup.mockInput.pressKey("ARROW_LEFT");
+  else if (k === "right") setup.mockInput.pressKey("ARROW_RIGHT");
+  else await setup.mockInput.typeText(k);
+  await Bun.sleep(15);
+  await setup.renderOnce();
+}
+
+/** Seed annotations directly through the daemon core (all on one block). */
+function seedAnnotations(count: number): void {
+  const blocks = parseBlocks(PLAN);
+  for (let index = 1; index <= count; index++) {
+    server.core.sessionAnnotate(session.id, {
+      id: `a_confirm_${index}`,
+      kind: "comment",
+      anchor: makeAnchor(blocks, 2, 0, 10),
+      body: `note ${String(index).padStart(2, "0")}`,
+    });
+  }
+}
+
+describe("rail submit confirm", () => {
+  test("submit expands the Submit button into the confirm card", async () => {
+    const setup = await renderApp();
+    expect(setup.captureCharFrame()).toContain("Submit review (0)");
+    await press(setup, "enter");
+    const frame = setup.captureCharFrame();
+    // the card: title, honest counts, verdict selector, word-buttons
+    expect(frame).toContain("submit review");
+    expect(frame).toContain("0 annotations · 0 blocking");
+    expect(frame).toContain("[Approve]"); // nothing pending: approve default
+    expect(frame).toContain(" Submit ");
+    expect(frame).toContain(" Cancel ");
+    // key hints live in the status line, not on the buttons
+    expect(frame).toContain("verdict ←/→ · ⏎ submit · esc cancel");
+    // the bottom bar stayed a one-line hint: no detached verdict bar
+    expect(frame).not.toContain("Submit review (0) on ⏎");
+  });
+
+  test("left/right cycles the verdict selector in the card", async () => {
+    const setup = await renderApp();
+    await press(setup, "enter");
+    expect(setup.captureCharFrame()).toContain("[Approve]");
+    await press(setup, "right");
+    expect(setup.captureCharFrame()).toContain("[Changes]");
+    await press(setup, "right");
+    expect(setup.captureCharFrame()).toContain("[Comment]");
+    await press(setup, "left");
+    expect(setup.captureCharFrame()).toContain("[Changes]");
+  });
+
+  test("esc cancels the card and restores the plain Submit button", async () => {
+    const setup = await renderApp();
+    await press(setup, "enter");
+    expect(setup.captureCharFrame()).toContain("[Approve]");
+    await press(setup, "escape");
+    const frame = setup.captureCharFrame();
+    expect(frame).not.toContain("[Approve]");
+    expect(frame).not.toContain("0 annotations");
+    expect(frame).toContain("Submit review (0)");
+  });
+
+  test("enter in the card resolves the session through the controller", async () => {
+    seedAnnotations(1);
+    const setup = await renderApp();
+    await press(setup, "enter");
+    const frame = setup.captureCharFrame();
+    expect(frame).toContain("1 annotations · 0 blocking");
+    expect(frame).toContain("[Changes]"); // pending items: request changes default
+    await setup.mockInput.typeText("Tighten the steps.");
+    await press(setup, "enter");
+    await Bun.sleep(120);
+    await setup.renderOnce();
+    const stored = server.core.sessionGet(session.id);
+    expect(stored.status).toBe("resolved");
+    expect(stored.verdict!.kind).toBe("request_changes");
+    // the completion flow after submit is unchanged
+    expect(setup.captureCharFrame()).toContain("✎ feedback sent");
+  });
+
+  test("the annotation stack stays scrollable while the card is open", async () => {
+    seedAnnotations(12);
+    const setup = await renderApp();
+    // walk annotation focus to the last card: the rail scrolls it into view
+    for (let index = 0; index < 12; index++) await press(setup, "n");
+    const scrolled = setup.captureCharFrame();
+    expect(scrolled).toContain("note 12");
+    expect(scrolled).not.toContain("note 01");
+    await press(setup, "enter");
+    const opened = setup.captureCharFrame();
+    // the card is pinned outside the scrollbox; the stack above stays
+    // scrolled away from the top when the card takes its space
+    expect(opened).toContain("12 annotations · 0 blocking");
+    expect(opened).not.toContain("note 01");
+    // the stack still scrolls with the card open: wheel over the rail
+    // brings the last card back into view while the confirm card stays put
+    for (let turn = 0; turn < 12; turn++) await setup.mockMouse.scroll(100, 10, "down");
+    await setup.renderOnce();
+    const scrolledWithCard = setup.captureCharFrame();
+    expect(scrolledWithCard).toContain("note 12");
+    expect(scrolledWithCard).toContain("12 annotations · 0 blocking");
+    expect(scrolledWithCard).not.toContain("note 01");
+  });
+
+  test("read-only observers never see the confirm card", async () => {
+    seedAnnotations(1);
+    const setup = await renderApp({ readOnly: true });
+    await press(setup, "enter");
+    const frame = setup.captureCharFrame();
+    expect(frame).toContain("observer - read-only");
+    expect(frame).not.toContain("1 annotations");
+    expect(frame).not.toContain("[Changes]");
+    expect(setup.captureCharFrame()).not.toContain("verdict ←/→");
+    expect(server.core.sessionGet(session.id).status).toBe("pending");
+  });
+});

package/src/App.test.tsx

@@ -86,7 +86,7 @@ describe("plan rendering", () => {
     expect(frame).toContain("Context");
     expect(frame).toContain("persists sessions to disk atomically");
     expect(frame).toContain("- move the store");
-    expect(frame).toContain("REVIEW (0)");
+    expect(frame).toContain("Review (0)");
     expect(frame).toContain("Submit review (0)");
   });
 });
@@ -108,7 +108,7 @@ describe("keyboard grammar", () => {
     await press(setup, "j");
     await press(setup, "c");
     await setup.renderOnce();
-    expect(setup.captureCharFrame()).toContain("COMMENT ON");
+    expect(setup.captureCharFrame()).toContain('comment on "The daemon');
     await type(setup, "Define atomically.");
     await press(setup, "enter");
     await Bun.sleep(80);
@@ -167,7 +167,7 @@ describe("keyboard grammar", () => {
 });
 
 describe("submit", () => {
-  test("⏎ opens the verdict bar; verdict + summary resolve the session", async () => {
+  test("⏎ opens the rail confirm card; verdict + summary resolve the session", async () => {
     const setup = await renderApp();
     await press(setup, "j");
     await press(setup, "j");
@@ -177,7 +177,7 @@ describe("submit", () => {
     await Bun.sleep(80);
     await press(setup, "enter"); // open submit
     await setup.renderOnce();
-    expect(setup.captureCharFrame()).toContain("[Request changes]");
+    expect(setup.captureCharFrame()).toContain("[Changes]");
     await type(setup, "Expand the steps.");
     await press(setup, "enter");
     await Bun.sleep(120);
@@ -186,7 +186,8 @@ describe("submit", () => {
     expect(stored.status).toBe("resolved");
     expect(stored.verdict!.kind).toBe("request_changes");
     expect(stored.verdict!.feedback).toContain("Needs a phase list.");
-    expect(setup.captureCharFrame()).toContain("resolved: request changes");
+    // submit hands the reviewer back to the agent via the completion overlay
+    expect(setup.captureCharFrame()).toContain("✎ feedback sent");
   });
 
   test("approve via ←/→ verdict cycling", async () => {

package/src/config.ts

@@ -8,6 +8,8 @@ import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { OBSIDIAN_DEFAULTS, type ObsidianConfig } from "@cueloop/integration-obsidian";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 import { DARK, type Theme } from "./theme";
 
 export interface KeymapConfig {
@@ -18,9 +20,13 @@ export interface IntegrationsConfig {
   obsidian: ObsidianConfig;
 }
 
+/** Post-submit behavior: "off" prompts, 0 closes instantly, N counts down. */
+export type AutoClose = "off" | number;
+
 export interface CueloopConfig {
   keys: Record<string, string[]>;
   theme: Theme;
+  ui: { autoClose: AutoClose };
   integrations: IntegrationsConfig;
 }
 
@@ -51,6 +57,7 @@ function layer(base: CueloopConfig, raw: Record<string, unknown>): CueloopConfig
   const out: CueloopConfig = {
     keys: { ...base.keys },
     theme: { ...base.theme },
+    ui: { ...base.ui },
     integrations: { obsidian: { ...base.integrations.obsidian } },
   };
   const keys = raw["keys"] as KeymapConfig | undefined;
@@ -59,6 +66,11 @@ function layer(base: CueloopConfig, raw: Record<string, unknown>): CueloopConfig
       out.keys[action] = Array.isArray(combo) ? combo : [combo];
     }
   }
+  const ui = raw["ui"] as { auto_close?: unknown } | undefined;
+  if (ui && ui.auto_close !== undefined) {
+    if (ui.auto_close === "off") out.ui.autoClose = "off";
+    else if (typeof ui.auto_close === "number" && ui.auto_close >= 0) out.ui.autoClose = ui.auto_close;
+  }
   const theme = raw["theme"] as Partial<Record<keyof Theme, string>> | undefined;
   if (theme) {
     for (const [token, value] of Object.entries(theme)) {
@@ -86,6 +98,7 @@ export function loadConfig(opts: { repoRoot?: string; userConfigPath?: string }
   let config: CueloopConfig = {
     keys: { ...DEFAULT_KEYS },
     theme: { ...DARK },
+    ui: { autoClose: "off" },
     integrations: { obsidian: { ...OBSIDIAN_DEFAULTS } },
   };
   const userPath =
@@ -111,3 +124,27 @@ export function actionFor(keys: Record<string, string[]>, name: string, shift: b
   }
   return undefined;
 }
+
+/**
+ * Persist the auto-close choice into the user config file. Line-level TOML
+ * surgery on the one key we own: replace an existing `auto_close`, or append
+ * an `[ui]` section - a full TOML writer is not worth its weight here.
+ */
+export function persistAutoClose(value: AutoClose, userConfigPath?: string): void {
+  const path =
+    userConfigPath ??
+    process.env.CUELOOP_CONFIG ??
+    join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "cueloop", "config.toml");
+  const rendered = value === "off" ? '"off"' : String(value);
+  let text = "";
+  if (existsSync(path)) text = readFileSync(path, "utf8");
+  if (/^\s*auto_close\s*=/m.test(text)) {
+    text = text.replace(/^(\s*)auto_close\s*=.*$/m, `$1auto_close = ${rendered}`);
+  } else if (/^\[ui\]/m.test(text)) {
+    text = text.replace(/^\[ui\]\s*$/m, `[ui]\nauto_close = ${rendered}`);
+  } else {
+    text = text.trimEnd() + (text.trim() ? "\n\n" : "") + `[ui]\nauto_close = ${rendered}\n`;
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, text);
+}

package/src/herdr.test.ts

@@ -0,0 +1,68 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { focusHerdrPane, returnPaneFor } from "./herdr";
+
+let dir: string;
+const savedEnv: Record<string, string | undefined> = {};
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "cueloop-herdr-"));
+  for (const k of ["HERDR_ENV", "HERDR_PANE_ID", "HERDR_BIN_PATH", "CUELOOP_RETURN_PANE"]) {
+    savedEnv[k] = process.env[k];
+    delete process.env[k];
+  }
+});
+afterEach(() => {
+  for (const [k, v] of Object.entries(savedEnv)) {
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe("returnPaneFor", () => {
+  test("outside herdr there is never a return target", () => {
+    expect(returnPaneFor("w1:p1")).toBeUndefined();
+  });
+
+  test("env override wins, session meta is the fallback", () => {
+    process.env.HERDR_ENV = "1";
+    process.env.HERDR_PANE_ID = "w1:p9";
+    expect(returnPaneFor("w1:p1")).toBe("w1:p1");
+    process.env.CUELOOP_RETURN_PANE = "w1:p2";
+    expect(returnPaneFor("w1:p1")).toBe("w1:p2");
+  });
+
+  test("returning to our own pane is a no-op", () => {
+    process.env.HERDR_ENV = "1";
+    process.env.HERDR_PANE_ID = "w1:p1";
+    expect(returnPaneFor("w1:p1")).toBeUndefined();
+  });
+});
+
+describe("focusHerdrPane", () => {
+  test("resolves the pane's tab and focuses it", () => {
+    const log = join(dir, "calls.log");
+    const stub = join(dir, "herdr");
+    writeFileSync(
+      stub,
+      `#!/bin/sh
+echo "$@" >> "${log}"
+if [ "$1" = "pane" ]; then echo '{"result":{"pane":{"tab_id":"w1:t3"}}}'; fi
+`,
+    );
+    Bun.spawnSync(["chmod", "+x", stub]);
+    process.env.HERDR_BIN_PATH = stub;
+    expect(focusHerdrPane("w1:p1")).toBe(true);
+    const calls = readFileSync(log, "utf8").trim().split("\n");
+    expect(calls[0]).toBe("pane get w1:p1");
+    expect(calls[1]).toBe("tab focus w1:t3");
+  });
+
+  test("a missing binary never throws", () => {
+    process.env.HERDR_BIN_PATH = join(dir, "nope");
+    expect(focusHerdrPane("w1:p1")).toBe(false);
+  });
+});

package/src/herdr.ts

@@ -0,0 +1,34 @@
+/**
+ * First-class herdr return (#23): a review opened beside an agent should hand
+ * focus back to the agent's pane when it closes, not leave the reviewer on a
+ * dead tab. Detection is the ambient env contract; the return target comes
+ * from CUELOOP_RETURN_PANE (set by whoever opened this pane) or the session's
+ * recorded herdrPane (set by the adapter hook). Everything here is
+ * best-effort: focus failures never block closing the review.
+ */
+
+export function insideHerdr(): boolean {
+  return process.env.HERDR_ENV === "1";
+}
+
+export function returnPaneFor(sessionHerdrPane?: string): string | undefined {
+  if (!insideHerdr()) return undefined;
+  const pane = process.env.CUELOOP_RETURN_PANE ?? sessionHerdrPane;
+  // returning to our own pane would be a no-op at best
+  return pane && pane !== process.env.HERDR_PANE_ID ? pane : undefined;
+}
+
+/** Focus the tab holding the target pane. Synchronous: runs just before exit. */
+export function focusHerdrPane(paneId: string): boolean {
+  const bin = process.env.HERDR_BIN_PATH ?? "herdr";
+  try {
+    const got = Bun.spawnSync([bin, "pane", "get", paneId], { stdout: "pipe", stderr: "ignore" });
+    if (got.exitCode !== 0) return false;
+    const parsed = JSON.parse(got.stdout.toString()) as { result?: { pane?: { tab_id?: string } } };
+    const tab = parsed.result?.pane?.tab_id;
+    if (!tab) return false;
+    return Bun.spawnSync([bin, "tab", "focus", tab], { stdout: "ignore", stderr: "ignore" }).exitCode === 0;
+  } catch {
+    return false;
+  }
+}

package/src/keymap.test.ts

@@ -0,0 +1,270 @@
+/**
+ * The keyboard grammar as data: every mode x key produces a known intent
+ * list, the read-only rule is one gate, and plan and diff reviews share one
+ * path for annotation navigation, deletion, and submit.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { DEFAULT_KEYS } from "./config";
+import { reduceKey, type Intent, type KeyState } from "./keymap";
+
+function state(patch: Partial<KeyState> = {}): KeyState {
+  return {
+    keys: DEFAULT_KEYS,
+    readOnly: false,
+    overlay: "none",
+    view: "plan",
+    spanMode: false,
+    resolved: false,
+    hasInboxItems: true,
+    annotationCount: 1,
+    hasFocusedAnnotation: true,
+    cursorAnnotatable: true,
+    ...patch,
+  };
+}
+
+function key(name: string, shift = false): { name: string; shift: boolean } {
+  return { name, shift };
+}
+
+describe("compose overlay", () => {
+  const s = state({ overlay: "compose" });
+  const table: [string, Intent[]][] = [
+    ["escape", [{ t: "closeOverlay" }]],
+    ["return", [{ t: "saveCompose" }]],
+    ["enter", [{ t: "saveCompose" }]],
+    ["left", []],
+    ["right", []],
+    ["j", []],
+    ["q", []],
+  ];
+  for (const [name, expected] of table) {
+    test(`${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(s, key(name))).toEqual(expected);
+    });
+  }
+});
+
+describe("submit overlay", () => {
+  const s = state({ overlay: "submit" });
+  const table: [string, Intent[]][] = [
+    ["escape", [{ t: "closeOverlay" }]],
+    ["return", [{ t: "submitVerdict" }]],
+    ["enter", [{ t: "submitVerdict" }]],
+    ["left", [{ t: "cycleVerdict", dir: -1 }]],
+    ["right", [{ t: "cycleVerdict", dir: 1 }]],
+    ["j", []],
+    ["q", []],
+  ];
+  for (const [name, expected] of table) {
+    test(`${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(s, key(name))).toEqual(expected);
+    });
+  }
+});
+
+describe("completion overlay", () => {
+  const prompt = state({ overlay: "completion-prompt" });
+  const counting = state({ overlay: "completion-counting" });
+  const table: [KeyState, string, Intent[]][] = [
+    [prompt, "return", [{ t: "finishReview" }]],
+    [prompt, "enter", [{ t: "finishReview" }]],
+    [prompt, "q", [{ t: "finishReview" }]],
+    [prompt, "a", [{ t: "optInAutoClose" }]],
+    [prompt, "escape", [{ t: "dismissCompletion" }]],
+    [prompt, "j", []],
+    [counting, "return", [{ t: "finishReview" }]],
+    [counting, "q", [{ t: "finishReview" }]],
+    [counting, "a", []],
+    [counting, "escape", [{ t: "dismissCompletion" }]],
+  ];
+  for (const [s, name, expected] of table) {
+    test(`${s.overlay} ${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(s, key(name))).toEqual(expected);
+    });
+  }
+});
+
+describe("inbox mode", () => {
+  const s = state({ view: "inbox" });
+  const table: [string, Intent[]][] = [
+    ["j", [{ t: "inboxMove", to: "down" }]],
+    ["down", [{ t: "inboxMove", to: "down" }]],
+    ["k", [{ t: "inboxMove", to: "up" }]],
+    ["up", [{ t: "inboxMove", to: "up" }]],
+    ["return", [{ t: "openSession" }]],
+    ["enter", [{ t: "openSession" }]],
+    ["q", [{ t: "exit" }]],
+    ["c", []],
+    ["escape", []],
+  ];
+  for (const [name, expected] of table) {
+    test(`${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(s, key(name))).toEqual(expected);
+    });
+  }
+
+  test("an empty inbox swallows every non-quit key", () => {
+    const empty = state({ view: "inbox", hasInboxItems: false });
+    for (const name of ["j", "k", "down", "up", "return", "enter"]) {
+      expect(reduceKey(empty, key(name))).toEqual([]);
+    }
+    expect(reduceKey(empty, key("q"))).toEqual([{ t: "exit" }]);
+  });
+});
+
+describe("plan normal mode", () => {
+  const s = state();
+  const table: [string, boolean, Intent[]][] = [
+    ["j", false, [{ t: "move", to: "down" }]],
+    ["down", false, [{ t: "move", to: "down" }]],
+    ["k", false, [{ t: "move", to: "up" }]],
+    ["up", false, [{ t: "move", to: "up" }]],
+    ["g", false, [{ t: "move", to: "top" }]],
+    ["g", true, [{ t: "move", to: "bottom" }]],
+    ["v", false, [{ t: "startSpan" }]],
+    ["c", false, [{ t: "openCompose", kind: "comment", from: "cursor" }]],
+    ["s", false, [{ t: "openCompose", kind: "suggestion", from: "cursor" }]],
+    // the default state has a selected card, so Cut and edit act on the card
+    ["x", false, [{ t: "removeAnnotation" }]],
+    ["e", false, [{ t: "editCard" }]],
+    ["n", false, [{ t: "nextAnn" }]],
+    ["p", false, [{ t: "prevAnn" }]],
+    ["backspace", false, [{ t: "removeAnnotation" }]],
+    ["return", false, [{ t: "openSubmit" }]],
+    ["q", false, [{ t: "exit" }]],
+    ["escape", false, [{ t: "deselect" }]],
+    ["z", false, []],
+  ];
+  for (const [name, shift, expected] of table) {
+    test(`${shift ? "shift+" : ""}${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(s, key(name, shift))).toEqual(expected);
+    });
+  }
+
+  test("resolved sessions guard the mutating verbs", () => {
+    const r = state({ resolved: true });
+    for (const name of ["c", "s", "x", "e"]) {
+      expect(reduceKey(r, key(name))).toEqual([{ t: "status", msg: "review submitted - read-only" }]);
+    }
+    expect(reduceKey(r, key("return"))).toEqual([]);
+    expect(reduceKey(r, key("backspace"))).toEqual([]);
+  });
+
+  test("cut text cannot host a comment or a span", () => {
+    const cut = state({ cursorAnnotatable: false });
+    expect(reduceKey(cut, key("c"))).toEqual([{ t: "status", msg: "text is cut - restore it first" }]);
+    expect(reduceKey(cut, key("s"))).toEqual([{ t: "status", msg: "text is cut - restore it first" }]);
+    expect(reduceKey(cut, key("v"))).toEqual([]);
+  });
+
+  test("annotation navigation without annotations reports, delete without focus is silent", () => {
+    const none = state({ annotationCount: 0, hasFocusedAnnotation: false });
+    expect(reduceKey(none, key("n"))).toEqual([{ t: "status", msg: "no annotations" }]);
+    expect(reduceKey(none, key("p"))).toEqual([{ t: "status", msg: "no annotations" }]);
+    expect(reduceKey(none, key("backspace"))).toEqual([]);
+  });
+
+  test("without a selected card x cuts the block and e opens the editor", () => {
+    const unfocused = state({ hasFocusedAnnotation: false });
+    expect(reduceKey(unfocused, key("x"))).toEqual([{ t: "cut" }]);
+    expect(reduceKey(unfocused, key("e"))).toEqual([{ t: "edit" }]);
+  });
+});
+
+describe("span mode", () => {
+  const s = state({ spanMode: true });
+  const table: [string, Intent[]][] = [
+    ["l", [{ t: "spanKey", name: "l" }]],
+    ["h", [{ t: "spanKey", name: "h" }]],
+    ["w", [{ t: "spanKey", name: "w" }]],
+    ["b", [{ t: "spanKey", name: "b" }]],
+    ["$", [{ t: "spanKey", name: "$" }]],
+    ["0", [{ t: "spanKey", name: "0" }]],
+    ["c", [{ t: "openCompose", kind: "comment", from: "span" }]],
+    ["s", [{ t: "openCompose", kind: "suggestion", from: "span" }]],
+    ["escape", [{ t: "closeOverlay" }]],
+    ["q", [{ t: "exit" }]],
+    ["j", []],
+  ];
+  for (const [name, expected] of table) {
+    test(`${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(s, key(name))).toEqual(expected);
+    });
+  }
+});
+
+describe("diff mode", () => {
+  const s = state({ view: "diff" });
+  const table: [string, Intent[]][] = [
+    ["j", [{ t: "move", to: "down" }]],
+    ["k", [{ t: "move", to: "up" }]],
+    ["g", [{ t: "move", to: "top" }]],
+    ["c", [{ t: "openCompose", kind: "comment", from: "cursor" }]],
+    ["n", [{ t: "nextAnn" }]],
+    ["p", [{ t: "prevAnn" }]],
+    ["backspace", [{ t: "removeAnnotation" }]],
+    ["return", [{ t: "openSubmit" }]],
+    ["v", [{ t: "status", msg: "plan-only verb - diff review uses c on a line" }]],
+    ["x", [{ t: "status", msg: "plan-only verb - diff review uses c on a line" }]],
+    ["e", [{ t: "status", msg: "plan-only verb - diff review uses c on a line" }]],
+    ["s", [{ t: "status", msg: "plan-only verb - diff review uses c on a line" }]],
+    ["q", [{ t: "exit" }]],
+  ];
+  for (const [name, expected] of table) {
+    test(`${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(s, key(name))).toEqual(expected);
+    });
+  }
+
+  test("comment guards: resolved first, then non-code rows", () => {
+    expect(reduceKey(state({ view: "diff", resolved: true }), key("c"))).toEqual([
+      { t: "status", msg: "review submitted - read-only" },
+    ]);
+    expect(reduceKey(state({ view: "diff", cursorAnnotatable: false }), key("c"))).toEqual([
+      { t: "status", msg: "move to a code line to comment" },
+    ]);
+  });
+});
+
+describe("duplicated-branch collapse", () => {
+  test("plan and diff produce the same intents for annotation nav, delete, and submit", () => {
+    for (const patch of [
+      {},
+      { annotationCount: 0, hasFocusedAnnotation: false },
+      { resolved: true },
+    ] as Partial<KeyState>[]) {
+      for (const name of ["n", "p", "backspace", "return"]) {
+        const plan = reduceKey(state(patch), key(name));
+        const diff = reduceKey(state({ ...patch, view: "diff" }), key(name));
+        expect(diff).toEqual(plan);
+      }
+    }
+  });
+});
+
+describe("read-only filter", () => {
+  test("every mutating key answers observer - read-only, in plan and diff", () => {
+    for (const view of ["plan", "diff"] as const) {
+      const s = state({ view, readOnly: true });
+      for (const name of ["c", "s", "x", "e", "backspace", "return", "enter"]) {
+        expect(reduceKey(s, key(name))).toEqual([{ t: "status", msg: "observer - read-only" }]);
+      }
+    }
+  });
+
+  test("navigation and annotation focus still work for observers", () => {
+    const s = state({ readOnly: true });
+    expect(reduceKey(s, key("j"))).toEqual([{ t: "move", to: "down" }]);
+    expect(reduceKey(s, key("n"))).toEqual([{ t: "nextAnn" }]);
+    expect(reduceKey(s, key("q"))).toEqual([{ t: "exit" }]);
+  });
+
+  test("span-mode c/s are gated by key name even under a rebound keymap", () => {
+    const rebound = { ...DEFAULT_KEYS, comment: ["m"], suggest: ["t"] };
+    const s = state({ spanMode: true, readOnly: true, keys: rebound });
+    expect(reduceKey(s, key("c"))).toEqual([{ t: "status", msg: "observer - read-only" }]);
+    expect(reduceKey(s, key("s"))).toEqual([{ t: "status", msg: "observer - read-only" }]);
+  });
+});