@cueloop/client 0.1.0-alpha.15 → 0.1.0-alpha.17

package/src/keymap.test.ts

@@ -20,6 +20,7 @@ function state(patch: Partial<KeyState> = {}): KeyState {
     annotationCount: 1,
     hasFocusedAnnotation: true,
     cursorAnnotatable: true,
+    walkAtEnd: false,
     ...patch,
   };
 }
@@ -29,11 +30,11 @@ function key(name: string, shift = false): { name: string; shift: boolean } {
 }
 
 describe("compose overlay", () => {
-  const s = state({ overlay: "compose" });
+  const keyState = state({ overlay: "compose" });
   const table: [string, Intent[]][] = [
-    ["escape", [{ t: "closeOverlay" }]],
-    ["return", [{ t: "saveCompose" }]],
-    ["enter", [{ t: "saveCompose" }]],
+    ["escape", [{ type: "closeOverlay" }]],
+    ["return", [{ type: "saveCompose" }]],
+    ["enter", [{ type: "saveCompose" }]],
     ["left", []],
     ["right", []],
     ["j", []],
@@ -41,25 +42,25 @@ describe("compose overlay", () => {
   ];
   for (const [name, expected] of table) {
     test(`${name} -> ${JSON.stringify(expected)}`, () => {
-      expect(reduceKey(s, key(name))).toEqual(expected);
+      expect(reduceKey(keyState, key(name))).toEqual(expected);
     });
   }
 });
 
 describe("submit overlay", () => {
-  const s = state({ overlay: "submit" });
+  const keyState = 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 }]],
+    ["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(s, key(name))).toEqual(expected);
+      expect(reduceKey(keyState, key(name))).toEqual(expected);
     });
   }
 });
@@ -68,40 +69,40 @@ 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, "return", [{ type: "finishReview" }]],
+    [prompt, "enter", [{ type: "finishReview" }]],
+    [prompt, "q", [{ type: "finishReview" }]],
+    [prompt, "a", [{ type: "optInAutoClose" }]],
+    [prompt, "escape", [{ type: "dismissCompletion" }]],
     [prompt, "j", []],
-    [counting, "return", [{ t: "finishReview" }]],
-    [counting, "q", [{ t: "finishReview" }]],
-    [counting, "a", [{ t: "optInAutoClose" }]],
-    [counting, "escape", [{ t: "dismissCompletion" }]],
+    [counting, "return", [{ type: "finishReview" }]],
+    [counting, "q", [{ type: "finishReview" }]],
+    [counting, "a", [{ type: "optInAutoClose" }]],
+    [counting, "escape", [{ type: "dismissCompletion" }]],
   ];
-  for (const [s, name, expected] of table) {
-    test(`${s.overlay} ${name} -> ${JSON.stringify(expected)}`, () => {
-      expect(reduceKey(s, key(name))).toEqual(expected);
+  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 s = state({ view: "inbox" });
+  const keyState = 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" }]],
+    ["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(s, key(name))).toEqual(expected);
+      expect(reduceKey(keyState, key(name))).toEqual(expected);
     });
   }
 
@@ -110,124 +111,160 @@ describe("inbox mode", () => {
     for (const name of ["j", "k", "down", "up", "return", "enter"]) {
       expect(reduceKey(empty, key(name))).toEqual([]);
     }
-    expect(reduceKey(empty, key("q"))).toEqual([{ t: "exit" }]);
+    expect(reduceKey(empty, key("q"))).toEqual([{ type: "exit" }]);
   });
 });
 
 describe("plan normal mode", () => {
-  const s = state();
+  const keyState = 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" }]],
+    ["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, [{ 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" }]],
+    ["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(s, key(name, shift))).toEqual(expected);
+      expect(reduceKey(keyState, key(name, shift))).toEqual(expected);
     });
   }
 
   test("resolved sessions guard the mutating verbs", () => {
-    const r = state({ resolved: true });
+    const resolvedState = 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(resolvedState, key(name))).toEqual([{ type: "status", message: "review submitted - read-only" }]);
     }
-    expect(reduceKey(r, key("return"))).toEqual([]);
-    expect(reduceKey(r, key("backspace"))).toEqual([]);
+    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([{ 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("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([{ t: "status", msg: "no annotations" }]);
-    expect(reduceKey(none, key("p"))).toEqual([{ t: "status", msg: "no annotations" }]);
+    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([{ t: "cut" }]);
-    expect(reduceKey(unfocused, key("e"))).toEqual([{ t: "edit" }]);
+    expect(reduceKey(unfocused, key("x"))).toEqual([{ type: "cut" }]);
+    expect(reduceKey(unfocused, key("e"))).toEqual([{ type: "edit" }]);
   });
 });
 
 describe("span mode", () => {
-  const s = state({ spanMode: true });
+  const keyState = 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" }]],
+    ["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(s, key(name))).toEqual(expected);
+      expect(reduceKey(keyState, key(name))).toEqual(expected);
     });
   }
 });
 
 describe("diff mode", () => {
-  const s = state({ view: "diff" });
+  const keyState = 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" }]],
+    ["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(s, key(name))).toEqual(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([
-      { t: "status", msg: "review submitted - read-only" },
+      { type: "status", message: "review submitted - read-only" },
     ]);
     expect(reduceKey(state({ view: "diff", cursorAnnotatable: false }), key("c"))).toEqual([
-      { t: "status", msg: "move to a code line to comment" },
+      { 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 [
@@ -247,24 +284,24 @@ describe("duplicated-branch collapse", () => {
 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 });
+      const keyState = 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" }]);
+        expect(reduceKey(keyState, key(name))).toEqual([{ type: "status", message: "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" }]);
+    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 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" }]);
+    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" }]);
   });
 });

package/src/keymap.ts

@@ -1,5 +1,5 @@
 /**
- * The keyboard grammar as a pure reducer (#70): view state in, intents out.
+ * The keyboard grammar as a pure reducer: view state in, intents out.
  * App builds a KeyState per key event, calls reduceKey, and dispatches the
  * intents to controller verbs and view-state setters - no branch bodies live
  * in the key handler. Diff and plan reviews share one path for annotation
@@ -9,29 +9,33 @@
 import { actionFor } from "./config";
 
 export type Intent =
-  | { t: "exit" }
-  | { t: "status"; msg: string }
-  | { t: "move"; to: "down" | "up" | "top" | "bottom" }
-  | { t: "inboxMove"; to: "down" | "up" }
-  | { t: "openSession" }
-  | { t: "startSpan" }
-  | { t: "spanKey"; name: string }
-  | { t: "openCompose"; kind: "comment" | "suggestion"; from: "cursor" | "span" }
-  | { t: "openSubmit" }
-  | { t: "cut" }
-  | { t: "edit" }
-  | { t: "editCard" }
-  | { t: "nextAnn" }
-  | { t: "prevAnn" }
-  | { t: "removeAnnotation" }
-  | { t: "deselect" }
-  | { t: "closeOverlay" }
-  | { t: "saveCompose" }
-  | { t: "submitVerdict" }
-  | { t: "cycleVerdict"; dir: -1 | 1 }
-  | { t: "finishReview" }
-  | { t: "optInAutoClose" }
-  | { t: "dismissCompletion" };
+  | { type: "exit" }
+  | { type: "status"; message: string }
+  | { type: "move"; to: "down" | "up" | "top" | "bottom" }
+  | { type: "inboxMove"; to: "down" | "up" }
+  | { type: "openSession" }
+  | { type: "startSpan" }
+  | { type: "spanKey"; name: string }
+  | { type: "openCompose"; kind: "comment" | "suggestion"; from: "cursor" | "span" }
+  | { type: "openSubmit" }
+  | { type: "cut" }
+  | { type: "edit" }
+  | { type: "editCard" }
+  | { type: "nextAnnotation" }
+  | { type: "prevAnnotation" }
+  | { type: "walkStart" }
+  | { type: "walkForward" }
+  | { type: "walkBack" }
+  | { type: "walkLeave" }
+  | { type: "removeAnnotation" }
+  | { type: "deselect" }
+  | { type: "closeOverlay" }
+  | { type: "saveCompose" }
+  | { type: "submitVerdict" }
+  | { type: "cycleVerdict"; dir: -1 | 1 }
+  | { type: "finishReview" }
+  | { type: "optInAutoClose" }
+  | { type: "dismissCompletion" };
 
 export interface KeyInput {
   name: string;
@@ -43,10 +47,12 @@ export interface KeyState {
   keys: Record<string, string[]>;
   readOnly: boolean;
   /** Layer that owns keys before the grammar runs. */
-  overlay: "none" | "compose" | "submit" | "completion-prompt" | "completion-counting";
+  overlay: "none" | "walk" | "compose" | "submit" | "completion-prompt" | "completion-counting";
   view: "inbox" | "plan" | "diff";
   /** Plan-only span selection sub-mode. */
   spanMode: boolean;
+  /** The walk cursor sits on the end card - return offers the submit action. */
+  walkAtEnd: boolean;
   resolved: boolean;
   hasInboxItems: boolean;
   annotationCount: number;
@@ -56,12 +62,12 @@ export interface KeyState {
 }
 
 /** Verbs that write session state; an observer never reaches their handlers. */
-const MUTATING_ACTIONS = new Set(["comment", "suggest", "cut", "edit", "delete_annotation", "submit"]);
+const MUTATING_ACTIONS = new Set(["comment", "suggest", "cut", "edit", "delete_annotation", "submit", "walk"]);
 
 const SPAN_KEYS = ["l", "h", "w", "b", "$", "0"];
 
-function status(msg: string): Intent[] {
-  return [{ t: "status", msg }];
+function status(message: string): Intent[] {
+  return [{ type: "status", message }];
 }
 
 /**
@@ -75,23 +81,36 @@ export function reduceKey(state: KeyState, key: KeyInput, resolvedAction?: strin
   // compose/submit overlays own the keys via focused inputs; only escape,
   // return, and verdict arrows route through the grammar
   if (state.overlay === "compose" || state.overlay === "submit") {
-    if (name === "escape") return [{ t: "closeOverlay" }];
+    if (name === "escape") return [{ type: "closeOverlay" }];
     if (name === "return" || name === "enter") {
-      return [state.overlay === "compose" ? { t: "saveCompose" } : { t: "submitVerdict" }];
+      return [state.overlay === "compose" ? { type: "saveCompose" } : { type: "submitVerdict" }];
     }
     if (state.overlay === "submit" && (name === "left" || name === "right")) {
-      return [{ t: "cycleVerdict", dir: name === "left" ? -1 : 1 }];
+      return [{ type: "cycleVerdict", dir: name === "left" ? -1 : 1 }];
     }
     return [];
   }
   if (state.overlay === "completion-prompt" || state.overlay === "completion-counting") {
-    if (name === "return" || name === "enter" || name === "q") return [{ t: "finishReview" }];
-    if (name === "a") return [{ t: "optInAutoClose" }];
-    if (name === "escape") return [{ t: "dismissCompletion" }];
+    if (name === "return" || name === "enter" || name === "q") return [{ type: "finishReview" }];
+    if (name === "a") return [{ type: "optInAutoClose" }];
+    if (name === "escape") return [{ type: "dismissCompletion" }];
+    return [];
+  }
+  // the walk wizard owns its keys while active: ] advances (marking the
+  // current file viewed), [ steps back, escape leaves keeping progress, and
+  // return on the end card hands over to the submit confirm
+  if (state.overlay === "walk") {
+    if (name === "]") return [{ type: "walkForward" }];
+    if (name === "[") return [{ type: "walkBack" }];
+    if (name === "escape") return [{ type: "walkLeave" }];
+    if ((name === "return" || name === "enter") && state.walkAtEnd) {
+      return [{ type: "walkLeave" }, { type: "openSubmit" }];
+    }
+    if (name === "q") return [{ type: "exit" }];
     return [];
   }
   const action = resolvedAction ?? actionFor(state.keys, name, key.shift);
-  if (action === "quit") return [{ t: "exit" }];
+  if (action === "quit") return [{ type: "exit" }];
   // the ONE read-only rule: any mutating attempt answers instead of acting
   // (span-mode c/s are hardwired keys, so they gate by name as well)
   const mutating = MUTATING_ACTIONS.has(action ?? "") || (state.spanMode && (name === "c" || name === "s"));
@@ -105,19 +124,24 @@ export function reduceKey(state: KeyState, key: KeyInput, resolvedAction?: strin
 
 function inboxGrammar(state: KeyState, name: string): Intent[] {
   if (!state.hasInboxItems) return [];
-  if (name === "j" || name === "down") return [{ t: "inboxMove", to: "down" }];
-  if (name === "k" || name === "up") return [{ t: "inboxMove", to: "up" }];
-  if (name === "return" || name === "enter") return [{ t: "openSession" }];
+  if (name === "j" || name === "down") return [{ type: "inboxMove", to: "down" }];
+  if (name === "k" || name === "up") return [{ type: "inboxMove", to: "up" }];
+  if (name === "return" || name === "enter") return [{ type: "openSession" }];
   return [];
 }
 
 function diffGrammar(state: KeyState, action: string | undefined): Intent[] {
-  const nav = navIntent(action);
-  if (nav) return nav;
+  const navigation = navigationIntent(action);
+  if (navigation) return navigation;
+  if (action === "walk") {
+    // marking viewed writes the session record, so a resolved review answers
+    if (state.resolved) return status("review submitted - read-only");
+    return [{ type: "walkStart" }];
+  }
   if (action === "comment") {
     if (state.resolved) return status("review submitted - read-only");
     if (!state.cursorAnnotatable) return status("move to a code line to comment");
-    return [{ t: "openCompose", kind: "comment", from: "cursor" }];
+    return [{ type: "openCompose", kind: "comment", from: "cursor" }];
   }
   const shared = annotationCluster(state, action);
   if (shared) return shared;
@@ -128,38 +152,39 @@ function diffGrammar(state: KeyState, action: string | undefined): Intent[] {
 }
 
 function spanGrammar(name: string): Intent[] {
-  if (name === "escape") return [{ t: "closeOverlay" }];
-  if (SPAN_KEYS.includes(name)) return [{ t: "spanKey", name }];
+  if (name === "escape") return [{ type: "closeOverlay" }];
+  if (SPAN_KEYS.includes(name)) return [{ type: "spanKey", name }];
   if (name === "c" || name === "s") {
-    return [{ t: "openCompose", kind: name === "s" ? "suggestion" : "comment", from: "span" }];
+    return [{ type: "openCompose", kind: name === "s" ? "suggestion" : "comment", from: "span" }];
   }
   return [];
 }
 
 function planGrammar(state: KeyState, action: string | undefined, name: string): Intent[] {
-  const nav = navIntent(action);
-  if (nav) return nav;
-  if (name === "escape") return [{ t: "deselect" }];
-  if (action === "span") return state.cursorAnnotatable ? [{ t: "startSpan" }] : [];
+  const navigation = navigationIntent(action);
+  if (navigation) return navigation;
+  if (action === "walk") return status("the guided walk is a diff-review mode");
+  if (name === "escape") return [{ type: "deselect" }];
+  if (action === "span") return state.cursorAnnotatable ? [{ type: "startSpan" }] : [];
   if (action === "comment" || action === "suggest") {
     if (state.resolved) return status("review submitted - read-only");
     if (!state.cursorAnnotatable) return status("text is cut - restore it first");
-    return [{ t: "openCompose", kind: action === "suggest" ? "suggestion" : "comment", from: "cursor" }];
+    return [{ type: "openCompose", kind: action === "suggest" ? "suggestion" : "comment", from: "cursor" }];
   }
   if (action === "cut" || action === "edit") {
     if (state.resolved) return status("review submitted - read-only");
     // the document selects, the rail edits: with a card selected, Cut deletes
     // the annotation and edit rewrites the card body in place
-    if (state.hasFocusedAnnotation) return [action === "cut" ? { t: "removeAnnotation" } : { t: "editCard" }];
-    return [{ t: action }];
+    if (state.hasFocusedAnnotation) return [action === "cut" ? { type: "removeAnnotation" } : { type: "editCard" }];
+    return [{ type: action }];
   }
   return annotationCluster(state, action) ?? [];
 }
 
 /** Cursor movement is the same intent everywhere; views clamp their own bounds. */
-function navIntent(action: string | undefined): Intent[] | null {
+function navigationIntent(action: string | undefined): Intent[] | null {
   if (action === "down" || action === "up" || action === "top" || action === "bottom") {
-    return [{ t: "move", to: action }];
+    return [{ type: "move", to: action }];
   }
   return null;
 }
@@ -168,12 +193,12 @@ function navIntent(action: string | undefined): Intent[] | null {
 function annotationCluster(state: KeyState, action: string | undefined): Intent[] | null {
   if (action === "next_annotation" || action === "prev_annotation") {
     if (!state.annotationCount) return status("no annotations");
-    return [{ t: action === "next_annotation" ? "nextAnn" : "prevAnn" }];
+    return [{ type: action === "next_annotation" ? "nextAnnotation" : "prevAnnotation" }];
   }
   if (action === "delete_annotation") {
     if (state.resolved || !state.hasFocusedAnnotation) return [];
-    return [{ t: "removeAnnotation" }];
+    return [{ type: "removeAnnotation" }];
   }
-  if (action === "submit") return state.resolved ? [] : [{ t: "openSubmit" }];
+  if (action === "submit") return state.resolved ? [] : [{ type: "openSubmit" }];
   return null;
 }

package/src/run.ts

@@ -10,15 +10,15 @@ export interface RunClientOptions {
   home?: string;
 }
 
-export async function runClient(opts: RunClientOptions): Promise<number> {
+export async function runClient(options: RunClientOptions): Promise<number> {
   // mouse movement reporting makes multiplexers forward drags to the app,
   // so the renderer's native selection is the drag driver
   const renderer = await createCliRenderer({ enableMouseMovement: true });
   return new Promise<number>((resolve) => {
     createRoot(renderer).render(
       React.createElement(App, {
-        home: opts.home,
-        sessionId: opts.sessionId,
+        home: options.home,
+        sessionId: options.sessionId,
         onExit: (code: number) => {
           renderer.destroy();
           resolve(code);