@cueloop/client 0.1.0-alpha.0

package/src/config.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DEFAULT_KEYS, actionFor, loadConfig } from "./config";
+import { DARK } from "./theme";
+
+describe("loadConfig", () => {
+  test("defaults when no file exists", () => {
+    const c = loadConfig({ userConfigPath: "/nonexistent/config.toml" });
+    expect(c.keys["comment"]).toEqual(["c"]);
+    expect(c.theme.accent).toBe(DARK.accent);
+  });
+
+  test("user config rebinds actions and overrides theme tokens", () => {
+    const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg-"));
+    const path = join(dir, "config.toml");
+    writeFileSync(
+      path,
+      `[keys]\ncomment = "a"\nsubmit = ["return", "S"]\n\n[theme]\naccent = "#ff0000"\n`,
+    );
+    try {
+      const c = loadConfig({ userConfigPath: path });
+      expect(c.keys["comment"]).toEqual(["a"]);
+      expect(c.keys["submit"]).toEqual(["return", "S"]);
+      expect(c.keys["cut"]).toEqual(["x"]); // untouched defaults survive
+      expect(c.theme.accent).toBe("#ff0000");
+      expect(c.theme.green).toBe(DARK.green);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("repo config layers over user config", () => {
+    const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg2-"));
+    const user = join(dir, "user.toml");
+    const repoRoot = join(dir, "repo");
+    writeFileSync(user, `[keys]\ncomment = "a"\n`);
+    Bun.spawnSync(["mkdir", "-p", join(repoRoot, ".cueloop")]);
+    writeFileSync(join(repoRoot, ".cueloop", "config.toml"), `[keys]\ncomment = "z"\n`);
+    try {
+      const c = loadConfig({ userConfigPath: user, repoRoot });
+      expect(c.keys["comment"]).toEqual(["z"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("broken config never blocks a review", () => {
+    const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg3-"));
+    const path = join(dir, "config.toml");
+    writeFileSync(path, "not [valid toml");
+    try {
+      const c = loadConfig({ userConfigPath: path });
+      expect(c.keys["comment"]).toEqual(["c"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("integrations.obsidian config", () => {
+  test("defaults when the section is absent", () => {
+    const c = loadConfig({ userConfigPath: "/nonexistent/config.toml" });
+    expect(c.integrations.obsidian.vault).toBeUndefined();
+    expect(c.integrations.obsidian.folder).toBe("cueloop");
+    expect(c.integrations.obsidian.filenameFormat).toBe("{YYYY}-{MM}-{DD} - {title}");
+    expect(c.integrations.obsidian.separator).toBe("space");
+    expect(c.integrations.obsidian.exportOn).toBe("manual");
+  });
+
+  test("user config sets the section; invalid enum values are ignored", () => {
+    const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg-obs-"));
+    const path = join(dir, "config.toml");
+    writeFileSync(
+      path,
+      `[integrations.obsidian]\nvault = "/notes/vault"\nfolder = "plans"\nexportOn = "approve"\nseparator = "comma"\n`,
+    );
+    try {
+      const c = loadConfig({ userConfigPath: path });
+      expect(c.integrations.obsidian.vault).toBe("/notes/vault");
+      expect(c.integrations.obsidian.folder).toBe("plans");
+      expect(c.integrations.obsidian.exportOn).toBe("approve");
+      expect(c.integrations.obsidian.separator).toBe("space"); // invalid value falls back
+      expect(c.keys["comment"]).toEqual(["c"]); // other sections untouched
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("repo config layers over user config for the section", () => {
+    const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg-obs2-"));
+    const user = join(dir, "user.toml");
+    const repoRoot = join(dir, "repo");
+    writeFileSync(user, `[integrations.obsidian]\nvault = "/user/vault"\nexportOn = "resolve"\n`);
+    Bun.spawnSync(["mkdir", "-p", join(repoRoot, ".cueloop")]);
+    writeFileSync(join(repoRoot, ".cueloop", "config.toml"), `[integrations.obsidian]\nfolder = "repo-plans"\n`);
+    try {
+      const c = loadConfig({ userConfigPath: user, repoRoot });
+      expect(c.integrations.obsidian.vault).toBe("/user/vault"); // user layer survives
+      expect(c.integrations.obsidian.exportOn).toBe("resolve");
+      expect(c.integrations.obsidian.folder).toBe("repo-plans"); // repo layer wins
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("actionFor", () => {
+  test("resolves keys and shifted keys to actions", () => {
+    expect(actionFor(DEFAULT_KEYS, "j", false)).toBe("down");
+    expect(actionFor(DEFAULT_KEYS, "g", true)).toBe("bottom"); // G
+    expect(actionFor(DEFAULT_KEYS, "return", false)).toBe("submit");
+    expect(actionFor(DEFAULT_KEYS, "zz", false)).toBeUndefined();
+  });
+});

package/src/config.ts

@@ -0,0 +1,113 @@
+/**
+ * Layered TOML config (#20): built-in defaults → user config → trusted repo
+ * config → env. Sections: [keys] action = "combo" (every action rebindable),
+ * [theme] per-token overrides, [integrations.obsidian] notes-vault export.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { OBSIDIAN_DEFAULTS, type ObsidianConfig } from "@cueloop/integration-obsidian";
+import { DARK, type Theme } from "./theme";
+
+export interface KeymapConfig {
+  [action: string]: string | string[];
+}
+
+export interface IntegrationsConfig {
+  obsidian: ObsidianConfig;
+}
+
+export interface CueloopConfig {
+  keys: Record<string, string[]>;
+  theme: Theme;
+  integrations: IntegrationsConfig;
+}
+
+/** Every action in the grammar, with its default binding(s). */
+export const DEFAULT_KEYS: Record<string, string[]> = {
+  down: ["j", "down"],
+  up: ["k", "up"],
+  top: ["g"],
+  bottom: ["G"],
+  span: ["v"],
+  comment: ["c"],
+  suggest: ["s"],
+  cut: ["x"],
+  edit: ["e"],
+  next_annotation: ["n"],
+  prev_annotation: ["p"],
+  delete_annotation: ["backspace"],
+  submit: ["return", "enter"],
+  quit: ["q"],
+};
+
+function parseToml(text: string): Record<string, unknown> {
+  // Bun ships a native TOML parser
+  return Bun.TOML.parse(text) as Record<string, unknown>;
+}
+
+function layer(base: CueloopConfig, raw: Record<string, unknown>): CueloopConfig {
+  const out: CueloopConfig = {
+    keys: { ...base.keys },
+    theme: { ...base.theme },
+    integrations: { obsidian: { ...base.integrations.obsidian } },
+  };
+  const keys = raw["keys"] as KeymapConfig | undefined;
+  if (keys) {
+    for (const [action, combo] of Object.entries(keys)) {
+      out.keys[action] = Array.isArray(combo) ? combo : [combo];
+    }
+  }
+  const theme = raw["theme"] as Partial<Record<keyof Theme, string>> | undefined;
+  if (theme) {
+    for (const [token, value] of Object.entries(theme)) {
+      if (token in out.theme && typeof value === "string") {
+        (out.theme as unknown as Record<string, string>)[token] = value;
+      }
+    }
+  }
+  const integrations = raw["integrations"] as Record<string, unknown> | undefined;
+  const obsidian = integrations?.["obsidian"] as Record<string, unknown> | undefined;
+  if (obsidian) {
+    const o = out.integrations.obsidian;
+    if (typeof obsidian["vault"] === "string") o.vault = obsidian["vault"];
+    if (typeof obsidian["folder"] === "string") o.folder = obsidian["folder"];
+    if (typeof obsidian["filenameFormat"] === "string") o.filenameFormat = obsidian["filenameFormat"];
+    const sep = obsidian["separator"];
+    if (sep === "space" || sep === "dash" || sep === "underscore") o.separator = sep;
+    const on = obsidian["exportOn"];
+    if (on === "approve" || on === "resolve" || on === "manual") o.exportOn = on;
+  }
+  return out;
+}
+
+export function loadConfig(opts: { repoRoot?: string; userConfigPath?: string } = {}): CueloopConfig {
+  let config: CueloopConfig = {
+    keys: { ...DEFAULT_KEYS },
+    theme: { ...DARK },
+    integrations: { obsidian: { ...OBSIDIAN_DEFAULTS } },
+  };
+  const userPath =
+    opts.userConfigPath ??
+    process.env.CUELOOP_CONFIG ??
+    join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "cueloop", "config.toml");
+  for (const path of [userPath, opts.repoRoot ? join(opts.repoRoot, ".cueloop", "config.toml") : undefined]) {
+    if (!path || !existsSync(path)) continue;
+    try {
+      config = layer(config, parseToml(readFileSync(path, "utf8")));
+    } catch {
+      // a broken config never blocks a review; defaults win
+    }
+  }
+  return config;
+}
+
+/** Reverse lookup: key name (+shift) → action, per the loaded keymap. */
+export function actionFor(keys: Record<string, string[]>, name: string, shift: boolean): string | undefined {
+  const wanted = shift && name.length === 1 ? name.toUpperCase() : name;
+  for (const [action, combos] of Object.entries(keys)) {
+    if (combos.includes(wanted)) return action;
+  }
+  return undefined;
+}

package/src/editor.ts

@@ -0,0 +1,34 @@
+/**
+ * File-level edit mode = the $EDITOR hand-off (#22, #11): write the working
+ * copy to a temp file, run the user's editor on it, read the result back.
+ * Tests point CUELOOP_EDITOR at a non-interactive command.
+ */
+
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export interface EditResult {
+  content: string;
+  changed: boolean;
+}
+
+export function editInEditor(content: string, filename = "plan.md"): EditResult {
+  const editor = process.env.CUELOOP_EDITOR ?? process.env.VISUAL ?? process.env.EDITOR;
+  if (!editor) throw new Error("no editor: set $EDITOR (or $CUELOOP_EDITOR)");
+  const dir = mkdtempSync(join(tmpdir(), "cueloop-edit-"));
+  const path = join(dir, filename);
+  writeFileSync(path, content);
+  try {
+    const proc = Bun.spawnSync([...editor.split(" "), path], {
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+    });
+    if (proc.exitCode !== 0) throw new Error(`editor exited ${proc.exitCode}`);
+    const next = readFileSync(path, "utf8");
+    return { content: next, changed: next !== content };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { runClient, type RunClientOptions } from "./run";
+export { serveClient, type ServeHandle, type ServeOptions } from "./serve";

package/src/run.ts

@@ -0,0 +1,28 @@
+/** Real-terminal entry: render the App and resolve when the user quits. */
+
+import React from "react";
+import { createCliRenderer } from "@opentui/core";
+import { createRoot } from "@opentui/react";
+import { App } from "./App";
+
+export interface RunClientOptions {
+  sessionId?: string;
+  home?: string;
+}
+
+export async function runClient(opts: RunClientOptions): Promise<number> {
+  const renderer = await createCliRenderer();
+  return new Promise<number>((resolve) => {
+    createRoot(renderer).render(
+      React.createElement(App, {
+        home: opts.home,
+        sessionId: opts.sessionId,
+        onExit: (code: number) => {
+          renderer.destroy();
+          resolve(code);
+          process.exit(code);
+        },
+      }),
+    );
+  });
+}

package/src/serve.test.ts

@@ -0,0 +1,96 @@
+/**
+ * SSH smoke test: serveClient on an ephemeral localhost port, a programmatic
+ * ssh2 client connects with no credentials (the tunnel-of-trust model),
+ * requests a PTY shell, and the first frames carry the observer TUI.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Client } from "ssh2";
+import { DaemonServer } from "@cueloop/daemon";
+import type { ReviewSession } from "@cueloop/schema";
+import { serveClient, type ServeHandle } from "./serve";
+
+const PLAN = "# Rollout Plan\n\nShip the store move behind a flag.\n";
+
+let home: string;
+let daemon: DaemonServer;
+let session: ReviewSession;
+let handle: ServeHandle;
+
+beforeEach(async () => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-serve-"));
+  daemon = new DaemonServer({ home, idleExitMs: 0 });
+  daemon.start();
+  session = daemon.core.sessionCreate({
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: "plan", content: PLAN, meta: { title: "Rollout Plan", planPath: "plan.md" } },
+  });
+  handle = await serveClient({ port: 0, sessionId: session.id, home, banner: false });
+});
+
+afterEach(async () => {
+  await handle.close();
+  daemon.stop();
+  rmSync(home, { recursive: true, force: true });
+});
+
+/** 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> {
+  return new Promise((resolve, reject) => {
+    const conn = new Client();
+    let out = "";
+    let done = false;
+    const finish = (err?: Error) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      conn.end();
+      err ? reject(err) : resolve(out);
+    };
+    const timer = setTimeout(() => finish(new Error(`timed out; captured:\n${out}`)), timeoutMs);
+    conn
+      .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");
+            if (until(out)) finish();
+          });
+          stream.on("close", () => finish(new Error(`stream closed early; captured:\n${out}`)));
+        });
+      })
+      .on("error", (err) => finish(err))
+      // password-less: the server runs auth "open", so `none` auth succeeds
+      .connect({ host: "127.0.0.1", port, username: "observer" });
+  });
+}
+
+describe("cueloop serve", () => {
+  test("listens on localhost, persists a host key under CUELOOP_HOME/ssh", () => {
+    expect(handle.host).toBe("127.0.0.1");
+    expect(handle.port).toBeGreaterThan(0);
+    expect(handle.fingerprints.length).toBe(1);
+    expect(handle.fingerprints[0]).toStartWith("SHA256:");
+    expect(existsSync(join(home, "ssh", "host_key"))).toBe(true);
+  });
+
+  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"));
+    expect(bytes).toContain("cueloop");
+    expect(bytes).toContain("Rollout Plan");
+    // observer chrome, not the controller's mutating hint bar
+    expect(bytes).toContain("observer - read-only");
+  });
+
+  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")),
+    ]);
+    expect(a).toContain("Rollout Plan");
+    expect(b).toContain("Rollout Plan");
+  });
+});

package/src/serve.ts

@@ -0,0 +1,75 @@
+/**
+ * SSH-served TUI (#22 share path): `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.
+ *
+ * Trust model - tunnel of trust, no passwords, no keys:
+ * the server authenticates nobody ("open" auth). Access control is the act of
+ * sharing the address deliberately: it binds to 127.0.0.1 by default, so a
+ * remote teammate reaches it only through a channel the owner opened on
+ * purpose (an SSH tunnel, a tailnet address via --host). Anyone who can reach
+ * the port can watch - and only watch: observers cannot mutate the session.
+ * The host key is generated once under CUELOOP_HOME/ssh/host_key (0600) so
+ * fingerprints stay stable across restarts.
+ */
+
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import React from "react";
+import { createRoot } from "@opentui/react";
+import { createServer } from "@opentui/ssh";
+import { cueloopHome } from "@cueloop/daemon";
+import { App } from "./App";
+
+export interface ServeOptions {
+  /** TCP port for the SSH listener; 0 picks an ephemeral port. Default 2222. */
+  port?: number;
+  /** Bind address. Default 127.0.0.1 - widen deliberately (e.g. a tailnet IP). */
+  host?: string;
+  /** Open every connection on this session; omit for the inbox. */
+  sessionId?: string;
+  /** CUELOOP_HOME override (daemon socket + ssh host key live under it). */
+  home?: string;
+  /** Silence the @opentui/ssh startup banner (tests). Default true. */
+  banner?: boolean;
+  onError?: (err: unknown) => void;
+}
+
+export interface ServeHandle {
+  host: string;
+  port: number;
+  /** SHA256 host-key fingerprints, for out-of-band verification. */
+  fingerprints: string[];
+  close(): Promise<void>;
+}
+
+export async function serveClient(opts: ServeOptions = {}): Promise<ServeHandle> {
+  const home = opts.home ?? cueloopHome();
+  const sshDir = join(home, "ssh");
+  mkdirSync(sshDir, { recursive: true, mode: 0o700 });
+
+  const server = createServer({
+    // password-less by design; see the trust model in the module comment
+    auth: "open",
+    hostKey: { path: join(sshDir, "host_key") },
+    startupBanner: opts.banner ?? true,
+    idleTimeout: "2h",
+    onError: opts.onError,
+  }).serve((session) => {
+    const root = createRoot(session.renderer);
+    root.render(
+      React.createElement(App, {
+        home,
+        sessionId: opts.sessionId,
+        readOnly: true,
+        // q disconnects only this observer, never the server
+        onExit: () => session.end(),
+      }),
+    );
+    session.onClose(() => root.unmount());
+  });
+
+  const info = await server.listen(opts.port ?? 2222, opts.host ?? "127.0.0.1");
+  return { ...info, close: () => server.close() };
+}

package/src/theme.ts

@@ -0,0 +1,46 @@
+/**
+ * Semantic theme tokens (#22). 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.
+ */
+
+export interface Theme {
+  bg: string;
+  panel: string;
+  elevated: string;
+  border: string;
+  text: string;
+  textMuted: string;
+  textDim: string;
+  accent: string;
+  accentInk: string;
+  green: string;
+  red: string;
+  blue: string;
+  cursorBg: string;
+  markCommentBg: string;
+  markSuggestionBg: string;
+  insFg: string;
+  delFg: string;
+}
+
+export const DARK: Theme = {
+  bg: "#1f1f29",
+  panel: "#1a1a23",
+  elevated: "#23232f",
+  border: "#3a3a4a",
+  text: "#e4e6ec",
+  textMuted: "#b1b6c4",
+  textDim: "#6b7280",
+  accent: "#f5a3a3",
+  accentInk: "#2a1416",
+  green: "#62d96b",
+  red: "#ff6b6b",
+  blue: "#84a6e8",
+  cursorBg: "#33262a",
+  markCommentBg: "#3d2a2e",
+  markSuggestionBg: "#20351f",
+  insFg: "#62d96b",
+  delFg: "#ff6b6b",
+}

package/src/view-diff.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from "bun:test";
+import { diffRowAnchor, diffRows } from "./view-diff";
+
+const PATCH = `diff --git a/src/store.ts b/src/store.ts
+index 111..222 100644
+--- a/src/store.ts
++++ b/src/store.ts
+@@ -1,5 +1,6 @@
+ import { join } from "node:path";
+ export class Store {
+-  private items = [];
++  private items = new Map();
++  private ready = false;
+   constructor() {}
+@@ -20,3 +21,3 @@
+ export function helper() {
+-  return 1;
++  return 2;
+ }
+`;
+
+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(del.text).toContain("private items = [];");
+    expect(del.oldLine).toBe(3);
+    const adds = rows.filter((r) => r.t === "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);
+  });
+
+  test("context lines carry both line numbers", () => {
+    const rows = diffRows(PATCH);
+    const ctx = rows.find((r) => r.t === "ctx")!;
+    expect(ctx.oldLine).toBe(1);
+    expect(ctx.newLine).toBe(1);
+  });
+});
+
+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);
+    expect(anchor.quote).toContain("new Map()");
+    expect(anchor.prefix.length).toBeGreaterThan(0);
+    expect(anchor.suffix.length).toBeGreaterThan(0);
+  });
+});

package/src/view-diff.ts

@@ -0,0 +1,86 @@
+/**
+ * Diff artifact projection (#18 slice 3): 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.
+ */
+
+import { parsePatchFiles, type FileDiffMetadata } from "@pierre/diffs";
+
+export type DiffRowType = "file" | "hunk" | "ctx" | "add" | "del";
+
+export interface DiffRow {
+  t: DiffRowType;
+  text: string;
+  file: string;
+  oldLine?: number;
+  newLine?: number;
+}
+
+export function diffRows(patchText: string): DiffRow[] {
+  const rows: 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 });
+      for (const hunk of file.hunks) {
+        rows.push({ t: "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++) {
+              rows.push({
+                t: "ctx",
+                text: file.additionLines[seg.additionLineIndex + i] ?? "",
+                file: file.name,
+                oldLine: oldLine++,
+                newLine: newLine++,
+              });
+            }
+          } else {
+            for (let i = 0; i < seg.deletions; i++) {
+              rows.push({
+                t: "del",
+                text: file.deletionLines[seg.deletionLineIndex + i] ?? "",
+                file: file.name,
+                oldLine: oldLine++,
+              });
+            }
+            for (let i = 0; i < seg.additions; i++) {
+              rows.push({
+                t: "add",
+                text: file.additionLines[seg.additionLineIndex + i] ?? "",
+                file: file.name,
+                newLine: newLine++,
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+  return rows;
+}
+
+function fileLabel(file: FileDiffMetadata): string {
+  return file.prevName && file.prevName !== file.name ? `${file.prevName} → ${file.name}` : file.name;
+}
+
+/** 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];
+  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) : "",
+  };
+}
+
+/** Location label for the rail and feedback: file:newLine (or old for del). */
+export function diffRowLocation(row: DiffRow): string {
+  const line = row.newLine ?? row.oldLine;
+  return line !== undefined ? `${row.file}:${line}` : row.file;
+}