@prometheus-ai/agent 0.5.3 → 0.5.8

package/src/modes/theme/theme.ts

@@ -9,11 +9,11 @@ import {
 	highlightCode as nativeHighlightCode,
 	supportsLanguage as nativeSupportsLanguage,
 } from "@prometheus-ai/natives";
-import type { EditorTheme, MarkdownTheme, SelectListTheme, SymbolTheme } from "@prometheus-ai/tui";
+import type { EditorTheme, MarkdownTheme, SelectListTheme, SettingsListTheme, SymbolTheme } from "@prometheus-ai/tui";
 import { adjustHsv, colorLuma, getCustomThemesDir, isEnoent, logger, relativeLuminance } from "@prometheus-ai/utils";
 import chalk from "chalk";
 import { LRUCache } from "lru-cache/raw";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 // Embed theme JSON files at build time
 import darkThemeJson from "./dark.json" with { type: "json" };
 import { defaultThemes } from "./defaults";
@@ -43,6 +43,7 @@ export type SymbolKey =
 	| "status.running"
 	| "status.shadowed"
 	| "status.aborted"
+	| "status.done"
 	// Navigation
 	| "nav.cursor"
 	| "nav.selected"
@@ -95,6 +96,7 @@ export type SymbolKey =
 	| "icon.pause"
 	| "icon.loop"
 	| "icon.folder"
+	| "icon.search"
 	| "icon.scratchFolder"
 	| "icon.file"
 	| "icon.git"
@@ -105,7 +107,9 @@ export type SymbolKey =
 	| "icon.cost"
 	| "icon.time"
 	| "icon.prometheus"
+	| "icon.ghost"
 	| "icon.agents"
+	| "icon.job"
 	| "icon.cache"
 	| "icon.input"
 	| "icon.output"
@@ -127,6 +131,8 @@ export type SymbolKey =
 	| "icon.extensionInstruction"
 	// STT
 	| "icon.mic"
+	// Compaction divider
+	| "icon.camera"
 	// Thinking Levels
 	| "thinking.minimal"
 	| "thinking.low"
@@ -192,12 +198,35 @@ export type SymbolKey =
 	| "tab.model"
 	| "tab.interaction"
 	| "tab.context"
-	| "tab.editing"
+	| "tab.files"
+	| "tab.shell"
 	| "tab.tools"
 	| "tab.memory"
 	| "tab.tasks"
 	| "tab.providers"
-	| "tab.channels";
+	// Tool identity icons
+	| "tool.write"
+	| "tool.edit"
+	| "tool.bash"
+	| "tool.ssh"
+	| "tool.lsp"
+	| "tool.gh"
+	| "tool.webSearch"
+	| "tool.exa"
+	| "tool.browser"
+	| "tool.eval"
+	| "tool.debug"
+	| "tool.mcp"
+	| "tool.job"
+	| "tool.task"
+	| "tool.todo"
+	| "tool.memory"
+	| "tool.ask"
+	| "tool.resolve"
+	| "tool.review"
+	| "tool.inspectImage"
+	| "tool.goal"
+	| "tool.irc";
 
 type SymbolMap = Record<SymbolKey, string>;
 
@@ -213,6 +242,7 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	"status.running": "⟳",
 	"status.shadowed": "◌",
 	"status.aborted": "⏹",
+	"status.done": "•",
 	// Navigation
 	"nav.cursor": "❯",
 	"nav.selected": "➤",
@@ -265,6 +295,7 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	"icon.pause": "⏸",
 	"icon.loop": "↻",
 	"icon.folder": "📁",
+	"icon.search": "🔍",
 	"icon.scratchFolder": "🗑",
 	"icon.file": "📄",
 	"icon.git": "⎇",
@@ -274,8 +305,10 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	"icon.context": "◫",
 	"icon.cost": "💲",
 	"icon.time": "⏱",
-	"icon.prometheus": "P",
+	"icon.prometheus": "π",
+	"icon.ghost": "👻",
 	"icon.agents": "👥",
+	"icon.job": "⚙",
 	"icon.cache": "💾",
 	"icon.input": "⤵",
 	"icon.output": "⤴",
@@ -297,13 +330,15 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	"icon.extensionInstruction": "📘",
 	// STT
 	"icon.mic": "🎤",
+	// Compaction divider
+	"icon.camera": "📷",
 	// Thinking levels
 	"thinking.minimal": "◔ min",
 	"thinking.low": "◑ low",
 	"thinking.medium": "◒ med",
 	"thinking.high": "◕ high",
 	"thinking.xhigh": "◉ xhigh",
-	"thinking.autoPending": "▣?",
+	"thinking.autoPending": "⟳",
 	// Checkboxes
 	"checkbox.checked": "☑",
 	"checkbox.unchecked": "☐",
@@ -362,12 +397,35 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	"tab.model": "🤖",
 	"tab.interaction": "⌨",
 	"tab.context": "📋",
-	"tab.editing": "💻",
+	"tab.files": "📁",
+	"tab.shell": "💻",
 	"tab.tools": "🔧",
 	"tab.memory": "🧠",
 	"tab.tasks": "📦",
 	"tab.providers": "🌐",
-	"tab.channels": "💬",
+	// Tool identity icons (per-tool signature glyph on the success header)
+	"tool.write": "✎",
+	"tool.edit": "✎",
+	"tool.bash": "❯",
+	"tool.ssh": "⇄",
+	"tool.lsp": "💡",
+	"tool.gh": "⎇",
+	"tool.webSearch": "⌕",
+	"tool.exa": "🔭",
+	"tool.browser": "🌐",
+	"tool.eval": "▶",
+	"tool.debug": "🐞",
+	"tool.mcp": "🔌",
+	"tool.job": "⚙",
+	"tool.task": "⇶",
+	"tool.todo": "☑",
+	"tool.memory": "🧠",
+	"tool.ask": "?",
+	"tool.resolve": "✓",
+	"tool.review": "◉",
+	"tool.inspectImage": "🖼",
+	"tool.goal": "◎",
+	"tool.irc": "✉",
 };
 
 const NERD_SYMBOLS: SymbolMap = {
@@ -392,6 +450,8 @@ const NERD_SYMBOLS: SymbolMap = {
 	"status.shadowed": "◐",
 	// pick:  | alt:  
 	"status.aborted": "\uf04d",
+	// pick: • | alt: ● ·
+	"status.done": "•",
 	// Navigation
 	// pick:  | alt:  
 	"nav.cursor": "\uf054",
@@ -490,6 +550,7 @@ const NERD_SYMBOLS: SymbolMap = {
 	"icon.loop": "\uf021",
 	// pick:  | alt:  
 	"icon.folder": "\uf115",
+	"icon.search": "\uf002",
 	// pick:  | alt:
 	"icon.scratchFolder": "\uf014",
 	// pick:  | alt:  
@@ -508,10 +569,14 @@ const NERD_SYMBOLS: SymbolMap = {
 	"icon.cost": "\uf155",
 	// pick:  | alt: ◷ ◴
 	"icon.time": "\uf017",
-	// pick:  | alt: P
+	// pick:  | alt: π ∏ ∑
 	"icon.prometheus": "\ue22c",
+	// pick: 󰊠 (nf-md-ghost) | alt: 👻
+	"icon.ghost": "\u{f02a0}",
 	// pick:  | alt: 
 	"icon.agents": "\uf0c0",
+	// pick:  (nf-fa-gear) | alt:  ⚙
+	"icon.job": "\uf013",
 	// pick:  | alt:  
 	"icon.cache": "\uf1c0",
 	// pick:  | alt:  →
@@ -550,6 +615,8 @@ const NERD_SYMBOLS: SymbolMap = {
 	"icon.extensionInstruction": "\uf02d",
 	// STT - fa-microphone
 	"icon.mic": "\uf130",
+	// Compaction divider - fa-camera-retro
+	"icon.camera": "\uf083",
 	// Thinking Levels - emoji labels
 	// pick: 🤨 min | alt:  min  min
 	"thinking.minimal": "\u{F0E7} min",
@@ -561,8 +628,8 @@ const NERD_SYMBOLS: SymbolMap = {
 	"thinking.high": "\u{F111} high",
 	// pick: 🧠 xhi | alt:  xhi  xhi
 	"thinking.xhigh": "\u{F06D} xhi",
-	// pick: 󰞋 (nf-md-help_box) | alt:  [?]
-	"thinking.autoPending": "\u{f078b}",
+	// pick:  (fa-circle-o-notch) | alt: 󰂼 (nf-md-cached) ⟳
+	"thinking.autoPending": "\uf1ce",
 	// Checkboxes
 	// pick:  | alt:  
 	"checkbox.checked": "\uf14a",
@@ -632,12 +699,35 @@ const NERD_SYMBOLS: SymbolMap = {
 	"tab.model": "󰚩",
 	"tab.interaction": "󰌌",
 	"tab.context": "󰘸",
-	"tab.editing": "",
+	"tab.files": "󰈔",
+	"tab.shell": "󰆍",
 	"tab.tools": "󰠭",
 	"tab.memory": "󰧑",
 	"tab.tasks": "󰐱",
 	"tab.providers": "󰖟",
-	"tab.channels": "󰍩",
+	// Tool identity icons (per-tool signature glyph on the success header)
+	"tool.write": "\uEA7F",
+	"tool.edit": "\uEA73",
+	"tool.bash": "\uEBCA",
+	"tool.ssh": "\uEB3A",
+	"tool.lsp": "\uEA61",
+	"tool.gh": "\uEA84",
+	"tool.webSearch": "\uEB01",
+	"tool.exa": "\uEB68",
+	"tool.browser": "\uEAAE",
+	"tool.eval": "\uEBAF",
+	"tool.debug": "\uEAD8",
+	"tool.mcp": "\uEB2D",
+	"tool.job": "\uEBA2",
+	"tool.task": "\uf4a0",
+	"tool.todo": "\uEAB3",
+	"tool.memory": "\uEACE",
+	"tool.ask": "\uEAC7",
+	"tool.resolve": "\uEBB1",
+	"tool.review": "\uEA70",
+	"tool.inspectImage": "\uEAEA",
+	"tool.goal": "\uEBF8",
+	"tool.irc": "\uF086",
 };
 
 const ASCII_SYMBOLS: SymbolMap = {
@@ -652,6 +742,7 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"status.running": "[~]",
 	"status.shadowed": "[/]",
 	"status.aborted": "[-]",
+	"status.done": "*",
 	// Navigation
 	"nav.cursor": ">",
 	"nav.selected": "->",
@@ -704,6 +795,7 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"icon.pause": "||",
 	"icon.loop": "loop",
 	"icon.folder": "[D]",
+	"icon.search": "[/]",
 	"icon.scratchFolder": "[T]",
 	"icon.file": "[F]",
 	"icon.git": "git:",
@@ -713,8 +805,10 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"icon.context": "ctx:",
 	"icon.cost": "$",
 	"icon.time": "t:",
-	"icon.prometheus": "P",
+	"icon.prometheus": "pi",
+	"icon.ghost": "@",
 	"icon.agents": "AG",
+	"icon.job": "bg",
 	"icon.cache": "cache",
 	"icon.input": "in:",
 	"icon.output": "out:",
@@ -736,13 +830,15 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"icon.extensionInstruction": "IN",
 	// STT
 	"icon.mic": "MIC",
+	// Compaction divider
+	"icon.camera": "[o]",
 	// Thinking Levels
 	"thinking.minimal": "[min]",
 	"thinking.low": "[low]",
 	"thinking.medium": "[med]",
 	"thinking.high": "[high]",
 	"thinking.xhigh": "[xhi]",
-	"thinking.autoPending": "[?]",
+	"thinking.autoPending": "[~]",
 	// Checkboxes
 	"checkbox.checked": "[x]",
 	"checkbox.unchecked": "[ ]",
@@ -799,12 +895,35 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"tab.model": "[M]",
 	"tab.interaction": "[I]",
 	"tab.context": "[X]",
-	"tab.editing": "[E]",
+	"tab.files": "[F]",
+	"tab.shell": "[S]",
 	"tab.tools": "[T]",
 	"tab.memory": "[Y]",
 	"tab.tasks": "[K]",
 	"tab.providers": "[P]",
-	"tab.channels": "[C]",
+	// Tool identity icons (per-tool signature glyph on the success header)
+	"tool.write": "+f",
+	"tool.edit": "~",
+	"tool.bash": "$",
+	"tool.ssh": "ssh",
+	"tool.lsp": "lsp",
+	"tool.gh": "gh",
+	"tool.webSearch": "web",
+	"tool.exa": "exa",
+	"tool.browser": "[w]",
+	"tool.eval": ">_",
+	"tool.debug": "dbg",
+	"tool.mcp": "<>",
+	"tool.job": "job",
+	"tool.task": ">>>",
+	"tool.todo": "[x]",
+	"tool.memory": "mem",
+	"tool.ask": "[?]",
+	"tool.resolve": "[v]",
+	"tool.review": "rev",
+	"tool.inspectImage": "[i]",
+	"tool.goal": "(o)",
+	"tool.irc": "irc",
 };
 
 const SYMBOL_PRESETS: Record<SymbolPreset, SymbolMap> = {
@@ -1290,9 +1409,23 @@ const langMap: Record<string, SymbolKey> = {
 	bin: "lang.binary",
 };
 
+/**
+ * Resolve a theme color value (hex string or 256-color index) to a CSS hex string.
+ * Empty string represents the default terminal color.
+ */
+function resolveToHex(value: string | number, isLight: boolean): string {
+	if (typeof value === "number") return ansi256ToHex(value);
+	if (value === "") return isLight ? "#000000" : "#e5e5e7";
+	return value;
+}
+
 export class Theme {
 	#fgColors: Record<ThemeColor, string>;
 	#bgColors: Record<ThemeBg, string>;
+	/** Resolved hex strings for foreground colors — populated at construction. */
+	readonly #hexFgColors: Record<ThemeColor, string>;
+	/** Resolved hex strings for background colors — populated at construction. */
+	readonly #hexBgColors: Record<ThemeBg, string>;
 	#symbols: SymbolMap;
 	#spinnerFramesOverrides: Partial<Record<SpinnerType, string[]>>;
 	/**
@@ -1305,7 +1438,6 @@ export class Theme {
 	readonly statusLineLuminance: number | undefined;
 	/** WCAG relative luminance of the status-line background — basis for accent contrast. */
 	readonly #statusLineContrastLuminance: number | undefined;
-
 	constructor(
 		fgColors: Record<ThemeColor, string | number>,
 		bgColors: Record<ThemeBg, string | number>,
@@ -1316,13 +1448,19 @@ export class Theme {
 	) {
 		this.statusLineLuminance = colorLuma(bgColors.statusLineBg);
 		this.#statusLineContrastLuminance = relativeLuminance(bgColors.statusLineBg);
+		const slIsLight = this.statusLineLuminance !== undefined && this.statusLineLuminance > 0.5;
+
 		this.#fgColors = {} as Record<ThemeColor, string>;
+		this.#hexFgColors = {} as Record<ThemeColor, string>;
 		for (const [key, value] of Object.entries(fgColors) as [ThemeColor, string | number][]) {
 			this.#fgColors[key] = fgAnsi(value, mode);
+			this.#hexFgColors[key] = resolveToHex(value, slIsLight);
 		}
 		this.#bgColors = {} as Record<ThemeBg, string>;
+		this.#hexBgColors = {} as Record<ThemeBg, string>;
 		for (const [key, value] of Object.entries(bgColors) as [ThemeBg, string | number][]) {
 			this.#bgColors[key] = bgAnsi(value, mode);
+			this.#hexBgColors[key] = resolveToHex(value, slIsLight);
 		}
 		// Build symbol map from preset + overrides
 		const baseSymbols = SYMBOL_PRESETS[symbolPreset];
@@ -1350,6 +1488,70 @@ export class Theme {
 		return this.isLight ? this.#statusLineContrastLuminance : undefined;
 	}
 
+	/**
+	 * Get the resolved CSS hex string for a foreground theme color.
+	 */
+	getColorHex(color: ThemeColor): string {
+		const hex = this.#hexFgColors[color];
+		if (hex === undefined) throw new Error(`Unknown theme color: ${color}`);
+		return hex || (this.isLight ? "#000000" : "#e5e5e7");
+	}
+
+	/**
+	 * Get all foreground and background theme colors as CSS hex strings.
+	 * Skips colors resolved to the default terminal color (unstyled).
+	 */
+	getAllThemeColorHexes(): string[] {
+		const hexes: string[] = [];
+		for (const hex of Object.values(this.#hexFgColors)) {
+			if (hex) hexes.push(hex);
+		}
+		for (const hex of Object.values(this.#hexBgColors)) {
+			if (hex) hexes.push(hex);
+		}
+		return hexes;
+	}
+
+	/**
+	 * Get the most visually dominant theme colors as CSS hex strings — accent,
+	 * border, success, error, warning, heading, link, diff markers, etc.
+	 * These are the colors the session accent could visually clash with.
+	 * Skips colors resolved to the default terminal color (unstyled).
+	 */
+	getMajorThemeColorHexes(): string[] {
+		const majors: ThemeColor[] = [
+			"accent",
+			"border",
+			"borderAccent",
+			"borderMuted",
+			"success",
+			"error",
+			"warning",
+			"mdHeading",
+			"mdLink",
+			"mdCode",
+			"mdCodeBlock",
+			"mdQuoteBorder",
+			"mdListBullet",
+			"toolDiffAdded",
+			"toolDiffRemoved",
+			"customMessageLabel",
+			"thinkingText",
+		];
+		const hexes: string[] = [];
+		for (const key of majors) {
+			const hex = this.#hexFgColors[key];
+			if (hex) hexes.push(hex);
+		}
+		return hexes;
+	}
+	/**
+	 * Get the resolved CSS hex string for the theme's accent color.
+	 */
+	getAccentColorHex(): string {
+		return this.getColorHex("accent");
+	}
+
 	fg(color: ThemeColor, text: string): string {
 		const ansi = this.#fgColors[color];
 		if (!ansi) throw new Error(`Unknown theme color: ${color}`);
@@ -1485,6 +1687,7 @@ export class Theme {
 			running: this.#symbols["status.running"],
 			shadowed: this.#symbols["status.shadowed"],
 			aborted: this.#symbols["status.aborted"],
+			done: this.#symbols["status.done"],
 		};
 	}
 
@@ -1570,8 +1773,10 @@ export class Theme {
 			context: this.#symbols["icon.context"],
 			cost: this.#symbols["icon.cost"],
 			time: this.#symbols["icon.time"],
-			prometheus: this.#symbols["icon.prometheus"],
+			pi: this.#symbols["icon.prometheus"],
+			ghost: this.#symbols["icon.ghost"],
 			agents: this.#symbols["icon.agents"],
+			job: this.#symbols["icon.job"],
 			cache: this.#symbols["icon.cache"],
 			input: this.#symbols["icon.input"],
 			output: this.#symbols["icon.output"],
@@ -1592,6 +1797,7 @@ export class Theme {
 			extensionContextFile: this.#symbols["icon.extensionContextFile"],
 			extensionInstruction: this.#symbols["icon.extensionInstruction"],
 			mic: this.#symbols["icon.mic"],
+			camera: this.#symbols["icon.camera"],
 		};
 	}
 
@@ -1892,6 +2098,11 @@ var currentThemeName: string | undefined;
 export function getCurrentThemeName(): string | undefined {
 	return currentThemeName;
 }
+
+/** Returns unstyled `text` before `initTheme()` assigns the global theme; use only for early-render paths. */
+export function fgOrPlain(color: ThemeColor, text: string, styledText: string = text): string {
+	return typeof theme === "undefined" ? text : theme.fg(color, styledText);
+}
 var currentSymbolPresetOverride: SymbolPreset | undefined;
 var currentColorBlindMode: boolean = false;
 var themeWatcher: fs.FSWatcher | undefined;
@@ -1902,6 +2113,7 @@ var autoDarkTheme: string = "dark";
 var autoLightTheme: string = "light";
 var onThemeChangeCallback: (() => void) | undefined;
 var themeLoadRequestId: number = 0;
+let themeEpoch = 0;
 
 function getCurrentThemeOptions(): CreateThemeOptions {
 	return {
@@ -1954,9 +2166,7 @@ export async function setTheme(
 		if (enableWatcher) {
 			await startThemeWatcher();
 		}
-		if (onThemeChangeCallback) {
-			onThemeChangeCallback();
-		}
+		notifyThemeChange();
 		return { success: true };
 	} catch (error) {
 		if (requestId !== themeLoadRequestId) {
@@ -1965,6 +2175,10 @@ export async function setTheme(
 		// Theme is invalid - fall back to dark theme
 		currentThemeName = "dark";
 		theme = await loadTheme("dark", getCurrentThemeOptions());
+		// The active theme just changed to the fallback — bump the epoch so memoized
+		// renderers (e.g. ToolExecutionComponent) re-shape with the fallback colors
+		// instead of holding the failed theme's stale styling.
+		notifyThemeChange();
 		// Don't start watcher for fallback theme
 		return {
 			success: false,
@@ -1981,9 +2195,7 @@ export async function previewTheme(name: string): Promise<{ success: boolean; er
 			return { success: false, error: "Theme preview superseded by a newer request" };
 		}
 		theme = loadedTheme;
-		if (onThemeChangeCallback) {
-			onThemeChangeCallback();
-		}
+		notifyThemeChange();
 		return { success: true };
 	} catch (error) {
 		if (requestId !== themeLoadRequestId) {
@@ -2030,9 +2242,7 @@ export function setThemeInstance(themeInstance: Theme): void {
 	theme = themeInstance;
 	currentThemeName = "<in-memory>";
 	stopThemeWatcher();
-	if (onThemeChangeCallback) {
-		onThemeChangeCallback();
-	}
+	notifyThemeChange();
 }
 
 /**
@@ -2053,7 +2263,7 @@ export async function setSymbolPreset(preset: SymbolPreset): Promise<void> {
 		theme = await loadTheme("dark", getCurrentThemeOptions());
 		if (requestId !== themeLoadRequestId) return;
 	}
-	onThemeChangeCallback?.();
+	notifyThemeChange();
 }
 
 /**
@@ -2082,7 +2292,7 @@ export async function setColorBlindMode(enabled: boolean): Promise<void> {
 		theme = await loadTheme("dark", getCurrentThemeOptions());
 		if (requestId !== themeLoadRequestId) return;
 	}
-	onThemeChangeCallback?.();
+	notifyThemeChange();
 }
 
 /**
@@ -2096,6 +2306,23 @@ export function onThemeChange(callback: () => void): void {
 	onThemeChangeCallback = callback;
 }
 
+/**
+ * Monotonic counter bumped on any theme-affecting change that should invalidate
+ * cached renders: theme swaps and reloads (including the invalid-theme dark
+ * fallback), theme previews, symbol-preset changes, and color-blind-mode
+ * changes — everything that routes through {@link notifyThemeChange}. Consumers
+ * key cached renders on it so the next render re-shapes their output.
+ */
+export function getThemeEpoch(): number {
+	return themeEpoch;
+}
+
+/** Bump the theme epoch and notify the registered theme-change listener. */
+function notifyThemeChange(): void {
+	themeEpoch++;
+	onThemeChangeCallback?.();
+}
+
 /**
  * Get available symbol presets.
  */
@@ -2148,9 +2375,7 @@ async function startThemeWatcher(): Promise<void> {
 			loadTheme(watchedThemeName, getCurrentThemeOptions())
 				.then(loadedTheme => {
 					theme = loadedTheme;
-					if (onThemeChangeCallback) {
-						onThemeChangeCallback();
-					}
+					notifyThemeChange();
 				})
 				.catch(() => {
 					// Ignore errors (file might be in invalid state while being edited)
@@ -2190,9 +2415,7 @@ function reevaluateAutoTheme(debugLabel: string): void {
 	loadTheme(resolved, getCurrentThemeOptions())
 		.then(loadedTheme => {
 			theme = loadedTheme;
-			if (onThemeChangeCallback) {
-				onThemeChangeCallback();
-			}
+			notifyThemeChange();
 		})
 		.catch(err => {
 			logger.debug(`Theme switch on ${debugLabel} failed`, { error: String(err) });
@@ -2314,18 +2537,74 @@ function ansi256ToHex(index: number): string {
 	return `#${grayHex}${grayHex}${grayHex}`;
 }
 
+/**
+ * Classify a parsed theme JSON as light/dark by the perceived luminance of its
+ * status-line background. Mirrors {@link Theme.isLight} so the synchronous
+ * helpers below stay in lockstep with the runtime classifier — see the comment
+ * on `Theme.statusLineLuminance` for why `statusLineBg` is the source of truth
+ * (themes like `porcelain` style a dark chat bubble on an otherwise-light
+ * theme, so `userMessageBg` is unreliable).
+ */
+function isLightThemeJson(themeJson: ThemeJson): boolean {
+	try {
+		const resolved = resolveVarRefs(themeJson.colors.statusLineBg, themeJson.vars ?? {});
+		const luminance = colorLuma(resolved);
+		return luminance !== undefined && luminance > 0.5;
+	} catch {
+		return false;
+	}
+}
+
+function getHtmlDefaultTextForSurface(surface: string | number | undefined): string {
+	const luminance = surface === undefined ? undefined : colorLuma(surface);
+	return luminance !== undefined && luminance > 0.5 ? "#000000" : "#e5e5e7";
+}
+
+function resolveThemeExportColors(themeJson: ThemeJson): {
+	pageBg?: string;
+	cardBg?: string;
+	infoBg?: string;
+} {
+	const exportSection = themeJson.export;
+	if (!exportSection) return {};
+
+	const vars = themeJson.vars ?? {};
+	const resolve = (value: string | number | undefined): string | undefined => {
+		if (value === undefined) return undefined;
+		if (typeof value === "number") return ansi256ToHex(value);
+		if (value === "" || value.startsWith("#")) return value;
+		const varName = value.startsWith("$") ? value.slice(1) : value;
+		if (varName in vars) {
+			const resolved = resolveVarRefs(varName, vars);
+			return typeof resolved === "number" ? ansi256ToHex(resolved) : resolved;
+		}
+		return value;
+	};
+
+	return {
+		pageBg: resolve(exportSection.pageBg),
+		cardBg: resolve(exportSection.cardBg),
+		infoBg: resolve(exportSection.infoBg),
+	};
+}
+
 /**
  * Get resolved theme colors as CSS-compatible hex strings.
  * Used by HTML export to generate CSS custom properties.
  */
 export async function getResolvedThemeColors(themeName?: string): Promise<Record<string, string>> {
 	const name = themeName ?? getDefaultTheme();
-	const isLight = name === "light";
 	const themeJson = await loadThemeJson(name);
+	const exportColors = resolveThemeExportColors(themeJson);
 	const resolved = resolveThemeColors(themeJson.colors, themeJson.vars);
 
-	// Default text color for empty values (terminal uses default fg color)
-	const defaultText = isLight ? "#000000" : "#e5e5e7";
+	// Empty foreground tokens use the terminal default color. In HTML export,
+	// that default must contrast the export surface, not the TUI status line:
+	// custom light themes can still export dark transcript cards when they omit
+	// `export`, because generateThemeVars derives those cards from userMessageBg.
+	const defaultText = getHtmlDefaultTextForSurface(
+		exportColors.cardBg ?? exportColors.pageBg ?? resolved.userMessageBg,
+	);
 
 	const cssColors: Record<string, string> = {};
 	for (const [key, value] of Object.entries(resolved)) {
@@ -2342,8 +2621,9 @@ export async function getResolvedThemeColors(themeName?: string): Promise<Record
 }
 
 /**
- * Check if a theme is a "light" theme by analyzing its background color luminance.
- * Loads theme JSON synchronously (built-in or custom file) and resolves userMessageBg.
+ * Check if a theme is a "light" theme by analyzing its status-line background
+ * luminance. Loads theme JSON synchronously (built-in or custom file on disk)
+ * for callers in synchronous flows (settings migration, setup wizard).
  */
 export function isLightTheme(themeName?: string): boolean {
 	const name = themeName ?? "dark";
@@ -2360,13 +2640,7 @@ export function isLightTheme(themeName?: string): boolean {
 			return false;
 		}
 	}
-	try {
-		const resolved = resolveVarRefs(themeJson.colors.userMessageBg, themeJson.vars ?? {});
-		const luminance = colorLuma(resolved);
-		return luminance !== undefined && luminance > 0.5;
-	} catch {
-		return false;
-	}
+	return isLightThemeJson(themeJson);
 }
 
 /**
@@ -2381,27 +2655,7 @@ export async function getThemeExportColors(themeName?: string): Promise<{
 	const name = themeName ?? getDefaultTheme();
 	try {
 		const themeJson = await loadThemeJson(name);
-		const exportSection = themeJson.export;
-		if (!exportSection) return {};
-
-		const vars = themeJson.vars ?? {};
-		const resolve = (value: string | number | undefined): string | undefined => {
-			if (value === undefined) return undefined;
-			if (typeof value === "number") return ansi256ToHex(value);
-			if (value === "" || value.startsWith("#")) return value;
-			const varName = value.startsWith("$") ? value.slice(1) : value;
-			if (varName in vars) {
-				const resolved = resolveVarRefs(varName, vars);
-				return typeof resolved === "number" ? ansi256ToHex(resolved) : resolved;
-			}
-			return value;
-		};
-
-		return {
-			pageBg: resolve(exportSection.pageBg),
-			cardBg: resolve(exportSection.cardBg),
-			infoBg: resolve(exportSection.infoBg),
-		};
+		return resolveThemeExportColors(themeJson);
 	} catch {
 		return {};
 	}
@@ -2443,19 +2697,19 @@ function getHighlightColors(t: Theme): NativeHighlightColors {
  * switch (which always reassigns `theme`) must invalidate every entry.
  *
  * Why this exists: animated tool blocks (eval/bash) repaint their box on every
- * ~16ms border-shimmer frame, and markdown re-lexes on every streamed delta.
- * Without memoization each frame re-tokenizes an unchanged code body through the
- * Rust FFI — ~26ms for 100 lines, ~40ms for 150 — overrunning the 16ms frame
- * budget and starving the spinner/render timers (the "TUI freeze").
+ * ~33ms border-shimmer frame, and markdown re-lexes on every streamed delta.
+ * Without memoization each frame can re-tokenize an unchanged code body through
+ * the Rust FFI — ~26ms for 100 lines, ~40ms for 150 — consuming or overrunning
+ * the 33ms frame budget and starving the spinner/render timers (the "TUI freeze").
  */
 const HIGHLIGHT_CACHE_MAX = 256;
 const highlightCache = new LRUCache<string, string>({ max: HIGHLIGHT_CACHE_MAX });
 let highlightCacheTheme: Theme | undefined;
 
-function highlightCached(code: string, validLang: string | undefined): string | null {
-	if (highlightCacheTheme !== theme) {
+function highlightCached(code: string, validLang: string | undefined, highlightTheme: Theme): string | null {
+	if (highlightCacheTheme !== highlightTheme) {
 		highlightCache.clear();
-		highlightCacheTheme = theme;
+		highlightCacheTheme = highlightTheme;
 	}
 	const key = `${validLang ?? ""}\x00${code}`;
 	const hit = highlightCache.get(key);
@@ -2464,7 +2718,7 @@ function highlightCached(code: string, validLang: string | undefined): string |
 	}
 	let highlighted: string;
 	try {
-		highlighted = nativeHighlightCode(code, validLang, getHighlightColors(theme));
+		highlighted = nativeHighlightCode(code, validLang, getHighlightColors(highlightTheme));
 	} catch {
 		return null;
 	}
@@ -2476,9 +2730,9 @@ function highlightCached(code: string, validLang: string | undefined): string |
  * Highlight code with syntax coloring based on file extension or language.
  * Returns array of highlighted lines.
  */
-export function highlightCode(code: string, lang?: string): string[] {
+export function highlightCode(code: string, lang?: string, highlightTheme: Theme = theme): string[] {
 	const validLang = lang && nativeSupportsLanguage(lang) ? lang : undefined;
-	const highlighted = highlightCached(code, validLang);
+	const highlighted = highlightCached(code, validLang, highlightTheme);
 	// Always return a fresh array: callers (e.g. renderCodeCell) push extra lines
 	// onto the result, which would corrupt the cached string otherwise.
 	return (highlighted ?? code).split("\n");
@@ -2526,7 +2780,7 @@ export function getMarkdownTheme(): MarkdownTheme {
 		resolveMermaidAscii,
 		highlightCode: (code: string, lang?: string): string[] => {
 			const validLang = lang && nativeSupportsLanguage(lang) ? lang : undefined;
-			const highlighted = highlightCached(code, validLang);
+			const highlighted = highlightCached(code, validLang, theme);
 			if (highlighted !== null) return highlighted.split("\n");
 			return code.split("\n").map(line => theme.fg("mdCodeBlock", line));
 		},
@@ -2544,6 +2798,7 @@ export function getSelectListTheme(): SelectListTheme {
 		scrollInfo: (text: string) => theme.fg("muted", text),
 		noMatch: (text: string) => theme.fg("muted", text),
 		symbols: getSymbolTheme(),
+		hovered: (text: string) => theme.bg("selectedBg", text),
 	};
 }
 
@@ -2556,14 +2811,19 @@ export function getEditorTheme(): EditorTheme {
 	};
 }
 
-export function getSettingsListTheme(): import("@prometheus-ai/tui").SettingsListTheme {
+export function getSettingsListTheme(): SettingsListTheme {
 	return {
 		label: (text: string, selected: boolean, changed: boolean) =>
 			changed ? theme.fg("statusLineGitDirty", text) : selected ? theme.fg("accent", text) : text,
 		value: (text: string, selected: boolean, changed: boolean) =>
-			selected ? theme.fg("accent", text) : changed ? theme.fg("statusLineGitDirty", text) : theme.fg("muted", text),
+			changed ? theme.fg("statusLineGitDirty", text) : selected ? theme.fg("accent", text) : theme.fg("muted", text),
 		description: (text: string) => theme.fg("dim", text),
 		cursor: theme.fg("accent", `${theme.nav.cursor} `),
 		hint: (text: string) => theme.fg("dim", text),
+		heading: (text: string, dimmed: boolean) =>
+			dimmed ? theme.fg("dim", theme.underline(text)) : theme.fg("muted", theme.bold(theme.underline(text))),
+		section: (text: string, active: boolean) =>
+			active ? theme.fg("accent", theme.bold(text)) : theme.fg("muted", text),
+		hovered: (text: string) => theme.bg("selectedBg", text),
 	};
 }