@visual-z/xeno 0.2.0 → 0.3.0

package/src/store/workspace-observation.ts

@@ -0,0 +1,113 @@
+/** P.3: explicit source inventory for verification and optional Git checkpoints. */
+import { readdir, lstat } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { blobAddress, digestFile } from "./blobs.ts";
+
+// Conservative resource budgets, not measured performance targets. Exceeding them is unknown, never an empty workspace.
+const MAX_FILES = 20_000;
+const MAX_BYTES = 256 * 1024 * 1024;
+export const MAX_UNTRACKED_BYTES = 2 * 1024 * 1024;
+export const SOURCE_IGNORE = [".git", ".xeno", "node_modules", "target", ".venv", "venv", "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache", ".tox", ".gradle", ".next", ".turbo", ".cache"];
+const ignored = (path: string) => path.split("/").some(part => SOURCE_IGNORE.includes(part));
+
+/** Bounded subprocess; private-repository callers override only Git's storage, never the user's index. */
+export async function gitBytes(root: string, args: readonly string[], input?: Uint8Array, signal?: AbortSignal,
+  environment: Record<string, string> = {}): Promise<Uint8Array> {
+  if (signal?.aborted) throw new Error("Git observation cancelled");
+  const env: Record<string, string | undefined> = { ...process.env, GIT_OPTIONAL_LOCKS: "0", ...environment };
+  for (const key of ["GIT_INDEX_FILE", "GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR", "GIT_OBJECT_DIRECTORY", "GIT_ALTERNATE_OBJECT_DIRECTORIES"]) {
+    if (!(key in environment)) delete env[key];
+  }
+  const child = Bun.spawn(["git", "--no-optional-locks", ...args], { cwd: root, env, stdin: input ?? "ignore", stdout: "pipe", stderr: "pipe" });
+  const abort = () => child.kill();
+  const timer = setTimeout(abort, 10_000);
+  signal?.addEventListener("abort", abort, { once: true });
+  const read = async (stream: ReadableStream<Uint8Array>) => {
+    const reader = stream.getReader(), chunks: Uint8Array[] = [];
+    let bytes = 0;
+    for (;;) {
+      const item = await reader.read();
+      if (item.done) break;
+      bytes += item.value.length;
+      if (bytes > MAX_BYTES) { child.kill(); throw new Error("Git observation exceeds resource budget"); }
+      chunks.push(item.value);
+    }
+    return Buffer.concat(chunks);
+  };
+  try {
+    const [stdout, , code] = await Promise.all([read(child.stdout), read(child.stderr), child.exited]);
+    if (code !== 0 || signal?.aborted) throw new Error("Git observation unavailable or cancelled");
+    return stdout;
+  } finally { clearTimeout(timer); signal?.removeEventListener("abort", abort); }
+}
+const text = (bytes: Uint8Array) => new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+
+export async function sourceInventory(root: string, signal?: AbortSignal, requireGit = false, ownedPaths: readonly string[] = []): Promise<{ paths: string[]; git: boolean }> {
+  const owned = ownedPaths.map(path => relative(resolve(root), resolve(path))).filter(path => path && !path.startsWith("../"));
+  const excluded = (path: string) => ignored(path) || owned.some(directory => path === directory || path.startsWith(directory + "/"));
+  let git = false;
+  try { await gitBytes(root, ["rev-parse", "--show-toplevel"], undefined, signal); git = true; }
+  catch { if (requireGit || signal?.aborted) throw new Error("Git checkpoints require a Git working directory"); }
+  let candidates: { path: string; tracked: boolean }[] = [];
+  if (git) {
+    const tracked = text(await gitBytes(root, ["ls-files", "-z", "--cached"], undefined, signal)).split("\0").filter(Boolean);
+    const untracked = text(await gitBytes(root, ["ls-files", "-z", "--others", "--exclude-standard"], undefined, signal)).split("\0").filter(Boolean);
+    candidates = [...new Set(tracked)].map(path => ({ path, tracked: true }));
+    const known = new Set(tracked);
+    candidates.push(...untracked.filter(path => !known.has(path)).map(path => ({ path, tracked: false })));
+  } else {
+    let entries = 0;
+    const walk = async (directory: string, prefix: string): Promise<void> => {
+      if (signal?.aborted) throw new Error("workspace observation cancelled");
+      for (const entry of await readdir(directory, { withFileTypes: true })) {
+        if (++entries > MAX_FILES) throw new Error("source inventory exceeds file budget");
+        const path = prefix + entry.name;
+        if (excluded(path)) continue;
+        if (entry.isDirectory()) await walk(join(directory, entry.name), path + "/");
+        else if (entry.isFile()) candidates.push({ path, tracked: true });
+      }
+    };
+    await walk(root, "");
+  }
+  candidates = candidates.filter(candidate => !excluded(candidate.path));
+  if (candidates.length > MAX_FILES) throw new Error("source inventory exceeds file budget");
+  const paths: string[] = [];
+  let bytes = 0;
+  for (const candidate of candidates.sort((a, b) => a.path < b.path ? -1 : 1)) {
+    if (signal?.aborted) throw new Error("workspace observation cancelled");
+    const path = candidate.path;
+    if (excluded(path)) continue;
+    const parts = path.split("/");
+    if (parts.includes("..") || path.startsWith("/")) throw new Error("unsafe source inventory");
+    let safe = true;
+    for (let i = 1; i <= parts.length; i++) {
+      try {
+        const info = await lstat(join(root, ...parts.slice(0, i)));
+        if (info.isSymbolicLink() || i === parts.length && !info.isFile()) { safe = false; break; }
+        if (i === parts.length) {
+          if (!candidate.tracked && info.size > MAX_UNTRACKED_BYTES) { safe = false; break; }
+          bytes += info.size;
+        }
+      } catch (error) {
+        if ((error as { code?: string }).code !== "ENOENT") throw error;
+        safe = false; break;
+      }
+    }
+    if (bytes > MAX_BYTES) throw new Error("source inventory exceeds byte budget");
+    if (safe) paths.push(path);
+  }
+  return { paths, git };
+}
+
+export type WorkspaceObservation = { ok: true; fingerprint: string } | { ok: false; reason: string };
+export async function observeWorkspace(root: string, signal?: AbortSignal, ownedPaths: readonly string[] = []): Promise<WorkspaceObservation> {
+  try {
+    const inventory = await sourceInventory(root, signal, false, ownedPaths);
+    const entries: [string, string, number][] = [];
+    for (const path of inventory.paths) {
+      if (signal?.aborted) throw new Error("workspace observation cancelled");
+      entries.push([path, await digestFile(join(root, path)), (await lstat(join(root, path))).mode & 0o777]);
+    }
+    return { ok: true, fingerprint: blobAddress(JSON.stringify(["source-v1", inventory.git ? "git" : "files", entries])) };
+  } catch (error) { return { ok: false, reason: error instanceof Error ? error.message : "workspace observation unavailable" }; }
+}

package/src/tui/ansi-spans.ts

@@ -0,0 +1,126 @@
+/**
+ * ANSI → styled spans. Pure; no renderer import.
+ *
+ * Message content (Markdown with highlighting, Mermaid, diffs, tool views)
+ * and every extension renderer produce `string[]` lines with SGR escapes —
+ * that is the Pi-compatible component contract extensions already rely on.
+ * The OpenTUI view draws cells from styled chunks, not escapes, and ships no
+ * ANSI parser, so this module is the one bridge: it turns those lines into
+ * spans the view converts to TextChunks. Keeping the bridge here (instead of
+ * re-implementing every renderer natively) keeps the extension API and the
+ * tested renderers intact across the UI rewrite (D20).
+ *
+ * Supported: SGR 0/1/2/3/4/7/9/22/23/24/27/29, 30–37/90–97/39, 40–47/100–107/49,
+ * 38;5;n / 48;5;n, 38;2;r;g;b / 48;2;r;g;b, OSC 8 hyperlinks. Every other
+ * CSI/OSC/APC (cursor moves, Pi's cursor marker, kitty graphics) is dropped:
+ * a renderable lays out its own cells, so movement escapes have no meaning.
+ */
+
+export type SpanColor = { kind: "index"; index: number } | { kind: "rgb"; r: number; g: number; b: number };
+
+export interface SpanStyle {
+  readonly fg?: SpanColor;
+  readonly bg?: SpanColor;
+  readonly bold?: boolean;
+  readonly dim?: boolean;
+  readonly italic?: boolean;
+  readonly underline?: boolean;
+  readonly reverse?: boolean;
+  readonly strikethrough?: boolean;
+  readonly link?: string;
+}
+
+export interface Span { readonly text: string; readonly style: SpanStyle }
+
+type Mutable = { -readonly [K in keyof SpanStyle]: SpanStyle[K] };
+
+function applySgr(style: Mutable, params: number[]): void {
+  if (params.length === 0) params = [0];
+  for (let i = 0; i < params.length; i++) {
+    const p = params[i]!;
+    if (p === 0) { for (const key of Object.keys(style) as (keyof Mutable)[]) if (key !== "link") delete style[key]; }
+    else if (p === 1) style.bold = true;
+    else if (p === 2) style.dim = true;
+    else if (p === 3) style.italic = true;
+    else if (p === 4) style.underline = true;
+    else if (p === 7) style.reverse = true;
+    else if (p === 9) style.strikethrough = true;
+    else if (p === 22) { delete style.bold; delete style.dim; }
+    else if (p === 23) delete style.italic;
+    else if (p === 24) delete style.underline;
+    else if (p === 27) delete style.reverse;
+    else if (p === 29) delete style.strikethrough;
+    else if (p >= 30 && p <= 37) style.fg = { kind: "index", index: p - 30 };
+    else if (p >= 90 && p <= 97) style.fg = { kind: "index", index: p - 90 + 8 };
+    else if (p === 39) delete style.fg;
+    else if (p >= 40 && p <= 47) style.bg = { kind: "index", index: p - 40 };
+    else if (p >= 100 && p <= 107) style.bg = { kind: "index", index: p - 100 + 8 };
+    else if (p === 49) delete style.bg;
+    else if (p === 38 || p === 48) {
+      const mode = params[i + 1];
+      let color: SpanColor | undefined;
+      if (mode === 5 && params[i + 2] !== undefined) { color = { kind: "index", index: clamp(params[i + 2]!) }; i += 2; }
+      else if (mode === 2 && params[i + 4] !== undefined) { color = { kind: "rgb", r: clamp(params[i + 2]!), g: clamp(params[i + 3]!), b: clamp(params[i + 4]!) }; i += 4; }
+      else break; // malformed extended colour: ignore the rest of this sequence
+      if (p === 38) style.fg = color; else style.bg = color;
+    }
+  }
+}
+
+function clamp(n: number): number { return Math.max(0, Math.min(255, Number.isFinite(n) ? n : 0)); }
+
+function freeze(style: Mutable): SpanStyle { return { ...style }; }
+
+function sameStyle(a: SpanStyle, b: SpanStyle): boolean { return JSON.stringify(a) === JSON.stringify(b); }
+
+/** Parse one line. Adjacent text with equal style merges into one span. */
+export function ansiSpans(line: string): Span[] {
+  const spans: Span[] = [];
+  const style: Mutable = {};
+  let text = "";
+  const flush = () => {
+    if (!text) return;
+    const frozen = freeze(style);
+    const last = spans[spans.length - 1];
+    if (last && sameStyle(last.style, frozen)) spans[spans.length - 1] = { text: last.text + text, style: frozen };
+    else spans.push({ text, style: frozen });
+    text = "";
+  };
+  let i = 0;
+  while (i < line.length) {
+    const ch = line[i]!;
+    if (ch !== "\x1b") { text += ch; i++; continue; }
+    const kind = line[i + 1];
+    if (kind === "[") {
+      let j = i + 2;
+      while (j < line.length && !/[@-~]/.test(line[j]!)) j++;
+      const body = line.slice(i + 2, j);
+      if (line[j] === "m" && /^[0-9;]*$/.test(body)) {
+        flush();
+        applySgr(style, body === "" ? [] : body.split(";").map(part => (part === "" ? 0 : Number(part))));
+      }
+      i = j + 1;
+      continue;
+    }
+    if (kind === "]" || kind === "_" || kind === "P") {
+      let j = i + 2;
+      while (j < line.length && line[j] !== "\x07" && !(line[j] === "\x1b" && line[j + 1] === "\\")) j++;
+      const body = line.slice(i + 2, j);
+      if (kind === "]" && body.startsWith("8;")) {
+        flush();
+        const url = body.slice(body.indexOf(";", 2) + 1);
+        if (url) style.link = url; else delete style.link;
+      }
+      i = line[j] === "\x07" ? j + 1 : j + 2;
+      continue;
+    }
+    i += 2;
+  }
+  flush();
+  return spans;
+}
+
+/** Visible text of a line: what a terminal would print, escapes removed. */
+export function plainText(line: string): string {
+  return ansiSpans(line).map(span => span.text).join("");
+}

package/src/tui/style.ts

@@ -72,23 +72,26 @@ export type ColorTokens = {
   readonly mdLink: string;
 };
 
-/** Must stay in lockstep with core/theme.ts dark builtin. */
+/**
+ * Must stay in lockstep with core/theme.ts dark builtin: terminal slots only,
+ * no truecolor, no background, no SGR faint for muted text.
+ */
 export const DEFAULT_COLORS: ColorTokens = {
-  "text": "38;2;212;212;212",
-  "thinkingText": "38;2;128;128;128",
-  "toolTitle": "38;2;212;212;212",
-  "toolOutput": "38;2;128;128;128",
-  "error": "38;2;204;102;102",
-  "toolDiffAdded": "38;2;181;189;104",
-  "toolDiffRemoved": "38;2;204;102;102",
-  "status": "38;2;128;128;128",
-  "prompt": "38;2;212;212;212",
-  "selectedBg": "48;2;58;58;74",
-  "muted": "38;2;128;128;128",
-  "warning": "38;2;255;255;0",
-  "mdHeading": "38;2;240;198;116",
-  "mdCode": "38;2;138;190;183",
-  "mdLink": "38;2;129;162;190"
+  "text": "",
+  "thinkingText": "95",
+  "toolTitle": "",
+  "toolOutput": "37",
+  "error": "91",
+  "toolDiffAdded": "92",
+  "toolDiffRemoved": "91",
+  "status": "37",
+  "prompt": "",
+  "selectedBg": "",
+  "muted": "37",
+  "warning": "93",
+  "mdHeading": "94",
+  "mdCode": "96",
+  "mdLink": "94"
 };
 
 function anyAttr(a: Attrs, color: string): boolean {

package/src/tui/ui/atomic-draft.ts

@@ -0,0 +1,121 @@
+import { TextareaRenderable, type OptimizedBuffer, type KeyEvent } from "@opentui/core";
+
+/** D20: the native editor owns text and undo; this adapter only protects registered ASCII tokens.
+ * Offsets in OpenTUI are terminal cells, while app projections use UTF-16. Resolve token starts
+ * through the native buffer, so wide glyphs, combining marks, tabs and newlines stay its concern.
+ * Native virtual extmarks in 0.5.14 subtract one on left navigation and do not expand word or
+ * selection deletion; use one range policy for every edit rather than patching their internals.
+ */
+export interface DraftAtom { readonly start: number; readonly end: number }
+
+export class AtomicDraftArea extends TextareaRenderable {
+  atoms: ((text: string) => readonly DraftAtom[]) | undefined;
+  onRendered: (() => void) | undefined;
+  private killed = "";
+
+  get textCursor(): number { return this.editBuffer.getTextRange(0, this.cursorOffset).length; }
+
+  private ranges(): DraftAtom[] {
+    const text = this.plainText;
+    return (this.atoms?.(text) ?? []).map(atom => {
+      // Every token starts with one ASCII character. The first native prefix containing it
+      // ends exactly one cell after its start, irrespective of the preceding Unicode text.
+      let low = 0, high = text.length * Math.max(2, this.editBuffer.getTabWidth()) + 1;
+      while (low < high) {
+        const middle = Math.floor((low + high) / 2);
+        if (this.editBuffer.getTextRange(0, middle).length > atom.start) high = middle;
+        else low = middle + 1;
+      }
+      const start = Math.max(0, low - 1);
+      return { start, end: start + atom.end - atom.start };
+    });
+  }
+
+  private snap(direction = 0): void {
+    if (this.hasSelection()) return;
+    const cursor = this.cursorOffset;
+    const atom = this.ranges().find(range => cursor > range.start && cursor < range.end);
+    if (!atom) return;
+    this.editorView.setCursorByOffset(direction < 0 ? atom.start : direction > 0 ? atom.end :
+      cursor - atom.start < atom.end - cursor ? atom.start : atom.end);
+    this.requestRender();
+  }
+
+  private move(action: () => boolean, direction: number): boolean {
+    const result = action(); this.snap(direction); return result;
+  }
+  override moveCursorLeft(options?: { select?: boolean }): boolean { return this.move(() => super.moveCursorLeft(options), -1); }
+  override moveCursorRight(options?: { select?: boolean }): boolean { return this.move(() => super.moveCursorRight(options), 1); }
+  override moveCursorUp(options?: { select?: boolean }): boolean { return this.move(() => super.moveCursorUp(options), 0); }
+  override moveCursorDown(options?: { select?: boolean }): boolean { return this.move(() => super.moveCursorDown(options), 0); }
+  override moveWordBackward(options?: { select?: boolean }): boolean { return this.move(() => super.moveWordBackward(options), -1); }
+  override moveWordForward(options?: { select?: boolean }): boolean { return this.move(() => super.moveWordForward(options), 1); }
+  override gotoVisualLineHome(options?: { select?: boolean }): boolean { return this.move(() => super.gotoVisualLineHome(options), -1); }
+  override gotoVisualLineEnd(options?: { select?: boolean }): boolean { return this.move(() => super.gotoVisualLineEnd(options), 1); }
+  override setCursor(row: number, col: number): void { super.setCursor(row, col); this.snap(); }
+
+  private erase(start: number, end: number, kill = false): boolean {
+    if (start > end) [start, end] = [end, start];
+    if (start === end) return true;
+    for (const atom of this.ranges()) {
+      if (atom.start < end && atom.end > start) { start = Math.min(start, atom.start); end = Math.max(end, atom.end); }
+    }
+    if (kill) this.killed = this.editBuffer.getTextRange(start, end);
+    const a = this.editBuffer.offsetToPosition(start), b = this.editBuffer.offsetToPosition(end);
+    if (!a || !b) return false;
+    this.clearSelection();
+    this.editBuffer.deleteRange(a.row, a.col, b.row, b.col);
+    this.requestRender();
+    return true;
+  }
+  override deleteSelection(): boolean {
+    const selection = this.getSelection();
+    return selection ? this.erase(selection.start, selection.end) : false;
+  }
+  override deleteCharBackward(): boolean {
+    if (this.hasSelection()) return this.deleteSelection();
+    const atom = this.ranges().find(range => this.cursorOffset > range.start && this.cursorOffset <= range.end);
+    return atom ? this.erase(atom.start, atom.end) : super.deleteCharBackward();
+  }
+  override deleteChar(): boolean {
+    if (this.hasSelection()) return this.deleteSelection();
+    const atom = this.ranges().find(range => this.cursorOffset >= range.start && this.cursorOffset < range.end);
+    return atom ? this.erase(atom.start, atom.end) : super.deleteChar();
+  }
+  override deleteWordBackward(): boolean {
+    if (this.hasSelection()) return this.deleteSelection();
+    return this.erase(this.editBuffer.getPrevWordBoundary().offset, this.cursorOffset, true);
+  }
+  override deleteWordForward(): boolean {
+    if (this.hasSelection()) return this.deleteSelection();
+    return this.erase(this.cursorOffset, this.editBuffer.getNextWordBoundary().offset, true);
+  }
+  override deleteToLineStart(): boolean {
+    const cursor = this.editBuffer.getCursorPosition();
+    return cursor.col ? this.erase(this.editBuffer.getLineStartOffset(cursor.row), cursor.offset, true) : super.deleteToLineStart();
+  }
+  override deleteToLineEnd(): boolean {
+    const end = this.editBuffer.getEOL().offset;
+    return end > this.cursorOffset ? this.erase(this.cursorOffset, end, true) : super.deleteToLineEnd();
+  }
+  override insertText(text: string): void {
+    if (this.hasSelection()) this.deleteSelection();
+    this.snap(); super.insertText(text);
+  }
+  override insertChar(char: string): void {
+    if (this.hasSelection()) this.deleteSelection();
+    this.snap(); super.insertChar(char);
+  }
+  override newLine(): boolean {
+    if (this.hasSelection()) this.deleteSelection();
+    this.snap(); return super.newLine();
+  }
+  override handleKeyPress(event: KeyEvent): boolean {
+    if (event.ctrl && event.name === "y" && this.killed) { this.insertText(this.killed); return true; }
+    return super.handleKeyPress(event);
+  }
+  clearKilledText(): void { this.killed = ""; }
+  override render(buffer: OptimizedBuffer, deltaTime: number): void {
+    this.snap(); super.render(buffer, deltaTime); this.onRendered?.();
+  }
+}

package/src/tui/ui/canvas.ts

@@ -0,0 +1,96 @@
+/**
+ * Rows of styled segments drawn straight into the frame buffer.
+ *
+ * Chrome (input box edges, top bar, sidebar, greeting, completion list)
+ * changes often and never needs wrapping or selection, so it skips the text
+ * layout machinery: setting a TextRenderable's content re-measures the node
+ * and dirties Yoga, even for an identical string (OpenTUI 0.5.14,
+ * TextBufferRenderable). A Canvas only stores rows and requests a frame;
+ * the activity glyph is read at paint time, so a spinner tick touches no
+ * node at all (docs/tasks/refactor-tui-dock-layout.md DoD 9).
+ */
+import { Renderable, TextAttributes, type OptimizedBuffer, type RenderContext, type RenderableOptions, type RGBA } from "@opentui/core";
+import type { UiColors } from "./colors.ts";
+import type { Role } from "./edge.ts";
+import type { Line } from "./status.ts";
+import { displayWidth } from "../width.ts";
+
+export interface CanvasOptions extends RenderableOptions<Canvas> {
+  readonly colors: UiColors;
+  /** The current activity glyph for `spin` segments. */
+  readonly glyph?: () => string;
+}
+
+export function roleColor(colors: UiColors, role: Role): RGBA {
+  switch (role) {
+    case "text": return colors.text;
+    case "muted": return colors.muted;
+    case "edge": return colors.edge;
+    case "line": return colors.line;
+    case "accent": return colors.accent;
+    case "success": return colors.success;
+    case "error": return colors.error;
+    case "warning": return colors.warning;
+    case "reasoning": return colors.reasoning;
+    case "code": return colors.code;
+  }
+}
+
+export class Canvas extends Renderable {
+  private rows: readonly Line[] = [];
+  private colors: UiColors;
+  private readonly glyph: () => string;
+
+  constructor(ctx: RenderContext, options: CanvasOptions) {
+    super(ctx, options);
+    this.colors = options.colors;
+    this.glyph = options.glyph ?? (() => "●");
+  }
+
+  get lines(): readonly Line[] { return this.rows; }
+  /** Plain text of what is drawn (tests, /debug). */
+  get text(): string { return this.rows.map(row => row.map(seg => seg.spin ? this.glyph() : seg.text).join("")).join("\n"); }
+
+  /** Store new rows; an identical set requests nothing. */
+  setRows(rows: readonly Line[]): void {
+    if (sameRows(rows, this.rows)) return;
+    this.rows = rows;
+    this.requestRender();
+  }
+
+  setColors(colors: UiColors): void { this.colors = colors; this.requestRender(); }
+
+  protected override renderSelf(buffer: OptimizedBuffer): void {
+    const x0 = this.screenX, y0 = this.screenY, width = this.width, height = this.height;
+    for (let row = 0; row < Math.min(height, this.rows.length); row++) {
+      // Rows scrolled above the buffer must be skipped here: the native drawText
+      // clamps a negative row to 0, where the scissor (the scroll viewport) lets it through.
+      const y = y0 + row;
+      if (y < 0 || y >= buffer.height) continue;
+      let x = x0;
+      for (const seg of this.rows[row]!) {
+        const text = seg.spin ? this.glyph() : seg.text;
+        if (!text) continue;
+        const w = seg.spin ? 1 : displayWidth(text);
+        if (x - x0 + w > width) break;
+        const attributes = (seg.bold ? TextAttributes.BOLD : 0) | (seg.italic ? TextAttributes.ITALIC : 0);
+        buffer.drawText(text, x, y, roleColor(this.colors, seg.role), undefined, attributes);
+        x += w;
+      }
+    }
+  }
+}
+
+function sameRows(a: readonly Line[], b: readonly Line[]): boolean {
+  if (a === b) return true;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i]!, y = b[i]!;
+    if (x.length !== y.length) return false;
+    for (let j = 0; j < x.length; j++) {
+      const p = x[j]!, q = y[j]!;
+      if (p.text !== q.text || p.role !== q.role || p.bold !== q.bold || p.italic !== q.italic || p.spin !== q.spin) return false;
+    }
+  }
+  return true;
+}

package/src/tui/ui/colors.ts

@@ -0,0 +1,70 @@
+/**
+ * The view's colour vocabulary, as OpenTUI colours ready to draw with.
+ *
+ * Built-in appearances come from the terminal's own palette (ink.ts): the
+ * background is never painted and body text is the terminal's foreground.
+ * A custom theme file supplies explicit colours instead. `src/tui` may not
+ * import core, so the app maps its Theme into this record (apps/ui/theme.ts).
+ *
+ * Colour carries a stable role: one accent for navigation, success/error
+ * only for logged outcomes (D11), warning for things waiting on the user.
+ */
+import { RGBA } from "@opentui/core";
+import { terminalInks, type InkSet, type InkSpec } from "./ink.ts";
+
+export interface UiColors {
+  /** The terminal default unless a custom theme sets one explicitly. */
+  readonly background: RGBA;
+  readonly text: RGBA;
+  readonly muted: RGBA;
+  /** The input box border. */
+  readonly edge: RGBA;
+  /** Rules, separators and scrollbar tracks. */
+  readonly line: RGBA;
+  readonly accent: RGBA;
+  readonly success: RGBA;
+  readonly error: RGBA;
+  readonly warning: RGBA;
+  readonly reasoning: RGBA;
+  readonly code: RGBA;
+  /** Mouse-selected text (feat-tui-copy-selection). */
+  readonly selectionBg: RGBA;
+  readonly selectionFg: RGBA;
+}
+
+const cache = new Map<string, RGBA>();
+function cached(key: string, make: () => RGBA): RGBA {
+  let value = cache.get(key);
+  if (!value) { value = make(); cache.set(key, value); }
+  return value;
+}
+
+export function inkColor(spec: InkSpec): RGBA {
+  switch (spec.kind) {
+    case "default": return cached("default:fg", () => RGBA.defaultForeground());
+    case "index": return cached(`index:${spec.index}`, () => RGBA.fromIndex(spec.index));
+    case "rgb": return rgba(spec.hex);
+  }
+}
+
+/** The terminal's own background: SGR 49, so transparency and blur survive. */
+export const TERMINAL_BACKGROUND: RGBA = RGBA.defaultBackground();
+/** Nothing at all (OpenTUI skips the cell's background). */
+export const CLEAR: RGBA = RGBA.fromValues(0, 0, 0, 0);
+
+export function colorsFromInks(inks: InkSet): UiColors {
+  return {
+    background: inks.background.kind === "default" ? TERMINAL_BACKGROUND : inkColor(inks.background),
+    text: inkColor(inks.text), muted: inkColor(inks.muted), edge: inkColor(inks.edge), line: inkColor(inks.line),
+    accent: inkColor(inks.accent), success: inkColor(inks.success), error: inkColor(inks.error),
+    warning: inkColor(inks.warning), reasoning: inkColor(inks.reasoning), code: inkColor(inks.code),
+    selectionBg: inkColor(inks.selectionBg), selectionFg: inkColor(inks.selectionFg),
+  };
+}
+
+/** Before the terminal answers (or when it never does). */
+export const FALLBACK_COLORS: UiColors = colorsFromInks(terminalInks(null, "dark"));
+
+export function rgba(hex: string): RGBA {
+  return cached(`hex:${hex}`, () => RGBA.fromHex(hex));
+}