@oh-my-pi/pi-tui 8.0.20 → 8.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-tui",
-	"version": "8.0.20",
+	"version": "8.1.0",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"type": "module",
 	"main": "src/index.ts",
@@ -10,8 +10,7 @@
 	},
 	"files": [
 		"src/**/*",
-		"README.md",
-		"tsconfig.json"
+		"README.md"
 	],
 	"keywords": [
 		"tui",
@@ -43,12 +42,5 @@
 	"devDependencies": {
 		"@xterm/headless": "^5.5.0",
 		"@xterm/xterm": "^5.5.0"
-	},
-	"exports": {
-		".": {
-			"types": "./src/index.ts",
-			"import": "./src/index.ts"
-		},
-		"./*": "./src/*"
 	}
 }

package/src/components/markdown.ts

@@ -1,4 +1,6 @@
+import type { MermaidImage } from "@oh-my-pi/pi-tui/mermaid";
 import type { SymbolTheme } from "@oh-my-pi/pi-tui/symbols";
+import { encodeITerm2, encodeKitty, getCapabilities, getCellDimensions } from "@oh-my-pi/pi-tui/terminal-image";
 import type { Component } from "@oh-my-pi/pi-tui/tui";
 import { applyBackgroundToLine, visibleWidth, wrapTextWithAnsi } from "@oh-my-pi/pi-tui/utils";
 import { marked, type Token } from "marked";
@@ -42,6 +44,12 @@ export interface MarkdownTheme {
 	strikethrough: (text: string) => string;
 	underline: (text: string) => string;
 	highlightCode?: (code: string, lang?: string) => string[];
+	/**
+	 * Lookup a pre-rendered mermaid image by source hash.
+	 * Hash is computed as `Bun.hash(source.trim()).toString(16)`.
+	 * Return null to fall back to text rendering.
+	 */
+	getMermaidImage?: (sourceHash: string) => MermaidImage | null;
 	symbols: SymbolTheme;
 }
 
@@ -125,7 +133,12 @@ export class Markdown implements Component {
 		// Wrap lines (NO padding, NO background yet)
 		const wrappedLines: string[] = [];
 		for (const line of renderedLines) {
-			wrappedLines.push(...wrapTextWithAnsi(line, contentWidth));
+			// Skip wrapping for image protocol lines (would corrupt escape sequences)
+			if (this.containsImage(line)) {
+				wrappedLines.push(line);
+			} else {
+				wrappedLines.push(...wrapTextWithAnsi(line, contentWidth));
+			}
 		}
 
 		// Add margins and background to each wrapped line
@@ -135,6 +148,12 @@ export class Markdown implements Component {
 		const contentLines: string[] = [];
 
 		for (const line of wrappedLines) {
+			// Image lines must be output raw - no margins or background
+			if (this.containsImage(line)) {
+				contentLines.push(line);
+				continue;
+			}
+
 			const lineWithMargins = leftMargin + line + rightMargin;
 
 			if (bgFn) {
@@ -267,6 +286,24 @@ export class Markdown implements Component {
 			}
 
 			case "code": {
+				// Handle mermaid diagrams with image rendering when available
+				if (token.lang === "mermaid" && this.theme.getMermaidImage) {
+					const hash = Bun.hash(token.text.trim()).toString(16);
+					const image = this.theme.getMermaidImage(hash);
+					const caps = getCapabilities();
+
+					if (image && caps.images) {
+						const imageLines = this.renderMermaidImage(image, width);
+						if (imageLines) {
+							lines.push(...imageLines);
+							if (nextTokenType !== "space") {
+								lines.push("");
+							}
+							break;
+						}
+					}
+				}
+
 				const codeIndent = " ".repeat(this.codeBlockIndent);
 				lines.push(this.theme.codeBlockBorder(`\`\`\`${token.lang || ""}`));
 				if (this.theme.highlightCode) {
@@ -658,4 +695,63 @@ export class Markdown implements Component {
 		lines.push(""); // Add spacing after table
 		return lines;
 	}
+
+	private containsImage(line: string): boolean {
+		return line.includes("\x1b_G") || line.includes("\x1b]1337;File=");
+	}
+
+	/**
+	 * Render a mermaid image using terminal graphics protocol.
+	 * Returns array of lines (image placeholder rows) or null if rendering fails.
+	 */
+	private renderMermaidImage(image: MermaidImage, availableWidth: number): string[] | null {
+		const caps = getCapabilities();
+		if (!caps.images) return null;
+
+		const cellDims = getCellDimensions();
+		const scale = 0.5; // Render at 50% of natural size
+
+		// Calculate natural size in cells (don't scale up, only down if needed)
+		const naturalColumns = Math.ceil((image.widthPx * scale) / cellDims.widthPx);
+		const naturalRows = Math.ceil((image.heightPx * scale) / cellDims.heightPx);
+
+		// Use natural size, but cap to available width
+		const columns = Math.min(naturalColumns, availableWidth);
+
+		// If we had to shrink width, calculate proportional height
+		let rows: number;
+		if (columns < naturalColumns) {
+			// Scaled down - recalculate height
+			const scale = columns / naturalColumns;
+			rows = Math.max(1, Math.ceil(naturalRows * scale));
+		} else {
+			// Natural size
+			rows = naturalRows;
+		}
+
+		let sequence: string;
+		if (caps.images === "kitty") {
+			sequence = encodeKitty(image.base64, { columns, rows });
+		} else if (caps.images === "iterm2") {
+			sequence = encodeITerm2(image.base64, {
+				width: columns,
+				height: "auto",
+				preserveAspectRatio: true,
+			});
+		} else {
+			return null;
+		}
+
+		// Reserve space with empty lines, then output image with cursor-up
+		// This ensures TUI accounts for image height in layout
+		const lines: string[] = [];
+		for (let i = 0; i < rows - 1; i++) {
+			lines.push("");
+		}
+		// Move cursor up to first row, then output image
+		const moveUp = rows > 1 ? `\x1b[${rows - 1}A` : "";
+		lines.push(moveUp + sequence);
+
+		return lines;
+	}
 }

package/src/components/settings-list.ts

@@ -131,7 +131,7 @@ export class SettingsList implements Component {
 
 		// Add hint
 		lines.push("");
-		lines.push(this.theme.hint("  Enter/Space to change · Esc to cancel"));
+		lines.push(this.theme.hint("Enter/Space to change · Esc to cancel"));
 
 		return lines;
 	}

package/src/index.ts

@@ -47,6 +47,14 @@ export {
 	parseKittySequence,
 	setKittyProtocolActive,
 } from "./keys";
+// Mermaid diagram support
+export {
+	extractMermaidBlocks,
+	type MermaidImage,
+	type MermaidRenderOptions,
+	prerenderMermaidBlocks,
+	renderMermaidToPng,
+} from "./mermaid";
 // Input buffering for batch splitting
 export { StdinBuffer, type StdinBufferEventMap, type StdinBufferOptions } from "./stdin-buffer";
 export type { BoxSymbols, SymbolTheme } from "./symbols";

package/src/mermaid.ts

@@ -0,0 +1,140 @@
+import { mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { $ } from "bun";
+
+export interface MermaidImage {
+	base64: string;
+	widthPx: number;
+	heightPx: number;
+}
+
+export interface MermaidRenderOptions {
+	theme?: "default" | "dark" | "forest" | "neutral";
+	backgroundColor?: string;
+	width?: number;
+	scale?: number;
+}
+
+/**
+ * Render mermaid diagram source to PNG.
+ *
+ * Uses `mmdc` (mermaid-cli) which must be installed and in PATH.
+ * Returns null if rendering fails or mmdc is unavailable.
+ */
+export async function renderMermaidToPng(
+	source: string,
+	options: MermaidRenderOptions = {},
+): Promise<MermaidImage | null> {
+	const mmdc = Bun.which("mmdc");
+	if (!mmdc) {
+		return null;
+	}
+
+	const tmpDir = join(tmpdir(), `mermaid-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+	const inputPath = join(tmpDir, "input.mmd");
+	const outputPath = join(tmpDir, "output.png");
+
+	try {
+		await mkdir(tmpDir, { recursive: true });
+		await Bun.write(inputPath, source);
+
+		const args: string[] = ["-i", inputPath, "-o", outputPath, "-q"];
+
+		if (options.theme) {
+			args.push("-t", options.theme);
+		}
+		if (options.backgroundColor) {
+			args.push("-b", options.backgroundColor);
+		}
+		if (options.width) {
+			args.push("-w", String(options.width));
+		}
+		if (options.scale) {
+			args.push("-s", String(options.scale));
+		}
+
+		const result = await $`${mmdc} ${args}`.quiet().nothrow();
+		if (result.exitCode !== 0) {
+			return null;
+		}
+
+		const outputFile = Bun.file(outputPath);
+		if (!(await outputFile.exists())) {
+			return null;
+		}
+
+		const buffer = Buffer.from(await outputFile.arrayBuffer());
+		const base64 = buffer.toString("base64");
+
+		const dims = parsePngDimensions(buffer);
+		if (!dims) {
+			return null;
+		}
+
+		return {
+			base64,
+			widthPx: dims.width,
+			heightPx: dims.height,
+		};
+	} catch {
+		return null;
+	} finally {
+		await rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+	}
+}
+
+function parsePngDimensions(buffer: Buffer): { width: number; height: number } | null {
+	if (buffer.length < 24) return null;
+	if (buffer[0] !== 0x89 || buffer[1] !== 0x50 || buffer[2] !== 0x4e || buffer[3] !== 0x47) {
+		return null;
+	}
+	return {
+		width: buffer.readUInt32BE(16),
+		height: buffer.readUInt32BE(20),
+	};
+}
+
+/**
+ * Extract mermaid code blocks from markdown text.
+ * Returns array of { source, startIndex, endIndex } for each block.
+ */
+export function extractMermaidBlocks(markdown: string): { source: string; hash: string }[] {
+	const blocks: { source: string; hash: string }[] = [];
+	const regex = /```mermaid\s*\n([\s\S]*?)```/g;
+
+	for (let match = regex.exec(markdown); match !== null; match = regex.exec(markdown)) {
+		const source = match[1].trim();
+		const hash = Bun.hash(source).toString(16);
+		blocks.push({ source, hash });
+	}
+
+	return blocks;
+}
+
+/**
+ * Pre-render all mermaid blocks in markdown text.
+ * Returns a cache map: hash → MermaidImage.
+ */
+export async function prerenderMermaidBlocks(
+	markdown: string,
+	options: MermaidRenderOptions = {},
+): Promise<Map<string, MermaidImage>> {
+	const blocks = extractMermaidBlocks(markdown);
+	const cache = new Map<string, MermaidImage>();
+
+	const results = await Promise.all(
+		blocks.map(async ({ source, hash }) => {
+			const image = await renderMermaidToPng(source, options);
+			return { hash, image };
+		}),
+	);
+
+	for (const { hash, image } of results) {
+		if (image) {
+			cache.set(hash, image);
+		}
+	}
+
+	return cache;
+}

package/src/terminal.ts

@@ -13,20 +13,24 @@ let activeTerminal: ProcessTerminal | null = null;
  * Resets terminal state without requiring access to the ProcessTerminal instance
  */
 export function emergencyTerminalRestore(): void {
-	const terminal = activeTerminal;
-	if (terminal) {
-		terminal.stop();
-		terminal.showCursor();
-	} else {
-		// Blind restore if no instance tracked - covers edge cases
-		process.stdout.write(
-			"\x1b[?2004l" + // Disable bracketed paste
-				"\x1b[<u" + // Pop kitty keyboard protocol
-				"\x1b[?25h", // Show cursor
-		);
-		if (process.stdin.setRawMode) {
-			process.stdin.setRawMode(false);
+	try {
+		const terminal = activeTerminal;
+		if (terminal) {
+			terminal.stop();
+			terminal.showCursor();
+		} else {
+			// Blind restore if no instance tracked - covers edge cases
+			process.stdout.write(
+				"\x1b[?2004l" + // Disable bracketed paste
+					"\x1b[<u" + // Pop kitty keyboard protocol
+					"\x1b[?25h", // Show cursor
+			);
+			if (process.stdin.setRawMode) {
+				process.stdin.setRawMode(false);
+			}
 		}
+	} catch {
+		// Terminal may already be dead during crash cleanup - ignore errors
 	}
 }
 export interface Terminal {
@@ -93,7 +97,7 @@ export class ProcessTerminal implements Terminal {
 		process.stdin.resume();
 
 		// Enable bracketed paste mode - terminal will wrap pastes in \x1b[200~ ... \x1b[201~
-		process.stdout.write("\x1b[?2004h");
+		this.safeWrite("\x1b[?2004h");
 
 		// Set up resize handler immediately
 		process.stdout.on("resize", this.resizeHandler);
@@ -137,7 +141,7 @@ export class ProcessTerminal implements Terminal {
 					// Flag 1 = disambiguate escape codes
 					// Flag 2 = report event types (press/repeat/release)
 					// Flag 4 = report alternate keys
-					process.stdout.write("\x1b[>7u");
+					this.safeWrite("\x1b[>7u");
 					return; // Don't forward protocol response to TUI
 				}
 			}
@@ -172,7 +176,7 @@ export class ProcessTerminal implements Terminal {
 	private queryAndEnableKittyProtocol(): void {
 		this.setupStdinBuffer();
 		process.stdin.on("data", this.stdinDataHandler!);
-		process.stdout.write("\x1b[?u");
+		this.safeWrite("\x1b[?u");
 	}
 
 	stop(): void {
@@ -182,11 +186,11 @@ export class ProcessTerminal implements Terminal {
 		}
 
 		// Disable bracketed paste mode
-		process.stdout.write("\x1b[?2004l");
+		this.safeWrite("\x1b[?2004l");
 
 		// Disable Kitty keyboard protocol (pop the flags we pushed) - only if we enabled it
 		if (this._kittyProtocolActive) {
-			process.stdout.write("\x1b[<u");
+			this.safeWrite("\x1b[<u");
 			this._kittyProtocolActive = false;
 			setKittyProtocolActive(false);
 		}
@@ -215,7 +219,19 @@ export class ProcessTerminal implements Terminal {
 	}
 
 	write(data: string): void {
-		process.stdout.write(data);
+		this.safeWrite(data);
+	}
+
+	private safeWrite(data: string): void {
+		try {
+			process.stdout.write(data);
+		} catch (err) {
+			// EIO means terminal is dead - exit gracefully instead of crashing
+			if (err && typeof err === "object" && (err as { code?: string }).code === "EIO") {
+				process.exit(1);
+			}
+			throw err;
+		}
 	}
 
 	get columns(): number {
@@ -229,36 +245,36 @@ export class ProcessTerminal implements Terminal {
 	moveBy(lines: number): void {
 		if (lines > 0) {
 			// Move down
-			process.stdout.write(`\x1b[${lines}B`);
+			this.safeWrite(`\x1b[${lines}B`);
 		} else if (lines < 0) {
 			// Move up
-			process.stdout.write(`\x1b[${-lines}A`);
+			this.safeWrite(`\x1b[${-lines}A`);
 		}
 		// lines === 0: no movement
 	}
 
 	hideCursor(): void {
-		process.stdout.write("\x1b[?25l");
+		this.safeWrite("\x1b[?25l");
 	}
 
 	showCursor(): void {
-		process.stdout.write("\x1b[?25h");
+		this.safeWrite("\x1b[?25h");
 	}
 
 	clearLine(): void {
-		process.stdout.write("\x1b[K");
+		this.safeWrite("\x1b[K");
 	}
 
 	clearFromCursor(): void {
-		process.stdout.write("\x1b[J");
+		this.safeWrite("\x1b[J");
 	}
 
 	clearScreen(): void {
-		process.stdout.write("\x1b[2J\x1b[H"); // Clear screen and move to home (1,1)
+		this.safeWrite("\x1b[2J\x1b[H"); // Clear screen and move to home (1,1)
 	}
 
 	setTitle(title: string): void {
 		// OSC 0;title BEL - set terminal window title
-		process.stdout.write(`\x1b]0;${title}\x07`);
+		this.safeWrite(`\x1b]0;${title}\x07`);
 	}
 }

package/tsconfig.json

@@ -1,42 +0,0 @@
-{
-	"compilerOptions": {
-		"target": "ES2024",
-		"module": "ESNext",
-		"lib": [
-			"ES2024"
-		],
-		"strict": true,
-		"esModuleInterop": true,
-		"skipLibCheck": true,
-		"forceConsistentCasingInFileNames": true,
-		"moduleResolution": "Bundler",
-		"resolveJsonModule": true,
-		"allowImportingTsExtensions": true,
-		"experimentalDecorators": true,
-		"emitDecoratorMetadata": true,
-		"useDefineForClassFields": false,
-		"types": [
-			"bun",
-			"node"
-		],
-		"noEmit": true,
-		"baseUrl": ".",
-		"paths": {
-			"@oh-my-pi/pi-tui": [
-				"./src/index.ts"
-			],
-			"@oh-my-pi/pi-tui/*": [
-				"./src/*"
-			]
-		}
-	},
-	"include": [
-		"src/**/*.ts"
-	],
-	"exclude": [
-		"node_modules",
-		"dist",
-		"**/*.test.ts",
-		"test/**"
-	]
-}