jeo-code 0.1.0

package/src/tui/components/ascii-art.ts

@@ -0,0 +1,340 @@
+import chalk from "chalk";
+import { stageIndexForStep, clampStageIndex, type StageGradient } from "./evolution";
+import { applyGradient, hexToRgb, ColorLevel } from "./color";
+
+export interface AsciiStage {
+  name: string;
+  art: string[];
+  color: (s: string) => string;
+  lineColors?: ((s: string) => string)[];
+  /**
+   * Optional animation frames (each a full art block). When present the live TUI
+   * cycles them by tick for a "breathing"/rotating effect; `art` is frame 0 and
+   * the fallback when `frames` is absent. Frames should match `art`'s line count.
+   */
+  frames?: string[][];
+}
+
+export const EVOLUTION_STAGES: AsciiStage[] = [
+  {
+    name: "Primordial Cell",
+    color: s => chalk.cyan(s),
+    art: [
+      "      .---.      ",
+      "     / o o \\     ",
+      "     \\  -  /     ",
+      "      '---'      ",
+      " [Primordial Cell]"
+    ],
+    lineColors: [
+      chalk.cyan,
+      chalk.cyan,
+      chalk.cyan,
+      chalk.cyan,
+      s => chalk.bold.cyan(s)
+    ],
+    // Pulsing membrane + nucleus (a primordial cell "breathing").
+    frames: [
+      [
+        "      .---.      ",
+        "     / o o \\     ",
+        "     \\  -  /     ",
+        "      '---'      ",
+        " [Primordial Cell]"
+      ],
+      [
+        "      .===.      ",
+        "     / O O \\     ",
+        "     \\  ~  /     ",
+        "      '==='      ",
+        " [Primordial Cell]"
+      ]
+    ]
+  },
+  {
+    name: "Double Helix (DNA)",
+    color: s => chalk.green(s),
+    art: [
+      "      \\  /      ",
+      "       \\/       ",
+      "       /\\       ",
+      "      /  \\      ",
+      "      \\  /      ",
+      "       \\/       ",
+      "       /\\       ",
+      " [Double Helix] "
+    ],
+    lineColors: [
+      chalk.green,
+      chalk.cyan,
+      chalk.green,
+      chalk.cyan,
+      chalk.green,
+      chalk.cyan,
+      chalk.green,
+      s => chalk.bold.green(s)
+    ],
+    // Twisting double helix (diagonals flip to simulate rotation).
+    frames: [
+      [
+        "      \\  /      ",
+        "       \\/       ",
+        "       /\\       ",
+        "      /  \\      ",
+        "      \\  /      ",
+        "       \\/       ",
+        "       /\\       ",
+        " [Double Helix] "
+      ],
+      [
+        "       \\/       ",
+        "       /\\       ",
+        "      /  \\      ",
+        "      \\  /      ",
+        "       \\/       ",
+        "       /\\       ",
+        "      /  \\      ",
+        " [Double Helix] "
+      ],
+      [
+        "      /  \\      ",
+        "      \\  /      ",
+        "       \\/       ",
+        "       /\\       ",
+        "      /  \\      ",
+        "      \\  /      ",
+        "       \\/       ",
+        " [Double Helix] "
+      ]
+    ]
+  },
+  {
+    name: "Tool User (Homo Habilis)",
+    color: s => chalk.yellow(s),
+    art: [
+      "       .---.     ",
+      "      /| | |\\    ",
+      "     | |_|_| |   ",
+      "     |  ___  |---|",
+      "     | |   | |   |",
+      "     '-'   '-'   '-'",
+      "   [Tool User]   "
+    ],
+    lineColors: [
+      chalk.yellow,
+      chalk.yellow,
+      chalk.yellow,
+      s => s.replace("___", chalk.red("___")),
+      chalk.yellow,
+      chalk.yellow,
+      s => chalk.bold.yellow(s)
+    ]
+  },
+  {
+    name: "AI Coding Agent",
+    color: s => chalk.magenta(s),
+    art: [
+      "      .-------.  ",
+      "    _|_  o o  _|_",
+      "   |   |  ^  |   |",
+      "   |   | === |   |",
+      "   |___|_____|___|",
+      "     /         \\ ",
+      "  [AI Coding Agent]"
+    ],
+    lineColors: [
+      chalk.magenta,
+      s => s.replace("o o", chalk.green("o o")),
+      chalk.magenta,
+      s => s.replace("===", chalk.cyan("===")),
+      chalk.magenta,
+      chalk.magenta,
+      s => chalk.bold.magenta(s)
+    ]
+  },
+  {
+    name: "Super intelligence (Singularity)",
+    color: s => chalk.blue(s),
+    art: [
+      "     _  ____   ____ ",
+      "    | |/ ___| / ___|",
+      " _  | | |    | |    ",
+      "| |_| | |___ | |___ ",
+      " \\___/ \\____| \\____|",
+      "  [Singularity Era] "
+    ],
+    lineColors: [
+      chalk.red,
+      chalk.yellow,
+      chalk.green,
+      chalk.blue,
+      chalk.magenta,
+      s => chalk.bold.cyan(s)
+    ]
+  }
+];
+
+/**
+ * Returns the evolutionary ASCII-art stage for an agent step against its budget.
+ * Delegates stage selection to the canonical evolution model so the art evolves
+ * in lockstep with the spinner, meter, and footer track. Guards out-of-range
+ * step/maxSteps via the canonical index math.
+ */
+export function getEvolutionStage(step: number, maxSteps: number = 25): AsciiStage {
+  return EVOLUTION_STAGES[stageIndexForStep(step, maxSteps)]!;
+}
+
+/** Returns the ASCII-art stage for an explicit stage index (clamped). */
+export function getStageByIndex(index: number): AsciiStage {
+  return EVOLUTION_STAGES[clampStageIndex(index)]!;
+}
+
+/** All art blocks for a stage (its animation `frames`, or `[art]` as a fallback). */
+export function stageBlocks(stage: AsciiStage): string[][] {
+  return stage.frames && stage.frames.length > 0 ? stage.frames : [stage.art];
+}
+
+/** The art block for a given animation tick (wraps; falls back to `art`). */
+export function stageFrame(stage: AsciiStage, tick = 0): string[] {
+  const blocks = stageBlocks(stage);
+  const t = Number.isFinite(tick) ? Math.trunc(tick) : 0;
+  const i = ((t % blocks.length) + blocks.length) % blocks.length;
+  return blocks[i]!;
+}
+
+/** Max art line count across all stages + frames (for stable block height). */
+export function stageHeight(): number {
+  let h = 0;
+  for (const s of EVOLUTION_STAGES) for (const block of stageBlocks(s)) h = Math.max(h, block.length);
+  return h;
+}
+
+/** Max plain line width across all stages + frames (for clean right-edge alignment). */
+export function stageWidth(): number {
+  let w = 0;
+  for (const s of EVOLUTION_STAGES) for (const block of stageBlocks(s)) for (const line of block) w = Math.max(w, line.length);
+  return w;
+}
+
+/** The bracketed caption line embedded in a stage's art, e.g. "[Tool User]". */
+export function stageCaption(stage: AsciiStage): string | undefined {
+  return stage.art.find(line => /\[.+\]/.test(line))?.trim();
+}
+
+export interface RenderAsciiOptions {
+  /** Apply per-line / stage colors (default true). Pass false for NO_COLOR / plain. */
+  color?: boolean;
+  /** Right-pad every line to this plain width (default: this stage's max width). */
+  width?: number;
+  /** Bottom-pad the block to this many lines for a stable block height (default: no pad). */
+  height?: number;
+  /** Terminal width. If the terminal width is less than the art width, returns an empty block. */
+  cols?: number;
+  /** Whether to overlay synapses firing animation (random glowing dots). */
+  firing?: boolean;
+  /** Animation tick: selects a `stage.frames` block (wraps); default frame 0. */
+  frame?: number;
+  /**
+   * Paint each line with a left→right truecolor gradient (`from`→`to` hex),
+   * downgrading to 256/16/plain per `colorLevel`. Takes precedence over
+   * per-line colors; suppresses the `firing` overlay for a clean gradient.
+   */
+  gradient?: StageGradient;
+  /** Color tier for gradient rendering (default TrueColor). */
+  colorLevel?: ColorLevel;
+}
+
+/**
+ * Render a stage's ASCII art. Lines are right-padded to a uniform width (clean
+ * right edge) and the block is optionally bottom-padded to a uniform height so
+ * the live TUI never jumps as stages change. Color can be disabled for
+ * NO_COLOR / non-TTY / plain previews.
+ */
+export function renderAsciiArt(stage: AsciiStage, opts: RenderAsciiOptions = {}): string[] {
+  const useColor = opts.color !== false;
+  const source = opts.frame !== undefined ? stageFrame(stage, opts.frame) : stage.art;
+  const width = opts.width ?? Math.max(0, ...source.map(l => l.length));
+  if (opts.cols !== undefined && opts.cols < width) {
+    return [];
+  }
+  const gradient = useColor ? opts.gradient : undefined;
+  const level = opts.colorLevel ?? ColorLevel.TrueColor;
+  const lines = source.map((line, idx) => {
+    let padded = line.length < width ? line + " ".repeat(width - line.length) : line;
+    if (gradient) {
+      return applyGradient(padded, hexToRgb(gradient.from), hexToRgb(gradient.to), level);
+    }
+    if (opts.firing && useColor) {
+      const spaceIdxs: number[] = [];
+      for (let i = 0; i < padded.length; i++) {
+        if (padded[i] === " ") {
+          spaceIdxs.push(i);
+        }
+      }
+      if (spaceIdxs.length > 0) {
+        const chars = ["*", ".", "o", "+", "\u2727"];
+        const numSparks = Math.min(2, Math.floor(Math.random() * 3));
+        const arr = padded.split("");
+        for (let s = 0; s < numSparks; s++) {
+          const randSpace = spaceIdxs[Math.floor(Math.random() * spaceIdxs.length)];
+          const randChar = chars[Math.floor(Math.random() * chars.length)];
+          arr[randSpace] = chalk.yellow.bold(randChar);
+        }
+        padded = arr.join("");
+      }
+    }
+    if (!useColor) return padded;
+    if (stage.lineColors && stage.lineColors[idx]) return stage.lineColors[idx]!(padded);
+    return stage.color(padded);
+  });
+  if (opts.height && lines.length < opts.height) {
+    const blank = " ".repeat(width);
+    while (lines.length < opts.height) lines.push(blank);
+  }
+  return lines;
+}
+
+export interface AnimateAsciiOptions extends RenderAsciiOptions {
+  delayMs?: number;
+  write?: (s: string) => void;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+/** Stream a stage's art line-by-line. `write`/`sleep` are injectable for tests. */
+export async function animateAsciiArt(stage: AsciiStage, opts: AnimateAsciiOptions = {}): Promise<void> {
+  const delayMs = opts.delayMs ?? 60;
+  const write = opts.write ?? ((s: string) => process.stdout.write(s));
+  const sleep = opts.sleep ?? ((ms: number) => Bun.sleep(ms));
+  for (const line of renderAsciiArt(stage, opts)) {
+    write(line + "\n");
+    if (delayMs > 0) await sleep(delayMs);
+  }
+}
+
+export interface AnimateFramesOptions extends RenderAsciiOptions {
+  /** Frames to play across (default = the stage's frame count). */
+  frames?: number;
+  /** Delay between frames in ms (default 120). */
+  frameDelayMs?: number;
+  write?: (s: string) => void;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+/**
+ * Play a stage's animation frames in place by clearing and redrawing the block
+ * `frames` times. Returns the number of frames drawn. `write`/`sleep` are
+ * injectable so tests can run with zero delay.
+ */
+export async function animateFrames(stage: AsciiStage, opts: AnimateFramesOptions = {}): Promise<number> {
+  const write = opts.write ?? ((s: string) => process.stdout.write(s));
+  const sleep = opts.sleep ?? ((ms: number) => Bun.sleep(ms));
+  const delay = opts.frameDelayMs ?? 120;
+  const total = Math.max(1, opts.frames ?? stageBlocks(stage).length);
+  const height = opts.height ?? stageHeight();
+  for (let f = 0; f < total; f++) {
+    const block = renderAsciiArt(stage, { ...opts, frame: f, height });
+    write(block.join("\n") + "\n");
+    if (delay > 0 && f < total - 1) await sleep(delay);
+  }
+  return total;
+}

package/src/tui/components/autocomplete.ts

@@ -0,0 +1,165 @@
+/**
+ * Interactive autocomplete engine for the REPL.
+ *
+ * Completes slash-command *names* and their *arguments*:
+ *  - `/mod`            → `/model`, `/models`
+ *  - `/model gpt`      → live (logged-in) model ids + aliases + catalog ids
+ *  - `/provider an`    → provider names; second arg → that provider's live models
+ *  - `/agents exec`    → subagent role ids; second arg → live model ids
+ *  - `/thinking h`     → low/medium/high
+ *
+ * Pure + synchronous: the dynamic data (live models from the OAuth-authenticated
+ * accounts, alias snapshot) is passed in via `CompletionContext`, so the readline
+ * completer never blocks on the network. Static data (slash names, catalog ids,
+ * provider names, role ids) is filled by `staticCompletionContext()`.
+ */
+import { SLASH_COMMANDS } from "./slash";
+import { catalogIds } from "../../ai/model-catalog-compat";
+import { PROVIDER_NAMES } from "../../ai/provider-status";
+import { SUBAGENT_ROLES } from "../../agent/subagents";
+
+export interface CompletionContext {
+  slashCommands: string[];
+  /** Flattened live model ids discovered from logged-in providers (cache). */
+  liveModels: string[];
+  /** Alias names (e.g. fast/sonnet/gpt). */
+  aliases: string[];
+  /** Curated catalog model ids. */
+  catalogModels: string[];
+  providers: string[];
+  roleIds: string[];
+  thinkingLevels: string[];
+  /** Live model ids for a given provider (for `/provider <p> <model>`). */
+  modelsForProvider: (provider: string) => string[];
+}
+
+export interface CompletionResult {
+  /** Candidate completions for `token`, ranked, de-duplicated, capped. */
+  completions: string[];
+  /** The substring being completed (what readline should replace). */
+  token: string;
+  /** What was completed: command | model | provider | role | thinking | subcommand | none. */
+  kind: string;
+}
+
+const MAX_COMPLETIONS = 50;
+const THINKING_LEVELS = ["low", "medium", "high"];
+
+/** Static half of a completion context (no network/config needed). */
+export function staticCompletionContext(): Omit<CompletionContext, "liveModels" | "aliases" | "modelsForProvider"> {
+  return {
+    slashCommands: [...SLASH_COMMANDS],
+    catalogModels: catalogIds(),
+    providers: [...PROVIDER_NAMES],
+    roleIds: SUBAGENT_ROLES.map(r => r.id),
+    thinkingLevels: [...THINKING_LEVELS],
+  };
+}
+
+/** Tokenize a line into words + whether it ends with whitespace (→ completing a new token). */
+export function tokenize(line: string): { tokens: string[]; trailingSpace: boolean } {
+  const trailingSpace = /\s$/.test(line);
+  const tokens = line.split(/\s+/).filter(t => t.length > 0);
+  return { tokens, trailingSpace };
+}
+
+function prefixHits(pool: string[], token: string): string[] {
+  const q = token.toLowerCase();
+  return pool.filter(c => c.toLowerCase().startsWith(q));
+}
+
+/** De-duplicate (case-insensitive, first wins), preserving order, capped. */
+function dedupeCap(items: string[], cap = MAX_COMPLETIONS): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const it of items) {
+    const k = it.toLowerCase();
+    if (seen.has(k)) continue;
+    seen.add(k);
+    out.push(it);
+    if (out.length >= cap) break;
+  }
+  return out;
+}
+
+/** Rank model candidates: live (logged-in) first, then aliases, then catalog. */
+function rankedModelPool(ctx: CompletionContext): string[] {
+  return dedupeCap([...ctx.liveModels, ...ctx.aliases, ...ctx.catalogModels], Number.MAX_SAFE_INTEGER);
+}
+
+/**
+ * Compute completions for the current input line. Returns an empty list for
+ * non-slash input (free-text prompts are not completed).
+ */
+export function complete(line: string, ctx: CompletionContext): CompletionResult {
+  if (!line.startsWith("/")) return { completions: [], token: line, kind: "none" };
+
+  const { tokens, trailingSpace } = tokenize(line);
+  // Completing the command name itself (single token, still typing it).
+  if (tokens.length <= 1 && !trailingSpace) {
+    const token = tokens[0] ?? "/";
+    return { completions: dedupeCap(prefixHits(ctx.slashCommands, token)), token, kind: "command" };
+  }
+
+  const cmd = tokens[0]!.toLowerCase();
+  // Token currently being completed (empty when the line ends with a space).
+  const token = trailingSpace ? "" : tokens[tokens.length - 1]!;
+  // 0-based index of the argument being completed.
+  const argIndex = (trailingSpace ? tokens.length : tokens.length - 1) - 1;
+
+  const finish = (pool: string[], kind: string): CompletionResult => ({
+    completions: dedupeCap(prefixHits(pool, token)),
+    token,
+    kind,
+  });
+
+  switch (cmd) {
+    case "/model": {
+      if (token.startsWith("#")) return { completions: [], token, kind: "none" }; // numbered pick
+      if (argIndex === 0) return finish(["save", ...rankedModelPool(ctx)], "model");
+      // `/model save <id>` second arg → models
+      if (argIndex === 1 && tokens[1]?.toLowerCase() === "save") return finish(rankedModelPool(ctx), "model");
+      return { completions: [], token, kind: "none" };
+    }
+    case "/models":
+      return argIndex === 0 ? finish(["refresh"], "subcommand") : { completions: [], token, kind: "none" };
+    case "/provider": {
+      if (argIndex === 0) return finish(ctx.providers, "provider");
+      if (argIndex === 1) return finish(ctx.modelsForProvider(tokens[1] ?? ""), "model");
+      return { completions: [], token, kind: "none" };
+    }
+    case "/agents": {
+      if (argIndex === 0) return finish(ctx.roleIds, "role");
+      if (argIndex === 1) return finish(["maxSteps", ...rankedModelPool(ctx)], "model");
+      if (argIndex === 2 && tokens[2]?.toLowerCase() === "maxsteps") return { completions: [], token, kind: "none" };
+      return { completions: [], token, kind: "none" };
+    }
+    case "/thinking":
+      return argIndex === 0 ? finish(ctx.thinkingLevels, "thinking") : { completions: [], token, kind: "none" };
+    default:
+      return { completions: [], token, kind: "none" };
+  }
+}
+
+/** Longest common prefix of a list (for tab "fill to ambiguity"). */
+export function commonPrefix(items: string[]): string {
+  if (items.length === 0) return "";
+  let prefix = items[0]!;
+  for (const s of items.slice(1)) {
+    let i = 0;
+    while (i < prefix.length && i < s.length && prefix[i]!.toLowerCase() === s[i]!.toLowerCase()) i++;
+    prefix = prefix.slice(0, i);
+    if (!prefix) break;
+  }
+  return prefix;
+}
+
+/**
+ * Adapter for Node/Bun `readline` completer contract: returns
+ * `[completions, tokenBeingReplaced]`. When nothing matches, returns the empty
+ * hit list with the whole line so readline leaves the input untouched.
+ */
+export function readlineCompleter(line: string, ctx: CompletionContext): [string[], string] {
+  const r = complete(line, ctx);
+  return [r.completions, r.completions.length ? r.token : line];
+}

package/src/tui/components/capability.ts

@@ -0,0 +1,29 @@
+/**
+ * Terminal unicode capability detection for the evolution TUI.
+ *
+ * The art is ASCII, but the spinner (braille), meter (block glyphs), and track
+ * (●/○) use unicode. On a terminal that cannot render them (legacy `linux`
+ * console, `dumb`, or a non-UTF locale) we fall back to ASCII-only glyph sets.
+ * Pure + injectable so tests can pin the decision.
+ */
+import type { EnvLike } from "./color";
+
+/**
+ * Whether the terminal can render the unicode glyphs the TUI uses. Heuristics:
+ *  - `TERM=dumb`/`linux` → no (legacy console fonts lack braille).
+ *  - any locale var (`LC_ALL`/`LC_CTYPE`/`LANG`) mentioning UTF → yes.
+ *  - a locale var set but NOT mentioning UTF → no.
+ *  - nothing set → default yes (modern emulators are UTF-8).
+ */
+export function supportsUnicode(env: EnvLike = process.env): boolean {
+  const term = (env.TERM ?? "").toLowerCase();
+  if (term === "dumb" || term === "linux") return false;
+
+  const locale = env.LC_ALL ?? env.LC_CTYPE ?? env.LANG;
+  if (locale !== undefined && locale !== "") {
+    return /utf-?8/i.test(locale);
+  }
+
+  // No locale signal — assume a modern UTF-8 terminal.
+  return true;
+}

package/src/tui/components/code-view.ts

@@ -0,0 +1,146 @@
+/**
+ * Code view (코드뷰) — pure formatters that render file content and diffs inside
+ * the TUI with a line-number gutter, ANSI-aware width clamping, light
+ * language-aware coloring, and a bounded line budget. Used by the `/view` and
+ * `/diff` slash commands. Everything is a pure function over strings so it can be
+ * unit-tested with an ANSI-stripping helper.
+ */
+import chalk from "chalk";
+import { truncate } from "../terminal";
+
+const LANG_BY_EXT: Record<string, string> = {
+  ts: "ts", tsx: "ts", mts: "ts", cts: "ts",
+  js: "js", jsx: "js", mjs: "js", cjs: "js",
+  json: "json", jsonc: "json",
+  md: "md", markdown: "md",
+  py: "py", sh: "sh", bash: "sh", zsh: "sh",
+  yml: "yaml", yaml: "yaml", toml: "toml",
+  css: "css", html: "html", rs: "rust", go: "go",
+};
+
+/** Line-comment token per language (used for whole-line comment dimming). */
+const COMMENT_TOKEN: Record<string, string> = {
+  ts: "//", js: "//", rust: "//", go: "//", css: "/*",
+  py: "#", sh: "#", yaml: "#", toml: "#",
+};
+
+const KEYWORDS = new Set([
+  "import", "export", "from", "const", "let", "var", "function", "return", "class",
+  "interface", "type", "if", "else", "for", "while", "await", "async", "new",
+  "try", "catch", "finally", "throw", "def", "fn", "pub", "struct", "enum", "impl",
+]);
+
+/** Map a file path to a language id for highlighting. Unknown → "". */
+export function detectLanguage(filePath: string): string {
+  const ext = filePath.split(".").pop()?.toLowerCase() ?? "";
+  return LANG_BY_EXT[ext] ?? "";
+}
+
+export function languageLabel(lang: string): string {
+  return lang || "text";
+}
+
+export interface ParsedRange {
+  start: number;
+  end?: number;
+}
+
+/** Parse "start-end" / "start-" / "start" into 1-based bounds. null when invalid. */
+export function parseLineRange(spec: string): ParsedRange | null {
+  const m = spec.trim().match(/^(\d+)(?:-(\d+)?)?$/);
+  if (!m) return null;
+  const start = Math.max(1, parseInt(m[1], 10));
+  if (m[2]) {
+    const end = parseInt(m[2], 10);
+    if (end < start) return null;
+    return { start, end };
+  }
+  // "start-" → open-ended; "start" → single line.
+  return spec.includes("-") ? { start } : { start, end: start };
+}
+
+/** Slice content by 1-based [start,end]; returns { lines, startLine }. */
+export function sliceLines(content: string, range?: ParsedRange): { lines: string[]; startLine: number } {
+  const all = content.split("\n");
+  if (!range) return { lines: all, startLine: 1 };
+  const start = Math.min(Math.max(1, range.start), all.length || 1);
+  const end = range.end ? Math.min(range.end, all.length) : all.length;
+  return { lines: all.slice(start - 1, end), startLine: start };
+}
+
+/** Conservative, single-pass light highlight: whole-line comments, then string literals. */
+export function lightHighlightLine(line: string, lang: string): string {
+  const token = COMMENT_TOKEN[lang];
+  if (token && line.trimStart().startsWith(token)) return chalk.gray(line);
+  // String literals (double / single / backtick), non-greedy, no escapes handling.
+  let out = line.replace(/(["'`])(?:\\.|(?!\1).)*\1/g, m => chalk.green(m));
+  if (out !== line) return out;
+  // No strings → keyword pass on word boundaries.
+  out = line.replace(/\b[A-Za-z_]+\b/g, w => (KEYWORDS.has(w) ? chalk.cyan(w) : w));
+  return out;
+}
+
+export interface CodeViewOptions {
+  startLine?: number;
+  lang?: string;
+  cols?: number;
+  maxLines?: number;
+  /** 1-based absolute line numbers to mark in the gutter. */
+  highlight?: number[];
+  /** Enable light coloring (default true). */
+  color?: boolean;
+  /** Gutter separator glyph (default "│"). */
+  sep?: string;
+}
+
+/** Render code with a right-aligned line-number gutter, clamped to `cols`. */
+export function formatCodeBlock(content: string, opts: CodeViewOptions = {}): string[] {
+  const startLine = opts.startLine ?? 1;
+  const cols = opts.cols ?? 100;
+  const maxLines = opts.maxLines ?? 200;
+  const sep = opts.sep ?? "│";
+  const color = opts.color !== false;
+  const lang = opts.lang ?? "";
+  const highlight = new Set(opts.highlight ?? []);
+
+  const allLines = content.split("\n");
+  const shown = allLines.slice(0, maxLines);
+  const lastNo = startLine + shown.length - 1;
+  const gutterW = Math.max(String(lastNo).length, 2);
+
+  const out: string[] = [];
+  for (let i = 0; i < shown.length; i++) {
+    const no = startLine + i;
+    const marked = highlight.has(no);
+    const numText = String(no).padStart(gutterW);
+    const num = color ? (marked ? chalk.yellow.bold(numText) : chalk.gray(numText)) : numText;
+    const body = color ? lightHighlightLine(shown[i], lang) : shown[i];
+    const marker = marked ? (color ? chalk.yellow("▶") : ">") : " ";
+    const line = `${marker}${num} ${sep} ${body}`;
+    out.push(truncate(line, cols));
+  }
+  if (allLines.length > maxLines) {
+    const more = allLines.length - maxLines;
+    out.push(color ? chalk.gray(`  …(+${more} more line${more === 1 ? "" : "s"})`) : `  …(+${more} more lines)`);
+  }
+  return out;
+}
+
+/** Render a unified diff with +/-/@@ coloring, clamped to `cols`. */
+export function formatDiff(diffText: string, opts: { cols?: number; maxLines?: number; color?: boolean } = {}): string[] {
+  const cols = opts.cols ?? 100;
+  const maxLines = opts.maxLines ?? 400;
+  const color = opts.color !== false;
+  const lines = diffText.split("\n");
+  const shown = lines.slice(0, maxLines);
+  const out = shown.map(l => {
+    if (!color) return truncate(l, cols);
+    if (l.startsWith("+++") || l.startsWith("---")) return truncate(chalk.bold(l), cols);
+    if (l.startsWith("@@")) return truncate(chalk.cyan(l), cols);
+    if (l.startsWith("+")) return truncate(chalk.green(l), cols);
+    if (l.startsWith("-")) return truncate(chalk.red(l), cols);
+    return truncate(l, cols);
+  });
+  if (lines.length > maxLines) out.push(color ? chalk.gray(`  …(+${lines.length - maxLines} more)`) : `  …(+${lines.length - maxLines} more)`);
+  return out;
+}