@oh-my-pi/pi-tui 16.0.2 → 16.0.3

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## [Unreleased]
 
+## [16.0.3] - 2026-06-16
+
+### Added
+
+- Added `\tfrac` support to stacked display-math rendering so it now displays as a vertical fraction in `latexToBlock` output
+- Added markdown parsing for own-line display-math blocks (`$$...$$` and `\[...\]`) and delimiter-free `\begin{...}...\end{...}` math environments so block equations render via LaTeX-to-Unicode
+- Added stacked rendering of display-math fractions (`\frac`, `\dfrac`, `\cfrac`): the numerator is drawn over a horizontal bar over the denominator, with surrounding terms and `align`/`equation`-style environment rows aligned to the bar. Triggered for own-line `$$`/`\[` blocks, bare `\begin{...}` environments, and a paragraph whose sole content is a single display-math span; inline `$...$` fractions stay single-line (`½`, `(a+b)/c`)
+- Added bare math auto-rendering in `renderMathInText` for math-shaped lines and math environment blocks that omit `$`/`\(` delimiters
+- Added LaTeX-to-Unicode rendering for markdown math spans, converting `$$...$$`, `$...$`, `\(...\)`, and `\[...\]` into readable Unicode in Markdown output
+- Exported LaTeX conversion helpers from the package entrypoint so consumers can call `latexToUnicode`, `latexToBlock`, `renderMathInText`, `inlineMathSpanEnd`, and `isBareMathEnvironment` directly
+- Expanded LaTeX-to-Unicode conversion coverage for additional math fonts, delimiters, extensible arrows, layout environments, cancel/brace annotations, references, and AMS symbols
+- Added ANSI color rendering for LaTeX `\textcolor`, scoped `\color`, `\colorbox`, and `\fcolorbox`, including xcolor/CSS color parsing and truecolor/256-color terminal output
+- Added an optional `maxWidth` parameter to `MarkdownTheme.resolveMermaidAscii` to allow diagram resolvers to fit ASCII output to the available content width
+
+### Changed
+
+- Changed markdown math rendering to preserve multiline layout for display equations, keeping `\\` row breaks as separate output lines (including inside list items)
+
+### Fixed
+
+- Fixed `alignat`/`alignedat`/`gatheredat` rendering in `latexToBlock` so the required `{n}` preamble is not rendered as visible math content
+- Fixed math parsing to leave non-math LaTeX snippets (for example `\begin{itemize}`) and fenced code blocks as literal text instead of rendering them as math
+- Fixed `renderInlineMarkdown` to handle top-level display-math tokens so raw `$$...$$` delimiters are no longer leaked
+- Fixed inline math span detection so escaped dollars and currency-like patterns (such as `$5` and `$10`) are not converted as math
+- Fixed Mermaid diagram rendering in Markdown code blocks to clip each ASCII line to content width before wrapping, preventing preformatted diagram rows from fragmenting
+- Fixed fullscreen overlays losing keyboard focus to hidden prompt surfaces, which could make settings unresponsive while a background approval request was pending ([#2789](https://github.com/can1357/oh-my-pi/issues/2789)).
+- Fixed `bun test` runs inside a real terminal leaking TUI output: `ProcessTerminal` now honors a headless test-runtime default, so frame paints, `start()` capability probes (OSC 11 / DA1 / kitty), the progress keepalive, notifications, and teardown escapes no longer reach the developer's terminal, and stdin raw mode is never engaged. Previously `#safeWrite` only skipped on `!process.stdout.isTTY`, so a developer running the suite in an interactive terminal saw stray status/editor boxes and probe queries. Terminal-contract suites opt back into real I/O via `setTerminalHeadless(false)`
+
 ## [16.0.2] - 2026-06-16
 
 ### Fixed

package/dist/types/components/markdown.d.ts

@@ -44,7 +44,7 @@ export interface MarkdownTheme {
      * Resolve a mermaid ASCII rendering by fenced block source text.
      * Return null to fall back to fenced code rendering.
      */
-    resolveMermaidAscii?: (source: string) => string | null;
+    resolveMermaidAscii?: (source: string, maxWidth?: number) => string | null;
     symbols: SymbolTheme;
 }
 export declare class Markdown implements Component {

package/dist/types/index.d.ts

@@ -19,6 +19,8 @@ export * from "./fuzzy";
 export * from "./keybindings";
 export * from "./keys";
 export * from "./kitty-graphics";
+export * from "./latex-block";
+export * from "./latex-to-unicode";
 export * from "./mouse";
 export * from "./stdin-buffer";
 export type * from "./symbols";

package/dist/types/latex-block.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Render a display LaTeX math fragment to lines, stacking `\frac` vertically.
+ * Top-level source newlines become vertical rows (so a `lhs =` line stays above
+ * its block); each row stacks fractions via `parseExpr`. Inline math should use
+ * `latexToUnicode` instead — fractions there stay single-line.
+ */
+export declare function latexToBlock(src: string): string[];

package/dist/types/latex-to-unicode.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Convert a bare LaTeX math fragment (no surrounding `$`/`\(` delimiters) to its
+ * best-effort Unicode rendering. Unknown commands degrade to their bare name;
+ * `\\` becomes a newline. Always returns a string (never throws).
+ */
+export declare function latexToUnicode(src: string): string;
+/**
+ * True when `env` is a math environment safe to auto-render without `$`/`\[`
+ * delimiters. The trailing `*` of starred variants (`align*`, `equation*`) is
+ * ignored; text-mode environments (`tabular`, `itemize`, …) return false.
+ */
+export declare function isBareMathEnvironment(env: string): boolean;
+/**
+ * Scan prose for math spans — `$$…$$`, `\[…\]` (display) and `$…$`, `\(…\)`
+ * (inline) — and replace each with its Unicode rendering, leaving everything
+ * else verbatim. Newlines inside a span collapse to spaces so the result stays
+ * single-line-safe.
+ *
+ * Inline `$…$` uses pandoc's anti-currency heuristics: the opener must not be
+ * followed by whitespace, the closer must not be preceded by whitespace nor
+ * followed by a digit, and `\$` is treated as a literal dollar — so "$5 and
+ * $10" is left untouched.
+ */
+export declare function renderMathInText(text: string): string;
+/**
+ * Index of the `$` that closes an inline math span opened at `open` (the index
+ * of the opening `$`), or -1 when the run is not inline math. Applies pandoc's
+ * anti-currency heuristics: the opener must not be followed by whitespace, the
+ * closer must not be preceded by whitespace nor followed by a digit, `\$` is a
+ * literal dollar, and the span may not span a newline. Shared by
+ * `renderMathInText` and the markdown math tokenizer so the rule has one home.
+ */
+export declare function inlineMathSpanEnd(text: string, open: number): number;

package/dist/types/tui.d.ts

@@ -66,6 +66,11 @@ export interface Component {
      */
     dispose?(): void;
 }
+/** Lets an overlay root delegate keyboard focus to components it owns. */
+export interface OverlayFocusOwner {
+    /** Returns true when `component` is a focus target inside this overlay. */
+    ownsOverlayFocusTarget(component: Component): boolean;
+}
 /**
  * Component seam for append-only native-scrollback commits. A component that
  * renders a finalized prefix followed by a live/mutating suffix reports the

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "16.0.2",
+	"version": "16.0.3",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -37,8 +37,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "16.0.2",
-		"@oh-my-pi/pi-utils": "16.0.2",
+		"@oh-my-pi/pi-natives": "16.0.3",
+		"@oh-my-pi/pi-utils": "16.0.3",
 		"lru-cache": "11.5.1",
 		"marked": "^18.0.5"
 	},

package/src/components/markdown.ts

@@ -1,14 +1,18 @@
 import { LRUCache } from "lru-cache/raw";
-import { Marked, marked, type Token, Tokenizer, type Tokens } from "marked";
+import { Marked, type Token, Tokenizer, type TokenizerAndRendererExtension, type Tokens } from "marked";
+import { latexToBlock } from "../latex-block";
+import { inlineMathSpanEnd, isBareMathEnvironment, latexToUnicode } from "../latex-to-unicode";
 import type { SymbolTheme } from "../symbols";
 import { TERMINAL } from "../terminal-capabilities";
 import type { Component } from "../tui";
 import {
 	applyBackgroundToLine,
+	Ellipsis,
 	encodeTextSized,
 	getSegmenter,
 	padding,
 	replaceTabs,
+	truncateToWidth,
 	visibleWidth,
 	wrapTextWithAnsi,
 } from "../utils";
@@ -48,6 +52,126 @@ markdownParser.setOptions({
 	tokenizer: new StrictStrikethroughTokenizer(),
 });
 
+// Math spans (`$$…$$`, `\[…\]`, `$…$`, `\(…\)`) are tokenized as a dedicated
+// `math` inline token before markdown's escape/emphasis/link rules run, so
+// backslash commands (`\frac`, `\alpha`) and intraword underscores (`x_i`)
+// survive intact instead of being mangled or split. The `$…$` form uses
+// pandoc's anti-currency heuristic (`inlineMathSpanEnd`) so "$5 and $10" is
+// never math. Inline extensions run before marked's escape tokenizer, so
+// `\(…\)` becomes math while a genuinely escaped `\$` is left to `escape` and
+// renders as a literal dollar.
+const mathExtension: TokenizerAndRendererExtension = {
+	name: "math",
+	level: "inline",
+	start(src) {
+		const m = /\$|\\\(|\\\[/.exec(src);
+		return m ? m.index : undefined;
+	},
+	tokenizer(src) {
+		if (src.startsWith("$$")) {
+			const end = src.indexOf("$$", 2);
+			if (end !== -1 && src.slice(2, end).trim().length > 0) {
+				return { type: "math", raw: src.slice(0, end + 2), text: src.slice(2, end), display: true };
+			}
+			return undefined;
+		}
+		if (src.startsWith("\\[")) {
+			const end = src.indexOf("\\]", 2);
+			if (end !== -1) return { type: "math", raw: src.slice(0, end + 2), text: src.slice(2, end), display: true };
+			return undefined;
+		}
+		if (src.startsWith("\\(")) {
+			const end = src.indexOf("\\)", 2);
+			if (end !== -1) return { type: "math", raw: src.slice(0, end + 2), text: src.slice(2, end), display: false };
+			return undefined;
+		}
+		if (src.charCodeAt(0) === 0x24 /* $ */) {
+			const end = inlineMathSpanEnd(src, 0);
+			if (end !== -1) return { type: "math", raw: src.slice(0, end + 1), text: src.slice(1, end), display: false };
+		}
+		return undefined;
+	},
+	renderer(token) {
+		return (token as { text?: string }).text ?? "";
+	},
+};
+
+// Display math blocks: opening `$$` / `\[` and closing `$$` / `\]` each alone on
+// their own line (≤3 leading spaces). Matched at the block level — before
+// paragraph/list parsing — so a multi-line equation (e.g. a matrix with `\\`
+// row breaks) renders across several lines instead of being collapsed onto one,
+// and blank lines inside the block don't split it. The own-line requirement
+// keeps inline `$$…$$` inside prose for the inline tokenizer above.
+const MATH_BLOCK_DOLLAR = /^ {0,3}\$\$[ \t]*\n([\s\S]+?)\n {0,3}\$\$[ \t]*(?:\n|$)/;
+const MATH_BLOCK_BRACKET = /^ {0,3}\\\[[ \t]*\n([\s\S]+?)\n {0,3}\\\][ \t]*(?:\n|$)/;
+const MATH_BLOCK_START = /(?:^|\n) {0,3}(?:\$\$|\\\[)[ \t]*\n/;
+const mathBlockExtension: TokenizerAndRendererExtension = {
+	name: "mathBlock",
+	level: "block",
+	start(src) {
+		const m = MATH_BLOCK_START.exec(src);
+		return m ? m.index : undefined;
+	},
+	tokenizer(src) {
+		const m = MATH_BLOCK_DOLLAR.exec(src) ?? MATH_BLOCK_BRACKET.exec(src);
+		if (!m || m[1].trim().length === 0) return undefined;
+		return { type: "math", raw: m[0], text: m[1], display: true };
+	},
+	renderer(token) {
+		return (token as { text?: string }).text ?? "";
+	},
+};
+
+// Bare (delimiter-less) display-math environments: `\begin{<mathenv>}…\end{…}`
+// written without `$$`/`\[` fences (common in raw model output). Captured at the
+// block level as a whole unit — including any immediately preceding `lhs =`
+// line — so marked never splits it on inline `\\` row breaks. Restricted to math
+// environments (isBareMathEnvironment), and the `≤3 leading spaces` + "block
+// starts at offset 0" guards keep fenced/indented `\begin{cases}` code blocks
+// for marked's own code rules.
+const BARE_ENV_BEGIN = /(?:^|\n)[ \t]{0,3}\\begin\{([A-Za-z]+\*?)\}/;
+function bareMathEnvBlock(src: string): readonly [number, number] | null {
+	const bm = BARE_ENV_BEGIN.exec(src);
+	if (!bm || !isBareMathEnvironment(bm[1])) return null;
+	const beginLineStart = bm.index === 0 ? 0 : bm.index + 1; // skip the matched leading `\n`
+	const endToken = `\\end{${bm[1]}}`;
+	const endAt = src.indexOf(endToken, bm.index);
+	if (endAt === -1) return null;
+	// The `\end` must close before any blank line (i.e. within the same block).
+	if (/\n[ \t]*\n/.test(src.slice(beginLineStart, endAt))) return null;
+	let blockEnd = endAt + endToken.length;
+	while (src[blockEnd] === " " || src[blockEnd] === "\t") blockEnd++;
+	if (src[blockEnd] === "\n") blockEnd++;
+	// Pull in one immediately-preceding `lhs =`/open-delimiter line (e.g. `f(x) =`).
+	let start = beginLineStart;
+	if (start > 0 && src[start - 1] === "\n") {
+		const prevStart = src.lastIndexOf("\n", start - 2) + 1;
+		const prevLine = src.slice(prevStart, start - 1);
+		if (/[=([{]\s*$/.test(prevLine)) start = prevStart;
+	}
+	return [start, blockEnd];
+}
+const mathEnvBlockExtension: TokenizerAndRendererExtension = {
+	name: "mathEnvBlock",
+	level: "block",
+	start(src) {
+		const r = bareMathEnvBlock(src);
+		return r ? r[0] : undefined;
+	},
+	tokenizer(src) {
+		const r = bareMathEnvBlock(src);
+		if (r?.[0] !== 0) return undefined; // only consume when the block starts at offset 0
+		const raw = src.slice(0, r[1]);
+		const text = raw.replace(/\n[ \t]*$/, "");
+		if (text.trim().length === 0) return undefined;
+		return { type: "math", raw, text, display: true };
+	},
+	renderer(token) {
+		return (token as { text?: string }).text ?? "";
+	},
+};
+markdownParser.use({ extensions: [mathBlockExtension, mathEnvBlockExtension, mathExtension] });
+
 // ---------------------------------------------------------------------------
 // Module-level LRU render cache
 // ---------------------------------------------------------------------------
@@ -131,7 +255,7 @@ export interface MarkdownTheme {
 	 * Resolve a mermaid ASCII rendering by fenced block source text.
 	 * Return null to fall back to fenced code rendering.
 	 */
-	resolveMermaidAscii?: (source: string) => string | null;
+	resolveMermaidAscii?: (source: string, maxWidth?: number) => string | null;
 	symbols: SymbolTheme;
 }
 
@@ -186,9 +310,46 @@ function encodeTextSizedHeading(text: string, scale: 1 | 2 | 3): string {
 	return out;
 }
 
+const MATH_NEWLINES = /\n+/g;
+
+/** True for the custom inline `math` token produced by the math extension. */
+function isMathToken(token: Token): token is Token & { text: string; display: boolean } {
+	return (token as { type: string }).type === "math";
+}
+
+/** Convert a `math` token's LaTeX to single-line Unicode for inline rendering. */
+function renderMathToken(text: string): string {
+	return latexToUnicode(text).replace(MATH_NEWLINES, " ");
+}
+
+/**
+ * When a paragraph's only meaningful content is a single display math token
+ * (`$$…$$` / `\[…\]`), return it so the paragraph can be stacked multi-line
+ * instead of flattened inline. Models routinely write display math on one line,
+ * which marked captures as an inline `display:true` math token inside a
+ * paragraph; without this it would flatten through `renderMathToken`.
+ */
+function soleDisplayMath(tokens?: Token[]): (Token & { text: string }) | null {
+	if (!tokens) return null;
+	let math: (Token & { text: string; display: boolean }) | null = null;
+	for (const token of tokens) {
+		if (isMathToken(token) && token.display) {
+			if (math) return null;
+			math = token;
+		} else if (!(token.type === "text" && typeof token.text === "string" && token.text.trim() === "")) {
+			return null;
+		}
+	}
+	return math;
+}
+
 function plainInlineTokens(tokens: Token[]): string {
 	let result = "";
 	for (const token of tokens) {
+		if (isMathToken(token)) {
+			result += renderMathToken(token.text);
+			continue;
+		}
 		switch (token.type) {
 			case "text":
 				result += token.tokens && token.tokens.length > 0 ? plainInlineTokens(token.tokens) : token.text;
@@ -658,6 +819,14 @@ export class Markdown implements Component {
 	#renderToken(token: Token, width: number, nextTokenType?: string, styleContext?: InlineStyleContext): string[] {
 		const lines: string[] = [];
 
+		// Display math block (own-line `$$…$$` / `\[…\]`): stack `\frac` vertically
+		// and keep `\\` row breaks, so fractions and matrices span multiple lines.
+		if (isMathToken(token)) {
+			for (const mathLine of latexToBlock(token.text)) lines.push(this.#applyDefaultStyle(mathLine));
+			if (nextTokenType && nextTokenType !== "space") lines.push("");
+			return lines;
+		}
+
 		switch (token.type) {
 			case "heading": {
 				const headingLevel = token.depth;
@@ -692,6 +861,12 @@ export class Markdown implements Component {
 			}
 
 			case "paragraph": {
+				const displayMath = soleDisplayMath(token.tokens);
+				if (displayMath) {
+					for (const mathLine of latexToBlock(displayMath.text)) lines.push(this.#applyDefaultStyle(mathLine));
+					if (nextTokenType && nextTokenType !== "list" && nextTokenType !== "space") lines.push("");
+					break;
+				}
 				const paragraphText = this.#renderInlineTokens(token.tokens || [], styleContext);
 				lines.push(paragraphText);
 				// Don't add spacing if next token is space or list
@@ -702,13 +877,18 @@ export class Markdown implements Component {
 			}
 
 			case "code": {
-				// Handle mermaid diagrams with ASCII rendering when available
+				// Mermaid diagrams render as ASCII art when the theme supplies a
+				// resolver. The art is preformatted, so clip each row to the content
+				// width: the later wrap pass would otherwise fragment the box-drawing
+				// canvas. truncateToWidth is ANSI- and wide-char-aware, and the
+				// resolver already re-fits over-wide horizontal graphs top-down.
 				if (token.lang === "mermaid" && this.#theme.resolveMermaidAscii) {
-					const ascii = this.#theme.resolveMermaidAscii(token.text);
-
+					const ascii = this.#theme.resolveMermaidAscii(token.text, width);
 					if (ascii) {
-						for (const asciiLine of Bun.stripANSI(ascii).split("\n")) {
-							lines.push(asciiLine);
+						for (const asciiLine of ascii.split("\n")) {
+							lines.push(
+								visibleWidth(asciiLine) > width ? truncateToWidth(asciiLine, width, Ellipsis.Omit) : asciiLine,
+							);
 						}
 						if (nextTokenType && nextTokenType !== "space") {
 							lines.push("");
@@ -839,6 +1019,10 @@ export class Markdown implements Component {
 		const swatchGlyph = this.#theme.symbols.colorSwatch || DEFAULT_COLOR_SWATCH_GLYPH;
 
 		for (const token of tokens) {
+			if (isMathToken(token)) {
+				result += applyTextWithNewlines(renderMathToken(token.text));
+				continue;
+			}
 			switch (token.type) {
 				case "text":
 					// Text tokens in list items can have nested tokens for inline formatting
@@ -996,16 +1180,29 @@ export class Markdown implements Component {
 					lines.push({ text: nestedLine, nested: true });
 				}
 			} else if (token.type === "text") {
-				// Text content (may have inline tokens)
-				const text =
-					token.tokens && token.tokens.length > 0
-						? this.#renderInlineTokens(token.tokens, styleContext)
-						: token.text || "";
-				lines.push({ text, nested: false });
+				// Text content (may have inline tokens, or a sole display-math token)
+				const displayMath = soleDisplayMath(token.tokens);
+				if (displayMath) {
+					const apply = styleContext?.applyText ?? ((t: string) => this.#applyDefaultStyle(t));
+					for (const mathLine of latexToBlock(displayMath.text))
+						lines.push({ text: apply(mathLine), nested: false });
+				} else {
+					const text =
+						token.tokens && token.tokens.length > 0
+							? this.#renderInlineTokens(token.tokens, styleContext)
+							: token.text || "";
+					lines.push({ text, nested: false });
+				}
 			} else if (token.type === "paragraph") {
 				// Paragraph in list item
-				const text = this.#renderInlineTokens(token.tokens || [], styleContext);
-				lines.push({ text, nested: false });
+				const apply = styleContext?.applyText ?? ((t: string) => this.#applyDefaultStyle(t));
+				const displayMath = soleDisplayMath(token.tokens);
+				if (displayMath) {
+					for (const mathLine of latexToBlock(displayMath.text))
+						lines.push({ text: apply(mathLine), nested: false });
+				} else {
+					lines.push({ text: this.#renderInlineTokens(token.tokens || [], styleContext), nested: false });
+				}
 			} else if (token.type === "code") {
 				// Code block in list item
 				const codeIndent = padding(this.#codeBlockIndent);
@@ -1022,6 +1219,10 @@ export class Markdown implements Component {
 					}
 				}
 				lines.push({ text: this.#theme.codeBlockBorder("```"), nested: false });
+			} else if (isMathToken(token)) {
+				// Display math block inside a list item: stack fractions / matrix rows.
+				const apply = styleContext?.applyText ?? ((t: string) => this.#applyDefaultStyle(t));
+				for (const mathLine of latexToBlock(token.text)) lines.push({ text: apply(mathLine), nested: false });
 			} else {
 				// Other token types - try to render as inline
 				const text = this.#renderInlineTokens([token], styleContext);
@@ -1249,10 +1450,14 @@ export class Markdown implements Component {
 export function renderInlineMarkdown(text: string, mdTheme: MarkdownTheme, baseColor?: (t: string) => string): string {
 	// Guard against undefined/null during streaming — partial JSON can leave fields unpopulated.
 	if (typeof text !== "string") return (baseColor ?? (t => t))(text != null ? String(text) : "");
-	const tokens = marked.lexer(text);
+	const tokens = markdownParser.lexer(text);
 	const applyText = baseColor ?? ((t: string) => t);
 	let result = "";
 	for (const token of tokens) {
+		if (isMathToken(token)) {
+			result += applyText(renderMathToken(token.text));
+			continue;
+		}
 		if (token.type === "paragraph" && token.tokens) {
 			result += renderInlineTokens(token.tokens, mdTheme, applyText);
 		} else if (token.type === "list") {
@@ -1274,6 +1479,10 @@ function renderInlineTokens(tokens: Token[], mdTheme: MarkdownTheme, applyText:
 	let result = "";
 	const styleReset = applyText("");
 	for (const token of tokens) {
+		if (isMathToken(token)) {
+			result += applyText(renderMathToken(token.text));
+			continue;
+		}
 		switch (token.type) {
 			case "text":
 				if (token.tokens && token.tokens.length > 0) {

package/src/index.ts

@@ -29,6 +29,9 @@ export * from "./keybindings";
 export * from "./keys";
 // Kitty graphics: Unicode placeholders
 export * from "./kitty-graphics";
+// LaTeX → Unicode/ANSI math rendering
+export * from "./latex-block";
+export * from "./latex-to-unicode";
 // SGR mouse report parsing
 export * from "./mouse";
 // Mermaid diagram support