@pify/pretty 0.5.0 → 0.6.0

package/README.md

@@ -16,7 +16,7 @@ Nothing here changes what a tool does. If this extension is removed, every comma
 |---|---|---|
 | `read` | `Read src/app.ts · lines 1–50` → `50 lines` | Syntax-highlighted content, theme-matched |
 | `bash` | `Bash npm test` → `✓ 12 output lines` / `✗ first error line` | Output, with a 12-line preview while it runs |
-| `edit` | `Edit src/app.ts` → `+12 -3` | Colourised diff with word-level emphasis |
+| `edit` | `Edit src/app.ts` → `+12 -3` | Syntax-highlighted diff with line numbers and word-level emphasis |
 | `write` | `Write y.md · 34 lines` → `✓ written` | — |
 | `grep` / `find` | `Grep TODO in src` → `7 matches` | The match list |
 | `ls` | `List packages` → `23 entries` | The listing |
@@ -40,6 +40,19 @@ Colours come from the theme's own `toolDiffAdded` / `toolDiffRemoved` / `toolDif
 
 Very long lines are not word-diffed at all: the comparison is quadratic, and a minified bundle on one line is not something anyone reads a word diff of.
 
+### Syntax, line numbers, and split
+
+The diff body is syntax-highlighted with pi's own highlighter — the same one the `read` renderer uses, so no extra dependency and the colours match your theme. Foreground is spent on the syntax, so the `+`/`−` signal moves to a subtle line background (the theme's `toolSuccessBg` / `toolErrorBg`; this package's themes map those to real diff tints), and the changed words are marked with reverse video *on top* of the syntax colour — the one combination where syntax, the add/remove signal, and word emphasis are all visible at once. A theme with no background support keeps the coloured `+`/`−` marker instead, so nothing is lost.
+
+Old/new line numbers run down the left. And with `diffSplit` on, a wide enough terminal shows the change side-by-side — old on the left, new on the right — falling back to the unified view below 100 columns. Turn either off in settings.
+
+```
+1 1   export function total(items) {
+2     - const sum = items.reduce((a, b) => a + b, 0);   ← "0" reversed on a faint red line
+  2   + const sum = items.reduce((a, b) => a + b, 1);   ← "1" reversed on a faint green line
+3 3     return sum;
+```
+
 ## Per-tool opt-out
 
 Each renderer toggles independently, and the choice is persisted per session:
@@ -65,10 +78,15 @@ Every cap in a renderer is somebody's taste, and the right number depends on you
   "expandedLines": 200,
   "diffLines": 200,
   "syntaxHighlight": true,
+  "diffSyntax": true,
+  "diffLineNumbers": true,
+  "diffSplit": false,
   "summaryClip": 100
 }
 ```
 
+`syntaxHighlight` highlights expanded `read` results; `diffSyntax` does the same for the body of an edit diff (turn it off to get the older foreground-only diff); `diffLineNumbers` toggles the old/new gutter; `diffSplit` renders the diff side-by-side when the terminal is at least 100 columns wide, unified otherwise.
+
 Unknown keys, wrong types and absurd numbers are reported at session start and fall back to the shipped defaults rather than taking the renderers down — a typo should tell you it was a typo instead of quietly doing nothing. `/pretty` shows the settings in force and where they came from.
 
 Expanded bodies are capped by `expandedLines`, because a 5,000-line diff or grep result rendered in full scrolls the conversation away — which is the problem this extension exists to solve.

package/extensions/pretty.ts

@@ -14,13 +14,13 @@
  * (giladbarnea/pi-pretty-bash), per-surface opt-in (pi-zentui).
  */
 import {
-  createBashTool,
-  createEditTool,
-  createFindTool,
-  createGrepTool,
-  createLsTool,
-  createReadTool,
-  createWriteTool,
+  createBashToolDefinition,
+  createEditToolDefinition,
+  createFindToolDefinition,
+  createGrepToolDefinition,
+  createLsToolDefinition,
+  createReadToolDefinition,
+  createWriteToolDefinition,
   getAgentDir,
   getLanguageFromPath,
   highlightCode,
@@ -39,7 +39,8 @@ import {
   replayBranch,
   statusLines,
 } from "../src/config.ts";
-import { colorizeDiff, diffStats, statsLabel } from "../src/diff.ts";
+import { colorizeDiff, diffStats, statsLabel, type DiffRenderOptions } from "../src/diff.ts";
+import { buildSplit, splitFits } from "../src/split.ts";
 import { limitsFrom, preview } from "../src/preview.ts";
 import { DEFAULT_SETTINGS, formatSettings, resolveSettings, type PrettySettings } from "../src/settings.ts";
 import {
@@ -59,6 +60,7 @@ import {
   DEFAULT_CONFIG,
   isRecord,
   textContent,
+  type HighlightLine,
   type PrettyConfig,
   type PrettyTool,
   type ThemeLike,
@@ -120,14 +122,42 @@ export default function pretty(pi: ExtensionAPI) {
   }
 
   function buildOriginals(cwd: string): Record<PrettyTool, AnyTool> {
+    // The *ToolDefinition* factories, not the createReadTool wrappers: the
+    // wrapper (wrapToolDefinition) copies only name/label/description/
+    // parameters/execute and DROPS promptSnippet, promptGuidelines and the
+    // built-in renderers. Re-registering the wrapped form removed six of the
+    // seven builtins from the system prompt's "Available tools" list —
+    // measured: with pretty loaded the list shrank to bash alone, and the
+    // Guidelines steered the model to bash for file operations because read,
+    // edit and write were no longer named. A renderer package must never
+    // change what the model is told it can do.
     return {
-      read: createReadTool(cwd) as unknown as AnyTool,
-      bash: createBashTool(cwd) as unknown as AnyTool,
-      edit: createEditTool(cwd) as unknown as AnyTool,
-      write: createWriteTool(cwd) as unknown as AnyTool,
-      grep: createGrepTool(cwd) as unknown as AnyTool,
-      find: createFindTool(cwd) as unknown as AnyTool,
-      ls: createLsTool(cwd) as unknown as AnyTool,
+      read: createReadToolDefinition(cwd) as unknown as AnyTool,
+      bash: createBashToolDefinition(cwd) as unknown as AnyTool,
+      edit: createEditToolDefinition(cwd) as unknown as AnyTool,
+      write: createWriteToolDefinition(cwd) as unknown as AnyTool,
+      grep: createGrepToolDefinition(cwd) as unknown as AnyTool,
+      find: createFindToolDefinition(cwd) as unknown as AnyTool,
+      ls: createLsToolDefinition(cwd) as unknown as AnyTool,
+    };
+  }
+
+  /**
+   * pi's own highlighter, one line at a time. `highlightCode` returns an array
+   * of ANSI lines; a diff feeds it one content line at a time, so join back to
+   * a single string. Best-effort — the diff renderer falls back to raw text if
+   * this throws on a grammar it cannot parse.
+   */
+  const highlightLine: HighlightLine = (code, language) => highlightCode(code, language).join("");
+
+  /** The diff-rendering options in force, given the current settings and file. */
+  function diffOptions(path: string | undefined): DiffRenderOptions {
+    const language = path ? getLanguageFromPath(path) : undefined;
+    return {
+      emphasis: true,
+      lineNumbers: settings.diffLineNumbers,
+      language: settings.diffSyntax ? language ?? undefined : undefined,
+      highlight: settings.diffSyntax ? highlightLine : undefined,
     };
   }
 
@@ -192,6 +222,7 @@ export default function pretty(pi: ExtensionAPI) {
             result: unknown,
             options: { expanded?: boolean; isPartial?: boolean },
             theme: ThemeLike,
+            context?: { args?: { path?: string } },
           ) => {
             if (options.isPartial) return new Text(theme.fg("warning", "Editing…"), 0, 0);
             if (isFailed(result)) {
@@ -203,7 +234,13 @@ export default function pretty(pi: ExtensionAPI) {
                 : "";
             const stats = statsLabel(theme, diffStats(diff));
             if (!options.expanded) return new Text(stats, 0, 0);
-            return new Text(`${stats}\n${colorizeDiff(theme, preview(diff, true, { collapsed: settings.collapsedLines, expanded: settings.diffLines }))}`, 0, 0);
+            const body = preview(diff, true, { collapsed: settings.collapsedLines, expanded: settings.diffLines });
+            const opts = diffOptions(context?.args?.path);
+            const columns = terminalColumns();
+            if (settings.diffSplit && splitFits(columns)) {
+              return new Text(`${stats}\n${buildSplit(theme, body, opts, columns!)}`, 0, 0);
+            }
+            return new Text(`${stats}\n${colorizeDiff(theme, body, opts)}`, 0, 0);
           },
         };
       case "write":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/pretty",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Compact, theme-aware rendering for pi's built-in tools: one-line summaries, syntax-highlighted reads, colorized diffs — behavior untouched",
   "keywords": [
     "pi-package",

package/src/ansi.ts

@@ -0,0 +1,87 @@
+/**
+ * Overlaying one attribute onto already-coloured text.
+ *
+ * Syntax highlighting spends the foreground: after `highlightCode` runs, a
+ * line is a string of printable characters interleaved with SGR escape
+ * sequences, and the character offsets a word diff computed against the raw
+ * text no longer line up with positions in that string. So to mark *which*
+ * words changed on a syntax-highlighted line — the thing that makes a long
+ * call's one changed argument findable — the marker cannot be another
+ * foreground colour. It has to be an attribute that composes with whatever is
+ * underneath: reverse video.
+ *
+ * `overlayRanges` walks the coloured string, counting only printable columns
+ * and copying escape sequences through untouched, and wraps the requested
+ * column ranges in an on/off pair. Reverse-video's pair (`\x1b[7m` / `\x1b[27m`)
+ * touches neither foreground nor background, so the syntax colours and any
+ * surrounding line background both survive.
+ *
+ * Zero dependencies, like the rest of this package.
+ */
+
+/** A half-open [start, end) run of printable columns. */
+export type Range = [number, number];
+
+/**
+ * Wrap each printable-column range of `ansi` in the `on`/`off` pair. Ranges
+ * must be sorted and non-overlapping; escape sequences are passed through and
+ * do not advance the column count, so offsets stay in raw-text coordinates.
+ */
+export function overlayRanges(ansi: string, ranges: readonly Range[], on: string, off: string): string {
+  if (ranges.length === 0) return ansi;
+  let out = "";
+  let col = 0;
+  let ri = 0;
+  let inside = false;
+  let i = 0;
+  while (i < ansi.length) {
+    if (ansi[i] === "\x1b") {
+      // Copy the whole CSI/SGR sequence: ESC, then usually '[', then
+      // parameter/intermediate bytes, then a final letter.
+      let j = i + 1;
+      if (ansi[j] === "[") {
+        j++;
+        while (j < ansi.length && !/[A-Za-z]/.test(ansi[j]!)) j++;
+      }
+      if (j < ansi.length) j++;
+      out += ansi.slice(i, j);
+      i = j;
+      continue;
+    }
+    while (ri < ranges.length && col >= ranges[ri]![1]) ri++;
+    const shouldBeInside = ri < ranges.length && col >= ranges[ri]![0];
+    if (shouldBeInside && !inside) {
+      out += on;
+      inside = true;
+    } else if (!shouldBeInside && inside) {
+      out += off;
+      inside = false;
+    }
+    out += ansi[i];
+    col++;
+    i++;
+  }
+  if (inside) out += off;
+  return out;
+}
+
+/** Printable width of an ANSI string — its length with escape sequences removed. */
+export function visibleLength(ansi: string): number {
+  let n = 0;
+  let i = 0;
+  while (i < ansi.length) {
+    if (ansi[i] === "\x1b") {
+      let j = i + 1;
+      if (ansi[j] === "[") {
+        j++;
+        while (j < ansi.length && !/[A-Za-z]/.test(ansi[j]!)) j++;
+      }
+      if (j < ansi.length) j++;
+      i = j;
+      continue;
+    }
+    n++;
+    i++;
+  }
+  return n;
+}

package/src/diff.ts

@@ -1,5 +1,6 @@
+import { overlayRanges, type Range } from "./ansi.ts";
 import { MIN_SIMILARITY, wordDiff, type Segment } from "./words.ts";
-import type { ThemeLike } from "./types.ts";
+import type { HighlightLine, ThemeLike } from "./types.ts";
 
 export interface DiffStats {
   added: number;
@@ -46,9 +47,103 @@ function fg(theme: ThemeLike, color: string, fallback: string, text: string): st
   }
 }
 
+/**
+ * A changed line's background. Foreground is already spent on syntax colours,
+ * so the +/- signal moves here. The keys are pi's tool-state backgrounds,
+ * which its builtin themes define and this package's themes map to real diff
+ * tints (`diff_add`/`diff_del`). A theme without `bg`, or one that does not
+ * know the key, leaves the line un-backgrounded — the coloured marker still
+ * carries the signal.
+ */
+function withBg(theme: ThemeLike, key: string, text: string): string {
+  if (!theme.bg) return text;
+  try {
+    return theme.bg(key, text);
+  } catch {
+    return text;
+  }
+}
+
 const ADDED = "toolDiffAdded";
 const REMOVED = "toolDiffRemoved";
 const CONTEXT = "toolDiffContext";
+const ADDED_BG = "toolSuccessBg";
+const REMOVED_BG = "toolErrorBg";
+
+// Reverse-video's SGR pair — see ansi.ts. Hard-coded rather than derived from
+// theme.inverse so the on/off can be injected mid-string around a range.
+const INV_ON = "\x1b[7m";
+const INV_OFF = "\x1b[27m";
+
+export interface DiffRenderOptions {
+  /** Word-level emphasis on paired lines (default true). */
+  emphasis?: boolean;
+  /** Prepend old/new line-number gutters (default false; the extension sets it). */
+  lineNumbers?: boolean;
+  /** Language for syntax highlighting; undefined leaves the body un-highlighted. */
+  language?: string;
+  /** Injected highlighter (the extension passes pi's `highlightCode`). */
+  highlight?: HighlightLine;
+}
+
+function normalize(options: boolean | DiffRenderOptions | undefined): DiffRenderOptions {
+  if (options === undefined) return { emphasis: true };
+  if (typeof options === "boolean") return { emphasis: options };
+  return { emphasis: options.emphasis ?? true, ...options };
+}
+
+interface LineNo {
+  old: number | null;
+  new: number | null;
+}
+
+/** Per-original-line old/new numbers, tracked across hunks. */
+function computeLineNos(lines: string[]): LineNo[] {
+  const nos: LineNo[] = [];
+  let oldNo = 0;
+  let newNo = 0;
+  let inHunk = false;
+  for (const line of lines) {
+    if (line.startsWith("@@")) {
+      const m = /@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(line);
+      if (m) {
+        oldNo = Number(m[1]);
+        newNo = Number(m[2]);
+      }
+      inHunk = true;
+      nos.push({ old: null, new: null });
+      continue;
+    }
+    // "\ No newline…" notes and this package's own "… +N more" truncation
+    // marker are not file lines and take no number.
+    if (!inHunk || line.startsWith("\\") || line.startsWith("…")) {
+      nos.push({ old: null, new: null });
+      continue;
+    }
+    if (line.startsWith("+") && !line.startsWith("+++")) {
+      nos.push({ old: null, new: newNo++ });
+    } else if (line.startsWith("-") && !line.startsWith("---")) {
+      nos.push({ old: oldNo++, new: null });
+    } else {
+      nos.push({ old: oldNo++, new: newNo++ });
+    }
+  }
+  return nos;
+}
+
+function gutterWidth(nos: LineNo[]): number {
+  let max = 0;
+  for (const n of nos) {
+    if (n.old !== null) max = Math.max(max, n.old);
+    if (n.new !== null) max = Math.max(max, n.new);
+  }
+  return String(max).length;
+}
+
+function formatGutter(theme: ThemeLike, no: LineNo, w: number): string {
+  const cell = (v: number | null) => (v === null ? " ".repeat(w) : String(v).padStart(w));
+  return theme.fg("dim", `${cell(no.old)} ${cell(no.new)} `);
+}
 
 function plain(theme: ThemeLike, line: string): string {
   if (line.startsWith("+++") || line.startsWith("---")) return theme.fg("dim", line);
@@ -59,24 +154,62 @@ function plain(theme: ThemeLike, line: string): string {
 }
 
 /**
- * Paint one side of a matched pair: what changed keeps the diff colour, what
- * carried over from the other line goes quiet. Segments are emitted one after
- * another and never nested, so there is no inner reset to swallow an outer
- * colour — the failure mode that makes hand-built ANSI look corrupted.
+ * Paint one side of a matched pair with foreground emphasis: what changed
+ * keeps the diff colour, what carried over goes quiet. Segments are emitted
+ * one after another and never nested, so there is no inner reset to swallow an
+ * outer colour — the failure mode that makes hand-built ANSI look corrupted.
  */
-function emphasize(
+function emphasize(theme: ThemeLike, marker: string, segments: Segment[], color: string, fallback: string): string {
+  return (
+    fg(theme, color, fallback, marker) +
+    segments.map((s) => (s.changed ? fg(theme, color, fallback, s.text) : fg(theme, CONTEXT, "dim", s.text))).join("")
+  );
+}
+
+/** Char ranges of the changed segments, in raw-content coordinates. */
+function changedRanges(segments: Segment[]): Range[] {
+  const ranges: Range[] = [];
+  let pos = 0;
+  for (const s of segments) {
+    if (s.changed) ranges.push([pos, pos + s.text.length]);
+    pos += s.text.length;
+  }
+  return ranges;
+}
+
+function highlight(theme: ThemeLike, opts: DiffRenderOptions, content: string): string {
+  if (!opts.highlight || !opts.language) return content;
+  try {
+    return opts.highlight(content, opts.language);
+  } catch {
+    return content;
+  }
+}
+
+/**
+ * A syntax-highlighted diff line: the content keeps its syntax colours, the
+ * +/- signal is a subtle line background, and the changed words are marked
+ * with reverse video overlaid on top — the only combination where all three
+ * survive at once (foreground is spent on syntax, so emphasis cannot be a
+ * fourth foreground).
+ */
+function syntaxLine(
   theme: ThemeLike,
+  opts: DiffRenderOptions,
   marker: string,
-  segments: Segment[],
+  content: string,
+  segments: Segment[] | null,
   color: string,
   fallback: string,
+  bgKey: string | null,
 ): string {
-  return (
-    fg(theme, color, fallback, marker) +
-    segments
-      .map((s) => (s.changed ? fg(theme, color, fallback, s.text) : fg(theme, CONTEXT, "dim", s.text)))
-      .join("")
-  );
+  let body = highlight(theme, opts, content);
+  if (segments && theme.inverse) {
+    const ranges = changedRanges(segments);
+    if (ranges.length > 0) body = overlayRanges(body, ranges, INV_ON, INV_OFF);
+  }
+  const line = fg(theme, color, fallback, marker) + body;
+  return bgKey ? withBg(theme, bgKey, line) : line;
 }
 
 /**
@@ -84,24 +217,42 @@ function emphasize(
  *
  * Line colour alone says *that* a line changed; when the change is one
  * argument in a long call, finding it is still the reader's job. So a removed
- * line and the added line that replaced it are compared word by word, and
- * only where they are similar enough for "what changed" to mean anything.
- * Lines with no counterpart — a pure insertion, a pure deletion, an unequal
- * run — are coloured whole, exactly as before.
+ * line and the added line that replaced it are compared word by word, and only
+ * where they are similar enough for "what changed" to mean anything. Lines
+ * with no counterpart — a pure insertion, a pure deletion, an unequal run —
+ * are coloured whole.
+ *
+ * With a `highlight` and `language`, the body is syntax-highlighted and the
+ * +/- signal moves to the line background so both are visible; without them it
+ * falls back to the foreground-only rendering. Line numbers are prepended when
+ * asked for.
  */
-export function colorizeDiff(theme: ThemeLike, diff: string, emphasis = true): string {
+export function colorizeDiff(theme: ThemeLike, diff: string, options?: boolean | DiffRenderOptions): string {
+  const opts = normalize(options);
   const lines = diff.split("\n");
-  if (!emphasis) return lines.map((line) => plain(theme, line)).join("\n");
+  const nos = opts.lineNumbers ? computeLineNos(lines) : null;
+  const width = nos ? gutterWidth(nos) : 0;
+  const syntax = Boolean(opts.highlight && opts.language);
+
+  const rendered: string[] = new Array(lines.length);
+  const put = (idx: number, text: string) => {
+    rendered[idx] = nos ? formatGutter(theme, nos[idx]!, width) + text : text;
+  };
+
+  const contextLine = (idx: number, line: string) => {
+    if (!syntax || line.startsWith("+++") || line.startsWith("---") || line.startsWith("@@") || line.startsWith("\\")) {
+      put(idx, plain(theme, line));
+      return;
+    }
+    // A context line keeps its leading space and gets syntax colour, no bg.
+    put(idx, line.slice(0, 1) + highlight(theme, opts, line.slice(1)));
+  };
 
-  const out: string[] = [];
   let inHunk = false;
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i]!;
     if (line.startsWith("@@")) inHunk = true;
 
-    // A removed run followed by an added run of the same length is the shape
-    // an in-place change takes; anything else is an insertion or a deletion,
-    // and pairing those would invent a correspondence that is not there.
     if (inHunk && line.startsWith("-") && !line.startsWith("---")) {
       const removed: string[] = [];
       let j = i;
@@ -111,30 +262,53 @@ export function colorizeDiff(theme: ThemeLike, diff: string, emphasis = true): s
       while (k < lines.length && lines[k]!.startsWith("+") && !lines[k]!.startsWith("+++")) added.push(lines[k++]!);
 
       const pairs =
-        removed.length > 0 && removed.length === added.length
+        opts.emphasis && removed.length > 0 && removed.length === added.length
           ? removed.map((minus, index) => wordDiff(minus.slice(1), added[index]!.slice(1)))
           : null;
 
       if (pairs && pairs.every((pair) => pair.similarity >= MIN_SIMILARITY)) {
         for (const [index, pair] of pairs.entries()) {
-          out.push(emphasize(theme, removed[index]![0]!, pair.removed, REMOVED, "error"));
+          const marker = removed[index]![0]!;
+          const content = removed[index]!.slice(1);
+          put(
+            i + index,
+            syntax
+              ? syntaxLine(theme, opts, marker, content, pair.removed, REMOVED, "error", REMOVED_BG)
+              : emphasize(theme, marker, pair.removed, REMOVED, "error"),
+          );
         }
         for (const [index, pair] of pairs.entries()) {
-          out.push(emphasize(theme, added[index]![0]!, pair.added, ADDED, "success"));
+          const marker = added[index]![0]!;
+          const content = added[index]!.slice(1);
+          put(
+            j + index,
+            syntax
+              ? syntaxLine(theme, opts, marker, content, pair.added, ADDED, "success", ADDED_BG)
+              : emphasize(theme, marker, pair.added, ADDED, "success"),
+          );
         }
         i = k - 1;
         continue;
       }
 
-      // The run has no line-for-line correspondence, so nothing inside it
-      // does either. Emitting it whole is what stops the tail of a 2-for-1
-      // rewrite from being re-scanned and paired with the line that replaced
-      // both of them.
-      for (const minus of removed) out.push(plain(theme, minus));
+      // No line-for-line correspondence, so nothing inside does either.
+      for (let index = 0; index < removed.length; index++) {
+        const minus = removed[index]!;
+        put(
+          i + index,
+          syntax ? syntaxLine(theme, opts, minus[0]!, minus.slice(1), null, REMOVED, "error", REMOVED_BG) : plain(theme, minus),
+        );
+      }
       i = j - 1;
       continue;
     }
-    out.push(plain(theme, line));
+
+    if (syntax && inHunk && line.startsWith("+") && !line.startsWith("+++")) {
+      put(i, syntaxLine(theme, opts, line[0]!, line.slice(1), null, ADDED, "success", ADDED_BG));
+      continue;
+    }
+
+    contextLine(i, line);
   }
-  return out.join("\n");
+  return rendered.join("\n");
 }

package/src/settings.ts

@@ -21,6 +21,12 @@ export interface PrettySettings {
   diffLines: number;
   /** Highlight expanded read results with pi's own highlighter. */
   syntaxHighlight: boolean;
+  /** Syntax-highlight the body of an edit diff, not just tint the lines. */
+  diffSyntax: boolean;
+  /** Prepend old/new line-number gutters to an expanded edit diff. */
+  diffLineNumbers: boolean;
+  /** Render the edit diff side-by-side (old | new) when the terminal is wide enough. */
+  diffSplit: boolean;
   /** Longest path/command shown in a one-line summary. */
   summaryClip: number;
 }
@@ -30,6 +36,9 @@ export const DEFAULT_SETTINGS: PrettySettings = {
   expandedLines: 200,
   diffLines: 200,
   syntaxHighlight: true,
+  diffSyntax: true,
+  diffLineNumbers: true,
+  diffSplit: false,
   summaryClip: 100,
 };
 
@@ -38,6 +47,9 @@ const LIMITS: Record<keyof PrettySettings, { min: number; max: number } | null>
   expandedLines: { min: 5, max: 10_000 },
   diffLines: { min: 5, max: 10_000 },
   syntaxHighlight: null,
+  diffSyntax: null,
+  diffLineNumbers: null,
+  diffSplit: null,
   summaryClip: { min: 20, max: 500 },
 };
 

package/src/split.ts

@@ -0,0 +1,163 @@
+/**
+ * Side-by-side diff, old on the left and new on the right.
+ *
+ * A unified diff answers "what changed"; a split answers "what did it become",
+ * which is the question you have when a block was rewritten rather than nudged.
+ * It costs width — two columns of code plus gutters and a separator — so it is
+ * opt-in and falls back to unified when the terminal cannot spare the columns
+ * (`splitFits`). Rows are still one `Text`: cells are padded by *visible*
+ * width, counting printable columns and not the escape sequences syntax
+ * highlighting leaves behind.
+ *
+ * Word-level emphasis is deliberately not carried over here — the spatial
+ * pairing is the emphasis in a split — so this stays a straightforward
+ * highlight-and-tint. Zero dependencies, like the rest of the package.
+ */
+import { visibleLength } from "./ansi.ts";
+import type { DiffRenderOptions } from "./diff.ts";
+import type { ThemeLike } from "./types.ts";
+
+/** Narrowest terminal a split is worth rendering in; below this, use unified. */
+export const MIN_SPLIT_WIDTH = 100;
+/** Narrowest a single code column may be squeezed to. */
+const MIN_CELL = 20;
+const SEP = " │ ";
+
+export function splitFits(columns: number | undefined): boolean {
+  return typeof columns === "number" && Number.isFinite(columns) && columns >= MIN_SPLIT_WIDTH;
+}
+
+interface Cell {
+  no: number | null;
+  marker: string;
+  content: string;
+}
+
+interface Row {
+  /** A row that spans both columns (hunk/file headers), pre-rendered. */
+  full?: string;
+  left?: Cell | null;
+  right?: Cell | null;
+}
+
+function fg(theme: ThemeLike, color: string, fallback: string, text: string): string {
+  try {
+    return theme.fg(color, text);
+  } catch {
+    return theme.fg(fallback, text);
+  }
+}
+
+function withBg(theme: ThemeLike, key: string, text: string): string {
+  if (!theme.bg) return text;
+  try {
+    return theme.bg(key, text);
+  } catch {
+    return text;
+  }
+}
+
+function highlight(opts: DiffRenderOptions, content: string): string {
+  if (!opts.highlight || !opts.language) return content;
+  try {
+    return opts.highlight(content, opts.language);
+  } catch {
+    return content;
+  }
+}
+
+function parseRows(lines: string[]): Row[] {
+  const rows: Row[] = [];
+  let oldNo = 0;
+  let newNo = 0;
+  let inHunk = false;
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i]!;
+    if (line.startsWith("@@")) {
+      const m = /@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(line);
+      if (m) {
+        oldNo = Number(m[1]);
+        newNo = Number(m[2]);
+      }
+      inHunk = true;
+      rows.push({ full: line });
+      i++;
+      continue;
+    }
+    if (!inHunk || line.startsWith("+++") || line.startsWith("---") || line.startsWith("\\") || line.startsWith("…")) {
+      rows.push({ full: line });
+      i++;
+      continue;
+    }
+    if (line.startsWith("-")) {
+      const removed: string[] = [];
+      while (i < lines.length && lines[i]!.startsWith("-") && !lines[i]!.startsWith("---")) removed.push(lines[i++]!);
+      const added: string[] = [];
+      while (i < lines.length && lines[i]!.startsWith("+") && !lines[i]!.startsWith("+++")) added.push(lines[i++]!);
+      const n = Math.max(removed.length, added.length);
+      for (let x = 0; x < n; x++) {
+        const left = x < removed.length ? { no: oldNo++, marker: "-", content: removed[x]!.slice(1) } : null;
+        const right = x < added.length ? { no: newNo++, marker: "+", content: added[x]!.slice(1) } : null;
+        rows.push({ left, right });
+      }
+      continue;
+    }
+    if (line.startsWith("+")) {
+      const added: string[] = [];
+      while (i < lines.length && lines[i]!.startsWith("+") && !lines[i]!.startsWith("+++")) added.push(lines[i++]!);
+      for (const a of added) rows.push({ left: null, right: { no: newNo++, marker: "+", content: a.slice(1) } });
+      continue;
+    }
+    // context
+    rows.push({
+      left: { no: oldNo++, marker: " ", content: line.slice(1) },
+      right: { no: newNo++, marker: " ", content: line.slice(1) },
+    });
+    i++;
+  }
+  return rows;
+}
+
+function maxNoWidth(rows: Row[]): number {
+  let max = 0;
+  for (const r of rows) {
+    if (r.left && r.left.no !== null) max = Math.max(max, r.left.no);
+    if (r.right && r.right.no !== null) max = Math.max(max, r.right.no);
+  }
+  return String(max).length;
+}
+
+function renderCell(theme: ThemeLike, opts: DiffRenderOptions, cell: Cell | null | undefined, numW: number, cellW: number): string {
+  const gutter = numW > 0 ? theme.fg("dim", (cell && cell.no !== null ? String(cell.no).padStart(numW) : " ".repeat(numW)) + " ") : "";
+  if (!cell) return gutter + " ".repeat(cellW);
+
+  const room = cellW - 1; // one column for the marker
+  const clipped = cell.content.length > room ? cell.content.slice(0, Math.max(0, room - 1)) + "…" : cell.content;
+  const marker = cell.marker === "+" ? fg(theme, "toolDiffAdded", "success", "+") : cell.marker === "-" ? fg(theme, "toolDiffRemoved", "error", "-") : " ";
+  let body = marker + highlight(opts, clipped);
+  const pad = cellW - visibleLength(body);
+  if (pad > 0) body += " ".repeat(pad);
+  if (cell.marker === "+") body = withBg(theme, "toolSuccessBg", body);
+  else if (cell.marker === "-") body = withBg(theme, "toolErrorBg", body);
+  return gutter + body;
+}
+
+function renderFull(theme: ThemeLike, line: string): string {
+  if (line.startsWith("@@")) return theme.fg("accent", line);
+  return theme.fg("dim", line);
+}
+
+export function buildSplit(theme: ThemeLike, diff: string, opts: DiffRenderOptions, columns: number): string {
+  const rows = parseRows(diff.split("\n"));
+  const numW = opts.lineNumbers ? maxNoWidth(rows) : 0;
+  const gut = numW > 0 ? numW + 1 : 0;
+  const cellW = Math.max(MIN_CELL, Math.floor((columns - SEP.length - 2 * gut) / 2));
+  return rows
+    .map((row) =>
+      row.full !== undefined
+        ? renderFull(theme, row.full)
+        : renderCell(theme, opts, row.left, numW, cellW) + theme.fg("dim", SEP) + renderCell(theme, opts, row.right, numW, cellW),
+    )
+    .join("\n");
+}

package/src/types.ts

@@ -7,8 +7,22 @@
 export interface ThemeLike {
   fg(color: string, text: string): string;
   bold(text: string): string;
+  /**
+   * Background paint, `theme.bg(key, text)`. Optional so src/ typechecks
+   * standalone and a test theme can omit it; the diff renderer guards its
+   * absence (and, like `fg`, a name the theme does not know). Used to give a
+   * changed line a subtle +/- background instead of a whole-line foreground
+   * tint, which is the only way a syntax-highlighted body can also read as a
+   * diff — foreground is already spent on the syntax.
+   */
+  bg?(color: string, text: string): string;
+  /** Reverse video, `theme.inverse(text)` — marks the exact changed words. */
+  inverse?(text: string): string;
 }
 
+/** Syntax-highlight one line of code to an ANSI string; empty deps in src/. */
+export type HighlightLine = (code: string, language: string) => string;
+
 /** The tools this extension can re-render. */
 export const PRETTY_TOOLS = ["read", "bash", "edit", "write", "grep", "find", "ls"] as const;
 export type PrettyTool = (typeof PRETTY_TOOLS)[number];