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

package/src/App.walk.test.tsx

@@ -0,0 +1,208 @@
+/**
+ * The guided walk in the virtual terminal: the wizard steps every
+ * changed file with a plain progress title, ] marks viewed and persists with
+ * the session, esc keeps progress, w resumes at the first unviewed file
+ * (across App instances - the daemon round-trip), the agent-note block
+ * renders only for files carrying a note, and the end card hands over to the
+ * submit confirm with the honest viewed count.
+ */
+
+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 type { ReviewSession } from "@cueloop/schema";
+import { App } from "./App";
+import { DARK } from "./theme";
+import { press, waitForState, waitForText, waitForTextGone } from "./test-support";
+
+const PATCH = `diff --git a/src/a.ts b/src/a.ts
+index 111..222 100644
+--- a/src/a.ts
++++ b/src/a.ts
+@@ -1,2 +1,2 @@
+ export const a = 1;
+-export const b = 2;
++export const b = 3;
+diff --git a/src/b.ts b/src/b.ts
+index 333..444 100644
+--- a/src/b.ts
++++ b/src/b.ts
+@@ -1,2 +1,2 @@
+ // header
+-old line
++new line
+diff --git a/src/c.ts b/src/c.ts
+index 555..666 100644
+--- a/src/c.ts
++++ b/src/c.ts
+@@ -1,1 +1,2 @@
+ keep
++added tail
+`;
+
+let home: string;
+let server: DaemonServer;
+let session: ReviewSession;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-walk-"));
+  server = new DaemonServer({ home, idleExitMs: 0 });
+  server.start();
+  session = server.core.sessionCreate({
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: "diff", content: PATCH, meta: { title: "working tree" } },
+  });
+});
+afterEach(() => {
+  server.stop();
+  rmSync(home, { recursive: true, force: true });
+});
+
+async function renderApp() {
+  const setup = await testRender(<App home={home} sessionId={session.id} />, { width: 120, height: 34 });
+  // Wait for session content, not just the chrome: pressing w before the diff
+  // loads drops the walk intent (no session, no diff view) and hangs the test.
+  await waitForText(setup, "src/a.ts");
+  return setup;
+}
+
+type Setup = Awaited<ReturnType<typeof renderApp>>;
+
+/** Foreground colors (hex) of every styled span containing the needle. */
+function foregroundsOf(setup: Setup, needle: string): string[] {
+  const foregrounds: string[] = [];
+  for (const line of setup.captureSpans().lines) {
+    for (const span of line.spans) {
+      if (!span.text.includes(needle)) continue;
+      const [red, green, blue] = span.fg.toInts();
+      foregrounds.push("#" + [red, green, blue].map((part) => part.toString(16).padStart(2, "0")).join(""));
+    }
+  }
+  return foregrounds;
+}
+
+describe("the guided walk", () => {
+  test("w walks all three files: progress title, persisted marks, end card, submit hand-over", async () => {
+    const setup = await renderApp();
+    await press(setup, "w");
+    await waitForText(setup, "file 1 of 3 · 0 viewed");
+    expect(setup.captureCharFrame()).toContain("src/a.ts");
+    expect(setup.captureCharFrame()).toContain("+1 -1");
+
+    await press(setup, "]");
+    await waitForText(setup, "file 2 of 3 · 1 viewed");
+    // the viewed mark rides the session record, not the client
+    await waitForState(setup, () => (server.core.sessionGet(session.id).viewedPaths ?? []).includes("src/a.ts"));
+
+    // [ steps back; the revisited card shows its viewed marker
+    await press(setup, "[");
+    await waitForText(setup, "file 1 of 3 · 1 viewed");
+    expect(setup.captureCharFrame()).toContain("· viewed");
+    await press(setup, "]");
+    await waitForText(setup, "file 2 of 3 · 1 viewed");
+
+    await press(setup, "]");
+    await waitForText(setup, "file 3 of 3 · 2 viewed");
+    await press(setup, "]");
+    await waitForText(setup, "walk complete");
+    expect(setup.captureCharFrame()).toContain("every file viewed (3/3)");
+    expect(server.core.sessionGet(session.id).viewedPaths).toEqual(["src/a.ts", "src/b.ts", "src/c.ts"]);
+
+    // the end card's return leaves the walk and opens the rail confirm
+    await press(setup, "enter");
+    await waitForText(setup, "submit review");
+    expect(setup.captureCharFrame()).toContain("3/3 files viewed");
+    await press(setup, "enter");
+    await waitForState(setup, () => server.core.sessionGet(session.id).status === "resolved");
+  });
+
+  test("esc keeps progress and w resumes at the first unviewed file", async () => {
+    const setup = await renderApp();
+    await press(setup, "w");
+    await waitForText(setup, "file 1 of 3 · 0 viewed");
+    await press(setup, "]");
+    await waitForText(setup, "file 2 of 3 · 1 viewed");
+
+    await press(setup, "escape");
+    await waitForTextGone(setup, "file 2 of 3");
+    // the sheet is back at full strength: no wizard card on screen
+    expect(setup.captureCharFrame()).not.toContain("· 1 viewed");
+
+    await press(setup, "w");
+    await waitForText(setup, "file 2 of 3 · 1 viewed");
+  });
+
+  test("a half-walked review resumes across App instances via the daemon", async () => {
+    const first = await renderApp();
+    await press(first, "w");
+    await waitForText(first, "file 1 of 3 · 0 viewed");
+    await press(first, "]");
+    await press(first, "]");
+    await waitForText(first, "file 3 of 3 · 2 viewed");
+    await waitForState(first, () => (server.core.sessionGet(session.id).viewedPaths ?? []).length === 2);
+    first.renderer.destroy();
+
+    // a fresh client reads the viewed set back from the session record
+    const second = await renderApp();
+    await press(second, "w");
+    await waitForText(second, "file 3 of 3 · 2 viewed");
+    expect(second.captureCharFrame()).toContain("src/c.ts");
+    // two full App boots with daemon round-trips need more than the default budget
+  }, 15_000);
+
+  test("the agent-note block renders only for files carrying a note", async () => {
+    server.core.sessionAnnotate(session.id, {
+      id: "note-b",
+      kind: "note",
+      anchor: { quote: "src/b.ts", prefix: "", suffix: "" },
+      body: "Swaps the stale line for the new constant.",
+    });
+    const setup = await renderApp();
+    await press(setup, "w");
+    await waitForText(setup, "file 1 of 3");
+    expect(setup.captureCharFrame()).not.toContain("agent note");
+
+    await press(setup, "]");
+    await waitForText(setup, "agent note");
+    expect(setup.captureCharFrame()).toContain("Swaps the stale line for the new constant.");
+
+    // a note is agent context, not reviewer feedback: it neither counts nor
+    // flips the default verdict, and never comes back in the feedback doc
+    await press(setup, "escape");
+    await waitForTextGone(setup, "agent note");
+    await press(setup, "enter");
+    await waitForText(setup, "0 annotations");
+    await press(setup, "enter");
+    await waitForState(setup, () => server.core.sessionGet(session.id).status === "resolved");
+    const resolved = server.core.sessionGet(session.id);
+    expect(resolved.verdict!.kind).toBe("approve");
+    expect(resolved.verdict!.feedback).not.toContain("Swaps the stale line");
+  });
+
+  test("the sheet dims behind the wizard; the preview keeps the diff colors", async () => {
+    const setup = await renderApp();
+    // before the walk the sheet's added line wears the insertion color
+    await waitForText(setup, "+new line");
+    expect(foregroundsOf(setup, "+new line")).toContain(DARK.insFg);
+
+    await press(setup, "w");
+    await waitForText(setup, "file 1 of 3 · 0 viewed");
+    // dimmed: the sheet line drops to the dim token...
+    expect(foregroundsOf(setup, "+new line")).toEqual([DARK.textDim]);
+    // ...while the wizard preview keeps the insertion color
+    expect(foregroundsOf(setup, "+export const b = 3;")).toContain(DARK.insFg);
+  });
+
+  test("walking a resolved review answers read-only", async () => {
+    server.core.sessionResolve(session.id, "approve", "");
+    const setup = await renderApp();
+    await waitForText(setup, "resolved");
+    await press(setup, "w");
+    await waitForText(setup, "review submitted - read-only");
+    expect(setup.captureCharFrame()).not.toContain("file 1 of 3");
+  });
+});

package/src/components/AnnotationCard.tsx

@@ -15,7 +15,7 @@ import { useComponentTheme } from "./theme-context";
 import { Card } from "./primitives/Card";
 import { Button } from "./primitives/Button";
 import { Toolbar } from "./primitives/Toolbar";
-import { truncate } from "./format";
+import { truncateToSingleLine } from "./truncate-text";
 
 export interface AnnotationDraft {
   text: string;
@@ -101,7 +101,7 @@ export function AnnotationCard({ id, kind, quote, draft, saved, theme }: Annotat
     const verb = kind === "suggestion" ? "suggest replacement for" : "comment on";
     return (
       <Card
-        title={` ${verb} "${truncate(quote, 40)}" `}
+        title={` ${verb} "${truncateToSingleLine(quote, 40)}" `}
         contentRows={editorRows(draft.text) + 1}
         borderColor={kindColor}
         marginLeft={2}
@@ -125,11 +125,11 @@ export function AnnotationCard({ id, kind, quote, draft, saved, theme }: Annotat
         {card.isBlocking ? <span fg={tokens.red}> · BLOCKING</span> : null}
         <span fg={tokens.textDim}>{card.isOrphan ? " · ORPHANED" : " · pending"}</span>
       </text>
-      <text fg={tokens.textDim}>  "{truncate(quote, 26)}"</text>
+      <text fg={tokens.textDim}>  "{truncateToSingleLine(quote, 26)}"</text>
       {card.editing ? (
         <DraftEditor draft={card.editing} theme={theme} />
       ) : (
-        <text fg={card.isOrphan ? tokens.textDim : tokens.textMuted}>  {truncate(card.body, 28)}</text>
+        <text fg={card.isOrphan ? tokens.textDim : tokens.textMuted}>  {truncateToSingleLine(card.body, 28)}</text>
       )}
     </box>
   );

package/src/components/ComposeBar.tsx

@@ -8,7 +8,7 @@ import React, { useRef } from "react";
 import type { KeyBinding, TextareaRenderable } from "@opentui/core";
 import type { Theme } from "../theme";
 import { useComponentTheme } from "./theme-context";
-import { truncate } from "./format";
+import { truncateToSingleLine } from "./truncate-text";
 
 export interface ComposeBarProps {
   kind: "comment" | "suggestion";
@@ -30,7 +30,7 @@ export function ComposeBar({ kind, quote, text, onInput, theme }: ComposeBarProp
   return (
     <box style={{ height: 1 + editorRows, backgroundColor: tokens.elevated, flexDirection: "column", paddingLeft: 1 }}>
       <text fg={kind === "suggestion" ? tokens.green : tokens.accent}>
-        {kind === "suggestion" ? "SUGGEST REPLACEMENT FOR" : "COMMENT ON"} “{truncate(quote, 60)}” · ⏎ save · esc cancel
+        {kind === "suggestion" ? "SUGGEST REPLACEMENT FOR" : "COMMENT ON"} “{truncateToSingleLine(quote, 60)}” · ⏎ save · esc cancel
       </text>
       <textarea
         ref={editorRef}

package/src/components/ConfirmCard.stories.tsx

@@ -20,3 +20,18 @@ export const RequestChanges: Story = {
   expectedColors: [DARK.red],
   size: { width: 40, height: 14 },
 };
+
+export const WithViewedSummary: Story = {
+  render: () => (
+    <ConfirmCard
+      verdict="approve"
+      summary=""
+      annotationCount={1}
+      blockingCount={0}
+      viewedSummary="2/3 files viewed"
+      {...callbacks}
+    />
+  ),
+  expectedColors: [DARK.green, DARK.textDim],
+  size: { width: 40, height: 14 },
+};

package/src/components/ConfirmCard.tsx

@@ -28,6 +28,11 @@ export interface ConfirmCardProps {
   summary: string;
   annotationCount: number;
   blockingCount: number;
+  /**
+   * The guided walk's honest coverage line for diff sessions, e.g.
+   * "2/3 files viewed". Undefined = no walk data, the row does not render.
+   */
+  viewedSummary?: string;
   onInput: (summary: string) => void;
   onSelectVerdict: (verdict: VerdictKind) => void;
   onSubmit: () => void;
@@ -76,6 +81,7 @@ export function ConfirmCard({
   summary,
   annotationCount,
   blockingCount,
+  viewedSummary,
   onInput,
   onSelectVerdict,
   onSubmit,
@@ -86,12 +92,13 @@ export function ConfirmCard({
   return (
     <Card
       title=" submit review "
-      contentRows={CONFIRM_CONTENT_ROWS}
+      contentRows={CONFIRM_CONTENT_ROWS + (viewedSummary !== undefined ? 1 : 0)}
       borderColor={tokens.accent}
       marginRight={1}
       theme={theme}
     >
       <text fg={tokens.textDim}>{`${annotationCount} annotations · ${blockingCount} blocking`}</text>
+      {viewedSummary !== undefined ? <text fg={tokens.textDim}>{viewedSummary}</text> : null}
       <box style={{ height: 1 }} />
       <VerdictSelector verdict={verdict} onSelectVerdict={onSelectVerdict} theme={theme} />
       <box style={{ height: 1 }} />

package/src/components/DiffSheet.tsx

@@ -13,7 +13,7 @@ import type { Annotation } from "@cueloop/schema";
 import type { DiffRow } from "../view-diff";
 import type { Theme } from "../theme";
 import { useComponentTheme } from "./theme-context";
-import { truncate } from "./format";
+import { truncateToSingleLine } from "./truncate-text";
 
 export interface DiffSheetProps {
   rows: DiffRow[];
@@ -43,7 +43,7 @@ function segmentRows(rows: DiffRow[], annotatedByRow: Map<number, Annotation>):
   };
   for (let rowIndex = 0; rowIndex < rows.length; rowIndex++) {
     const row = rows[rowIndex]!;
-    if (row.t === "file" || row.t === "hunk") {
+    if (row.kind === "file" || row.kind === "hunk") {
       closeChunk(null);
       segments.push({ kind: "header", rowIndex, row });
       chunkStart = rowIndex + 1;
@@ -79,7 +79,7 @@ function DiffChunk({
   const lineNumbers = useMemo(() => {
     const numbers = new Map<number, number>();
     segment.rows.forEach((row, lineIndex) => {
-      const gutterNumber = row.t === "del" ? row.oldLine : row.newLine;
+      const gutterNumber = row.kind === "del" ? row.oldLine : row.newLine;
       if (gutterNumber !== undefined) numbers.set(lineIndex, gutterNumber);
     });
     return numbers;
@@ -132,8 +132,8 @@ function DiffChunk({
       >
         <text style={{ wrapMode: "none" }} selectable={false}>
           {segment.rows.map((row, lineIndex) => {
-            const sign = row.t === "add" ? "+" : row.t === "del" ? "-" : " ";
-            const foreground = row.t === "add" ? tokens.insFg : row.t === "del" ? tokens.delFg : tokens.textMuted;
+            const sign = row.kind === "add" ? "+" : row.kind === "del" ? "-" : " ";
+            const foreground = row.kind === "add" ? tokens.insFg : row.kind === "del" ? tokens.delFg : tokens.textMuted;
             const isCursorRow = lineIndex === cursorInChunk;
             const isAnnotatedRow = segment.annotation !== null && lineIndex === segment.rows.length - 1;
             return (
@@ -152,7 +152,7 @@ function DiffChunk({
         <text>
           <span fg={tokens.textDim}>{"      "}</span>
           <span fg={segment.annotation.id === focusedAnnotationId ? tokens.text : tokens.accent}>
-            ◆ {truncate(segment.annotation.body, 70)}
+            ◆ {truncateToSingleLine(segment.annotation.body, 70)}
           </span>
         </text>
       ) : null}
@@ -168,7 +168,7 @@ export function DiffSheet({ rows, cursor, annotations, focusedAnnotationId, them
     const byRow = new Map<number, Annotation>();
     for (const annotation of annotations) {
       const rowIndex = rows.findIndex(
-        (row) => row.text === annotation.anchor.quote && (row.t === "ctx" || row.t === "add" || row.t === "del"),
+        (row) => row.text === annotation.anchor.quote && (row.kind === "ctx" || row.kind === "add" || row.kind === "del"),
       );
       if (rowIndex !== -1) byRow.set(rowIndex, annotation);
     }
@@ -213,7 +213,7 @@ export function DiffSheet({ rows, cursor, annotations, focusedAnnotationId, them
         {segments.map((segment, segmentIndex) => {
           if (segment.kind === "header") {
             const isCursor = segment.rowIndex === cursor;
-            if (segment.row.t === "file") {
+            if (segment.row.kind === "file") {
               return (
                 <text key={segmentIndex} fg={tokens.text} bg={isCursor ? tokens.cursorBg : tokens.panel}>
                   {isCursor ? "▎" : " "}■ {rowLine(segment.row)}

package/src/components/PlanSheet.stories.tsx

@@ -32,7 +32,7 @@ export const SpanSelection: Story = {
       display={fixtureDisplay()}
       marks={new Map()}
       cursor={2}
-      activeSpan={{ dispIdx: 2, start: 0, end: 10 }}
+      activeSpan={{ displayIndex: 2, start: 0, end: 10 }}
       compose={null}
       editOrphanCount={0}
       {...callbacks}
@@ -49,10 +49,10 @@ export const InlineCompose: Story = {
       display={fixtureDisplay()}
       marks={new Map()}
       cursor={2}
-      activeSpan={{ dispIdx: 2, start: 0, end: 10 }}
+      activeSpan={{ displayIndex: 2, start: 0, end: 10 }}
       compose={{
         kind: "comment",
-        dispIdx: 2,
+        displayIndex: 2,
         quote: "The daemon",
         draft: { text: "Which daemon?", onInput: () => {}, onSave: () => {}, onCancel: () => {} },
       }}

package/src/components/PlanSheet.tsx

@@ -23,7 +23,7 @@ import {
   type Mark,
   type SpanState,
   type StyleRun,
-} from "../view";
+} from "../view-plan";
 import type { Theme } from "../theme";
 import { useComponentTheme } from "./theme-context";
 import { CodeBlock } from "./CodeBlock";
@@ -32,7 +32,7 @@ import { Button } from "./primitives/Button";
 import { Toolbar } from "./primitives/Toolbar";
 
 export interface PlanSelection {
-  dispIdx: number;
+  displayIndex: number;
   start: number;
   end: number;
 }
@@ -43,12 +43,12 @@ export interface PlanSheetHandle {
   /** Anchor/extend the renderer's native selection from keyboard span offsets. */
   driveSpanSelection(span: SpanState): void;
   clearSelection(): void;
-  revealBlock(dispIdx: number): void;
+  revealBlock(displayIndex: number): void;
 }
 
 export interface PlanComposeState {
   kind: "comment" | "suggestion";
-  dispIdx: number;
+  displayIndex: number;
   quote: string;
   draft: AnnotationDraft;
 }
@@ -59,10 +59,10 @@ export interface PlanSheetProps {
   marks: Map<number, Mark[]>;
   cursor: number;
   /** Extra selection-style paint on one block (keyboard span or compose anchor). */
-  activeSpan: { dispIdx: number; start: number; end: number } | null;
+  activeSpan: { displayIndex: number; start: number; end: number } | null;
   compose: PlanComposeState | null;
   editOrphanCount: number;
-  onLineActivate: (dispIdx: number) => void;
+  onLineActivate: (displayIndex: number) => void;
   onEditRequest: () => void;
   theme?: Theme;
 }
@@ -110,17 +110,17 @@ export const PlanSheet = forwardRef<PlanSheetHandle, PlanSheetProps>(function Pl
     readSelection: (): PlanSelection | null => {
       if (!renderer?.hasSelection) return null;
       const ordered = [...blockRefs.current.entries()].sort(([a], [b]) => a - b);
-      for (const [dispIdx, blockRef] of ordered) {
+      for (const [displayIndex, blockRef] of ordered) {
         const selection = blockRef.renderable.getSelection();
         if (!selection || selection.end <= selection.start) continue;
         const range = workRangeForRendered(blockRef.runs, selection.start, selection.end);
-        if (range) return { dispIdx, ...range };
+        if (range) return { displayIndex, ...range };
       }
       return null;
     },
     driveSpanSelection: (span: SpanState): void => {
       if (!renderer) return;
-      const blockRef = blockRefs.current.get(span.dispIdx);
+      const blockRef = blockRefs.current.get(span.displayIndex);
       if (!blockRef) return;
       const renderedStart = renderedOffsetFor(blockRef.runs, span.start);
       const renderedEnd = renderedOffsetFor(blockRef.runs, span.end - 1);
@@ -133,48 +133,48 @@ export const PlanSheet = forwardRef<PlanSheetHandle, PlanSheetProps>(function Pl
     clearSelection: (): void => {
       renderer?.clearSelection();
     },
-    revealBlock: (dispIdx: number): void => {
+    revealBlock: (displayIndex: number): void => {
       try {
-        scrollRef.current?.scrollChildIntoView(`plan-block-${dispIdx}`);
+        scrollRef.current?.scrollChildIntoView(`plan-block-${displayIndex}`);
       } catch {
         // reveal is best-effort; selection state is already correct
       }
     },
   }));
 
-  const registerBlock = (dispIdx: number, renderable: TextRenderable | null, runs: StyleRun[]): void => {
-    if (renderable) blockRefs.current.set(dispIdx, { renderable, runs });
-    else blockRefs.current.delete(dispIdx);
+  const registerBlock = (displayIndex: number, renderable: TextRenderable | null, runs: StyleRun[]): void => {
+    if (renderable) blockRefs.current.set(displayIndex, { renderable, runs });
+    else blockRefs.current.delete(displayIndex);
   };
   // stale refs must not survive a shrinking display list
   useEffect(() => {
-    for (const dispIdx of blockRefs.current.keys()) {
-      if (dispIdx >= display.length) blockRefs.current.delete(dispIdx);
+    for (const displayIndex of blockRefs.current.keys()) {
+      if (displayIndex >= display.length) blockRefs.current.delete(displayIndex);
     }
   }, [display]);
 
   const children: React.ReactNode[] = [];
-  for (let dispIdx = 0; dispIdx < display.length; dispIdx++) {
-    const block = display[dispIdx]!;
-    const isCursor = dispIdx === cursor;
-    const gap = topGap(display[dispIdx - 1], block);
+  for (let displayIndex = 0; displayIndex < display.length; displayIndex++) {
+    const block = display[displayIndex]!;
+    const isCursor = displayIndex === cursor;
+    const gap = topGap(display[displayIndex - 1], block);
     if (block.kind === "code") {
       children.push(
         <CodeBlock
-          key={dispIdx}
-          id={`plan-block-${dispIdx}`}
+          key={displayIndex}
+          id={`plan-block-${displayIndex}`}
           language={(block.work ?? block.base)?.lang}
           content={displayText(block)}
           isCursor={isCursor}
           marginTop={gap}
-          isAnnotated={(marks.get(dispIdx) ?? []).length > 0}
+          isAnnotated={(marks.get(displayIndex) ?? []).length > 0}
           changeTag={block.type !== "same" ? tagLabel(block) : undefined}
           theme={theme}
         />,
       );
     } else {
-      const blockMarks = [...(marks.get(dispIdx) ?? [])];
-      if (activeSpan && activeSpan.dispIdx === dispIdx) {
+      const blockMarks = [...(marks.get(displayIndex) ?? [])];
+      if (activeSpan && activeSpan.displayIndex === displayIndex) {
         blockMarks.push({ start: activeSpan.start, end: activeSpan.end, role: "kspan" });
       }
       const runs = overlayMarks(blockRuns(block, true), blockMarks);
@@ -182,7 +182,7 @@ export const PlanSheet = forwardRef<PlanSheetHandle, PlanSheetProps>(function Pl
       const mappedRuns: StyleRun[] =
         block.type !== "same" ? [...runs, { text: ` [${tagLabel(block)}]`, role: "plain", start: null }] : runs;
       children.push(
-        <box key={dispIdx} id={`plan-block-${dispIdx}`} style={{ flexDirection: "row", marginTop: gap }}>
+        <box key={displayIndex} id={`plan-block-${displayIndex}`} style={{ flexDirection: "row", marginTop: gap }}>
           <text selectable={false}>
             <span fg={isCursor ? tokens.accent : tokens.textDim}>{isCursor ? "▎ " : "  "}</span>
             <span fg={tokens.textDim}>{marker(block)}</span>
@@ -193,8 +193,8 @@ export const PlanSheet = forwardRef<PlanSheetHandle, PlanSheetProps>(function Pl
             selectionBg={tokens.accent}
             selectionFg={tokens.accentInk}
             style={{ wrapMode: "word", flexGrow: 1, flexShrink: 1 }}
-            ref={(renderable: TextRenderable | null) => registerBlock(dispIdx, renderable, mappedRuns)}
-            onMouseUp={() => onLineActivate(dispIdx)}
+            ref={(renderable: TextRenderable | null) => registerBlock(displayIndex, renderable, mappedRuns)}
+            onMouseUp={() => onLineActivate(displayIndex)}
           >
             {runs.map((run, runIndex) => (
               <span key={runIndex} {...runStyle(run, block, tokens)}>
@@ -206,9 +206,9 @@ export const PlanSheet = forwardRef<PlanSheetHandle, PlanSheetProps>(function Pl
         </box>,
       );
     }
-    if (compose && compose.dispIdx === dispIdx) {
+    if (compose && compose.displayIndex === displayIndex) {
       children.push(
-        <AnnotationCard key={`compose-${dispIdx}`} kind={compose.kind} quote={compose.quote} draft={compose.draft} theme={theme} />,
+        <AnnotationCard key={`compose-${displayIndex}`} kind={compose.kind} quote={compose.quote} draft={compose.draft} theme={theme} />,
       );
     }
   }
@@ -274,7 +274,7 @@ function topGap(previous: DisplayBlock | undefined, current: DisplayBlock): numb
 
 function marker(block: DisplayBlock): string {
   if (block.kind === "li") return "- ";
-  if (block.kind === "oli") return `${block.oliNum ?? 1}. `;
+  if (block.kind === "oli") return `${block.orderedItemNumber ?? 1}. `;
   if (block.kind === "quote") return "▏ ";
   return "";
 }

package/src/components/WalkWizard.stories.tsx

@@ -0,0 +1,89 @@
+import React from "react";
+import { DARK } from "../theme";
+import type { WalkFile } from "../walk";
+import type { Story, StoryMeta } from "./story";
+import { WalkWizard } from "./WalkWizard";
+
+export const meta: StoryMeta = { title: "WalkWizard" };
+
+const FILES: WalkFile[] = [
+  {
+    path: "packages/daemon/src/store.ts",
+    added: 12,
+    removed: 3,
+    preview: [
+      { sign: "+", text: "const viewed = new Set<string>();" },
+      { sign: "+", text: "record.viewedPaths = [...viewed];" },
+      { sign: "-", text: "// viewed tracking lives in the client only" },
+    ],
+  },
+  {
+    path: "packages/client/src/walk.ts",
+    added: 48,
+    removed: 0,
+    preview: [{ sign: "+", text: "export function firstUnviewedIndex(files, viewed) {" }],
+  },
+  { path: "packages/schema/src/types.ts", added: 3, removed: 0, preview: [{ sign: "+", text: "viewedPaths?: string[];" }] },
+];
+
+const noop = (): void => {};
+
+export const FirstFile: Story = {
+  render: () => (
+    <WalkWizard
+      files={FILES}
+      index={0}
+      viewedPaths={new Set()}
+      terminalWidth={80}
+      onSubmitRequest={noop}
+      onBack={noop}
+    />
+  ),
+  // the main card wears the accent border; stats carry the +/- colors
+  expectedColors: [DARK.accent, DARK.green, DARK.red, DARK.insFg, DARK.delFg],
+};
+
+export const WithAgentNote: Story = {
+  render: () => (
+    <WalkWizard
+      files={FILES}
+      index={1}
+      viewedPaths={new Set(["packages/daemon/src/store.ts"])}
+      note="New module: pure helpers that pick the next unviewed file. No IO, unit tested."
+      terminalWidth={80}
+      onSubmitRequest={noop}
+      onBack={noop}
+    />
+  ),
+  // the agent-note block wears the plain gray border token, not the accent
+  expectedColors: [DARK.accent, DARK.border, DARK.textMuted],
+};
+
+export const EndCard: Story = {
+  render: () => (
+    <WalkWizard
+      files={FILES}
+      index={3}
+      viewedPaths={new Set(FILES.map((file) => file.path))}
+      terminalWidth={80}
+      onSubmitRequest={noop}
+      onBack={noop}
+    />
+  ),
+  // the end card wears the green border and the solid submit button
+  expectedColors: [DARK.green, DARK.accent, DARK.accentInk],
+};
+
+export const EndCardPartialPass: Story = {
+  render: () => (
+    <WalkWizard
+      files={FILES}
+      index={3}
+      viewedPaths={new Set(["packages/daemon/src/store.ts"])}
+      terminalWidth={80}
+      onSubmitRequest={noop}
+      onBack={noop}
+    />
+  ),
+  expectedColors: [DARK.green],
+};