@cueloop/client 0.1.0-alpha.14 → 0.1.0-alpha.16

package/src/components/WalkWizard.tsx

@@ -0,0 +1,146 @@
+/**
+ * The guided walk's focused card wizard (#83): one card per changed file
+ * floating over the dimmed diff, with a plain step count in the title - no
+ * progress bar. Below the main card a separate gray-bordered block carries
+ * the submitting agent's note for the file, when one exists. Past the last
+ * file the end card offers the submit action directly with honest counts.
+ * The keys live in the keymap's walk overlay; this component only renders.
+ */
+
+import React from "react";
+import type { Theme } from "../theme";
+import { useComponentTheme } from "./theme-context";
+import type { WalkFile } from "../walk";
+import { viewedCount } from "../walk";
+import { Card } from "./primitives/Card";
+import { Button } from "./primitives/Button";
+import { Toolbar } from "./primitives/Toolbar";
+
+export interface WalkWizardProps {
+  files: WalkFile[];
+  /** The wizard step; index === files.length renders the end card. */
+  index: number;
+  viewedPaths: ReadonlySet<string>;
+  /** The agent's note for the current file; the gray block renders only when set. */
+  note?: string;
+  /** Terminal width bounds the card width. */
+  terminalWidth: number;
+  /** End-card submit: leaves the walk and opens the rail confirm. */
+  onSubmitRequest: () => void;
+  onBack: () => void;
+  theme?: Theme;
+}
+
+/** The card never crowds the terminal edge nor stretches past reading width. */
+function wizardWidth(terminalWidth: number): number {
+  return Math.min(72, Math.max(24, terminalWidth - 8));
+}
+
+/** Note rows from a crude wrap estimate, capped so the block stays a block. */
+function noteRows(note: string, innerWidth: number): number {
+  return Math.min(3, Math.max(1, Math.ceil(note.length / Math.max(1, innerWidth))));
+}
+
+export function WalkWizard({
+  files,
+  index,
+  viewedPaths,
+  note,
+  terminalWidth,
+  onSubmitRequest,
+  onBack,
+  theme,
+}: WalkWizardProps): React.ReactNode {
+  const tokens = useComponentTheme(theme);
+  const width = wizardWidth(terminalWidth);
+  const viewed = viewedCount(files, viewedPaths);
+  const atEnd = index >= files.length;
+  const currentFile = files[index];
+
+  return (
+    <box
+      style={{
+        position: "absolute",
+        left: 0,
+        top: 0,
+        width: "100%",
+        height: "100%",
+        alignItems: "center",
+        justifyContent: "center",
+        flexDirection: "column",
+      }}
+    >
+      <box style={{ width, flexDirection: "column" }}>
+        {atEnd || !currentFile ? (
+          <Card
+            title=" walk complete "
+            contentRows={3}
+            borderColor={tokens.green}
+            backgroundColor={tokens.panel}
+            theme={theme}
+          >
+            <text fg={tokens.text}>
+              {viewed === files.length
+                ? `every file viewed (${viewed}/${files.length})`
+                : `${viewed} of ${files.length} files viewed`}
+            </text>
+            <box style={{ height: 1 }} />
+            <Toolbar>
+              <Button variant="solid" marginRight={2} onPress={onSubmitRequest} theme={theme}>
+                {" Submit review "}
+              </Button>
+              <Button onPress={onBack} theme={theme}>
+                {" [ back "}
+              </Button>
+            </Toolbar>
+          </Card>
+        ) : (
+          <>
+            <Card
+              title={` file ${index + 1} of ${files.length} · ${viewed} viewed `}
+              contentRows={3 + Math.max(1, currentFile.preview.length)}
+              borderColor={tokens.accent}
+              backgroundColor={tokens.panel}
+              theme={theme}
+            >
+              <text fg={tokens.text}>{currentFile.path}</text>
+              <text>
+                <span fg={tokens.green}>{`+${currentFile.added}`}</span>
+                <span fg={tokens.textDim}>{" "}</span>
+                <span fg={tokens.red}>{`-${currentFile.removed}`}</span>
+                <span fg={tokens.textDim}>{viewedPaths.has(currentFile.path) ? " · viewed" : ""}</span>
+              </text>
+              <box style={{ height: 1 }} />
+              {currentFile.preview.length === 0 ? (
+                <text fg={tokens.textDim}>(no changed lines)</text>
+              ) : (
+                currentFile.preview.map((previewLine, previewIndex) => (
+                  <text
+                    key={previewIndex}
+                    style={{ wrapMode: "none" }}
+                    fg={previewLine.sign === "+" ? tokens.insFg : tokens.delFg}
+                  >
+                    {previewLine.sign + previewLine.text}
+                  </text>
+                ))
+              )}
+            </Card>
+            {note !== undefined ? (
+              <box style={{ marginTop: 1, flexDirection: "column" }}>
+                <Card
+                  title=" agent note "
+                  contentRows={noteRows(note, width - 4)}
+                  borderColor={tokens.border}
+                  backgroundColor={tokens.panel}
+                  theme={theme}
+                >
+                  <text fg={tokens.textMuted}>{note}</text>
+                </Card>
+              </box>
+            ) : null}
+          </>
+        )}
+      </box>
+    </box>
+  );
+}

package/src/components/__snapshots__/stories.test.tsx.snap

@@ -262,11 +262,11 @@ exports[`stories catalog CompletionOverlay/ApprovedPrompt renders, snapshots, an
                                                                                 
                                                                                 
                                                                                 
-                               ✓ review approved                                
+                                review approved                                 
                                                                                 
                  The agent has your approval and is unblocked.                  
                                                                                 
-             ⏎ close · a always close after submit (3s) · esc stay              
+               close [return] · return to plan [esc] · always [a]               
                                                                                 
                                                                                 
                                                                                 
@@ -289,13 +289,13 @@ exports[`stories catalog CompletionOverlay/FeedbackCounting renders, snapshots,
                                                                                 
                                                                                 
                                                                                 
-                                                                                
-                                ✎ feedback sent                                 
+                                 feedback sent                                  
                                                                                 
                  The agent has your feedback and is unblocked.                  
+                      returning to agent/worker-3 on close                      
                        exported to vault/cueloop/plan.md                        
                                                                                 
-         closing in 3s - returning to agent/worker-3 · ⏎ now · esc stay         
+       close [return] · closing in 3s · return to plan [esc] · always [a]       
                                                                                 
                                                                                 
                                                                                 
@@ -1184,6 +1184,136 @@ exports[`stories catalog theme-context/ProviderSwap renders, snapshots, and carr
                                                                                 
                                                                                 
                                                                                 
+                                                                                
+"
+`;
+
+exports[`stories catalog ConfirmCard/WithViewedSummary renders, snapshots, and carries its colors: ConfirmCard/WithViewedSummary 1`] = `
+"╭─ submit review ─────────────────────╮ 
+│ 1 annotations · 0 blocking          │ 
+│ 2/3 files viewed                    │ 
+│                                     │ 
+│  Comment  [Approve]  Changes        │ 
+│                                     │ 
+│ summary for the agent (optional)    │ 
+│                                     │ 
+│  Submit    Cancel                   │ 
+╰─────────────────────────────────────╯ 
+                                        
+                                        
+                                        
+                                        
+"
+`;
+
+exports[`stories catalog WalkWizard/EndCard renders, snapshots, and carries its colors: WalkWizard/EndCard 1`] = `
+"                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+    ╭─ walk complete ──────────────────────────────────────────────────────╮    
+    │ every file viewed (3/3)                                              │    
+    │                                                                      │    
+    │  Submit review    [ back                                             │    
+    ╰──────────────────────────────────────────────────────────────────────╯    
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+"
+`;
+
+exports[`stories catalog WalkWizard/EndCardPartialPass renders, snapshots, and carries its colors: WalkWizard/EndCardPartialPass 1`] = `
+"                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+    ╭─ walk complete ──────────────────────────────────────────────────────╮    
+    │ 1 of 3 files viewed                                                  │    
+    │                                                                      │    
+    │  Submit review    [ back                                             │    
+    ╰──────────────────────────────────────────────────────────────────────╯    
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+"
+`;
+
+exports[`stories catalog WalkWizard/FirstFile renders, snapshots, and carries its colors: WalkWizard/FirstFile 1`] = `
+"                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+    ╭─ file 1 of 3 · 0 viewed ─────────────────────────────────────────────╮    
+    │ packages/daemon/src/store.ts                                         │    
+    │ +12 -3                                                               │    
+    │                                                                      │    
+    │ +const viewed = new Set<string>();                                   │    
+    │ +record.viewedPaths = [...viewed];                                   │    
+    │ -// viewed tracking lives in the client only                         │    
+    ╰──────────────────────────────────────────────────────────────────────╯    
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+"
+`;
+
+exports[`stories catalog WalkWizard/WithAgentNote renders, snapshots, and carries its colors: WalkWizard/WithAgentNote 1`] = `
+"                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+    ╭─ file 2 of 3 · 1 viewed ─────────────────────────────────────────────╮    
+    │ packages/client/src/walk.ts                                          │    
+    │ +48 -0                                                               │    
+    │                                                                      │    
+    │ +export function firstUnviewedIndex(files, viewed) {                 │    
+    ╰──────────────────────────────────────────────────────────────────────╯    
+                                                                                
+    ╭─ agent note ─────────────────────────────────────────────────────────╮    
+    │ New module: pure helpers that pick the next unviewed file. No IO,    │    
+    │ unit tested.                                                         │    
+    ╰──────────────────────────────────────────────────────────────────────╯    
+                                                                                
+                                                                                
+                                                                                
+                                                                                
+                                                                                
                                                                                 
 "
 `;

package/src/config.ts

@@ -46,6 +46,7 @@ export const DEFAULT_KEYS: Record<string, string[]> = {
   delete_annotation: ["backspace"],
   submit: ["return", "enter"],
   quit: ["q"],
+  walk: ["w"],
 };
 
 function parseToml(text: string): Record<string, unknown> {

package/src/key-bindings.test.ts

@@ -8,7 +8,7 @@ import { describe, expect, test } from "bun:test";
 import { DEFAULT_KEYS } from "./config";
 import { KeyBindings } from "./key-bindings";
 
-function bindings(context: { overlay?: "none" | "compose" | "submit"; spanMode?: boolean } = {}): KeyBindings {
+function bindings(context: { overlay?: "none" | "walk" | "compose" | "submit"; spanMode?: boolean } = {}): KeyBindings {
   const resolver = new KeyBindings(DEFAULT_KEYS);
   resolver.setContext({ overlay: context.overlay ?? "none", spanMode: context.spanMode ?? false });
   return resolver;
@@ -62,6 +62,17 @@ describe("mode layers own their keys", () => {
     expect(resolver.resolveAction({ name: "right", shift: false })).toBe("cycle_verdict_right");
     expect(resolver.resolveAction({ name: "return", shift: false })).toBe("submit_verdict");
   });
+
+  test("the walk overlay owns the bracket stepping and leaves the grammar keys dead", () => {
+    const resolver = bindings({ overlay: "walk" });
+    expect(resolver.resolveAction({ name: "]", shift: false })).toBe("walk_next");
+    expect(resolver.resolveAction({ name: "[", shift: false })).toBe("walk_prev");
+    expect(resolver.resolveAction({ name: "escape", shift: false })).toBe("walk_leave");
+    expect(resolver.resolveAction({ name: "return", shift: false })).toBe("walk_submit");
+    expect(resolver.resolveAction({ name: "q", shift: false })).toBe("quit");
+    expect(resolver.resolveAction({ name: "j", shift: false })).toBeUndefined();
+    expect(resolver.resolveAction({ name: "c", shift: false })).toBeUndefined();
+  });
 });
 
 describe("getActiveKeys-generated status hints", () => {
@@ -89,6 +100,12 @@ describe("getActiveKeys-generated status hints", () => {
     expect(bindings({ overlay: "submit" }).statusHint("submit")).toBe("verdict ←/→ · ⏎ submit · esc cancel");
   });
 
+  test("walk hint", () => {
+    expect(bindings({ overlay: "walk" }).statusHint("walk")).toBe(
+      "walk · ] next (marks viewed) · [ back · esc leave walk · q quit",
+    );
+  });
+
   test("read-only hint", () => {
     expect(bindings().statusHint("read-only")).toBe("observer - read-only · j/k move · n/p annotations · q quit");
   });

package/src/key-bindings.ts

@@ -24,7 +24,7 @@ export interface KeyLayerContext {
 }
 
 /** Hint templates keyed by the same view states the status line shows. */
-export type HintMode = "normal" | "card" | "span" | "compose" | "submit" | "read-only";
+export type HintMode = "normal" | "card" | "span" | "compose" | "submit" | "walk" | "read-only";
 
 type HintEntry =
   | { text: string }
@@ -70,6 +70,13 @@ const HINT_TEMPLATES: Record<HintMode, HintEntry[]> = {
     { 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" },
@@ -243,6 +250,20 @@ export class KeyBindings {
       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",

package/src/keymap.test.ts

@@ -20,6 +20,7 @@ function state(patch: Partial<KeyState> = {}): KeyState {
     annotationCount: 1,
     hasFocusedAnnotation: true,
     cursorAnnotatable: true,
+    walkAtEnd: false,
     ...patch,
   };
 }
@@ -76,7 +77,7 @@ describe("completion overlay", () => {
     [prompt, "j", []],
     [counting, "return", [{ t: "finishReview" }]],
     [counting, "q", [{ t: "finishReview" }]],
-    [counting, "a", []],
+    [counting, "a", [{ t: "optInAutoClose" }]],
     [counting, "escape", [{ t: "dismissCompletion" }]],
   ];
   for (const [s, name, expected] of table) {
@@ -228,6 +229,42 @@ describe("diff mode", () => {
   });
 });
 
+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([{ t: "walkStart" }]);
+    expect(reduceKey(state({ view: "diff", resolved: true }), key("w"))).toEqual([
+      { t: "status", msg: "review submitted - read-only" },
+    ]);
+    expect(reduceKey(state({ view: "diff", readOnly: true }), key("w"))).toEqual([
+      { t: "status", msg: "observer - read-only" },
+    ]);
+    expect(reduceKey(state(), key("w"))).toEqual([{ t: "status", msg: "the guided walk is a diff-review mode" }]);
+  });
+
+  const walking = state({ view: "diff", overlay: "walk" });
+  const table: [string, Intent[]][] = [
+    ["]", [{ t: "walkForward" }]],
+    ["[", [{ t: "walkBack" }]],
+    ["escape", [{ t: "walkLeave" }]],
+    ["q", [{ t: "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([{ t: "walkLeave" }, { t: "openSubmit" }]);
+    expect(reduceKey(atEnd, key("enter"))).toEqual([{ t: "walkLeave" }, { t: "openSubmit" }]);
+  });
+});
+
 describe("duplicated-branch collapse", () => {
   test("plan and diff produce the same intents for annotation nav, delete, and submit", () => {
     for (const patch of [

package/src/keymap.ts

@@ -23,6 +23,10 @@ export type Intent =
   | { t: "editCard" }
   | { t: "nextAnn" }
   | { t: "prevAnn" }
+  | { t: "walkStart" }
+  | { t: "walkForward" }
+  | { t: "walkBack" }
+  | { t: "walkLeave" }
   | { t: "removeAnnotation" }
   | { t: "deselect" }
   | { t: "closeOverlay" }
@@ -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,7 +62,7 @@ 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"];
 
@@ -86,10 +92,23 @@ export function reduceKey(state: KeyState, key: KeyInput, resolvedAction?: strin
   }
   if (state.overlay === "completion-prompt" || state.overlay === "completion-counting") {
     if (name === "return" || name === "enter" || name === "q") return [{ t: "finishReview" }];
-    if (name === "a" && state.overlay === "completion-prompt") return [{ t: "optInAutoClose" }];
+    if (name === "a") return [{ t: "optInAutoClose" }];
     if (name === "escape") return [{ t: "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 [{ t: "walkForward" }];
+    if (name === "[") return [{ t: "walkBack" }];
+    if (name === "escape") return [{ t: "walkLeave" }];
+    if ((name === "return" || name === "enter") && state.walkAtEnd) {
+      return [{ t: "walkLeave" }, { t: "openSubmit" }];
+    }
+    if (name === "q") return [{ t: "exit" }];
+    return [];
+  }
   const action = resolvedAction ?? actionFor(state.keys, name, key.shift);
   if (action === "quit") return [{ t: "exit" }];
   // the ONE read-only rule: any mutating attempt answers instead of acting
@@ -114,6 +133,11 @@ function inboxGrammar(state: KeyState, name: string): Intent[] {
 function diffGrammar(state: KeyState, action: string | undefined): Intent[] {
   const nav = navIntent(action);
   if (nav) return nav;
+  if (action === "walk") {
+    // marking viewed writes the session record, so a resolved review answers
+    if (state.resolved) return status("review submitted - read-only");
+    return [{ t: "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");
@@ -139,6 +163,7 @@ function spanGrammar(name: string): Intent[] {
 function planGrammar(state: KeyState, action: string | undefined, name: string): Intent[] {
   const nav = navIntent(action);
   if (nav) return nav;
+  if (action === "walk") return status("the guided walk is a diff-review mode");
   if (name === "escape") return [{ t: "deselect" }];
   if (action === "span") return state.cursorAnnotatable ? [{ t: "startSpan" }] : [];
   if (action === "comment" || action === "suggest") {