@linxiraos/pi-tui 1.1.26 → 1.2.0

package/src/theme/schema.d.ts

@@ -1,10 +1,19 @@
 import type { SpinnerFramesOverride } from "./symbols";
 export type ColorValue = string | number;
+/**
+ * Tokens a theme is allowed to omit. They resolve to the terminal default
+ * foreground, so `Theme.fg()` stays total for callers that paint a token a theme
+ * never declared (e.g. a `modelTags.<role>.color` reference) while
+ * `Theme.hasColor()` still reports them as unset.
+ */
+export declare const OPTIONAL_THEME_COLOR_RECORD: {
+    assistantMessageText: true;
+};
 export interface ThemeJson {
     $schema?: string;
     name: string;
     vars?: Record<string, ColorValue>;
-    colors: Omit<Record<ThemeColor | ThemeBg, ColorValue>, "thinkingMax"> & {
+    colors: Omit<Record<ThemeColor | ThemeBg, ColorValue>, "thinkingMax" | keyof typeof OPTIONAL_THEME_COLOR_RECORD> & Partial<Record<keyof typeof OPTIONAL_THEME_COLOR_RECORD, ColorValue>> & {
         thinkingMax?: ColorValue;
     };
     export?: {
@@ -36,7 +45,7 @@ export interface ThemeJson {
         spinnerFrames?: SpinnerFramesOverride;
     };
 }
-export type ThemeColor = "accent" | "border" | "borderAccent" | "borderMuted" | "success" | "error" | "warning" | "muted" | "dim" | "text" | "thinkingText" | "userMessageText" | "customMessageText" | "customMessageLabel" | "toolTitle" | "toolOutput" | "mdHeading" | "mdLink" | "mdLinkUrl" | "mdCode" | "mdCodeBlock" | "mdCodeBlockBorder" | "mdQuote" | "mdQuoteBorder" | "mdHr" | "mdListBullet" | "toolDiffAdded" | "toolDiffRemoved" | "toolDiffContext" | "syntaxComment" | "syntaxKeyword" | "syntaxFunction" | "syntaxVariable" | "syntaxString" | "syntaxNumber" | "syntaxType" | "syntaxOperator" | "syntaxPunctuation" | "thinkingOff" | "thinkingMinimal" | "thinkingLow" | "thinkingMedium" | "thinkingHigh" | "thinkingXhigh" | "thinkingMax" | "bashMode" | "pythonMode" | "statusLineSep" | "statusLineModel" | "statusLinePath" | "statusLineGitClean" | "statusLineGitDirty" | "statusLineContext" | "statusLineSpend" | "statusLineStaged" | "statusLineDirty" | "statusLineUntracked" | "statusLineOutput" | "statusLineCost" | "statusLineSubagents";
+export type ThemeColor = "accent" | "border" | "borderAccent" | "borderMuted" | "success" | "error" | "warning" | "muted" | "dim" | "text" | "assistantMessageText" | "thinkingText" | "userMessageText" | "customMessageText" | "customMessageLabel" | "toolTitle" | "toolOutput" | "mdHeading" | "mdLink" | "mdLinkUrl" | "mdCode" | "mdCodeBlock" | "mdCodeBlockBorder" | "mdQuote" | "mdQuoteBorder" | "mdHr" | "mdListBullet" | "toolDiffAdded" | "toolDiffRemoved" | "toolDiffContext" | "syntaxComment" | "syntaxKeyword" | "syntaxFunction" | "syntaxVariable" | "syntaxString" | "syntaxNumber" | "syntaxType" | "syntaxOperator" | "syntaxPunctuation" | "thinkingOff" | "thinkingMinimal" | "thinkingLow" | "thinkingMedium" | "thinkingHigh" | "thinkingXhigh" | "thinkingMax" | "bashMode" | "pythonMode" | "statusLineSep" | "statusLineModel" | "statusLinePath" | "statusLineGitClean" | "statusLineGitDirty" | "statusLineContext" | "statusLineSpend" | "statusLineStaged" | "statusLineDirty" | "statusLineUntracked" | "statusLineOutput" | "statusLineCost" | "statusLineSubagents";
 /** Check if a string is a valid ThemeColor value */
 export declare function isValidThemeColor(color: string): color is ThemeColor;
 export type ThemeBg = "selectedBg" | "userMessageBg" | "customMessageBg" | "toolPendingBg" | "toolSuccessBg" | "toolErrorBg" | "statusLineBg";

package/src/theme/schema.ts

@@ -6,11 +6,22 @@ import type { SpinnerFramesOverride } from "./symbols";
 
 export type ColorValue = string | number;
 
+/**
+ * Tokens a theme is allowed to omit. They resolve to the terminal default
+ * foreground, so `Theme.fg()` stays total for callers that paint a token a theme
+ * never declared (e.g. a `modelTags.<role>.color` reference) while
+ * `Theme.hasColor()` still reports them as unset.
+ */
+export const OPTIONAL_THEME_COLOR_RECORD = {
+	assistantMessageText: true,
+} satisfies Partial<Record<ThemeColor, true>>;
+
 export interface ThemeJson {
 	$schema?: string;
 	name: string;
 	vars?: Record<string, ColorValue>;
-	colors: Omit<Record<ThemeColor | ThemeBg, ColorValue>, "thinkingMax"> & { thinkingMax?: ColorValue };
+	colors: Omit<Record<ThemeColor | ThemeBg, ColorValue>, "thinkingMax" | keyof typeof OPTIONAL_THEME_COLOR_RECORD> &
+		Partial<Record<keyof typeof OPTIONAL_THEME_COLOR_RECORD, ColorValue>> & { thinkingMax?: ColorValue };
 	export?: {
 		pageBg?: ColorValue;
 		cardBg?: ColorValue;
@@ -52,6 +63,7 @@ export type ThemeColor =
 	| "muted"
 	| "dim"
 	| "text"
+	| "assistantMessageText"
 	| "thinkingText"
 	| "userMessageText"
 	| "customMessageText"
@@ -115,6 +127,7 @@ const THEME_COLOR_RECORD = {
 	muted: true,
 	dim: true,
 	text: true,
+	assistantMessageText: true,
 	thinkingText: true,
 	userMessageText: true,
 	customMessageText: true,

package/src/theme/session-color.ts

@@ -1,5 +1,5 @@
 import { TERMINAL } from "../terminal-capabilities";
-import { hexToOklch, oklchCusp, oklchToHex, relativeLuminance } from "@linxiraos/pi-utils";
+import { hexToOklch, hueDistance, oklchCusp, oklchToHex, relativeLuminance } from "@linxiraos/pi-utils";
 
 /**
  * Derive a stable 32-bit hash from a string using djb2.
@@ -49,12 +49,6 @@ const MIN_HUE_DISTANCE = 10;
 /** OKLCH chroma threshold below which hue is meaningless (near-gray). */
 const MIN_CHROMA_FOR_HUE = 0.03;
 
-/** Angular distance between two hue values (0-360). */
-function hueDistance(a: number, b: number): number {
-	const d = Math.abs(a - b);
-	return Math.min(d, 360 - d);
-}
-
 /**
  * Parse OKLCH hue (0-360) from a hex color string.
  * Returns undefined for near-gray colors where hue is not meaningful.

package/src/theme/symbols.d.ts

@@ -2,7 +2,7 @@ export type SymbolPreset = "unicode" | "nerd" | "ascii";
 /**
  * All available symbol keys organized by category.
  */
-export type SymbolKey = "status.success" | "status.error" | "status.warning" | "status.info" | "status.pending" | "status.disabled" | "status.enabled" | "status.running" | "status.shadowed" | "status.aborted" | "status.done" | "nav.cursor" | "nav.selected" | "nav.expand" | "nav.collapse" | "nav.back" | "tree.branch" | "tree.last" | "tree.vertical" | "tree.horizontal" | "tree.hook" | "progress.filled" | "progress.empty" | "context.speculation" | "context.compaction" | "boxRound.topLeft" | "boxRound.topRight" | "boxRound.bottomLeft" | "boxRound.bottomRight" | "boxRound.horizontal" | "boxRound.vertical" | "boxDotted.horizontal" | "boxDotted.vertical" | "boxSharp.topLeft" | "boxSharp.topRight" | "boxSharp.bottomLeft" | "boxSharp.bottomRight" | "boxSharp.horizontal" | "boxSharp.vertical" | "boxSharp.cross" | "boxSharp.teeDown" | "boxSharp.teeUp" | "boxSharp.teeRight" | "boxSharp.teeLeft" | "sep.powerline" | "sep.powerlineThin" | "sep.powerlineLeft" | "sep.powerlineRight" | "sep.powerlineThinLeft" | "sep.powerlineThinRight" | "sep.powerlineCapLeft" | "sep.block" | "sep.space" | "sep.asciiLeft" | "sep.asciiRight" | "sep.dot" | "sep.slash" | "sep.pipe" | "icon.model" | "icon.plan" | "icon.prewalk" | "icon.goal" | "icon.pause" | "icon.loop" | "icon.folder" | "icon.worktree" | "icon.search" | "icon.scratchFolder" | "icon.file" | "icon.git" | "icon.branch" | "icon.pr" | "icon.pin" | "icon.tokens" | "icon.context" | "icon.cost" | "icon.subscription" | "icon.advisor" | "icon.advisorClosed" | "icon.time" | "icon.omp" | "icon.ghost" | "icon.agents" | "icon.job" | "icon.cache" | "icon.cacheMiss" | "icon.input" | "icon.output" | "icon.throughput" | "icon.intelligence" | "icon.host" | "icon.session" | "icon.package" | "icon.warning" | "icon.rewind" | "icon.auto" | "icon.fast" | "icon.extensionSkill" | "icon.extensionTool" | "icon.extensionSlashCommand" | "icon.extensionMcp" | "icon.extensionRule" | "icon.extensionHook" | "icon.extensionPrompt" | "icon.extensionContextFile" | "icon.extensionInstruction" | "icon.vimNormal" | "icon.vimInsert" | "icon.vimVisual" | "icon.vimVisualLine" | "cmd.action" | "cmd.prompt" | "cmd.extension" | "cmd.settings" | "cmd.gear" | "cmd.shield" | "cmd.wave" | "cmd.compass" | "cmd.inbox" | "cmd.swap" | "cmd.expand" | "cmd.computer" | "cmd.eye" | "cmd.todo" | "cmd.stats" | "cmd.news" | "cmd.keyboard" | "cmd.export" | "cmd.clipboard" | "cmd.share" | "cmd.broadcast" | "cmd.globe" | "cmd.copy" | "cmd.plus" | "cmd.restart" | "cmd.eraser" | "cmd.trash" | "cmd.compress" | "cmd.vibrate" | "cmd.handoff" | "cmd.history" | "cmd.question" | "cmd.rocket" | "cmd.stethoscope" | "cmd.redo" | "cmd.bug" | "cmd.memory" | "cmd.pencil" | "cmd.folderMove" | "cmd.folderPlus" | "cmd.folderMinus" | "cmd.hammer" | "cmd.power" | "cmd.cart" | "icon.mic" | "icon.camera" | "thinking.minimal" | "thinking.low" | "thinking.medium" | "thinking.high" | "thinking.xhigh" | "thinking.max" | "thinking.autoPending" | "checkbox.checked" | "checkbox.unchecked" | "radio.selected" | "radio.unselected" | "format.bullet" | "format.dash" | "format.bracketLeft" | "format.bracketRight" | "md.quoteBorder" | "md.hrChar" | "md.bullet" | "md.colorSwatch" | "advisor.rail" | "skill.rail" | "lang.default" | "lang.typescript" | "lang.javascript" | "lang.python" | "lang.rust" | "lang.go" | "lang.java" | "lang.c" | "lang.cpp" | "lang.csharp" | "lang.ruby" | "lang.julia" | "lang.php" | "lang.swift" | "lang.kotlin" | "lang.shell" | "lang.html" | "lang.css" | "lang.json" | "lang.yaml" | "lang.markdown" | "lang.sql" | "lang.docker" | "lang.lua" | "lang.text" | "lang.env" | "lang.toml" | "lang.xml" | "lang.ini" | "lang.conf" | "lang.log" | "lang.csv" | "lang.tsv" | "lang.image" | "lang.pdf" | "lang.archive" | "lang.binary" | "chip.image" | "chip.video" | "chip.paste" | "tab.appearance" | "tab.model" | "tab.interaction" | "tab.context" | "tab.files" | "tab.shell" | "tab.tools" | "tab.memory" | "tab.tasks" | "tab.providers" | "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.launch" | "tool.task" | "tool.todo" | "tool.memory" | "tool.ask" | "tool.resolve" | "tool.review" | "tool.goal" | "tool.irc" | "tool.delete" | "tool.move" | "key.ctrl" | "key.ctrlMac" | "key.shift" | "key.alt" | "key.altMac" | "key.super" | "key.superMac" | "key.joiner" | "key.enter" | "key.esc" | "key.tab" | "key.backspace" | "key.delete" | "key.space" | "key.up" | "key.down" | "key.left" | "key.right";
+export type SymbolKey = "status.success" | "status.error" | "status.warning" | "status.info" | "status.pending" | "status.disabled" | "status.enabled" | "status.running" | "status.shadowed" | "status.aborted" | "status.done" | "nav.cursor" | "nav.selected" | "nav.expand" | "nav.collapse" | "nav.back" | "tree.branch" | "tree.last" | "tree.vertical" | "tree.horizontal" | "tree.hook" | "progress.filled" | "progress.empty" | "context.speculation" | "context.compaction" | "boxRound.topLeft" | "boxRound.topRight" | "boxRound.bottomLeft" | "boxRound.bottomRight" | "boxRound.horizontal" | "boxRound.vertical" | "boxDotted.horizontal" | "boxDotted.vertical" | "boxSharp.topLeft" | "boxSharp.topRight" | "boxSharp.bottomLeft" | "boxSharp.bottomRight" | "boxSharp.horizontal" | "boxSharp.vertical" | "boxSharp.cross" | "boxSharp.teeDown" | "boxSharp.teeUp" | "boxSharp.teeRight" | "boxSharp.teeLeft" | "sep.powerline" | "sep.powerlineThin" | "sep.powerlineLeft" | "sep.powerlineRight" | "sep.powerlineThinLeft" | "sep.powerlineThinRight" | "sep.powerlineCapLeft" | "sep.block" | "sep.space" | "sep.asciiLeft" | "sep.asciiRight" | "sep.dot" | "sep.slash" | "sep.pipe" | "icon.model" | "icon.plan" | "icon.prewalk" | "icon.goal" | "icon.pause" | "icon.loop" | "icon.folder" | "icon.worktree" | "icon.search" | "icon.scratchFolder" | "icon.file" | "icon.git" | "icon.branch" | "icon.pr" | "icon.pin" | "icon.tokens" | "icon.context" | "icon.cost" | "icon.subscription" | "icon.advisor" | "icon.advisorClosed" | "icon.time" | "icon.omp" | "icon.ghost" | "icon.agents" | "icon.job" | "icon.cache" | "icon.cacheMiss" | "icon.input" | "icon.output" | "icon.throughput" | "icon.intelligence" | "icon.host" | "icon.session" | "icon.package" | "icon.warning" | "icon.rewind" | "icon.auto" | "icon.fast" | "icon.extensionSkill" | "icon.extensionTool" | "icon.extensionSlashCommand" | "icon.extensionMcp" | "icon.extensionRule" | "icon.extensionHook" | "icon.extensionPrompt" | "icon.extensionContextFile" | "icon.extensionInstruction" | "icon.vimNormal" | "icon.vimInsert" | "icon.vimVisual" | "icon.vimVisualLine" | "icon.vimReplace" | "cmd.action" | "cmd.prompt" | "cmd.extension" | "cmd.settings" | "cmd.gear" | "cmd.shield" | "cmd.wave" | "cmd.compass" | "cmd.inbox" | "cmd.swap" | "cmd.expand" | "cmd.computer" | "cmd.eye" | "cmd.todo" | "cmd.stats" | "cmd.news" | "cmd.keyboard" | "cmd.export" | "cmd.clipboard" | "cmd.share" | "cmd.broadcast" | "cmd.globe" | "cmd.copy" | "cmd.plus" | "cmd.restart" | "cmd.eraser" | "cmd.trash" | "cmd.compress" | "cmd.vibrate" | "cmd.handoff" | "cmd.history" | "cmd.question" | "cmd.rocket" | "cmd.stethoscope" | "cmd.redo" | "cmd.bug" | "cmd.memory" | "cmd.pencil" | "cmd.folderMove" | "cmd.folderPlus" | "cmd.folderMinus" | "cmd.hammer" | "cmd.power" | "cmd.cart" | "icon.mic" | "icon.camera" | "thinking.minimal" | "thinking.low" | "thinking.medium" | "thinking.high" | "thinking.xhigh" | "thinking.max" | "thinking.autoPending" | "checkbox.checked" | "checkbox.unchecked" | "radio.selected" | "radio.unselected" | "format.bullet" | "format.dash" | "format.bracketLeft" | "format.bracketRight" | "md.quoteBorder" | "md.hrChar" | "md.bullet" | "md.colorSwatch" | "advisor.rail" | "skill.rail" | "lang.default" | "lang.typescript" | "lang.javascript" | "lang.python" | "lang.rust" | "lang.go" | "lang.java" | "lang.c" | "lang.cpp" | "lang.csharp" | "lang.ruby" | "lang.julia" | "lang.php" | "lang.swift" | "lang.kotlin" | "lang.shell" | "lang.html" | "lang.css" | "lang.json" | "lang.yaml" | "lang.markdown" | "lang.sql" | "lang.docker" | "lang.lua" | "lang.text" | "lang.env" | "lang.toml" | "lang.xml" | "lang.ini" | "lang.conf" | "lang.log" | "lang.csv" | "lang.tsv" | "lang.image" | "lang.pdf" | "lang.archive" | "lang.binary" | "chip.image" | "chip.video" | "chip.paste" | "tab.appearance" | "tab.model" | "tab.interaction" | "tab.context" | "tab.files" | "tab.shell" | "tab.tools" | "tab.memory" | "tab.tasks" | "tab.providers" | "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.launch" | "tool.task" | "tool.todo" | "tool.memory" | "tool.ask" | "tool.resolve" | "tool.review" | "tool.goal" | "tool.irc" | "tool.delete" | "tool.move" | "key.ctrl" | "key.ctrlMac" | "key.shift" | "key.alt" | "key.altMac" | "key.super" | "key.superMac" | "key.joiner" | "key.enter" | "key.esc" | "key.tab" | "key.backspace" | "key.delete" | "key.space" | "key.up" | "key.down" | "key.left" | "key.right";
 export type SymbolMap = Record<SymbolKey, string>;
 /**
  * Icon vocabulary for slash-command autocomplete type indicators. Each name

package/src/theme/symbols.ts

@@ -129,6 +129,7 @@ export type SymbolKey =
 	| "icon.vimInsert"
 	| "icon.vimVisual"
 	| "icon.vimVisualLine"
+	| "icon.vimReplace"
 	// Slash-command type indicators (autocomplete); names without an existing
 	// icon.* equivalent — see SlashCommandIconName for the full vocabulary.
 	| "cmd.action"
@@ -511,6 +512,7 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	"icon.vimInsert": "▎",
 	"icon.vimVisual": "◉",
 	"icon.vimVisualLine": "≡",
+	"icon.vimReplace": "▁",
 	// Slash-command type indicators
 	"cmd.action": "❯",
 	"cmd.prompt": "✎",
@@ -921,6 +923,8 @@ const NERD_SYMBOLS: SymbolMap = {
 	"icon.vimVisual": "\uf06e",
 	// pick:  (nf-fa-bars) | alt:  (nf-fa-align_left)
 	"icon.vimVisualLine": "\uf0c9",
+	// pick:  (nf-fa-exchange) | alt:  (nf-fa-repeat)
+	"icon.vimReplace": "\uf0ec",
 	// Slash-command type indicators
 	// pick:  (nf-cod-terminal) | alt:  (nf-fa-terminal)
 	"cmd.action": "\uea85",
@@ -1235,9 +1239,11 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"sep.pipe": " | ",
 	// Icons
 	"icon.model": "[M]",
-	"icon.plan": "plan",
-	"icon.prewalk": "prewalk",
-	"icon.goal": "goal",
+	// Mode icons are always followed by their word label ("Plan", "Prewalk", "Goal");
+	// an ASCII word here would just repeat it, so render the label alone.
+	"icon.plan": "",
+	"icon.prewalk": "",
+	"icon.goal": "",
 	"icon.pause": "||",
 	"icon.loop": "loop",
 	"icon.folder": "[D]",
@@ -1256,7 +1262,7 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"icon.advisor": "(adv)",
 	"icon.advisorClosed": "(adv)",
 	"icon.time": "t:",
-	"icon.omp": "pi",
+	"icon.omp": "zeta",
 	"icon.ghost": "@",
 	"icon.agents": "AG",
 	"icon.job": "bg",
@@ -1287,6 +1293,7 @@ const ASCII_SYMBOLS: SymbolMap = {
 	"icon.vimInsert": "I",
 	"icon.vimVisual": "V",
 	"icon.vimVisualLine": "L",
+	"icon.vimReplace": "R",
 	// Slash-command type indicators — unused; the icon column is disabled in ASCII mode
 	"cmd.action": "",
 	"cmd.prompt": "",

package/src/theme/theme-class.d.ts

@@ -54,6 +54,13 @@ export declare class Theme {
      * against. Built once per instance and frozen; callers share the object.
      */
     get sessionAccentInputs(): SessionAccentTheme;
+    /**
+     * True when the theme paints `color` with a real foreground — i.e. the token
+     * exists and is not the empty string (terminal default, `\x1b[39m`). Optional
+     * tokens absent from the theme JSON are also false. Callers use this to keep
+     * terminal-default behavior byte-for-byte when an optional token is unset.
+     */
+    hasColor(color: ThemeColor): boolean;
     fg(color: ThemeColor, text: string): string;
     /** Apply a foreground, replacing terminal-default tokens with the theme's contrast-safe fallback. */
     fgResolved(color: ThemeColor, text: string): string;

package/src/theme/theme-class.ts

@@ -2,7 +2,13 @@ import { colorLuma, relativeLuminance } from "@linxiraos/pi-utils/color";
 import * as logger from "@linxiraos/pi-utils/logger";
 import chalk from "@linxiraos/pi-utils/chalk";
 import { bgAnsi, colorToAnsi, fgAnsi, resolveToHex } from "./color";
-import { type ColorMode, isValidThemeColor, type ThemeBg, type ThemeColor } from "./schema";
+import {
+	type ColorMode,
+	isValidThemeColor,
+	OPTIONAL_THEME_COLOR_RECORD,
+	type ThemeBg,
+	type ThemeColor,
+} from "./schema";
 import type { SessionAccentTheme } from "./session-color";
 import {
 	type SlashCommandIconName,
@@ -204,6 +210,14 @@ export class Theme {
 			this.#fgColors[key] = fgAnsi(value, mode);
 			this.#hexFgColors[key] = hex;
 		}
+		// A theme may omit an optional token, but callers can still name it (a
+		// `modelTags.<role>.color` reference is validated against the theme color
+		// list). Resolve those to the terminal default so `fg()` stays total while
+		// `hasColor()` reports them as unset.
+		for (const key of Object.keys(OPTIONAL_THEME_COLOR_RECORD) as ThemeColor[]) {
+			this.#fgColors[key] ??= "\x1b[39m";
+			this.#hexFgColors[key] ??= "";
+		}
 		this.#bgColors = {} as Record<ThemeBg, string>;
 		this.#hexBgColors = {} as Record<ThemeBg, string>;
 		for (const [key, value] of Object.entries(bgColors) as [ThemeBg, string | number][]) {
@@ -322,6 +336,17 @@ export class Theme {
 		return this.#sessionAccentInputs;
 	}
 
+	/**
+	 * True when the theme paints `color` with a real foreground — i.e. the token
+	 * exists and is not the empty string (terminal default, `\x1b[39m`). Optional
+	 * tokens absent from the theme JSON are also false. Callers use this to keep
+	 * terminal-default behavior byte-for-byte when an optional token is unset.
+	 */
+	hasColor(color: ThemeColor): boolean {
+		const ansi = this.#fgColors[color];
+		return ansi !== undefined && ansi !== "\x1b[39m";
+	}
+
 	fg(color: ThemeColor, text: string): string {
 		const ansi = this.#fgColors[color];
 		if (!ansi) throw new Error(`Unknown theme color: ${color}`);

package/src/theme/theme-schema.json

@@ -33,7 +33,7 @@
 		},
 		"colors": {
 			"type": "object",
-			"description": "Theme color definitions (all required except thinkingMax)",
+			"description": "Theme color definitions (all required except thinkingMax and assistantMessageText)",
 			"required": [
 				"accent",
 				"border",
@@ -143,6 +143,10 @@
 					"$ref": "#/$defs/colorValue",
 					"description": "Default text color (usually empty string)"
 				},
+				"assistantMessageText": {
+					"$ref": "#/$defs/colorValue",
+					"description": "Assistant paragraph prose color (optional; empty string or omitted keeps the terminal default foreground)"
+				},
 				"thinkingText": {
 					"$ref": "#/$defs/colorValue",
 					"description": "Thinking text color"

package/src/theme/theme.d.ts

@@ -6,7 +6,7 @@ export { getAvailableThemes, getAvailableThemesWithPaths, getThemeByName, type T
 export { isValidThemeColor, type ThemeBg, type ThemeColor } from "./schema";
 export { getAvailableSymbolPresets, isValidSymbolPreset, type SpinnerType, type SymbolKey, type SymbolPreset, } from "./symbols";
 export { Theme } from "./theme-class";
-export { createHighlightStream, getEditorTheme, getMarkdownTheme, getSelectListTheme, getSettingsListTheme, getSymbolTheme, highlightCode, setMarkdownMermaidRendering, warmHighlighter, } from "./tui-adapters";
+export { createHighlightStream, getEditorTheme, getMarkdownTheme, getMarkdownThemeWithLinkTargets, getSelectListTheme, getSettingsListTheme, getSymbolTheme, highlightCode, setMarkdownMermaidRendering, warmHighlighter, } from "./tui-adapters";
 /** Active theme; imports remain live across initialization, previews, and theme switches. */
 export declare var theme: Theme;
 type ThemeBinding = (value: Theme) => void;

package/src/theme/theme.ts

@@ -5,6 +5,7 @@ import type { Terminal, TerminalAppearance } from "../terminal";
 import { colorLuma } from "@linxiraos/pi-utils/color";
 import { getCustomThemesDir } from "@linxiraos/pi-utils/dirs";
 import * as logger from "@linxiraos/pi-utils/logger";
+import { terminalMultiplexerSessions } from "../terminal-multiplexer";
 import { setActiveSymbolTheme } from "./active-symbols";
 import { ansi256ToHex, resolveThemeColors, resolveVarRefs } from "./color";
 import {
@@ -34,6 +35,7 @@ export {
 	createHighlightStream,
 	getEditorTheme,
 	getMarkdownTheme,
+	getMarkdownThemeWithLinkTargets,
 	getSelectListTheme,
 	getSettingsListTheme,
 	getSymbolTheme,
@@ -49,10 +51,12 @@ var terminalReportedAppearance: "dark" | "light" | undefined;
 var macOSReportedAppearance: "dark" | "light" | undefined;
 
 function shouldUseMacOSAppearanceFallback(): boolean {
-	// Zellij currently breaks OSC 11 passthrough on macOS, so terminal-derived
-	// appearance cannot be trusted there. Fall back to host macOS appearance
-	// without letting it override valid terminal signals elsewhere.
-	return process.platform === "darwin" && !!Bun.env.ZELLIJ;
+	// Some multiplexers break OSC 11 passthrough on some platforms (Zellij on
+	// macOS), so terminal-derived appearance cannot be trusted there. Fall back
+	// to host macOS appearance without letting it override valid terminal
+	// signals elsewhere.
+	const platform = process.platform;
+	return terminalMultiplexerSessions().some(multiplexer => multiplexer.backgroundQueryBrokenOn?.includes(platform));
 }
 
 function detectTerminalBackground(): "dark" | "light" {

package/src/theme/tui-adapters.d.ts

@@ -16,6 +16,9 @@ export declare function createHighlightStream(lang?: string, highlightTheme?: Th
 /** Warm native syntax grammars off-thread once per process. */
 export declare function warmHighlighter(): Promise<void>;
 export declare function getSymbolTheme(): SymbolTheme;
+/** Only themes assembled here have stable callbacks and private link state. */
+export declare function canCacheMarkdownListItems(candidate: MarkdownTheme): boolean;
+export declare function getMarkdownThemeWithLinkTargets(targets: ReadonlyMap<string, string>): MarkdownTheme;
 export declare function setMarkdownMermaidRendering(enabled: boolean): void;
 export declare function getMarkdownTheme(): MarkdownTheme;
 export declare function getSelectListTheme(): SelectListTheme;

package/src/theme/tui-adapters.ts

@@ -183,8 +183,75 @@ export function getSymbolTheme(): SymbolTheme {
 
 let cachedMarkdownTheme: MarkdownTheme | undefined;
 let cachedMarkdownThemeRef: Theme | undefined;
+const cacheableMarkdownThemes = new WeakMap<
+	MarkdownTheme,
+	{
+		theme: Theme;
+		fields: ReadonlyArray<readonly [PropertyKey, unknown]>;
+		symbolFields: ReadonlyArray<readonly [PropertyKey, unknown]>;
+		symbolValues: string;
+	}
+>();
+const linkTargetSnapshots = new WeakMap<ReadonlyMap<string, string>, ReadonlyMap<string, string>>();
 let markdownMermaidRendering = true;
 
+function ownFields(object: object): ReadonlyArray<readonly [PropertyKey, unknown]> {
+	return Reflect.ownKeys(object).map(key => [key, Object.getOwnPropertyDescriptor(object, key)?.value]);
+}
+
+function hasUnchangedOwnFields(object: object, fields: ReadonlyArray<readonly [PropertyKey, unknown]>): boolean {
+	if (Reflect.ownKeys(object).length !== fields.length) return false;
+	return fields.every(([key, value]) => {
+		const descriptor = Object.getOwnPropertyDescriptor(object, key);
+		return descriptor !== undefined && "value" in descriptor && descriptor.value === value;
+	});
+}
+
+/** Only themes assembled here have stable callbacks and private link state. */
+export function canCacheMarkdownListItems(candidate: MarkdownTheme): boolean {
+	const registered = cacheableMarkdownThemes.get(candidate);
+	if (registered === undefined || registered.theme !== theme || candidate.symbols === undefined) return false;
+	if (!hasUnchangedOwnFields(candidate, registered.fields)) return false;
+	if (!hasUnchangedOwnFields(candidate.symbols, registered.symbolFields)) return false;
+	try {
+		return JSON.stringify(candidate.symbols) === registered.symbolValues;
+	} catch {
+		return false;
+	}
+}
+
+function registerCacheableMarkdownTheme(markdownTheme: MarkdownTheme): void {
+	if (markdownTheme.symbols === undefined) return;
+	cacheableMarkdownThemes.set(markdownTheme, {
+		theme,
+		fields: ownFields(markdownTheme),
+		symbolFields: ownFields(markdownTheme.symbols),
+		symbolValues: JSON.stringify(markdownTheme.symbols),
+	});
+}
+
+export function getMarkdownThemeWithLinkTargets(targets: ReadonlyMap<string, string>): MarkdownTheme {
+	const base = getMarkdownTheme();
+	let snapshot = linkTargetSnapshots.get(targets);
+	let matches = snapshot?.size === targets.size;
+	if (matches && snapshot !== undefined) {
+		for (const [href, target] of targets) {
+			if (snapshot.get(href) !== target) {
+				matches = false;
+				break;
+			}
+		}
+	}
+	if (snapshot === undefined || !matches) {
+		snapshot = new Map(targets);
+		linkTargetSnapshots.set(targets, snapshot);
+	}
+	const stableSnapshot = snapshot;
+	const linked: MarkdownTheme = { ...base, resolveLink: href => stableSnapshot.get(href) };
+	if (canCacheMarkdownListItems(base)) registerCacheableMarkdownTheme(linked);
+	return linked;
+}
+
 export function setMarkdownMermaidRendering(enabled: boolean): void {
 	if (markdownMermaidRendering === enabled) return;
 	markdownMermaidRendering = enabled;
@@ -247,6 +314,7 @@ export function getMarkdownTheme(): MarkdownTheme {
 	};
 	cachedMarkdownTheme = markdownTheme;
 	cachedMarkdownThemeRef = theme;
+	registerCacheableMarkdownTheme(markdownTheme);
 	return markdownTheme;
 }
 

package/src/thinking.d.ts

@@ -4,7 +4,7 @@ import { ThinkingLevel } from "@linxiraos/pi-agent-core/thinking";
 import { Effort } from "@linxiraos/pi-catalog/effort";
 import type { Model } from "@linxiraos/pi-catalog/types";
 /** Thinking selectors accepted by CLI inputs, in display order. */
-export declare const CLI_THINKING_LEVELS: readonly string[];
+export declare const CLI_THINKING_LEVELS: readonly ConfiguredThinkingLevel[];
 /**
  * Metadata used to render thinking selector values in the coding-agent UI.
  */

package/src/thinking.ts

@@ -6,7 +6,7 @@ import { clampThinkingLevelForModel, getSupportedEfforts } from "@linxiraos/pi-c
 import { modelsAreEqual } from "@linxiraos/pi-catalog/models";
 import type { Model } from "@linxiraos/pi-catalog/types";
 /** Thinking selectors accepted by CLI inputs, in display order. */
-export const CLI_THINKING_LEVELS: readonly string[] = ["off", ...THINKING_EFFORTS, "auto"];
+export const CLI_THINKING_LEVELS: readonly ConfiguredThinkingLevel[] = ["off", ...THINKING_EFFORTS, "auto"];
 
 /**
  * Metadata used to render thinking selector values in the coding-agent UI.

package/src/tmux.d.ts

@@ -1,9 +1,16 @@
-/** Whether the process is running inside a tmux session. */
-export declare function isInsideTmux(env?: NodeJS.ProcessEnv): boolean;
-/** Wrap a control sequence in tmux's DCS passthrough envelope. */
-export declare function wrapTmuxPassthrough(payload: string): string;
+export { wrapTmuxPassthrough } from "./multiplexers/tmux";
 /** Pass a control sequence through tmux, leaving direct-terminal output unchanged. */
 export declare function wrapTmuxPassthroughIfNeeded(payload: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * Whether the terminal hosting this tmux session draws TSP programs natively:
+ * it sets the session user option `@tern-tsp` while it watches the session.
+ */
+export declare function tmuxSessionSpeaksTsp(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Stop (`on` false) or restore (`on` true) tmux turning this pane's APC
+ * strings into its title, which would otherwise swallow every TSP message.
+ */
+export declare function setTmuxPaneApcTitles(on: boolean, env?: NodeJS.ProcessEnv): void;
 /**
  * Resolve the terminal emulator name recorded for this tmux client.
  *

package/src/tmux.ts

@@ -1,19 +1,12 @@
 import { $which } from "@linxiraos/pi-utils";
 import { isBunTestRuntime } from "@linxiraos/pi-utils/env";
+import { tmuxMultiplexer, wrapTmuxPassthrough } from "./multiplexers/tmux";
 
-/** Whether the process is running inside a tmux session. */
-export function isInsideTmux(env: NodeJS.ProcessEnv = Bun.env): boolean {
-	return Boolean(env.TMUX);
-}
-
-/** Wrap a control sequence in tmux's DCS passthrough envelope. */
-export function wrapTmuxPassthrough(payload: string): string {
-	return `\x1bPtmux;${payload.replaceAll("\x1b", "\x1b\x1b")}\x1b\\`;
-}
+export { wrapTmuxPassthrough } from "./multiplexers/tmux";
 
 /** Pass a control sequence through tmux, leaving direct-terminal output unchanged. */
 export function wrapTmuxPassthroughIfNeeded(payload: string, env: NodeJS.ProcessEnv = Bun.env): string {
-	return isInsideTmux(env) ? wrapTmuxPassthrough(payload) : payload;
+	return tmuxMultiplexer.isInside(env) ? wrapTmuxPassthrough(payload) : payload;
 }
 
 const CLIENT_TERMTYPE_NAME = /^([A-Za-z][A-Za-z0-9._+-]*)(?=\s|\(|$)/u;
@@ -38,6 +31,49 @@ function queryTmuxClientTerminalName(env: NodeJS.ProcessEnv): string | null {
 	}
 }
 
+const TMUX_COMMAND_TIMEOUT_MS = 500;
+
+/** Run a tmux command against the current server; its stdout, or null on failure. */
+function runTmux(args: string[], env: NodeJS.ProcessEnv): string | null {
+	const tmux = $which("tmux", { PATH: env.PATH });
+	if (!tmux) return null;
+	try {
+		const result = Bun.spawnSync([tmux, ...args], {
+			env,
+			stdout: "pipe",
+			stderr: "ignore",
+			timeout: TMUX_COMMAND_TIMEOUT_MS,
+			killSignal: "SIGKILL",
+		});
+		return result.exitCode === 0 ? result.stdout.toString() : null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Whether the terminal hosting this tmux session draws TSP programs natively:
+ * it sets the session user option `@tern-tsp` while it watches the session.
+ */
+export function tmuxSessionSpeaksTsp(env: NodeJS.ProcessEnv = Bun.env): boolean {
+	return (runTmux(["show-options", "-qv", "@tern-tsp"], env)?.trim() ?? "") !== "";
+}
+
+/**
+ * Stop (`on` false) or restore (`on` true) tmux turning this pane's APC
+ * strings into its title, which would otherwise swallow every TSP message.
+ */
+export function setTmuxPaneApcTitles(on: boolean, env: NodeJS.ProcessEnv = Bun.env): void {
+	const pane = env.TMUX_PANE;
+	if (!pane) return;
+	runTmux(
+		on
+			? ["set-option", "-pu", "-t", pane, "allow-set-title"]
+			: ["set-option", "-p", "-t", pane, "allow-set-title", "off"],
+		env,
+	);
+}
+
 /**
  * Resolve the terminal emulator name recorded for this tmux client.
  *
@@ -46,7 +82,7 @@ function queryTmuxClientTerminalName(env: NodeJS.ProcessEnv): string | null {
  * query runs once per process and degrades to `null` when unavailable.
  */
 export function resolveTmuxClientTerminalName(env: NodeJS.ProcessEnv = Bun.env): string | null {
-	if (!isInsideTmux(env) || isBunTestRuntime()) return null;
+	if (!tmuxMultiplexer.isInside(env) || isBunTestRuntime()) return null;
 	if (cachedClientTerminalName === undefined) cachedClientTerminalName = queryTmuxClientTerminalName(env);
 	return cachedClientTerminalName;
 }