@pi-archimedes/diff 2.10.3 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/diff",
-  "version": "2.10.3",
+  "version": "2.11.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/danielcherubini/pi-archimedes.git"
@@ -24,12 +24,12 @@
     "get-east-asian-width": "^1.6.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.1.0",
-    "@earendil-works/pi-tui": ">=0.1.0"
+    "@earendil-works/pi-coding-agent": ">=1.2.0",
+    "@earendil-works/pi-tui": ">=1.2.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.87.0",
-    "@earendil-works/pi-tui": "^0.87.0",
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "@earendil-works/pi-tui": "1.2.0",
     "@types/diff": "^7.0.2",
     "typescript": "^6.0.0"
   },

package/src/ansi/codes.test.ts

@@ -212,16 +212,40 @@ describe("resolveDiffColors", () => {
 		expect(result.fgCtx).toBe("\x1b[38;2;100;100;100m");
 	});
 
-	it("falls back to defaults when getFgAnsi returns empty string", () => {
+	it("passes a terminal-default token through instead of substituting a hardcoded colour", () => {
+		// 1.2.0 answers a token set to "" with `\x1b[39m` — truthy — so the old
+		// `|| FG_ADD` could never fire for it, and the `""` shape that *did* fire
+		// it (pre-0.99.0) substituted a colour where the theme had said "the
+		// terminal's own". Both readings agree on the fix: a terminal default is
+		// an answer, not a missing value.
+		resetDiffColors();
+		for (const token of ["", "\x1b[39m", "\x1b[0m"]) {
+			const result = resolveDiffColors({ getFgAnsi: () => token });
+			expect(result).toEqual({ fgAdd: token, fgDel: token, fgCtx: token });
+		}
+	});
+
+	it("substitutes the hardcoded fallback per token, only where the theme has no answer", () => {
 		resetDiffColors();
 		const theme = {
-			getFgAnsi: () => "",
+			getFgAnsi: (token: string) => {
+				if (token === "toolDiffAdded") return "\x1b[38;2;50;200;50m";
+				// Unknown tokens throw in 1.2.0 (`tokenAnsi`), which used to take
+				// every colour in this row down to the hardcoded set.
+				throw new Error(`Unknown theme color: ${token}`);
+			},
 		};
 		const result = resolveDiffColors(theme);
-		expect(result.fgAdd).toBe(FG_ADD);
+		expect(result.fgAdd).toBe("\x1b[38;2;50;200;50m");
 		expect(result.fgDel).toBe(FG_DEL);
 		expect(result.fgCtx).toBe(FG_DIM);
 	});
+
+	it("keeps the hardcoded set for the no-theme-object path", () => {
+		resetDiffColors();
+		expect(resolveDiffColors(undefined)).toEqual(DEFAULT_DIFF_COLORS);
+		expect(resolveDiffColors({})).toEqual(DEFAULT_DIFF_COLORS);
+	});
 });
 
 // ── resetDiffColors ─────────────────────────────────────────────────────────

package/src/ansi/codes.ts

@@ -21,7 +21,8 @@ export const FG_SAFE_MUTED = "\x1b[38;2;139;148;158m";
 export const FG_STRIPE = "\x1b[38;2;40;40;40m"; // gray diagonal stripes
 
 export const BORDER_BAR = "▌";
-const BG_DEFAULT = "\x1b[49m"; // reset to terminal default background
+/** Reset to the terminal's own background — "no background color", not a color. */
+export const BG_DEFAULT = "\x1b[49m";
 
 // ---------------------------------------------------------------------------
 // DiffBg — instance-scoped background colors derived from a theme
@@ -107,6 +108,27 @@ export function themeCacheKey(theme?: any): string {
 
 export { deriveBgFromTheme };
 
+/**
+ * Read one foreground token from a theme, or undefined when the theme has no
+ * answer for it.
+ *
+ * A terminal-default answer is returned as-is. Since 0.99.0 a token set to `""`
+ * comes back as `\x1b[39m` — truthy — so a `getFgAnsi(…) || FG_*` chain could
+ * never fire for it, while the `""` shape that *did* fire it substituted a
+ * hardcoded color where the theme had said "the terminal's own". Both readings
+ * agree: a terminal default is an answer, and the hardcoded `FG_*` constants are
+ * only for a theme that cannot answer at all.
+ */
+function themeFgAnsi(theme: any, token: string): string | undefined {
+	if (typeof theme?.getFgAnsi !== "function") return undefined;
+	try {
+		const ansi = theme.getFgAnsi(token);
+		return typeof ansi === "string" ? ansi : undefined;
+	} catch {
+		return undefined; // unknown token: 1.x throws from `tokenAnsi`
+	}
+}
+
 export function resolveDiffColors(theme?: any): DiffColors {
 	const themeKey = themeCacheKey(theme);
 
@@ -115,13 +137,11 @@ export function resolveDiffColors(theme?: any): DiffColors {
 		_lastThemeKey = themeKey;
 	}
 	if (!theme?.getFgAnsi) return DEFAULT_DIFF_COLORS;
-	try {
-		return {
-			fgAdd: theme.getFgAnsi("toolDiffAdded") || FG_ADD,
-			fgDel: theme.getFgAnsi("toolDiffRemoved") || FG_DEL,
-			fgCtx: theme.getFgAnsi("toolDiffContext") || FG_DIM,
-		};
-	} catch {
-		return DEFAULT_DIFF_COLORS;
-	}
+	// Per token, so one unknown token cannot drag the whole row back to the
+	// hardcoded set.
+	return {
+		fgAdd: themeFgAnsi(theme, "toolDiffAdded") ?? FG_ADD,
+		fgDel: themeFgAnsi(theme, "toolDiffRemoved") ?? FG_DEL,
+		fgCtx: themeFgAnsi(theme, "toolDiffContext") ?? FG_DIM,
+	};
 }

package/src/ansi/colors.test.ts

@@ -1,8 +1,16 @@
 import { describe, it, expect } from "vitest";
 import * as fc from "fast-check";
-import { deriveBgFromTheme } from "./colors.js";
+import { Theme as PiTheme } from "@earendil-works/pi-coding-agent";
+import { deriveBgFromTheme, isTerminalDefault } from "./colors.js";
 import { DEFAULT_DIFF_BG, FG_RULE } from "./codes.js";
 
+// The escape that means "paint nothing": the terminal's own background. A theme
+// token set to "" (terminal default) reaches us as `\x1b[39m` / `\x1b[49m`, and
+// `\x1b[49m` is exactly what `bgBase` already uses when there is no base colour,
+// so "no colour" needs no new colour value — it needs a fallthrough that stops
+// inventing one.
+const BG_NONE = "\x1b[49m";
+
 // ── deriveBgFromTheme ───────────────────────────────────────────────────────
 
 describe("deriveBgFromTheme", () => {
@@ -199,7 +207,7 @@ describe("deriveBgFromTheme", () => {
 		);
 	});
 
-	it("property: all bg fields are valid truecolor bg escapes or defaults", () => {
+	it("property: all bg fields are valid truecolor bg escapes, the terminal default, or defaults", () => {
 		fc.assert(
 			fc.property(
 				fc.string({ maxLength: 50 }),
@@ -212,23 +220,197 @@ describe("deriveBgFromTheme", () => {
 						},
 					};
 					const result = deriveBgFromTheme(theme);
-					// Either we get valid truecolor bg escapes, or we get defaults
-					const isTruecolorBg = (s: string) => /\x1b\[48;2;\d+;\d+;\d+m/.test(s);
-					const allValid = [
+					// Three legal answers: a derived truecolour bg, "no colour" (a
+					// terminal-default token), or the no-theme-object fallback.
+					const isLegal = (s: string) =>
+						/\x1b\[48;2;\d+;\d+;\d+m/.test(s) || s === BG_NONE;
+					const allLegal = [
 						result.bgAdd,
 						result.bgDel,
 						result.bgAddW,
 						result.bgDelW,
 						result.bgGutterAdd,
 						result.bgGutterDel,
-					].every((bg) => isTruecolorBg(bg));
+					].every(isLegal);
 					const isDefault = result === DEFAULT_DIFF_BG || result.bgAdd === DEFAULT_DIFF_BG.bgAdd;
-					return allValid || isDefault;
+					return allLegal || isDefault;
 				},
 			),
 		);
 	});
 
+	// ── Palette tokens and terminal-default tokens ───────────────────────────
+	//
+	// The parser used to match only `38|48;2;r;g;b`. Every other token — the
+	// `38;5;n`/`48;5;n` sequences a non-truecolour terminal produces, and the
+	// indexed tokens pi's generated `system` theme uses when the terminal
+	// reports nothing — fell through to the hardcoded `DEFAULT_DIFF_BG` slabs,
+	// so the diff showed fixed dark green/red no matter what the theme said.
+
+	it("resolves a 38;5;n diff colour through the xterm-256 table", () => {
+		// Index 2 is (0,128,0) in the same table `core/src/color.ts` uses, so the
+		// added-line background is that accent mixed into the base at 0.08.
+		const theme = {
+			getFgAnsi: (token: string) => {
+				if (token === "toolDiffAdded") return "\x1b[38;5;2m";
+				if (token === "toolDiffRemoved") return "\x1b[38;5;1m";
+				return "\x1b[38;5;7m";
+			},
+		};
+		const result = deriveBgFromTheme(theme);
+		expect(result.bgAdd).toBe("\x1b[48;2;0;10;0m");
+		expect(result.bgDel).toBe("\x1b[48;2;13;0;0m");
+		expect(result.bgAddW).toBe("\x1b[48;2;0;26;0m");
+		expect(result.bgGutterDel).toBe("\x1b[48;2;8;0;0m");
+		// Not the hardcoded slab any more — the theme's own palette drove it.
+		expect(result.bgAdd).not.toBe(DEFAULT_DIFF_BG.bgAdd);
+	});
+
+	it("resolves a 48;5;n base background through the same table", () => {
+		// The asymmetry that makes core's helper insufficient on its own: this
+		// parser is fed background strings too (`theme.getBgAnsi(...)`), so 48;5;
+		// must resolve, not just 38;5;. 236 is the gray ramp at (48,48,48).
+		const theme = {
+			getFgAnsi: (token: string) => {
+				if (token === "toolDiffAdded") return "\x1b[38;5;2m";
+				if (token === "toolDiffRemoved") return "\x1b[38;5;1m";
+				return "\x1b[38;5;7m";
+			},
+			getBgAnsi: (token: string) => {
+				if (token === "toolSuccessBg") return "\x1b[48;5;236m";
+				if (token === "toolErrorBg") return "\x1b[48;5;237m";
+				return BG_NONE;
+			},
+		};
+		const result = deriveBgFromTheme(theme);
+		// The token itself is the base — passed through, not reparsed into a
+		// truecolour equivalent — and it is what the mix starts from.
+		expect(result.bgBase).toBe("\x1b[48;5;236m");
+		expect(result.bgEmpty).toBe("\x1b[48;5;236m");
+		expect(result.bgAdd).toBe("\x1b[48;2;44;54;44m");
+		expect(result.bgDel).toBe("\x1b[48;2;65;52;52m");
+	});
+
+	it("treats a terminal-default diff colour as no colour, not as DEFAULT_DIFF_BG", () => {
+		for (const token of ["", "\x1b[39m", "\x1b[0m"]) {
+			const theme = { getFgAnsi: () => token };
+			const result = deriveBgFromTheme(theme);
+			expect(JSON.stringify(token)).not.toBe("undefined");
+			for (const field of [
+				result.bgAdd,
+				result.bgDel,
+				result.bgAddW,
+				result.bgDelW,
+				result.bgGutterAdd,
+				result.bgGutterDel,
+				result.bgEmpty,
+			] as const) {
+				expect(field, `token ${JSON.stringify(token)}`).toBe(BG_NONE);
+			}
+			expect(result).not.toEqual(DEFAULT_DIFF_BG);
+			expect(result.bgAdd).not.toBe(DEFAULT_DIFF_BG.bgAdd);
+			// The reset still closes whatever state the line opened.
+			expect(result.rst).toContain("\x1b[0m");
+		}
+	});
+
+	it("keeps the side that has a colour tinted when only the other side declines one", () => {
+		const theme = {
+			getFgAnsi: (token: string) =>
+				token === "toolDiffAdded" ? "\x1b[38;2;0;255;0m" : "\x1b[39m",
+		};
+		const result = deriveBgFromTheme(theme);
+		expect(result.bgAdd).toBe("\x1b[48;2;0;20;0m");
+		expect(result.bgDel).toBe(BG_NONE);
+		expect(result.bgDelW).toBe(BG_NONE);
+		expect(result.bgGutterDel).toBe(BG_NONE);
+	});
+
+	it("treats a terminal-default base background as no base colour, keeping the accent tint", () => {
+		// `toolSuccessBg`/`toolErrorBg` are panel tokens: pi's generated system
+		// theme gives panels no background, so they arrive as `\x1b[49m`. That
+		// must not be read as a colour, and it must not discard the accent tint.
+		const theme = {
+			getFgAnsi: (token: string) => {
+				if (token === "toolDiffAdded") return "\x1b[38;2;0;255;0m";
+				if (token === "toolDiffRemoved") return "\x1b[38;2;255;0;0m";
+				return "\x1b[38;5;7m";
+			},
+			getBgAnsi: () => BG_NONE,
+		};
+		const result = deriveBgFromTheme(theme);
+		expect(result.bgBase).toBe(BG_NONE);
+		expect(result.bgAdd).toBe("\x1b[48;2;0;20;0m");
+	});
+
+	// ── Real pi 1.2.0 Theme objects ──────────────────────────────────
+	//
+	// The fixtures above hand-build escape strings. These build the real thing,
+	// because the whole point is that the shape of the incoming token is pi's
+	// business, not ours.
+
+	/**
+	 * A real pi 1.2.0 `Theme`. Every token that another token falls back to
+	 * (`scrollbarTrack`→`muted`, `scrollbarThumb`/`searchMatchText`→`text`,
+	 * `searchMatchBg`→`selectedBg`, `thinkingMax`→`thinkingXhigh`) has to be
+	 * present, because the constructor resolves the fallbacks eagerly.
+	 */
+	function realPiTheme(
+		tokens: Record<string, string | number>,
+		options: { appearance: "light" | "dark"; mode?: "truecolor" | "256color" },
+	): PiTheme {
+		const base: Record<string, string | number> = {
+			text: "#d8d8d8",
+			muted: "#8a8a8a",
+			selectedBg: "#213b49",
+			thinkingXhigh: "#c586c0",
+			...tokens,
+		};
+		return new PiTheme(
+			base as never,
+			base as never,
+			options.mode ?? "truecolor",
+			options,
+		) as PiTheme;
+	}
+
+	it("derives from an indexed (38;5;n) theme token on a real pi Theme", () => {
+		// What pi does when the terminal reports no colours: the system theme
+		// hands out ANSI indices, and the escape comes back as `38;5;n` even in
+		// truecolour mode because the *token* is indexed.
+		const theme = realPiTheme(
+			{ toolDiffAdded: 2, toolDiffRemoved: 1, toolDiffContext: 7 },
+			{ appearance: "dark" },
+		);
+		expect(theme.getFgAnsi("toolDiffAdded")).toBe("\x1b[38;5;2m");
+		const result = deriveBgFromTheme(theme);
+		expect(result.bgAdd).toBe("\x1b[48;2;0;10;0m");
+		expect(result.bgAdd).not.toBe(DEFAULT_DIFF_BG.bgAdd);
+	});
+
+	it("paints no background for a real pi Theme whose diff tokens are terminal default", () => {
+		const theme = realPiTheme(
+			{ toolDiffAdded: "", toolDiffRemoved: "", toolDiffContext: "" },
+			{ appearance: "light" },
+		);
+		expect(theme.getFgAnsi("toolDiffAdded")).toBe("\x1b[39m");
+		const result = deriveBgFromTheme(theme);
+		expect(result.bgAdd).toBe(BG_NONE);
+		expect(result.bgDel).toBe(BG_NONE);
+		expect(result).not.toEqual(DEFAULT_DIFF_BG);
+	});
+
+	it("classifies terminal-default sequences without cracking them open", () => {
+		expect(isTerminalDefault("")).toBe(true);
+		expect(isTerminalDefault("\x1b[39m")).toBe(true);
+		expect(isTerminalDefault("\x1b[49m")).toBe(true);
+		expect(isTerminalDefault("\x1b[0m")).toBe(true);
+		expect(isTerminalDefault("\x1b[m")).toBe(true);
+		expect(isTerminalDefault(undefined)).toBe(true);
+		expect(isTerminalDefault("\x1b[38;5;2m")).toBe(false);
+		expect(isTerminalDefault("\x1b[48;2;18;32;26m")).toBe(false);
+	});
+
 	it("property: divider always contains the rule character", () => {
 		fc.assert(
 			fc.property(

package/src/ansi/colors.ts

@@ -1,23 +1,143 @@
 /** Diff background color derivation from theme. */
 
 import type { DiffBg } from "./codes.js";
-import { DEFAULT_DIFF_BG, FG_RULE } from "./codes.js";
+import { BG_DEFAULT, DEFAULT_DIFF_BG, FG_RULE } from "./codes.js";
 
 // ---------------------------------------------------------------------------
 // Color helpers
 // ---------------------------------------------------------------------------
+//
+// This parser is a deliberate sibling of `parseAnsiFgToRgb` in
+// `packages/core/src/color.ts`; `pi-support.ts` is the one place that says what
+// keeping such a copy costs and why it is worth it. The sibling is not reusable
+// as-is for one reason: core is anchored to `^\x1b[38;` (foreground slot only),
+// while this one reads `38|48` because it is fed **background** strings, straight
+// from `theme.getBgAnsi(...)`.
 
-/** Parse 24-bit ANSI color code → RGB. Works for both fg and bg escapes. */
-function parseAnsiRgb(ansi: string): { r: number; g: number; b: number } | null {
-	const esc = "\x1b";
-	const m = ansi.match(new RegExp(`${esc}\\[(?:38|48);2;(\\d+);(\\d+);(\\d+)m`));
-	return m ? { r: +m[1]!, g: +m[2]!, b: +m[3]! } : null;
+interface RGB {
+	r: number;
+	g: number;
+	b: number;
+}
+
+// xterm standard 16-color palette (ANSI indices 0..15), same table as core.
+// Source: https://en.wikipedia.org/wiki/ANSI_escape_code#3-bit_and_4-bit
+const XTERM_16: readonly RGB[] = [
+	{ r: 0x00, g: 0x00, b: 0x00 }, // 0  black
+	{ r: 0x80, g: 0x00, b: 0x00 }, // 1  maroon
+	{ r: 0x00, g: 0x80, b: 0x00 }, // 2  green
+	{ r: 0x80, g: 0x80, b: 0x00 }, // 3  olive
+	{ r: 0x00, g: 0x00, b: 0x80 }, // 4  navy
+	{ r: 0x80, g: 0x80, b: 0x80 }, // 5  purple
+	{ r: 0x00, g: 0x80, b: 0x80 }, // 6  teal
+	{ r: 0xc0, g: 0xc0, b: 0xc0 }, // 7  silver
+	{ r: 0x80, g: 0x80, b: 0x80 }, // 8  grey
+	{ r: 0xff, g: 0x00, b: 0x00 }, // 9  red
+	{ r: 0x00, g: 0xff, b: 0x00 }, // 10 lime
+	{ r: 0xff, g: 0xff, b: 0x00 }, // 11 yellow
+	{ r: 0x00, g: 0x00, b: 0xff }, // 12 blue
+	{ r: 0xff, g: 0x00, b: 0xff }, // 13 fuchsia
+	{ r: 0x00, g: 0xff, b: 0xff }, // 14 aqua
+	{ r: 0xff, g: 0xff, b: 0xff }, // 15 white
+];
+
+// 6x6x6 cube levels for ANSI 16..231; 232..255 are the gray ramp.
+const CUBE_LEVELS: readonly number[] = [0, 95, 135, 175, 215, 255];
+
+const toByte = (value: number): number => Math.min(255, Math.max(0, Math.round(value)));
+
+/** xterm-256 index → RGB, or null for an index out of range. */
+function ansi256ToRgb(code: number): RGB | null {
+	const c = Math.floor(code);
+	if (!Number.isFinite(c) || c < 0 || c > 255) return null;
+	if (c < 16) return { ...XTERM_16[c]! };
+	if (c < 232) {
+		const idx = c - 16;
+		return {
+			r: CUBE_LEVELS[Math.floor(idx / 36) % 6]!,
+			g: CUBE_LEVELS[Math.floor(idx / 6) % 6]!,
+			b: CUBE_LEVELS[idx % 6]!,
+		};
+	}
+	const v = 8 + (c - 232) * 10;
+	return { r: v, g: v, b: v };
+}
+
+/**
+ * The escape sequences that mean *"the terminal's own color — paint nothing"*.
+ * A pi theme token set to `""` (terminal default) reaches us as `\x1b[39m` /
+ * `\x1b[49m` — truthy strings, so `|| FALLBACK` chains cannot see them. This is
+ * a comparison against a known set, never a decode of the color. Mirrors
+ * `isTerminalDefault` in `packages/core/src/chrome.ts`, duplicated for the same
+ * standalone-package reason as the table above.
+ */
+const TERMINAL_DEFAULT_SEQUENCES: ReadonlySet<string> = new Set([
+	"", // the answer itself, pre-0.99.0
+	"\x1b[0m", // full reset: no color left set
+	"\x1b[m", // …and its parameter-less form
+	"\x1b[39m", // a foreground token set to ""
+	"\x1b[49m", // a background token set to ""
+]);
+
+/** Does this theme answer mean "the terminal's own color", i.e. no color? */
+export function isTerminalDefault(ansi: string | undefined): boolean {
+	return ansi === undefined || TERMINAL_DEFAULT_SEQUENCES.has(ansi);
+}
+
+const TRUECOLOR_RE = /\x1b\[(?:38|48);2;(\d{1,3});(\d{1,3});(\d{1,3})m/;
+const PALETTE_RE = /\x1b\[(?:38|48);5;(\d{1,3})m/;
+
+/**
+ * Parse a theme escape into RGB. Both slots are read (`38;…` and `48;…`) with
+ * 24-bit and xterm-256 parameters, because a non-truecolor terminal — and
+ * pi's generated `system` theme on a terminal that reported no colors — hands
+ * out `38;5;n`/`48;5;n`. A terminal-default reset parses to *no color* (null),
+ * never to a color we then mix.
+ */
+function parseAnsiRgb(ansi: string): RGB | null {
+	if (!ansi || isTerminalDefault(ansi)) return null;
+	const truecolor = TRUECOLOR_RE.exec(ansi);
+	if (truecolor) {
+		return {
+			r: toByte(Number.parseInt(truecolor[1]!, 10)),
+			g: toByte(Number.parseInt(truecolor[2]!, 10)),
+			b: toByte(Number.parseInt(truecolor[3]!, 10)),
+		};
+	}
+	const palette = PALETTE_RE.exec(ansi);
+	if (palette) return ansi256ToRgb(Number.parseInt(palette[1]!, 10));
+	return null;
+}
+
+/**
+ * What one theme token says about color. `"none"` (terminal default) and
+ * `"unknown"` (no such token, no accessor, or a value we cannot read) are
+ * different answers: "none" is the theme declining to paint, "unknown" is the
+ * theme not being a usable source at all.
+ */
+type TokenColor =
+	| { kind: "color"; ansi: string; rgb: RGB }
+	| { kind: "none" }
+	| { kind: "unknown" };
+
+function readThemeToken(read: (() => unknown) | undefined): TokenColor {
+	if (!read) return { kind: "unknown" };
+	let ansi: unknown;
+	try {
+		ansi = read(); // 1.x throws for an unknown token (`tokenAnsi`)
+	} catch {
+		return { kind: "unknown" };
+	}
+	if (typeof ansi !== "string") return { kind: "unknown" };
+	if (isTerminalDefault(ansi)) return { kind: "none" };
+	const rgb = parseAnsiRgb(ansi);
+	return rgb ? { kind: "color", ansi, rgb } : { kind: "unknown" };
 }
 
 /** Mix an accent color into a base color at the given intensity (0.0–1.0). */
 function mixBg(
-	base: { r: number; g: number; b: number },
-	accent: { r: number; g: number; b: number },
+	base: RGB,
+	accent: RGB,
 	intensity: number,
 ): string {
 	const r = Math.round(base.r + (accent.r - base.r) * intensity);
@@ -32,43 +152,46 @@ function mixBg(
 
 /** Auto-derive diff background colors from the pi theme's fg diff colors. */
 export function deriveBgFromTheme(theme: any): DiffBg {
+	// No theme object to ask: the hardcoded fallbacks are the honest answer,
+	// which is the only place they still apply.
 	if (!theme?.getFgAnsi) return { ...DEFAULT_DIFF_BG };
 	try {
-		const fgAdd = theme.getFgAnsi("toolDiffAdded");
-		const fgDel = theme.getFgAnsi("toolDiffRemoved");
-		const addRgb = parseAnsiRgb(fgAdd);
-		const delRgb = parseAnsiRgb(fgDel);
-		if (!addRgb || !delRgb) return { ...DEFAULT_DIFF_BG };
+		const add = readThemeToken(() => theme.getFgAnsi("toolDiffAdded"));
+		const del = readThemeToken(() => theme.getFgAnsi("toolDiffRemoved"));
+		// Nothing readable to derive from — not a theme we can paint with.
+		if (add.kind === "unknown" || del.kind === "unknown") return { ...DEFAULT_DIFF_BG };
 
-		let addBase = { r: 0, g: 0, b: 0 };
-		let delBase = addBase;
-		let bgBase = "\x1b[49m"; // BG_DEFAULT
+		let addBase: RGB = { r: 0, g: 0, b: 0 };
+		let delBase: RGB = addBase;
+		let bgBase = BG_DEFAULT; // no base color: the terminal's own
 
 		if (theme.getBgAnsi) {
-			try {
-				const successBgAnsi = theme.getBgAnsi("toolSuccessBg");
-				const successParsed = parseAnsiRgb(successBgAnsi);
-				if (successParsed) {
-					addBase = successParsed;
-					delBase = successParsed;
-					bgBase = successBgAnsi;
-				}
-			} catch { /* no toolSuccessBg */ }
-
-			try {
-				const errorParsed = parseAnsiRgb(theme.getBgAnsi("toolErrorBg"));
-				if (errorParsed) delBase = errorParsed;
-			} catch { /* no toolErrorBg */ }
+			const success = readThemeToken(() => theme.getBgAnsi("toolSuccessBg"));
+			// A terminal-default panel background is *no base color*: leave the
+			// mix at its neutral start rather than inventing one.
+			if (success.kind === "color") {
+				addBase = success.rgb;
+				delBase = success.rgb;
+				bgBase = success.ansi;
+			}
+			const error = readThemeToken(() => theme.getBgAnsi("toolErrorBg"));
+			if (error.kind === "color") delBase = error.rgb;
 		}
 
-		const rst = bgBase === "\x1b[49m" ? "\x1b[0m" : `\x1b[0m${bgBase}`;
+		// A side whose accent token is terminal default gets no background at
+		// all — used to be the hardcoded `DEFAULT_DIFF_BG` slab, which is why a
+		// palette terminal showed fixed dark green/red whatever the theme said.
+		const tint = (base: RGB, accent: TokenColor, intensity: number): string =>
+			accent.kind === "color" ? mixBg(base, accent.rgb, intensity) : BG_DEFAULT;
+
+		const rst = bgBase === BG_DEFAULT ? "\x1b[0m" : `\x1b[0m${bgBase}`;
 		return {
-			bgAdd: mixBg(addBase, addRgb, 0.08),
-			bgDel: mixBg(delBase, delRgb, 0.1),
-			bgAddW: mixBg(addBase, addRgb, 0.2),
-			bgDelW: mixBg(delBase, delRgb, 0.22),
-			bgGutterAdd: mixBg(addBase, addRgb, 0.05),
-			bgGutterDel: mixBg(delBase, delRgb, 0.06),
+			bgAdd: tint(addBase, add, 0.08),
+			bgDel: tint(delBase, del, 0.1),
+			bgAddW: tint(addBase, add, 0.2),
+			bgDelW: tint(delBase, del, 0.22),
+			bgGutterAdd: tint(addBase, add, 0.05),
+			bgGutterDel: tint(delBase, del, 0.06),
 			bgEmpty: bgBase,
 			bgBase,
 			rst,

package/src/default-export.test.ts

@@ -2,12 +2,13 @@ import { describe, expect, it, vi } from "vitest";
 import defaultExport from "./index.js";
 
 describe("diff default export (standalone factory)", () => {
-	it("is a function that registers diff tools on session_start with a per-session theme", () => {
+	it("installs the diff rows once on session_start, without registering a tool", () => {
 		expect(typeof defaultExport).toBe("function");
 
 		const on = vi.fn();
 		const registerTool = vi.fn();
-		const pi = { on, registerTool } as any;
+		const registerToolRenderer = vi.fn();
+		const pi = { on, registerTool, registerToolRenderer } as any;
 
 		defaultExport(pi);
 
@@ -15,10 +16,19 @@ describe("diff default export (standalone factory)", () => {
 		expect(typeof startHandler).toBe("function");
 
 		// Mirror of meta's wiring: registerDiffTools(pi, getTheme, readConfig)
-		// runs per session with the session's ctx.theme.
+		// runs per session with the session's ctx.theme. Twice, to stand in for a
+		// `/reload` in the same process.
+		startHandler!({}, { ui: { theme: {} } });
 		startHandler!({}, { ui: { theme: {} } });
 
-		// write/edit tool overrides registered when the SDK loaded
-		expect(registerTool).toHaveBeenCalled();
+		// Nothing is taken over: pi's own `edit`/`write` stay registered, and the
+		// Archimedes rows come from renderer resolution (ADR 0029).
+		expect(registerTool).not.toHaveBeenCalled();
+		// One resolver per tool, and no duplicate stacked by the second session:
+		// pi keeps a list of resolvers and handlers per extension.
+		expect(registerToolRenderer).toHaveBeenCalledTimes(2);
+		const events = on.mock.calls.map((c: Array<unknown>) => c[0]);
+		expect(events.filter((e) => e === "tool_result")).toHaveLength(2); // edit + write
+		expect(events.filter((e) => e === "tool_call")).toHaveLength(1); // write only
 	});
-});
+});