@cueloop/client 0.1.0-alpha.2 → 0.1.0-alpha.20

package/src/key-bindings.ts

@@ -0,0 +1,353 @@
+/**
+ * Binding resolution over @opentui/keymap: the loaded config keymap
+ * registers as layers (grammar, span, compose, submit, completion) on one
+ * Keymap instance, key events resolve to action names through its dispatch,
+ * and the status-line hints generate from getActiveKeys() - a rebound key
+ * shows its real binding in the hints. The pure intent reducer (keymap.ts)
+ * stays the dispatch layer beneath: this module answers "which action", the
+ * reducer answers "which intents".
+ */
+
+import { Keymap, type KeymapEvent, type KeymapHost } from "@opentui/keymap";
+import { registerDefaultKeys } from "@opentui/keymap/addons";
+import type { KeyState } from "./keymap";
+
+export interface ResolvableKey {
+  name: string;
+  shift: boolean;
+}
+
+/** The layer-activation slice of the view state. */
+export interface KeyLayerContext {
+  overlay: KeyState["overlay"];
+  spanMode: boolean;
+}
+
+/** Hint templates keyed by the same view states the status line shows. */
+export type HintMode = "normal" | "card" | "span" | "compose" | "submit" | "walk" | "read-only";
+
+type HintEntry =
+  | { text: string }
+  | { commands: string[]; label: string; labelFirst?: boolean };
+
+const HINT_TEMPLATES: Record<HintMode, HintEntry[]> = {
+  normal: [
+    { commands: ["down", "up"], label: "move" },
+    { commands: ["span"], label: "span" },
+    { text: "drag selects" },
+    { commands: ["comment"], label: "comment" },
+    { commands: ["suggest"], label: "suggest" },
+    { commands: ["cut"], label: "cut" },
+    { commands: ["edit"], label: "edit" },
+    { commands: ["next_annotation", "prev_annotation"], label: "annotations" },
+    { commands: ["submit"], label: "submit" },
+    { commands: ["quit"], label: "quit" },
+  ],
+  card: [
+    { text: "card" },
+    { commands: ["edit"], label: "edit" },
+    { commands: ["cut"], label: "Cut" },
+    { commands: ["next_annotation", "prev_annotation"], label: "cards" },
+    { commands: ["deselect"], label: "deselect" },
+    { commands: ["submit"], label: "submit" },
+  ],
+  span: [
+    { text: "span" },
+    { commands: ["span_grow", "span_shrink"], label: "grow/shrink" },
+    { commands: ["span_slide_forward", "span_slide_back"], label: "slide" },
+    { commands: ["span_to_end"], label: "end" },
+    { commands: ["span_comment"], label: "comment" },
+    { commands: ["span_suggest"], label: "suggest" },
+    { commands: ["span_cancel"], label: "" },
+  ],
+  compose: [
+    { text: "typing" },
+    { commands: ["save_compose"], label: "save" },
+    { commands: ["cancel_overlay"], label: "cancel" },
+  ],
+  submit: [
+    { commands: ["cycle_verdict_left", "cycle_verdict_right"], label: "verdict", labelFirst: true },
+    { commands: ["submit_verdict"], label: "submit" },
+    { commands: ["cancel_submit"], label: "cancel" },
+  ],
+  walk: [
+    { text: "walk" },
+    { commands: ["walk_next"], label: "next (marks viewed)" },
+    { commands: ["walk_prev"], label: "back" },
+    { commands: ["walk_leave"], label: "leave walk" },
+    { commands: ["quit"], label: "quit" },
+  ],
+  "read-only": [
+    { text: "observer - read-only" },
+    { commands: ["down", "up"], label: "move" },
+    { commands: ["next_annotation", "prev_annotation"], label: "annotations" },
+    { commands: ["quit"], label: "quit" },
+  ],
+};
+
+/** Status-line glyphs for named keys. */
+const KEY_GLYPHS: Record<string, string> = {
+  return: "⏎",
+  enter: "⏎",
+  escape: "esc",
+  left: "←",
+  right: "→",
+  backspace: "⌫",
+  down: "↓",
+  up: "↑",
+};
+
+function makeKeymapEvent(name: string, shift = false): KeymapEvent {
+  return {
+    name,
+    ctrl: false,
+    shift,
+    meta: false,
+    preventDefault: () => {},
+    stopPropagation: () => {},
+    propagationStopped: false,
+  };
+}
+
+class HeadlessKeymapHost implements KeymapHost<object, KeymapEvent> {
+  readonly metadata = {
+    platform: "unknown" as const,
+    primaryModifier: "unknown" as const,
+    modifiers: {
+      ctrl: "supported" as const,
+      shift: "supported" as const,
+      meta: "supported" as const,
+      super: "unknown" as const,
+      hyper: "unknown" as const,
+    },
+  };
+  readonly rootTarget = {};
+  readonly isDestroyed = false;
+  private readonly pressListeners = new Set<(event: KeymapEvent) => void>();
+
+  getFocusedTarget(): object | null {
+    return null;
+  }
+  getParentTarget(): object | null {
+    return null;
+  }
+  isTargetDestroyed(): boolean {
+    return false;
+  }
+  onKeyPress(listener: (event: KeymapEvent) => void): () => void {
+    this.pressListeners.add(listener);
+    return () => this.pressListeners.delete(listener);
+  }
+  onKeyRelease(): () => void {
+    return () => {};
+  }
+  onFocusChange(): () => void {
+    return () => {};
+  }
+  onTargetDestroy(): () => void {
+    return () => {};
+  }
+  createCommandEvent(): KeymapEvent {
+    return makeKeymapEvent("");
+  }
+  emitKeyPress(event: KeymapEvent): void {
+    for (const listener of this.pressListeners) listener(event);
+  }
+}
+
+/**
+ * Terminal key events name shifted letters either "g"+shift or "G"; the
+ * keymap's canonical form is lowercase + the shift modifier. Non-letter
+ * single characters ("$", "0") already encode their shift in the character.
+ */
+function normalizedEvent(key: ResolvableKey): { name: string; shift: boolean } {
+  if (key.name.length === 1) {
+    if (/[a-zA-Z]/.test(key.name)) {
+      return { name: key.name.toLowerCase(), shift: key.shift || key.name !== key.name.toLowerCase() };
+    }
+    return { name: key.name, shift: false };
+  }
+  return { name: key.name, shift: key.shift };
+}
+
+/** Config combos write shifted letters as uppercase; the parser wants shift+. */
+function bindingKeyFor(combo: string): string {
+  if (combo.length === 1 && /[A-Z]/.test(combo)) return `shift+${combo.toLowerCase()}`;
+  return combo;
+}
+
+/** The grammar actions live in the base layer; these live in mode layers. */
+const SPAN_COMMANDS: [key: string, command: string][] = [
+  ["l", "span_grow"],
+  ["h", "span_shrink"],
+  ["w", "span_slide_forward"],
+  ["b", "span_slide_back"],
+  ["$", "span_to_end"],
+  ["0", "span_to_start"],
+  ["c", "span_comment"],
+  ["s", "span_suggest"],
+  ["escape", "span_cancel"],
+];
+
+export class KeyBindings {
+  private readonly host = new HeadlessKeymapHost();
+  private readonly keymap = new Keymap<object, KeymapEvent>(this.host);
+  private context: KeyLayerContext = { overlay: "none", spanMode: false };
+  private resolvedCommand: string | undefined;
+  private unregisterGrammarLayer: (() => void) | null = null;
+
+  constructor(keys: Record<string, string[]>) {
+    // the standard binding-string parser and event matcher
+    registerDefaultKeys(this.keymap);
+    // binding/layer `when` fields register runtime matchers, so getActiveKeys
+    // and dispatch only see the layer that owns the current mode
+    this.keymap.registerLayerFields({
+      when: (value, fieldContext) => {
+        if (typeof value === "function") fieldContext.activeWhen(value as () => boolean);
+      },
+    });
+    this.registerModeLayers();
+    this.setKeys(keys);
+  }
+
+  /** Rebuild the grammar layer from a (re)loaded config keymap. */
+  setKeys(keys: Record<string, string[]>): void {
+    this.unregisterGrammarLayer?.();
+    const bindings: { key: string; cmd: string }[] = [];
+    const commandNames = new Set<string>();
+    for (const [action, combos] of Object.entries(keys)) {
+      commandNames.add(action);
+      for (const combo of combos) bindings.push({ key: bindingKeyFor(combo), cmd: action });
+    }
+    // deselect is a hardwired escape in the plan grammar; hints show it
+    commandNames.add("deselect");
+    bindings.push({ key: "escape", cmd: "deselect" });
+    this.unregisterGrammarLayer = this.keymap.registerLayer({
+      priority: 0,
+      when: () => this.context.overlay === "none" && !this.context.spanMode,
+      bindings,
+      commands: [...commandNames].map((name) => ({
+        name,
+        run: () => {
+          this.resolvedCommand = name;
+          return true;
+        },
+      })),
+    });
+  }
+
+  private registerModeLayers(): void {
+    const record = (name: string) => ({
+      name,
+      run: () => {
+        this.resolvedCommand = name;
+        return true;
+      },
+    });
+    this.keymap.registerLayer({
+      priority: 10,
+      when: () => this.context.overlay === "none" && this.context.spanMode,
+      bindings: SPAN_COMMANDS.map(([key, command]) => ({ key, cmd: command })),
+      commands: SPAN_COMMANDS.map(([, command]) => record(command)),
+    });
+    // the walk wizard: prev/next stepping, leave, and submit from the end card
+    this.keymap.registerLayer({
+      priority: 20,
+      when: () => this.context.overlay === "walk",
+      bindings: [
+        { key: "]", cmd: "walk_next" },
+        { key: "[", cmd: "walk_prev" },
+        { key: "escape", cmd: "walk_leave" },
+        { key: "return", cmd: "walk_submit" },
+        { key: "enter", cmd: "walk_submit" },
+        { key: "q", cmd: "quit" },
+      ],
+      commands: [record("walk_next"), record("walk_prev"), record("walk_leave"), record("walk_submit"), record("quit")],
+    });
+    this.keymap.registerLayer({
+      priority: 20,
+      when: () => this.context.overlay === "compose",
+      bindings: [
+        { key: "return", cmd: "save_compose" },
+        { key: "enter", cmd: "save_compose" },
+        { key: "escape", cmd: "cancel_overlay" },
+      ],
+      commands: [record("save_compose"), record("cancel_overlay")],
+    });
+    this.keymap.registerLayer({
+      priority: 20,
+      when: () => this.context.overlay === "submit",
+      bindings: [
+        { key: "return", cmd: "submit_verdict" },
+        { key: "enter", cmd: "submit_verdict" },
+        { key: "left", cmd: "cycle_verdict_left" },
+        { key: "right", cmd: "cycle_verdict_right" },
+        { key: "escape", cmd: "cancel_submit" },
+      ],
+      commands: [
+        record("submit_verdict"),
+        record("cycle_verdict_left"),
+        record("cycle_verdict_right"),
+        record("cancel_submit"),
+      ],
+    });
+    this.keymap.registerLayer({
+      priority: 20,
+      when: () => this.context.overlay === "completion-prompt" || this.context.overlay === "completion-counting",
+      bindings: [
+        { key: "return", cmd: "finish_review" },
+        { key: "enter", cmd: "finish_review" },
+        { key: "q", cmd: "finish_review" },
+        { key: "a", cmd: "opt_in_auto_close" },
+        { key: "escape", cmd: "dismiss_completion" },
+      ],
+      commands: [record("finish_review"), record("opt_in_auto_close"), record("dismiss_completion")],
+    });
+  }
+
+  setContext(context: KeyLayerContext): void {
+    this.context = context;
+  }
+
+  /**
+   * Resolve a key event to its command name through the keymap's dispatch.
+   * In the base grammar layer the command IS the config action name, so the
+   * result feeds straight into the intent reducer.
+   */
+  resolveAction(key: ResolvableKey): string | undefined {
+    const normalized = normalizedEvent(key);
+    this.resolvedCommand = undefined;
+    this.host.emitKeyPress(makeKeymapEvent(normalized.name, normalized.shift));
+    return this.resolvedCommand;
+  }
+
+  /** First active key display for a command, mapped through the glyph table. */
+  private keyDisplayFor(command: string): string | null {
+    for (const activeKey of this.keymap.getActiveKeys({ includeBindings: true })) {
+      const bindingCommand =
+        typeof activeKey.command === "string" ? activeKey.command : activeKey.bindings?.[0]?.command;
+      if (bindingCommand !== command) continue;
+      return KEY_GLYPHS[activeKey.stroke.name] ?? activeKey.display;
+    }
+    return null;
+  }
+
+  /** The status-line hint for a view state, generated from the active keys. */
+  statusHint(mode: HintMode): string {
+    const fragments: string[] = [];
+    for (const entry of HINT_TEMPLATES[mode]) {
+      if ("text" in entry) {
+        fragments.push(entry.text);
+        continue;
+      }
+      const displays = entry.commands
+        .map((command) => this.keyDisplayFor(command))
+        .filter((display): display is string => display !== null);
+      if (!displays.length) continue;
+      const keyPart = displays.join("/");
+      if (!entry.label) fragments.push(keyPart);
+      else fragments.push(entry.labelFirst ? `${entry.label} ${keyPart}` : `${keyPart} ${entry.label}`);
+    }
+    return fragments.join(" · ");
+  }
+}

package/src/keymap.test.ts

@@ -0,0 +1,307 @@
+/**
+ * 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,
+    walkAtEnd: false,
+    ...patch,
+  };
+}
+
+function key(name: string, shift = false): { name: string; shift: boolean } {
+  return { name, shift };
+}
+
+describe("compose overlay", () => {
+  const keyState = state({ overlay: "compose" });
+  const table: [string, Intent[]][] = [
+    ["escape", [{ type: "closeOverlay" }]],
+    ["return", [{ type: "saveCompose" }]],
+    ["enter", [{ type: "saveCompose" }]],
+    ["left", []],
+    ["right", []],
+    ["j", []],
+    ["q", []],
+  ];
+  for (const [name, expected] of table) {
+    test(`${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(keyState, key(name))).toEqual(expected);
+    });
+  }
+});
+
+describe("submit overlay", () => {
+  const keyState = state({ overlay: "submit" });
+  const table: [string, Intent[]][] = [
+    ["escape", [{ type: "closeOverlay" }]],
+    ["return", [{ type: "submitVerdict" }]],
+    ["enter", [{ type: "submitVerdict" }]],
+    ["left", [{ type: "cycleVerdict", dir: -1 }]],
+    ["right", [{ type: "cycleVerdict", dir: 1 }]],
+    ["j", []],
+    ["q", []],
+  ];
+  for (const [name, expected] of table) {
+    test(`${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(keyState, 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", [{ type: "finishReview" }]],
+    [prompt, "enter", [{ type: "finishReview" }]],
+    [prompt, "q", [{ type: "finishReview" }]],
+    [prompt, "a", [{ type: "optInAutoClose" }]],
+    [prompt, "escape", [{ type: "dismissCompletion" }]],
+    [prompt, "j", []],
+    [counting, "return", [{ type: "finishReview" }]],
+    [counting, "q", [{ type: "finishReview" }]],
+    [counting, "a", [{ type: "optInAutoClose" }]],
+    [counting, "escape", [{ type: "dismissCompletion" }]],
+  ];
+  for (const [overlayState, name, expected] of table) {
+    test(`${overlayState.overlay} ${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(overlayState, key(name))).toEqual(expected);
+    });
+  }
+});
+
+describe("inbox mode", () => {
+  const keyState = state({ view: "inbox" });
+  const table: [string, Intent[]][] = [
+    ["j", [{ type: "inboxMove", to: "down" }]],
+    ["down", [{ type: "inboxMove", to: "down" }]],
+    ["k", [{ type: "inboxMove", to: "up" }]],
+    ["up", [{ type: "inboxMove", to: "up" }]],
+    ["return", [{ type: "openSession" }]],
+    ["enter", [{ type: "openSession" }]],
+    ["q", [{ type: "exit" }]],
+    ["c", []],
+    ["escape", []],
+  ];
+  for (const [name, expected] of table) {
+    test(`${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(keyState, 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([{ type: "exit" }]);
+  });
+});
+
+describe("plan normal mode", () => {
+  const keyState = state();
+  const table: [string, boolean, Intent[]][] = [
+    ["j", false, [{ type: "move", to: "down" }]],
+    ["down", false, [{ type: "move", to: "down" }]],
+    ["k", false, [{ type: "move", to: "up" }]],
+    ["up", false, [{ type: "move", to: "up" }]],
+    ["g", false, [{ type: "move", to: "top" }]],
+    ["g", true, [{ type: "move", to: "bottom" }]],
+    ["v", false, [{ type: "startSpan" }]],
+    ["c", false, [{ type: "openCompose", kind: "comment", from: "cursor" }]],
+    ["s", false, [{ type: "openCompose", kind: "suggestion", from: "cursor" }]],
+    // the default state has a selected card, so Cut and edit act on the card
+    ["x", false, [{ type: "removeAnnotation" }]],
+    ["e", false, [{ type: "editCard" }]],
+    ["n", false, [{ type: "nextAnnotation" }]],
+    ["p", false, [{ type: "prevAnnotation" }]],
+    ["backspace", false, [{ type: "removeAnnotation" }]],
+    ["return", false, [{ type: "openSubmit" }]],
+    ["q", false, [{ type: "exit" }]],
+    ["escape", false, [{ type: "deselect" }]],
+    ["z", false, []],
+  ];
+  for (const [name, shift, expected] of table) {
+    test(`${shift ? "shift+" : ""}${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(keyState, key(name, shift))).toEqual(expected);
+    });
+  }
+
+  test("resolved sessions guard the mutating verbs", () => {
+    const resolvedState = state({ resolved: true });
+    for (const name of ["c", "s", "x", "e"]) {
+      expect(reduceKey(resolvedState, key(name))).toEqual([{ type: "status", message: "review submitted - read-only" }]);
+    }
+    expect(reduceKey(resolvedState, key("return"))).toEqual([]);
+    expect(reduceKey(resolvedState, key("backspace"))).toEqual([]);
+  });
+
+  test("cut text cannot host a comment or a span", () => {
+    const cut = state({ cursorAnnotatable: false });
+    expect(reduceKey(cut, key("c"))).toEqual([{ type: "status", message: "text is cut - restore it first" }]);
+    expect(reduceKey(cut, key("s"))).toEqual([{ type: "status", message: "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([{ type: "status", message: "no annotations" }]);
+    expect(reduceKey(none, key("p"))).toEqual([{ type: "status", message: "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([{ type: "cut" }]);
+    expect(reduceKey(unfocused, key("e"))).toEqual([{ type: "edit" }]);
+  });
+});
+
+describe("span mode", () => {
+  const keyState = state({ spanMode: true });
+  const table: [string, Intent[]][] = [
+    ["l", [{ type: "spanKey", name: "l" }]],
+    ["h", [{ type: "spanKey", name: "h" }]],
+    ["w", [{ type: "spanKey", name: "w" }]],
+    ["b", [{ type: "spanKey", name: "b" }]],
+    ["$", [{ type: "spanKey", name: "$" }]],
+    ["0", [{ type: "spanKey", name: "0" }]],
+    ["c", [{ type: "openCompose", kind: "comment", from: "span" }]],
+    ["s", [{ type: "openCompose", kind: "suggestion", from: "span" }]],
+    ["escape", [{ type: "closeOverlay" }]],
+    ["q", [{ type: "exit" }]],
+    ["j", []],
+  ];
+  for (const [name, expected] of table) {
+    test(`${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(keyState, key(name))).toEqual(expected);
+    });
+  }
+});
+
+describe("diff mode", () => {
+  const keyState = state({ view: "diff" });
+  const table: [string, Intent[]][] = [
+    ["j", [{ type: "move", to: "down" }]],
+    ["k", [{ type: "move", to: "up" }]],
+    ["g", [{ type: "move", to: "top" }]],
+    ["c", [{ type: "openCompose", kind: "comment", from: "cursor" }]],
+    ["n", [{ type: "nextAnnotation" }]],
+    ["p", [{ type: "prevAnnotation" }]],
+    ["backspace", [{ type: "removeAnnotation" }]],
+    ["return", [{ type: "openSubmit" }]],
+    ["v", [{ type: "status", message: "plan-only verb - diff review uses c on a line" }]],
+    ["x", [{ type: "status", message: "plan-only verb - diff review uses c on a line" }]],
+    ["e", [{ type: "status", message: "plan-only verb - diff review uses c on a line" }]],
+    ["s", [{ type: "status", message: "plan-only verb - diff review uses c on a line" }]],
+    ["q", [{ type: "exit" }]],
+  ];
+  for (const [name, expected] of table) {
+    test(`${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(keyState, key(name))).toEqual(expected);
+    });
+  }
+
+  test("comment guards: resolved first, then non-code rows", () => {
+    expect(reduceKey(state({ view: "diff", resolved: true }), key("c"))).toEqual([
+      { type: "status", message: "review submitted - read-only" },
+    ]);
+    expect(reduceKey(state({ view: "diff", cursorAnnotatable: false }), key("c"))).toEqual([
+      { type: "status", message: "move to a code line to comment" },
+    ]);
+  });
+});
+
+describe("guided walk", () => {
+  test("w enters the walk in diff view; resolved and read-only sessions answer", () => {
+    expect(reduceKey(state({ view: "diff" }), key("w"))).toEqual([{ type: "walkStart" }]);
+    expect(reduceKey(state({ view: "diff", resolved: true }), key("w"))).toEqual([
+      { type: "status", message: "review submitted - read-only" },
+    ]);
+    expect(reduceKey(state({ view: "diff", readOnly: true }), key("w"))).toEqual([
+      { type: "status", message: "observer - read-only" },
+    ]);
+    expect(reduceKey(state(), key("w"))).toEqual([{ type: "status", message: "the guided walk is a diff-review mode" }]);
+  });
+
+  const walking = state({ view: "diff", overlay: "walk" });
+  const table: [string, Intent[]][] = [
+    ["]", [{ type: "walkForward" }]],
+    ["[", [{ type: "walkBack" }]],
+    ["escape", [{ type: "walkLeave" }]],
+    ["q", [{ type: "exit" }]],
+    // mid-walk return does nothing: submit lives on the end card only
+    ["return", []],
+    ["j", []],
+    ["c", []],
+  ];
+  for (const [name, expected] of table) {
+    test(`walking ${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(walking, key(name))).toEqual(expected);
+    });
+  }
+
+  test("the end card's return leaves the walk and opens the submit confirm", () => {
+    const atEnd = state({ view: "diff", overlay: "walk", walkAtEnd: true });
+    expect(reduceKey(atEnd, key("return"))).toEqual([{ type: "walkLeave" }, { type: "openSubmit" }]);
+    expect(reduceKey(atEnd, key("enter"))).toEqual([{ type: "walkLeave" }, { type: "openSubmit" }]);
+  });
+});
+
+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 keyState = state({ view, readOnly: true });
+      for (const name of ["c", "s", "x", "e", "backspace", "return", "enter"]) {
+        expect(reduceKey(keyState, key(name))).toEqual([{ type: "status", message: "observer - read-only" }]);
+      }
+    }
+  });
+
+  test("navigation and annotation focus still work for observers", () => {
+    const keyState = state({ readOnly: true });
+    expect(reduceKey(keyState, key("j"))).toEqual([{ type: "move", to: "down" }]);
+    expect(reduceKey(keyState, key("n"))).toEqual([{ type: "nextAnnotation" }]);
+    expect(reduceKey(keyState, key("q"))).toEqual([{ type: "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 keyState = state({ spanMode: true, readOnly: true, keys: rebound });
+    expect(reduceKey(keyState, key("c"))).toEqual([{ type: "status", message: "observer - read-only" }]);
+    expect(reduceKey(keyState, key("s"))).toEqual([{ type: "status", message: "observer - read-only" }]);
+  });
+});