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

package/src/serve.test.ts

@@ -38,7 +38,7 @@ afterEach(async () => {
 });
 
 /** Connect, open a PTY shell, resolve with the bytes seen until `until` matches. */
-function sshCapture(port: number, until: (s: string) => boolean, timeoutMs = 8000): Promise<string> {
+function sshCapture(port: number, until: (frame: string) => boolean, timeoutMs = 8000): Promise<string> {
   return new Promise((resolve, reject) => {
     const conn = new Client();
     let out = "";
@@ -55,8 +55,8 @@ function sshCapture(port: number, until: (s: string) => boolean, timeoutMs = 800
       .on("ready", () => {
         conn.shell({ term: "xterm-256color", cols: 100, rows: 30 }, (err, stream) => {
           if (err) return finish(err);
-          stream.on("data", (d: Buffer) => {
-            out += d.toString("utf8");
+          stream.on("data", (chunk: Buffer) => {
+            out += chunk.toString("utf8");
             if (until(out)) finish();
           });
           stream.on("close", () => finish(new Error(`stream closed early; captured:\n${out}`)));
@@ -78,7 +78,7 @@ describe("cueloop serve", () => {
   });
 
   test("an anonymous ssh client gets the observer TUI for the session", async () => {
-    const bytes = await sshCapture(handle.port, (s) => s.includes("Rollout Plan") && s.includes("observer"));
+    const bytes = await sshCapture(handle.port, (frame) => frame.includes("Rollout Plan") && frame.includes("observer"));
     expect(bytes).toContain("cueloop");
     expect(bytes).toContain("Rollout Plan");
     // observer chrome, not the controller's mutating hint bar
@@ -87,8 +87,8 @@ describe("cueloop serve", () => {
 
   test("two observers can watch at once", async () => {
     const [a, b] = await Promise.all([
-      sshCapture(handle.port, (s) => s.includes("Rollout Plan")),
-      sshCapture(handle.port, (s) => s.includes("Rollout Plan")),
+      sshCapture(handle.port, (frame) => frame.includes("Rollout Plan")),
+      sshCapture(handle.port, (frame) => frame.includes("Rollout Plan")),
     ]);
     expect(a).toContain("Rollout Plan");
     expect(b).toContain("Rollout Plan");

package/src/serve.ts

@@ -1,5 +1,5 @@
 /**
- * SSH-served TUI (#22 share path): `cueloop serve` lets teammates join a
+ * SSH-served TUI: `cueloop serve` lets teammates join a
  * review session over plain ssh. Every SSH connection renders <App> in
  * observer mode (readOnly) against the same local daemon; the one writable
  * controller stays the local owner's own `cueloop` TUI.
@@ -44,8 +44,8 @@ export interface ServeHandle {
   close(): Promise<void>;
 }
 
-export async function serveClient(opts: ServeOptions = {}): Promise<ServeHandle> {
-  const home = opts.home ?? cueloopHome();
+export async function serveClient(options: ServeOptions = {}): Promise<ServeHandle> {
+  const home = options.home ?? cueloopHome();
   const sshDir = join(home, "ssh");
   mkdirSync(sshDir, { recursive: true, mode: 0o700 });
 
@@ -53,15 +53,15 @@ export async function serveClient(opts: ServeOptions = {}): Promise<ServeHandle>
     // password-less by design; see the trust model in the module comment
     auth: "open",
     hostKey: { path: join(sshDir, "host_key") },
-    startupBanner: opts.banner ?? true,
+    startupBanner: options.banner ?? true,
     idleTimeout: "2h",
-    onError: opts.onError,
+    onError: options.onError,
   }).serve((session) => {
     const root = createRoot(session.renderer);
     root.render(
       React.createElement(App, {
         home,
-        sessionId: opts.sessionId,
+        sessionId: options.sessionId,
         readOnly: true,
         // q disconnects only this observer, never the server
         onExit: () => session.end(),
@@ -70,6 +70,6 @@ export async function serveClient(opts: ServeOptions = {}): Promise<ServeHandle>
     session.onClose(() => root.unmount());
   });
 
-  const info = await server.listen(opts.port ?? 2222, opts.host ?? "127.0.0.1");
+  const info = await server.listen(options.port ?? 2222, options.host ?? "127.0.0.1");
   return { ...info, close: () => server.close() };
 }

package/src/session-controller.ts

@@ -1,5 +1,5 @@
 /**
- * The review-session controller (#70): every daemon round-trip and mutation
+ * The review-session controller: every daemon round-trip and mutation
  * verb behind one React-free object. It owns connect/autostart/subscribe,
  * the session/inbox/status/error snapshot, optimistic apply, the mutation
  * verbs (cut/edit/annotate/submit/...), and the post-submit completion
@@ -22,8 +22,9 @@ import {
 } from "@cueloop/schema";
 import { Registry, type Exporter } from "@cueloop/extension-api";
 import { createObsidianExtension, shouldExport, type ObsidianConfig } from "@cueloop/integration-obsidian";
-import { buildDisplay, nextWorkBlock, type DisplayBlock } from "./view";
+import { buildDisplay, nextWorkBlock, type DisplayBlock } from "./view-plan";
 import { diffRowAnchor, diffRows, type DiffRow } from "./view-diff";
+import { firstUnviewedIndex, walkFiles, type WalkFile } from "./walk";
 import { editInEditor } from "./editor";
 import { focusHerdrPane, returnPaneFor } from "./herdr";
 import { persistAutoClose, type AutoClose, type CueloopConfig } from "./config";
@@ -53,6 +54,12 @@ export interface ControllerSnapshot {
    * hand-off - the reconciliation banner count. 0 = no banner.
    */
   editOrphanCount: number;
+  /**
+   * The guided walk's cursor (diff sessions): which wizard step is on
+   * screen. index === file count is the end card. null = not walking; the
+   * viewed set itself rides the session record, so leaving loses nothing.
+   */
+  walk: { index: number } | null;
 }
 
 export interface ReviewControllerOptions {
@@ -74,27 +81,36 @@ export interface ReviewController {
   connect(): void;
   close(): void;
   /** Loaded config parts the controller acts on: auto-close and exporters. */
-  applyConfig(cfg: CueloopConfig): void;
-  setStatus(msg: string): void;
+  applyConfig(config: CueloopConfig): void;
+  setStatus(message: string): void;
   /** Derived projections, cached per session identity. */
   display(): DisplayBlock[];
   rows(): DiffRow[];
+  /** The walk's step list, derived from the diff rows. */
+  files(): WalkFile[];
   working(): string;
   /** Open a session from the inbox. */
   open(id: string): void;
   /** Cut the block under the cursor, or restore a cut one. */
-  cut(dispIdx: number): void;
+  cut(displayIndex: number): void;
   /** The $EDITOR hand-off on the working copy. */
   edit(): void;
   /**
    * Anchor and store an annotation; both plan and diff anchor constructions.
    * Returns the minted annotation id so the view can select the new card.
    */
-  annotate(kind: "comment" | "suggestion", dispIdx: number, start: number, end: number, body: string): string | undefined;
+  annotate(kind: "comment" | "suggestion", displayIndex: number, start: number, end: number, body: string): string | undefined;
   /** Rewrite a stored annotation's body in place (the rail-card edit). */
   updateAnnotation(id: string, body: string): void;
   removeAnnotation(id: string): void;
   setWorkingCopy(content: string | undefined): void;
+  /** Enter the guided walk at the first unviewed file (diff sessions). */
+  walkStart(): void;
+  /** Mark the current file viewed (persists with the session) and advance. */
+  walkForward(): void;
+  walkBack(): void;
+  /** Leave the walk; the viewed set stays on the session record. */
+  walkLeave(): void;
   /** Resolve the review, run the export, start the completion hand-back. */
   submit(verdict: VerdictKind, summary: string): void;
   /** Close the review and, inside herdr, bounce focus back to the agent. */
@@ -104,21 +120,22 @@ export interface ReviewController {
   optInAutoClose(): void;
 }
 
-export function createReviewController(opts: ReviewControllerOptions): ReviewController {
-  return new Controller(opts);
+export function createReviewController(options: ReviewControllerOptions): ReviewController {
+  return new Controller(options);
 }
 
 class Controller implements ReviewController {
   readonly readOnly: boolean;
   private client: DaemonClient | null = null;
   private closed = false;
-  private snap: ControllerSnapshot = {
+  private snapshot: ControllerSnapshot = {
     session: null,
     inbox: null,
     status: "",
     error: null,
     completion: { phase: "idle" },
     editOrphanCount: 0,
+    walk: null,
   };
   private listeners = new Set<() => void>();
   private autoClose: AutoClose = "off";
@@ -128,11 +145,15 @@ class Controller implements ReviewController {
   private countdown: TimerHandle | undefined;
   /** Projections keyed by session identity so renders reuse one computation. */
   private derivedFor: ReviewSession | null = null;
-  private derived: { display: DisplayBlock[]; rows: DiffRow[] } = { display: [], rows: [] };
+  private derived: { display: DisplayBlock[]; rows: DiffRow[]; files: WalkFile[] } = {
+    display: [],
+    rows: [],
+    files: [],
+  };
 
-  constructor(private readonly opts: ReviewControllerOptions) {
-    this.readOnly = opts.readOnly ?? false;
-    this.clock = opts.clock ?? new SystemClock();
+  constructor(private readonly options: ReviewControllerOptions) {
+    this.readOnly = options.readOnly ?? false;
+    this.clock = options.clock ?? new SystemClock();
   }
 
   subscribe = (listener: () => void): (() => void) => {
@@ -140,28 +161,28 @@ class Controller implements ReviewController {
     return () => this.listeners.delete(listener);
   };
 
-  getSnapshot = (): ControllerSnapshot => this.snap;
+  getSnapshot = (): ControllerSnapshot => this.snapshot;
 
   private update(patch: Partial<ControllerSnapshot>): void {
-    this.snap = { ...this.snap, ...patch };
-    for (const l of this.listeners) l();
+    this.snapshot = { ...this.snapshot, ...patch };
+    for (const listener of this.listeners) listener();
   }
 
   connect(): void {
     void (async () => {
       try {
-        const client = await DaemonClient.connect({ home: this.opts.home, autostart: true });
+        const client = await DaemonClient.connect({ home: this.options.home, autostart: true });
         if (this.closed) return void client.close();
         this.client = client;
-        client.onEvent((e) => {
+        client.onEvent((event) => {
           // another controller/observer changed state: re-fetch
-          const s = this.snap.session;
-          if (s && e.sessionId === s.id) void this.refreshSession(s.id);
-          if (!this.opts.sessionId) void this.refreshInbox();
+          const session = this.snapshot.session;
+          if (session && event.sessionId === session.id) void this.refreshSession(session.id);
+          if (!this.options.sessionId) void this.refreshInbox();
         });
         await client.subscribe();
-        if (this.opts.sessionId) {
-          this.update({ session: await client.sessionGet(this.opts.sessionId) });
+        if (this.options.sessionId) {
+          this.update({ session: await client.sessionGet(this.options.sessionId) });
         } else {
           this.update({ inbox: await client.sessionList({ status: "pending" }) });
         }
@@ -182,28 +203,30 @@ class Controller implements ReviewController {
     this.countdown = undefined;
   }
 
-  applyConfig(cfg: CueloopConfig): void {
-    this.autoClose = cfg.ui.autoClose;
-    this.obsidian = cfg.integrations.obsidian;
+  applyConfig(config: CueloopConfig): void {
+    this.autoClose = config.ui.autoClose;
+    this.obsidian = config.integrations.obsidian;
     // bundled integrations register through the public extension API
     const registry = new Registry();
-    void registry.load("obsidian", createObsidianExtension(cfg.integrations.obsidian)).then((rec) => {
-      this.exporters = rec.exporters;
+    void registry.load("obsidian", createObsidianExtension(config.integrations.obsidian)).then((record) => {
+      this.exporters = record.exporters;
     });
   }
 
-  setStatus(msg: string): void {
-    this.update({ status: msg });
+  setStatus(message: string): void {
+    this.update({ status: message });
   }
 
   // ── derived projections ─────────────────────
   private ensureDerived(): void {
-    const s = this.snap.session;
-    if (this.derivedFor === s) return;
-    this.derivedFor = s;
+    const session = this.snapshot.session;
+    if (this.derivedFor === session) return;
+    this.derivedFor = session;
+    const rows = session && session.artifact.type === "diff" ? diffRows(session.artifact.content) : [];
     this.derived = {
-      display: s ? buildDisplay(s.artifact.content, s.workingCopy) : [],
-      rows: s && s.artifact.type === "diff" ? diffRows(s.artifact.content) : [],
+      display: session ? buildDisplay(session.artifact.content, session.workingCopy) : [],
+      rows,
+      files: walkFiles(rows),
     };
   }
 
@@ -217,9 +240,14 @@ class Controller implements ReviewController {
     return this.derived.rows;
   }
 
+  files(): WalkFile[] {
+    this.ensureDerived();
+    return this.derived.files;
+  }
+
   working(): string {
-    const s = this.snap.session;
-    return s ? (s.workingCopy ?? s.artifact.content) : "";
+    const session = this.snapshot.session;
+    return session ? (session.workingCopy ?? session.artifact.content) : "";
   }
 
   // Refreshes race the connection teardown: an event can arrive while close()
@@ -242,40 +270,41 @@ class Controller implements ReviewController {
   }
 
   /** Optimistic apply: the daemon response is the next session snapshot. */
-  private apply(p: Promise<ReviewSession>): void {
-    p.then((session) => this.update({ session })).catch((e: unknown) =>
-      this.setStatus(String(e instanceof Error ? e.message : e)),
+  private apply(mutation: Promise<ReviewSession>): void {
+    mutation.then((session) => this.update({ session })).catch((error: unknown) =>
+      this.setStatus(String(error instanceof Error ? error.message : error)),
     );
   }
 
   // ── verbs ───────────────────────────────────
   open(id: string): void {
-    const cached = this.snap.inbox?.find((s) => s.id === id);
+    this.locallyViewed.clear();
+    const cached = this.snapshot.inbox?.find((candidate) => candidate.id === id);
     if (cached) this.update({ session: cached });
     else void this.refreshSession(id);
   }
 
-  cut(dispIdx: number): void {
-    const session = this.snap.session;
+  cut(displayIndex: number): void {
+    const session = this.snapshot.session;
     if (!session || session.status === "resolved") return;
-    const d = this.display()[dispIdx];
-    if (!d) return;
+    const block = this.display()[displayIndex];
+    if (!block) return;
     const working = this.working();
-    if (d.type === "del") {
-      const line = restoreLine(nextWorkBlock(this.display(), dispIdx), working.split("\n").length);
+    if (block.type === "del") {
+      const line = restoreLine(nextWorkBlock(this.display(), displayIndex), working.split("\n").length);
       // restoreBlock returns undefined when the block structure round-trips
       // to the submitted revision - the working copy is gone
-      const restored = restoreBlock(session.artifact.content, working, d.base!, line);
+      const restored = restoreBlock(session.artifact.content, working, block.base!, line);
       this.setWorkingCopy(restored);
       this.setStatus("cut restored");
-    } else if (d.work) {
-      this.setWorkingCopy(cutBlock(working, d.work));
+    } else if (block.work) {
+      this.setWorkingCopy(cutBlock(working, block.work));
       this.setStatus("block cut - it serializes into the diff");
     }
   }
 
   edit(): void {
-    const session = this.snap.session;
+    const session = this.snapshot.session;
     if (!session || session.status === "resolved") return;
     try {
       const result = editInEditor(this.working(), "plan.md");
@@ -305,21 +334,21 @@ class Controller implements ReviewController {
 
   annotate(
     kind: "comment" | "suggestion",
-    dispIdx: number,
+    displayIndex: number,
     start: number,
     end: number,
     body: string,
   ): string | undefined {
-    const session = this.snap.session;
+    const session = this.snapshot.session;
     if (!session) return undefined;
     let anchor;
     if (session.artifact.type === "diff") {
-      anchor = { ...diffRowAnchor(this.rows(), dispIdx), blockIndex: dispIdx };
+      anchor = { ...diffRowAnchor(this.rows(), displayIndex), blockIndex: displayIndex };
     } else {
       const display = this.display();
-      const workBlocks = display.filter((d) => d.work).map((d) => d.work!);
-      const workIdx = display.slice(0, dispIdx + 1).filter((d) => d.work).length - 1;
-      anchor = makeAnchor(workBlocks, workIdx, start, end);
+      const workBlocks = display.filter((entry) => entry.work).map((entry) => entry.work!);
+      const workBlockIndex = display.slice(0, displayIndex + 1).filter((entry) => entry.work).length - 1;
+      anchor = makeAnchor(workBlocks, workBlockIndex, start, end);
     }
     const annotationId = newAnnotationId();
     this.apply(
@@ -335,7 +364,7 @@ class Controller implements ReviewController {
   }
 
   updateAnnotation(id: string, body: string): void {
-    const session = this.snap.session;
+    const session = this.snapshot.session;
     if (!session) return;
     const existing = session.annotations.find((annotation) => annotation.id === id);
     if (!existing) return;
@@ -352,21 +381,66 @@ class Controller implements ReviewController {
   }
 
   removeAnnotation(id: string): void {
-    const session = this.snap.session;
+    const session = this.snapshot.session;
     if (!session) return;
     this.apply(this.client!.sessionRemoveAnnotation(session.id, id));
     this.setStatus("annotation deleted");
   }
 
   setWorkingCopy(content: string | undefined): void {
-    const session = this.snap.session;
+    const session = this.snapshot.session;
     if (!session) return;
     this.apply(this.client!.sessionSetWorkingCopy(session.id, content));
   }
 
+  // ── the guided walk ─────────────────────────
+  // Marks sent but possibly not yet reflected in the session snapshot; the
+  // union keeps the walk title truthful and rapid advances from losing marks.
+  private locallyViewed = new Set<string>();
+
+  private viewedSet(): Set<string> {
+    return new Set([...(this.snapshot.session?.viewedPaths ?? []), ...this.locallyViewed]);
+  }
+
+  walkStart(): void {
+    const session = this.snapshot.session;
+    if (!session || session.artifact.type !== "diff") return;
+    const files = this.files();
+    if (files.length === 0) return this.setStatus("nothing to walk - the diff is empty");
+    // resume at the first unviewed file; a finished walk reopens on the end card
+    this.update({ walk: { index: firstUnviewedIndex(files, this.viewedSet()) } });
+  }
+
+  walkForward(): void {
+    const walk = this.snapshot.walk;
+    const session = this.snapshot.session;
+    if (!walk || !session) return;
+    const files = this.files();
+    const current = files[walk.index];
+    if (!current) return; // already on the end card
+    // advancing IS the viewed mark: the step is complete once you move past
+    // it; the daemon verb merges, so only the new path travels
+    if (!this.viewedSet().has(current.path)) {
+      this.locallyViewed.add(current.path);
+      this.apply(this.client!.sessionSetViewed(session.id, [current.path]));
+    }
+    this.update({ walk: { index: walk.index + 1 } });
+  }
+
+  walkBack(): void {
+    const walk = this.snapshot.walk;
+    if (!walk) return;
+    this.update({ walk: { index: Math.max(0, walk.index - 1) } });
+  }
+
+  walkLeave(): void {
+    if (this.snapshot.walk) this.update({ walk: null });
+  }
+
   submit(verdict: VerdictKind, summary: string): void {
-    const session = this.snap.session;
+    const session = this.snapshot.session;
     if (!session) return;
+    this.walkLeave();
     this.client!.sessionResolve(session.id, verdict, summary)
       .then((resolved) => {
         // The completion overlay heading already states the verdict, so the
@@ -376,8 +450,8 @@ class Controller implements ReviewController {
         const obsidian = this.obsidian;
         const exporter = this.exporters.get("obsidian");
         if (obsidian && exporter && shouldExport(obsidian.exportOn, verdict)) {
-          void exporter(resolved).then((r) => {
-            this.setStatus(r.success && r.path ? `exported to ${r.path}` : `export failed: ${r.error ?? "unknown"}`);
+          void exporter(resolved).then((exportResult) => {
+            this.setStatus(exportResult.success && exportResult.path ? `exported to ${exportResult.path}` : `export failed: ${exportResult.error ?? "unknown"}`);
           });
         }
         // Hand the reviewer back to the agent. The default is a visible
@@ -388,7 +462,7 @@ class Controller implements ReviewController {
         else if (typeof delay === "number") this.startCounting(delay);
         else this.startCounting(DEFAULT_AUTO_CLOSE);
       })
-      .catch((e: unknown) => this.setStatus(String(e instanceof Error ? e.message : e)));
+      .catch((error: unknown) => this.setStatus(String(error instanceof Error ? error.message : error)));
   }
 
   // ── completion hand-back ────────────────────
@@ -400,9 +474,9 @@ class Controller implements ReviewController {
 
   finishReview(): void {
     this.clearCountdown();
-    const pane = returnPaneFor(this.snap.session?.artifact.meta.herdrPane);
+    const pane = returnPaneFor(this.snapshot.session?.artifact.meta.herdrPane);
     if (pane) focusHerdrPane(pane);
-    this.opts.onExit?.(0);
+    this.options.onExit?.(0);
   }
 
   dismissCompletion(): void {

package/src/theme.ts

@@ -1,5 +1,5 @@
 /**
- * Semantic theme tokens (#22). Values carry over from the design-system
+ * Semantic theme tokens. Values carry over from the design-system
  * prototypes (tokens.css). One built-in dark theme for now; the theme
  * registry (palette-derived themes, terminal theme, user overrides) layers
  * on top of these slots without touching consumers.
@@ -27,6 +27,25 @@ export interface Theme {
   backdrop: string;
 }
 
+/**
+ * The dimmed variant behind the walk wizard: every reading color drops to
+ * the dim token so the file list stays legible context, not competition.
+ * Layout tokens (backgrounds, cursor) keep their values.
+ */
+export function dimmedTheme(theme: Theme): Theme {
+  return {
+    ...theme,
+    text: theme.textDim,
+    textMuted: theme.textDim,
+    accent: theme.textDim,
+    green: theme.textDim,
+    red: theme.textDim,
+    blue: theme.textDim,
+    insFg: theme.textDim,
+    delFg: theme.textDim,
+  };
+}
+
 export const DARK: Theme = {
   bg: "#1f1f29",
   panel: "#1a1a23",

package/src/view-diff.test.ts

@@ -22,22 +22,22 @@ index 111..222 100644
 describe("diffRows", () => {
   test("flattens files, hunks, and signed lines with line numbers", () => {
     const rows = diffRows(PATCH);
-    expect(rows[0]).toMatchObject({ t: "file", file: "src/store.ts" });
-    expect(rows[1]!.t).toBe("hunk");
-    const del = rows.find((r) => r.t === "del")!;
+    expect(rows[0]).toMatchObject({ kind: "file", file: "src/store.ts" });
+    expect(rows[1]!.kind).toBe("hunk");
+    const del = rows.find((row) => row.kind === "del")!;
     expect(del.text).toContain("private items = [];");
     expect(del.oldLine).toBe(3);
-    const adds = rows.filter((r) => r.t === "add");
+    const adds = rows.filter((row) => row.kind === "add");
     expect(adds[0]!.text).toContain("new Map()");
     expect(adds[0]!.newLine).toBe(3);
     expect(adds[1]!.newLine).toBe(4);
     // two hunks
-    expect(rows.filter((r) => r.t === "hunk").length).toBe(2);
+    expect(rows.filter((row) => row.kind === "hunk").length).toBe(2);
   });
 
   test("context lines carry both line numbers", () => {
     const rows = diffRows(PATCH);
-    const ctx = rows.find((r) => r.t === "ctx")!;
+    const ctx = rows.find((row) => row.kind === "ctx")!;
     expect(ctx.oldLine).toBe(1);
     expect(ctx.newLine).toBe(1);
   });
@@ -46,8 +46,8 @@ describe("diffRows", () => {
 describe("diffRowAnchor", () => {
   test("quote is the line, neighbors are the context selectors", () => {
     const rows = diffRows(PATCH);
-    const idx = rows.findIndex((r) => r.text.includes("new Map()"));
-    const anchor = diffRowAnchor(rows, idx);
+    const rowIndex = rows.findIndex((row) => row.text.includes("new Map()"));
+    const anchor = diffRowAnchor(rows, rowIndex);
     expect(anchor.quote).toContain("new Map()");
     expect(anchor.prefix.length).toBeGreaterThan(0);
     expect(anchor.suffix.length).toBeGreaterThan(0);

package/src/view-diff.ts

@@ -1,5 +1,5 @@
 /**
- * Diff artifact projection (#18 slice 3): flatten @pierre/diffs' parsed
+ * Diff artifact projection: flatten @pierre/diffs' parsed
  * patch model into render rows. Line-anchored annotations use the same
  * quote-primary anchors as plans: quote = the line content, prefix/suffix =
  * the neighbor lines - so the whole anchor/feedback pipeline is shared.
@@ -7,10 +7,10 @@
 
 import { parsePatchFiles, type FileDiffMetadata } from "@pierre/diffs";
 
-export type DiffRowType = "file" | "hunk" | "ctx" | "add" | "del";
+export type DiffRowKind = "file" | "hunk" | "ctx" | "add" | "del";
 
 export interface DiffRow {
-  t: DiffRowType;
+  kind: DiffRowKind;
   text: string;
   file: string;
   oldLine?: number;
@@ -22,35 +22,35 @@ export function diffRows(patchText: string): DiffRow[] {
   const patches = parsePatchFiles(patchText);
   for (const patch of patches) {
     for (const file of patch.files) {
-      rows.push({ t: "file", text: fileLabel(file), file: file.name });
+      rows.push({ kind: "file", text: fileLabel(file), file: file.name });
       for (const hunk of file.hunks) {
-        rows.push({ t: "hunk", text: hunk.hunkSpecs ?? "@@", file: file.name });
+        rows.push({ kind: "hunk", text: hunk.hunkSpecs ?? "@@", file: file.name });
         let oldLine = hunk.deletionStart;
         let newLine = hunk.additionStart;
-        for (const seg of hunk.hunkContent) {
-          if (seg.type === "context") {
-            for (let i = 0; i < seg.lines; i++) {
+        for (const segment of hunk.hunkContent) {
+          if (segment.type === "context") {
+            for (let i = 0; i < segment.lines; i++) {
               rows.push({
-                t: "ctx",
-                text: file.additionLines[seg.additionLineIndex + i] ?? "",
+                kind: "ctx",
+                text: file.additionLines[segment.additionLineIndex + i] ?? "",
                 file: file.name,
                 oldLine: oldLine++,
                 newLine: newLine++,
               });
             }
           } else {
-            for (let i = 0; i < seg.deletions; i++) {
+            for (let i = 0; i < segment.deletions; i++) {
               rows.push({
-                t: "del",
-                text: file.deletionLines[seg.deletionLineIndex + i] ?? "",
+                kind: "del",
+                text: file.deletionLines[segment.deletionLineIndex + i] ?? "",
                 file: file.name,
                 oldLine: oldLine++,
               });
             }
-            for (let i = 0; i < seg.additions; i++) {
+            for (let i = 0; i < segment.additions; i++) {
               rows.push({
-                t: "add",
-                text: file.additionLines[seg.additionLineIndex + i] ?? "",
+                kind: "add",
+                text: file.additionLines[segment.additionLineIndex + i] ?? "",
                 file: file.name,
                 newLine: newLine++,
               });
@@ -68,14 +68,14 @@ function fileLabel(file: FileDiffMetadata): string {
 }
 
 /** Quote-primary anchor for a diff row: neighbors as context selectors. */
-export function diffRowAnchor(rows: DiffRow[], idx: number): { quote: string; prefix: string; suffix: string } {
-  const row = rows[idx]!;
-  const prev = rows[idx - 1];
-  const next = rows[idx + 1];
+export function diffRowAnchor(rows: DiffRow[], rowIndex: number): { quote: string; prefix: string; suffix: string } {
+  const row = rows[rowIndex]!;
+  const prev = rows[rowIndex - 1];
+  const next = rows[rowIndex + 1];
   return {
     quote: row.text,
-    prefix: prev && (prev.t === "ctx" || prev.t === "add" || prev.t === "del") ? prev.text.slice(-24) : "",
-    suffix: next && (next.t === "ctx" || next.t === "add" || next.t === "del") ? next.text.slice(0, 24) : "",
+    prefix: prev && (prev.kind === "ctx" || prev.kind === "add" || prev.kind === "del") ? prev.text.slice(-24) : "",
+    suffix: next && (next.kind === "ctx" || next.kind === "add" || next.kind === "del") ? next.text.slice(0, 24) : "",
   };
 }