@oh-my-pi/pi-coding-agent 15.8.3 → 15.9.0

package/src/config/settings-schema.ts

@@ -23,6 +23,7 @@ import {
 	TINY_TITLE_MODEL_VALUES,
 } from "../tiny/models";
 import { EDIT_MODES } from "../utils/edit-mode";
+import { SEARCH_PROVIDER_OPTIONS, SEARCH_PROVIDER_PREFERENCES } from "../web/search/types";
 
 /** Unified settings schema - single source of truth for all settings.
  * Unified settings schema - single source of truth for all settings.
@@ -608,6 +609,24 @@ export const SETTINGS_SCHEMA = {
 			"Maximum height in terminal rows for inline images (default 20). Set to 0 to use only the viewport-based limit (60% of terminal height).",
 	},
 
+	"tui.maxInlineImages": {
+		type: "number",
+		default: 8,
+		description:
+			"Maximum number of inline images kept as live terminal graphics (default 8). Older images fall back to a text placeholder via a full redraw once the limit is exceeded. Set to 0 to keep every image (no limit).",
+	},
+
+	"tui.textSizing": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "appearance",
+			label: "Large Headings (Kitty)",
+			description:
+				"Render Markdown H1 headings at 2x scale using Kitty's OSC 66 text-sizing protocol. Only takes effect on Kitty terminals; ignored everywhere else. Off by default.",
+		},
+	},
+
 	"tui.hyperlinks": {
 		type: "enum",
 		values: ["off", "auto", "always"] as const,
@@ -2104,7 +2123,7 @@ export const SETTINGS_SCHEMA = {
 	"todo.enabled": {
 		type: "boolean",
 		default: true,
-		ui: { tab: "tools", label: "Todos", description: "Enable the todo_write tool for task tracking" },
+		ui: { tab: "tools", label: "Todos", description: "Enable the todo tool for task tracking" },
 	},
 
 	"todo.reminders": {
@@ -2866,65 +2885,13 @@ export const SETTINGS_SCHEMA = {
 	// Provider selection
 	"providers.webSearch": {
 		type: "enum",
-		values: [
-			"auto",
-			"exa",
-			"brave",
-			"jina",
-			"kimi",
-			"zai",
-			"perplexity",
-			"anthropic",
-			"gemini",
-			"codex",
-			"tavily",
-			"kagi",
-			"synthetic",
-			"parallel",
-			"searxng",
-		] as const,
+		values: SEARCH_PROVIDER_PREFERENCES,
 		default: "auto",
 		ui: {
 			tab: "providers",
 			label: "Web Search Provider",
 			description: "Provider for web search tool",
-			options: [
-				{
-					value: "auto",
-					label: "Auto",
-					description: "Preferred web-search provider",
-				},
-				{ value: "exa", label: "Exa", description: "Requires EXA_API_KEY" },
-				{ value: "brave", label: "Brave", description: "Requires BRAVE_API_KEY" },
-				{ value: "jina", label: "Jina", description: "Requires JINA_API_KEY" },
-				{ value: "kimi", label: "Kimi", description: "Requires MOONSHOT_SEARCH_API_KEY or MOONSHOT_API_KEY" },
-				{
-					value: "perplexity",
-					label: "Perplexity",
-					description: "Requires PERPLEXITY_COOKIES or PERPLEXITY_API_KEY",
-				},
-				{
-					value: "anthropic",
-					label: "Anthropic",
-					description: "Claude's native web_search tool (uses Anthropic OAuth or ANTHROPIC_API_KEY)",
-				},
-				{
-					value: "codex",
-					label: "OpenAI",
-					description: "OpenAI's native web_search (uses ChatGPT OAuth via /login openai-codex)",
-				},
-				{
-					value: "gemini",
-					label: "Gemini",
-					description: "Google Search grounding via Gemini (uses google-gemini-cli or google-antigravity OAuth)",
-				},
-				{ value: "zai", label: "Z.AI", description: "Calls Z.AI webSearchPrime MCP" },
-				{ value: "tavily", label: "Tavily", description: "Requires TAVILY_API_KEY" },
-				{ value: "kagi", label: "Kagi", description: "Requires KAGI_API_KEY (Kagi V1 Search API)" },
-				{ value: "synthetic", label: "Synthetic", description: "Requires SYNTHETIC_API_KEY" },
-				{ value: "parallel", label: "Parallel", description: "Requires PARALLEL_API_KEY" },
-				{ value: "searxng", label: "SearXNG", description: "Requires SEARXNG_ENDPOINT or searxng.endpoint" },
-			],
+			options: SEARCH_PROVIDER_OPTIONS,
 		},
 	},
 	"providers.image": {

package/src/debug/index.ts

@@ -6,7 +6,17 @@
 import * as fs from "node:fs/promises";
 import * as url from "node:url";
 import { getWorkProfile } from "@oh-my-pi/pi-natives";
-import { Container, Loader, type SelectItem, SelectList, Spacer, Text } from "@oh-my-pi/pi-tui";
+import {
+	Container,
+	isNotificationSuppressed,
+	Loader,
+	type SelectItem,
+	SelectList,
+	Spacer,
+	TERMINAL,
+	type TerminalNotification,
+	Text,
+} from "@oh-my-pi/pi-tui";
 import { getSessionsDir } from "@oh-my-pi/pi-utils";
 import { DynamicBorder } from "../modes/components/dynamic-border";
 import { getSelectListTheme, getSymbolTheme, theme } from "../modes/theme/theme";
@@ -15,10 +25,12 @@ import { formatBytes } from "../tools/render-utils";
 import { openPath } from "../utils/open";
 import { DebugLogViewerComponent } from "./log-viewer";
 import { generateHeapSnapshotData, type ProfilerSession, startCpuProfile } from "./profiler";
+import { buildSampleImage, ProtocolProbeComponent } from "./protocol-probe";
 import { RawSseViewerComponent } from "./raw-sse";
 import { resolveRawSseDebugBuffer } from "./raw-sse-buffer";
 import { clearArtifactCache, createDebugLogSource, createReportBundle, getArtifactCacheStats } from "./report-bundle";
 import { collectSystemInfo, formatSystemInfo } from "./system-info";
+import { collectTerminalState, formatTerminalState } from "./terminal-info";
 
 /** Debug menu options */
 const DEBUG_MENU_ITEMS: SelectItem[] = [
@@ -29,6 +41,12 @@ const DEBUG_MENU_ITEMS: SelectItem[] = [
 	{ value: "memory", label: "Report: memory issue", description: "Heap snapshot + bundle" },
 	{ value: "logs", label: "View: recent logs", description: "Show last 50 log entries" },
 	{ value: "system", label: "View: system info", description: "Show environment details" },
+	{ value: "terminal", label: "View: terminal state", description: "Subprotocols, geometry, scrollback strategy" },
+	{
+		value: "protocols",
+		label: "Test: terminal protocols",
+		description: "Styling, links, text sizing, graphics, notify",
+	},
 	{ value: "raw-sse", label: "View: raw SSE stream", description: "Show live provider SSE frames" },
 	{
 		value: "transcript",
@@ -106,6 +124,12 @@ export class DebugSelectorComponent extends Container {
 			case "system":
 				await this.#handleViewSystemInfo();
 				break;
+			case "terminal":
+				await this.#handleViewTerminalState();
+				break;
+			case "protocols":
+				await this.#handleViewProtocols();
+				break;
 			case "transcript":
 				await this.#handleTranscriptExport();
 				break;
@@ -352,6 +376,48 @@ export class DebugSelectorComponent extends Container {
 		this.ctx.ui.requestRender();
 	}
 
+	async #handleViewTerminalState(): Promise<void> {
+		const info = collectTerminalState({
+			columns: this.ctx.ui.terminal.columns,
+			rows: this.ctx.ui.terminal.rows,
+			synchronizedOutput: this.ctx.ui.synchronizedOutput,
+		});
+		const formatted = formatTerminalState(info);
+
+		this.ctx.chatContainer.addChild(new Spacer(1));
+		this.ctx.chatContainer.addChild(new DynamicBorder());
+		this.ctx.chatContainer.addChild(new Text(formatted, 1, 0));
+		this.ctx.chatContainer.addChild(new DynamicBorder());
+		this.ctx.ui.requestRender();
+	}
+
+	async #handleViewProtocols(): Promise<void> {
+		// Fire the desktop notification as a real side effect, then render a
+		// panel that samples every other special protocol and reports the
+		// notification outcome.
+		const suppressed = isNotificationSuppressed();
+		if (!suppressed) {
+			const sessionName = this.ctx.sessionManager.getSessionName();
+			const notification: TerminalNotification = {
+				title: sessionName || "Oh My Pi",
+				body: "Terminal protocol test",
+				type: "test",
+				actions: "focus",
+			};
+			TERMINAL.sendNotification(notification);
+		}
+
+		this.ctx.chatContainer.addChild(new Spacer(1));
+		this.ctx.chatContainer.addChild(
+			new ProtocolProbeComponent({
+				image: buildSampleImage(),
+				imageBudget: this.ctx.ui.imageBudget,
+				notificationSuppressed: suppressed,
+			}),
+		);
+		this.ctx.ui.requestRender();
+	}
+
 	async #handleTranscriptExport(): Promise<void> {
 		await this.ctx.handleDebugTranscriptCommand();
 	}

package/src/debug/protocol-probe.ts

@@ -0,0 +1,267 @@
+/**
+ * Terminal protocol smoke-test panel for the debug menu.
+ *
+ * Exercises every "special" escape protocol the renderer can emit so a human
+ * can eyeball which ones the active terminal actually honors:
+ *   - SGR text styling + 24-bit truecolor,
+ *   - OSC 8 hyperlinks,
+ *   - OSC 66 text sizing (large text),
+ *   - inline graphics (Kitty / iTerm2 / Sixel),
+ *   - OSC 9 / OSC 99 desktop notifications (fired by the caller).
+ *
+ * The sample image is generated in-process (a deterministic RGB gradient PNG)
+ * so the graphics test needs no asset on disk and works across all three image
+ * protocols, each of which decodes a standard PNG.
+ */
+import * as zlib from "node:zlib";
+import {
+	type Component,
+	Container,
+	encodeTextSized,
+	Image,
+	type ImageBudget,
+	ImageProtocol,
+	NotifyProtocol,
+	Spacer,
+	TERMINAL,
+	Text,
+	type TextSizingScale,
+} from "@oh-my-pi/pi-tui";
+import { DynamicBorder } from "../modes/components/dynamic-border";
+import { theme } from "../modes/theme/theme";
+
+const PNG_SIGNATURE = Uint8Array.of(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a);
+
+/** Frame a PNG chunk: 4-byte big-endian length, type+data, then the CRC-32 of type+data. */
+function pngChunk(type: string, data: Uint8Array): Uint8Array {
+	const body = Buffer.concat([Buffer.from(type, "latin1"), data]);
+	const out = Buffer.alloc(body.length + 8);
+	out.writeUInt32BE(data.length, 0);
+	body.copy(out, 4);
+	out.writeUInt32BE(Bun.hash.crc32(body) >>> 0, out.length - 4);
+	return out;
+}
+
+/**
+ * Encode raw 8-bit RGB pixels (`width * height * 3` bytes, row-major) as a PNG
+ * (color type 2, no interlacing). The IDAT payload is a real zlib stream from
+ * {@link zlib.deflateSync}, so the output is a fully valid PNG that every image
+ * protocol — including Sixel, which decodes the bytes natively — accepts.
+ */
+export function encodeRgbPng(width: number, height: number, rgb: Uint8Array): Uint8Array {
+	const ihdr = Buffer.alloc(13);
+	ihdr.writeUInt32BE(width, 0);
+	ihdr.writeUInt32BE(height, 4);
+	ihdr[8] = 8; // bit depth
+	ihdr[9] = 2; // color type: truecolor RGB
+	// compression (0), filter (0), interlace (0) are already zeroed.
+
+	const stride = width * 3;
+	// Each scanline is prefixed with a filter-type byte (0 = None).
+	const raw = Buffer.alloc((stride + 1) * height);
+	for (let y = 0; y < height; y++) {
+		raw.set(rgb.subarray(y * stride, y * stride + stride), y * (stride + 1) + 1);
+	}
+	const idat = zlib.deflateSync(raw);
+
+	return Buffer.concat([
+		PNG_SIGNATURE,
+		pngChunk("IHDR", ihdr),
+		pngChunk("IDAT", idat),
+		pngChunk("IEND", new Uint8Array(0)),
+	]);
+}
+
+export interface SampleImage {
+	base64: string;
+	mimeType: string;
+	dimensions: { widthPx: number; heightPx: number };
+}
+
+/** Build a deterministic RGB gradient PNG (red across, green down, constant blue). */
+export function buildSampleImage(width = 192, height = 128): SampleImage {
+	const denomX = Math.max(1, width - 1);
+	const denomY = Math.max(1, height - 1);
+	const rgb = new Uint8Array(width * height * 3);
+	for (let y = 0; y < height; y++) {
+		for (let x = 0; x < width; x++) {
+			const i = (y * width + x) * 3;
+			rgb[i] = Math.round((x / denomX) * 255);
+			rgb[i + 1] = Math.round((y / denomY) * 255);
+			rgb[i + 2] = 128;
+		}
+	}
+	const png = encodeRgbPng(width, height, rgb);
+	return {
+		base64: Buffer.from(png).toString("base64"),
+		mimeType: "image/png",
+		dimensions: { widthPx: width, heightPx: height },
+	};
+}
+
+const LARGE_TEXT_SAMPLE = "Aa Bb 123";
+
+/**
+ * OSC 66 text-sizing sample lines, one scaled span per requested scale. Each
+ * scaled row is followed by `scale - 1` blank rows that reserve the vertical
+ * cells its multi-cell glyphs occupy — mirroring the markdown H1 renderer so
+ * the next line does not paint over the bottom of the glyphs.
+ */
+export function buildLargeTextLines(scales: readonly TextSizingScale[] = [2, 3]): string[] {
+	const lines: string[] = [];
+	for (const scale of scales) {
+		lines.push(`  ${theme.fg("accent", encodeTextSized(`${LARGE_TEXT_SAMPLE} (${scale}x)`, { scale }))}`);
+		for (let reserved = 1; reserved < scale; reserved++) lines.push("");
+	}
+	return lines;
+}
+
+/** HSV (h in degrees, s/v in 0..1) to 8-bit RGB, for the truecolor demo bar. */
+function hsvToRgb(h: number, s: number, v: number): [number, number, number] {
+	const c = v * s;
+	const hp = (((h % 360) + 360) % 360) / 60;
+	const x = c * (1 - Math.abs((hp % 2) - 1));
+	let r = 0;
+	let g = 0;
+	let b = 0;
+	if (hp < 1) [r, g, b] = [c, x, 0];
+	else if (hp < 2) [r, g, b] = [x, c, 0];
+	else if (hp < 3) [r, g, b] = [0, c, x];
+	else if (hp < 4) [r, g, b] = [0, x, c];
+	else if (hp < 5) [r, g, b] = [x, 0, c];
+	else [r, g, b] = [c, 0, x];
+	const m = v - c;
+	const to8 = (n: number) => Math.round((n + m) * 255);
+	return [to8(r), to8(g), to8(b)];
+}
+
+/** A 24-bit-color hue sweep rendered as background-painted cells (one space each). */
+function truecolorBar(cells: number): string {
+	let out = "";
+	for (let i = 0; i < cells; i++) {
+		const [r, g, b] = hsvToRgb((i / cells) * 360, 0.85, 1);
+		out += `\x1b[48;2;${r};${g};${b}m `;
+	}
+	return `${out}\x1b[0m`;
+}
+
+function notifyProtocolLabel(): string {
+	switch (TERMINAL.notifyProtocol) {
+		case NotifyProtocol.Osc99:
+			return "OSC 99 (kitty)";
+		case NotifyProtocol.Osc9:
+			return "OSC 9 (iTerm2/WezTerm)";
+		default:
+			return "BEL";
+	}
+}
+
+function imageProtocolLabel(): string {
+	switch (TERMINAL.imageProtocol) {
+		case ImageProtocol.Kitty:
+			return "Kitty graphics";
+		case ImageProtocol.Iterm2:
+			return "iTerm2 inline images";
+		case ImageProtocol.Sixel:
+			return "Sixel";
+		default:
+			return "none — text fallback";
+	}
+}
+
+/** Emits a fixed list of lines verbatim — no wrapping or padding. Used for OSC 66 spans. */
+class RawLines implements Component {
+	#lines: readonly string[];
+	constructor(lines: readonly string[]) {
+		this.#lines = lines;
+	}
+	invalidate(): void {}
+	render(): string[] {
+		return [...this.#lines];
+	}
+}
+
+export interface ProtocolProbeOptions {
+	image: SampleImage;
+	imageBudget: ImageBudget;
+	/** Whether the desktop notification was suppressed (e.g. `PI_NOTIFICATIONS=off`). */
+	notificationSuppressed: boolean;
+}
+
+/**
+ * Self-contained panel that renders one sample of every special terminal
+ * protocol into the chat transcript.
+ */
+export class ProtocolProbeComponent extends Container {
+	constructor(options: ProtocolProbeOptions) {
+		super();
+		const hyperlinksOn = TERMINAL.hyperlinks;
+		const sizingOn = TERMINAL.textSizing;
+		const yesNo = (on: boolean) => (on ? theme.fg("success", "supported") : theme.fg("muted", "unsupported"));
+
+		this.addChild(new DynamicBorder());
+		this.addChild(new Text(theme.bold(theme.fg("accent", "Terminal Protocol Test")), 1, 0));
+
+		// Styling: SGR attributes, themed foregrounds, and a truecolor sweep.
+		const styling = [
+			theme.fg("muted", "Styling (SGR)"),
+			`  ${theme.bold("bold")}  ${theme.italic("italic")}  ${theme.underline("underline")}  ${theme.strikethrough("strike")}  ${theme.inverse(" inverse ")}  ${theme.fg("dim", "dim")}`,
+			`  ${theme.fg("accent", "accent")}  ${theme.fg("success", "success")}  ${theme.fg("warning", "warning")}  ${theme.fg("error", "error")}`,
+			`  truecolor: ${truecolorBar(32)} (${theme.fg("muted", `24-bit ${TERMINAL.trueColor ? "on" : "off"}`)})`,
+		].join("\n");
+		this.addChild(new Text(styling, 1, 0));
+		this.addChild(new Spacer(1));
+
+		// Hyperlinks: OSC 8. Renders as plain text where unsupported.
+		this.addChild(
+			new Text(
+				[
+					`${theme.fg("muted", "Hyperlinks (OSC 8)")} — ${yesNo(hyperlinksOn)}`,
+					`  \x1b]8;;https://github.com/can1357/oh-my-pi\x07oh-my-pi repo\x1b]8;;\x07`,
+				].join("\n"),
+				1,
+				0,
+			),
+		);
+		this.addChild(new Spacer(1));
+
+		// Text sizing: OSC 66.
+		this.addChild(new Text(`${theme.fg("muted", "Text sizing (OSC 66)")} — ${yesNo(sizingOn)}`, 1, 0));
+		if (sizingOn) {
+			this.addChild(new RawLines(buildLargeTextLines()));
+		} else {
+			this.addChild(
+				new Text(theme.fg("dim", "  (enable via the tui.textSizing setting on a Kitty terminal)"), 1, 0),
+			);
+		}
+		this.addChild(new Spacer(1));
+
+		// Graphics: Kitty / iTerm2 / Sixel, with a text fallback baked into Image.
+		this.addChild(new Text(`${theme.fg("muted", "Graphics")} — ${theme.fg("dim", imageProtocolLabel())}`, 1, 0));
+		this.addChild(
+			new Image(
+				options.image.base64,
+				options.image.mimeType,
+				{ fallbackColor: (text: string) => theme.fg("toolOutput", text) },
+				// Fixed modest caps (not the user's inline-image setting) keep the
+				// swatch a crisp, bounded preview rather than an upscaled wall.
+				{ maxWidthCells: 20, maxHeightCells: 16, budget: options.imageBudget },
+				options.image.dimensions,
+			),
+		);
+		this.addChild(new Spacer(1));
+
+		// Notifications: fired by the caller; this line reports the outcome.
+		const notifyStatus = options.notificationSuppressed
+			? theme.fg("warning", "suppressed (PI_NOTIFICATIONS)")
+			: theme.fg("success", "sent — check your desktop / titlebar");
+		this.addChild(
+			new Text(
+				`${theme.fg("muted", "Notification")} (${theme.fg("dim", notifyProtocolLabel())}) — ${notifyStatus}`,
+				1,
+				0,
+			),
+		);
+		this.addChild(new DynamicBorder());
+	}
+}

package/src/debug/terminal-info.ts

@@ -0,0 +1,127 @@
+/**
+ * Terminal state collection for the debug menu.
+ *
+ * Surfaces the detected terminal, the established subprotocols the renderer
+ * negotiated (graphics, desktop notifications, hyperlinks, true color), the
+ * scrollback/erase strategy, and the live geometry — the details that decide
+ * which escape sequences the renderer emits.
+ */
+import {
+	getCellDimensions,
+	ImageProtocol,
+	isOsc99Supported,
+	NotifyProtocol,
+	TERMINAL,
+	TERMINAL_ID,
+} from "@oh-my-pi/pi-tui";
+
+/** Live values the debug view reads off the running TUI, not the static capability table. */
+export interface TerminalRuntimeState {
+	columns: number;
+	rows: number;
+	/** Whether DEC 2026 synchronized-output wrappers are currently emitted. */
+	synchronizedOutput: boolean;
+}
+
+export interface TerminalStateInfo {
+	detectedId: string;
+	columns: number;
+	rows: number;
+	cellWidthPx: number;
+	cellHeightPx: number;
+	trueColor: boolean;
+	imageProtocol: string;
+	notifyProtocol: string;
+	osc99Confirmed: boolean;
+	hyperlinks: boolean;
+	deccara: boolean;
+	screenToScrollback: boolean;
+	eagerEraseScrollbackRisk: boolean;
+	synchronizedOutput: boolean;
+	multiplexer: string | null;
+	env: { TERM?: string; TERM_PROGRAM?: string; TERM_PROGRAM_VERSION?: string; COLORTERM?: string };
+}
+
+const IMAGE_PROTOCOL_NAMES: Record<ImageProtocol, string> = {
+	[ImageProtocol.Kitty]: "Kitty graphics",
+	[ImageProtocol.Iterm2]: "iTerm2 inline images",
+	[ImageProtocol.Sixel]: "Sixel",
+};
+
+const NOTIFY_PROTOCOL_NAMES: Record<NotifyProtocol, string> = {
+	[NotifyProtocol.Bell]: "BEL (\\a)",
+	[NotifyProtocol.Osc99]: "OSC 99 (kitty desktop notifications)",
+	[NotifyProtocol.Osc9]: "OSC 9 (iTerm2/WezTerm)",
+};
+
+/** Identify the multiplexer wrapping the session, if any (mirrors the renderer's gate). */
+function detectMultiplexer(env: NodeJS.ProcessEnv): string | null {
+	if (env.TMUX) return "tmux";
+	if (env.STY) return "screen";
+	if (env.ZELLIJ) return "zellij";
+	const term = env.TERM?.toLowerCase() ?? "";
+	if (term.startsWith("tmux")) return "tmux";
+	if (term.startsWith("screen")) return "screen";
+	return null;
+}
+
+/** Snapshot the active terminal capabilities and the live runtime geometry. */
+export function collectTerminalState(runtime: TerminalRuntimeState): TerminalStateInfo {
+	const env = Bun.env;
+	const cell = getCellDimensions();
+	return {
+		detectedId: TERMINAL_ID,
+		columns: runtime.columns,
+		rows: runtime.rows,
+		cellWidthPx: cell.widthPx,
+		cellHeightPx: cell.heightPx,
+		trueColor: TERMINAL.trueColor,
+		imageProtocol: TERMINAL.imageProtocol === null ? "none" : IMAGE_PROTOCOL_NAMES[TERMINAL.imageProtocol],
+		notifyProtocol: NOTIFY_PROTOCOL_NAMES[TERMINAL.notifyProtocol],
+		osc99Confirmed: isOsc99Supported(),
+		hyperlinks: TERMINAL.hyperlinks,
+		deccara: TERMINAL.deccara,
+		screenToScrollback: TERMINAL.supportsScreenToScrollback,
+		eagerEraseScrollbackRisk: TERMINAL.eagerEraseScrollbackRisk,
+		synchronizedOutput: runtime.synchronizedOutput,
+		multiplexer: detectMultiplexer(env),
+		env: {
+			TERM: env.TERM,
+			TERM_PROGRAM: env.TERM_PROGRAM,
+			TERM_PROGRAM_VERSION: env.TERM_PROGRAM_VERSION,
+			COLORTERM: env.COLORTERM,
+		},
+	};
+}
+
+const yesNo = (value: boolean): string => (value ? "yes" : "no");
+
+/** Format terminal state for display in the debug menu. */
+export function formatTerminalState(info: TerminalStateInfo): string {
+	const lines = [
+		"Terminal State",
+		"━━━━━━━━━━━━━━",
+		`Detected:     ${info.detectedId}`,
+		`Geometry:     ${info.columns}x${info.rows} cells · cell ${info.cellWidthPx}x${info.cellHeightPx}px`,
+		info.multiplexer ? `Multiplexer:  ${info.multiplexer}` : "Multiplexer:  none",
+		"",
+		"Subprotocols",
+		`  Graphics:     ${info.imageProtocol}`,
+		`  Notify:       ${info.notifyProtocol}${info.osc99Confirmed ? " · confirmed via DA" : ""}`,
+		`  Hyperlinks:   ${yesNo(info.hyperlinks)} (OSC 8)`,
+		`  True color:   ${yesNo(info.trueColor)} (24-bit SGR)`,
+		`  DECCARA:      ${yesNo(info.deccara)} (rectangular-SGR background fills)`,
+		`  Sync output:  ${yesNo(info.synchronizedOutput)} (DEC 2026)`,
+		"",
+		"Scrollback",
+		`  Screen->history clear: ${info.screenToScrollback ? "CSI 22 J" : "CSI 2 J (redraw)"}`,
+		`  Eager-erase risk:      ${yesNo(info.eagerEraseScrollbackRisk)} (ED3 may yank scrolled readers)`,
+		"",
+		"Detection signals",
+		`  TERM:                 ${info.env.TERM ?? "(unset)"}`,
+		`  TERM_PROGRAM:         ${info.env.TERM_PROGRAM ?? "(unset)"}`,
+		`  TERM_PROGRAM_VERSION: ${info.env.TERM_PROGRAM_VERSION ?? "(unset)"}`,
+		`  COLORTERM:            ${info.env.COLORTERM ?? "(unset)"}`,
+	];
+	return lines.join("\n");
+}