@oh-my-pi/pi-tui 16.5.2 → 17.0.1

package/src/components/markdown.ts

@@ -4,7 +4,7 @@ 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 type { Component, NativeScrollbackCommittedRows, NativeScrollbackReplay } from "../tui";
 import {
 	applyBackgroundToLine,
 	Ellipsis,
@@ -607,11 +607,17 @@ const RENDER_CACHE_MAX = 256; // sane cap: ~256 distinct message × width combos
 const RENDER_CACHE_MAX_SIZE = 512 * 1024;
 const RENDER_CACHE_MAX_ENTRY_SIZE = 32 * 1024;
 const EMPTY_RENDER_LINES: readonly string[] = [];
-const renderCache = new LRUCache<string, readonly string[]>({
+
+interface RenderCacheEntry {
+	lines: readonly string[];
+	tables: readonly RenderedTableLayout[];
+}
+
+const renderCache = new LRUCache<string, RenderCacheEntry>({
 	max: RENDER_CACHE_MAX,
 	maxSize: RENDER_CACHE_MAX_SIZE,
 	maxEntrySize: RENDER_CACHE_MAX_ENTRY_SIZE,
-	sizeCalculation: renderedLinesCacheSize,
+	sizeCalculation: renderCacheEntrySize,
 });
 
 function renderedLinesCacheSize(lines: readonly string[]): number {
@@ -620,6 +626,12 @@ function renderedLinesCacheSize(lines: readonly string[]): number {
 	return Math.max(1, size);
 }
 
+function renderCacheEntrySize(entry: RenderCacheEntry): number {
+	let size = renderedLinesCacheSize(entry.lines);
+	for (const table of entry.tables) size += table.key.length + table.columnWidths.length + 4;
+	return size;
+}
+
 // A reference-link definition (`[label]: dest`) resolves across the whole
 // document, so a split lex cannot reproduce it — disable the streaming fast path
 // when one is present (rare in streamed output). The label may contain
@@ -951,6 +963,7 @@ interface StreamPrefixLineCache extends RenderSignature {
 	text: string;
 	tokenCount: number;
 	lines: readonly string[];
+	tables: readonly TableRenderSpec[];
 }
 interface StreamingDiffLineCache extends RenderSignature {
 	lang: string | undefined;
@@ -958,7 +971,25 @@ interface StreamingDiffLineCache extends RenderSignature {
 	lines: readonly string[];
 }
 
-export class Markdown implements Component {
+interface TableLayoutLock {
+	availableWidth: number;
+	columnWidths: readonly number[];
+}
+
+interface TableRenderSpec extends TableLayoutLock {
+	key: string;
+	lineCount: number;
+	startRow: number;
+	endRow: number;
+}
+
+interface RenderedTableLayout extends TableLayoutLock {
+	key: string;
+	startRow: number;
+	endRow: number;
+}
+
+export class Markdown implements Component, NativeScrollbackCommittedRows, NativeScrollbackReplay {
 	#text: string;
 	#paddingX: number; // Left/right padding
 	#paddingY: number; // Top/bottom padding
@@ -1005,10 +1036,19 @@ export class Markdown implements Component {
 	#renderingFrozenPrefix = false;
 	#streamingDiffLineCache?: StreamingDiffLineCache;
 	#activeRenderSignature?: RenderSignature;
+	// Streaming tables may grow naturally while wholly repaintable. Once any
+	// physical row of a table enters native scrollback, its current column widths
+	// are locked for the rest of this append-only text lineage: future wider cells
+	// wrap inside those columns instead of reflowing immutable history above.
+	#tableLayoutWidth?: number;
+	#lockedTableLayouts = new Map<string, TableLayoutLock>();
+	#lastRenderedTableLayouts: RenderedTableLayout[] = [];
+	#activeTableRenderSpecs?: TableRenderSpec[];
 
 	#ignoreTight = false;
 
 	setIgnoreTight(ignore: boolean): this {
+		if (this.#ignoreTight !== ignore) this.#clearTableLayouts();
 		this.#ignoreTight = ignore;
 		this.invalidate();
 		return this;
@@ -1037,6 +1077,7 @@ export class Markdown implements Component {
 		// full lex + wrap runs per re-emit — one of the top CPU hotspots during
 		// streaming (issue #4353). Mirrors `Text.setText`'s guard.
 		if (text === this.#text) return false;
+		if (!text.startsWith(this.#text)) this.#clearTableLayouts();
 		this.#text = text;
 		if (!text.trim()) {
 			// Blank replacement: render() early-returns before #lexTokens can see
@@ -1080,6 +1121,41 @@ export class Markdown implements Component {
 		return this.#lastRenderSettledRows;
 	}
 
+	/**
+	 * Freeze every table whose first physical row is already part of the native
+	 * scrollback prefix. The recorded widths came from the exact frame that was
+	 * just emitted, so the next streamed delta cannot retroactively widen it.
+	 */
+	setNativeScrollbackCommittedRows(rows: number): void {
+		const committed = Number.isFinite(rows) ? Math.max(0, Math.trunc(rows)) : 0;
+		let changed = false;
+		for (const table of this.#lastRenderedTableLayouts) {
+			if (table.startRow >= committed || this.#lockedTableLayouts.has(table.key)) continue;
+			this.#lockedTableLayouts.set(table.key, {
+				availableWidth: table.availableWidth,
+				columnWidths: table.columnWidths.slice(),
+			});
+			changed = true;
+		}
+		if (changed) this.invalidate();
+	}
+
+	/** A destructive replay removes the immutable tape this layout was guarding. */
+	prepareNativeScrollbackReplay(): void {
+		this.#clearTableLayouts();
+		this.#tableLayoutWidth = undefined;
+		this.invalidate();
+	}
+
+	#clearTableLayouts(): void {
+		this.#lockedTableLayouts.clear();
+		this.#lastRenderedTableLayouts = [];
+		this.#activeTableRenderSpecs = undefined;
+		// Same-width replay/non-append rewrites could otherwise reuse physical
+		// prefix lines rendered with the retired locked widths.
+		this.#streamPrefixLineCache = undefined;
+	}
+
 	// Lex `text` into block tokens, reusing the frozen stable prefix when the text
 	// only grew (the streaming path). Falls back to a full lex whenever the prefix
 	// is no longer a prefix (non-append edit), the text carries reference-link
@@ -1159,6 +1235,11 @@ export class Markdown implements Component {
 	}
 
 	render(width: number): readonly string[] {
+		if (this.#tableLayoutWidth !== undefined && this.#tableLayoutWidth !== width) {
+			this.#clearTableLayouts();
+			this.invalidate();
+		}
+		this.#tableLayoutWidth = width;
 		// L1: per-instance cache — fastest path for repeated renders of the same
 		// instance at the same width (e.g. resize debounce, repeated redraws).
 		// Returning the cached reference is load-bearing: parents memoize their
@@ -1200,29 +1281,40 @@ export class Markdown implements Component {
 		// theme.heading is used as the representative theme probe — it's required
 		// by MarkdownTheme and is one of the most styling-sensitive entries.
 		let cacheKey: string | undefined;
-		if (!this.transientRenderCache) {
+		if (!this.transientRenderCache && this.#lockedTableLayouts.size === 0) {
 			cacheKey = this.#renderCacheKey(normalizedText, signature);
 			const cached = renderCache.get(cacheKey);
 			if (cached !== undefined) {
+				// Restore both the rendered rows and the geometry metadata that produced
+				// them. A later scrollback publication must never lock widths from an
+				// older transient frame against rows served from this cache entry.
+				this.#lastRenderedTableLayouts = cached.tables.map(table => ({
+					...table,
+					columnWidths: table.columnWidths.slice(),
+				}));
 				// Populate L1 so subsequent calls from this instance are O(1) map lookup.
 				this.#cachedText = this.#text;
 				this.#cachedWidth = width;
-				this.#cachedLines = cached;
-				return cached;
+				this.#cachedLines = cached.lines;
+				return cached.lines;
 			}
 		}
 
 		// Parse markdown to HTML-like tokens
 		const tokens = this.#lexTokens(normalizedText);
 		let contentLines: string[];
+		const tableRenderSpecs: TableRenderSpec[] = [];
+		this.#activeTableRenderSpecs = tableRenderSpecs;
 		this.#activeRenderSignature = signature;
 		try {
 			contentLines = this.transientRenderCache
 				? this.#renderStreamingContentLines(tokens, normalizedText, signature, contentWidth)
-				: this.#renderContentLines(tokens, 0, tokens.length, contentWidth, signature);
+				: this.#renderContentLines(tokens, 0, tokens.length, contentWidth, signature, 0, 0);
 		} finally {
 			this.#activeRenderSignature = undefined;
+			this.#activeTableRenderSpecs = undefined;
 		}
+		this.#lastRenderedTableLayouts = this.#resolveRenderedTableLayouts(tableRenderSpecs, signature.paddingY);
 		const emptyLines = this.#renderEmptyPaddingLines(signature);
 
 		// Combine top padding, content, and bottom padding
@@ -1239,7 +1331,13 @@ export class Markdown implements Component {
 		// Update L2 module-level LRU so future instances with the same key skip
 		// the marked.lexer + highlightCode (Rust FFI) work entirely.
 		if (cacheKey !== undefined) {
-			renderCache.set(cacheKey, result);
+			renderCache.set(cacheKey, {
+				lines: result,
+				tables: this.#lastRenderedTableLayouts.map(table => ({
+					...table,
+					columnWidths: table.columnWidths.slice(),
+				})),
+			});
 		}
 
 		return result;
@@ -1276,15 +1374,18 @@ export class Markdown implements Component {
 		const frozenText = this.#streamPrefixText;
 		const frozenTokenCount = this.#streamPrefixTokens?.length ?? 0;
 		if (frozenText === undefined || frozenTokenCount === 0 || !normalizedText.startsWith(frozenText)) {
-			return this.#renderContentLines(tokens, 0, tokens.length, contentWidth, signature);
+			return this.#renderContentLines(tokens, 0, tokens.length, contentWidth, signature, 0, 0);
 		}
 
 		const contentLines: string[] = [];
 		const reusablePrefix = this.#matchingStreamPrefixLineCache(normalizedText, frozenText, signature);
 		let renderedUntil = 0;
+		let renderedSourceOffset = 0;
 		if (reusablePrefix && reusablePrefix.tokenCount <= frozenTokenCount) {
 			contentLines.push(...reusablePrefix.lines);
+			this.#activeTableRenderSpecs?.push(...reusablePrefix.tables);
 			renderedUntil = reusablePrefix.tokenCount;
+			renderedSourceOffset = reusablePrefix.text.length;
 		}
 
 		if (renderedUntil < frozenTokenCount) {
@@ -1293,7 +1394,15 @@ export class Markdown implements Component {
 			this.#renderingFrozenPrefix = true;
 			try {
 				contentLines.push(
-					...this.#renderContentLines(tokens, renderedUntil, frozenTokenCount, contentWidth, signature),
+					...this.#renderContentLines(
+						tokens,
+						renderedUntil,
+						frozenTokenCount,
+						contentWidth,
+						signature,
+						contentLines.length,
+						renderedSourceOffset,
+					),
 				);
 			} finally {
 				this.#renderingFrozenPrefix = false;
@@ -1306,6 +1415,7 @@ export class Markdown implements Component {
 			text: frozenText,
 			tokenCount: frozenTokenCount,
 			lines: contentLines.slice(),
+			tables: this.#activeTableRenderSpecs?.slice() ?? [],
 		};
 
 		// Settled exposure (hard-monotone): these rows are declared final to
@@ -1322,7 +1432,17 @@ export class Markdown implements Component {
 		}
 
 		if (renderedUntil < tokens.length) {
-			contentLines.push(...this.#renderContentLines(tokens, renderedUntil, tokens.length, contentWidth, signature));
+			contentLines.push(
+				...this.#renderContentLines(
+					tokens,
+					renderedUntil,
+					tokens.length,
+					contentWidth,
+					signature,
+					contentLines.length,
+					frozenText.length,
+				),
+			);
 		}
 
 		return contentLines;
@@ -1356,23 +1476,57 @@ export class Markdown implements Component {
 		end: number,
 		contentWidth: number,
 		signature: RenderSignature,
+		rowOffset: number,
+		startingSourceOffset: number,
 	): string[] {
-		const renderedLines: string[] = [];
+		const wrappedLines: string[] = [];
+		let sourceOffset = startingSourceOffset;
 		for (let i = start; i < end; i++) {
 			const token = tokens[i];
 			const nextToken = tokens[i + 1];
-			renderedLines.push(...this.#renderToken(token, contentWidth, nextToken?.type));
-		}
-
-		const wrappedLines: string[] = [];
-		for (const line of renderedLines) {
-			// Skip wrapping for image protocol lines and OSC 66 sized headings
-			// (would corrupt escape sequences / split the indivisible sized span).
-			if (TERMINAL.isImageLine(line) || isOsc66Line(line)) {
-				wrappedLines.push(line);
-			} else {
-				wrappedLines.push(...wrapTextWithAnsi(line, contentWidth));
+			const tableSpecStart = this.#activeTableRenderSpecs?.length ?? 0;
+			const tokenWrappedRowStart = wrappedLines.length;
+			const tokenRowStart = rowOffset + tokenWrappedRowStart;
+			const renderedTokenLines = this.#renderToken(
+				token,
+				contentWidth,
+				nextToken?.type,
+				undefined,
+				`offset:${sourceOffset}`,
+			);
+			const tokenLineOffsets = [0];
+			for (const line of renderedTokenLines) {
+				// Skip wrapping for image protocol lines and OSC 66 sized headings
+				// (would corrupt escape sequences / split the indivisible sized span).
+				if (TERMINAL.isImageLine(line) || isOsc66Line(line)) {
+					wrappedLines.push(line);
+				} else {
+					wrappedLines.push(...wrapTextWithAnsi(line, contentWidth));
+				}
+				tokenLineOffsets.push(wrappedLines.length - tokenWrappedRowStart);
 			}
+			const tableSpecs = this.#activeTableRenderSpecs;
+			if (tableSpecs !== undefined) {
+				for (let specIndex = tableSpecStart; specIndex < tableSpecs.length; specIndex++) {
+					const spec = tableSpecs[specIndex]!;
+					let relativeStart: number;
+					let relativeEnd: number;
+					if (token.type === "table") {
+						// Exclude the optional inter-block blank from a top-level table's span.
+						relativeStart = 0;
+						relativeEnd = Math.min(renderedTokenLines.length, spec.lineCount);
+					} else {
+						// Container renderers express nested table spans relative to their
+						// returned lines. Preserve that exact span through this final wrap.
+						if (spec.startRow < 0 || spec.endRow <= spec.startRow) continue;
+						relativeStart = Math.min(renderedTokenLines.length, spec.startRow);
+						relativeEnd = Math.min(renderedTokenLines.length, spec.endRow);
+					}
+					spec.startRow = tokenRowStart + tokenLineOffsets[relativeStart]!;
+					spec.endRow = tokenRowStart + tokenLineOffsets[relativeEnd]!;
+				}
+			}
+			sourceOffset += token.raw.length;
 		}
 
 		const leftMargin = padding(signature.paddingX);
@@ -1416,6 +1570,21 @@ export class Markdown implements Component {
 		return contentLines;
 	}
 
+	#resolveRenderedTableLayouts(specs: readonly TableRenderSpec[], topPadding: number): RenderedTableLayout[] {
+		const layouts: RenderedTableLayout[] = [];
+		for (const spec of specs) {
+			if (spec.startRow < 0 || spec.endRow <= spec.startRow) continue;
+			layouts.push({
+				key: spec.key,
+				availableWidth: spec.availableWidth,
+				columnWidths: spec.columnWidths.slice(),
+				startRow: topPadding + spec.startRow,
+				endRow: topPadding + spec.endRow,
+			});
+		}
+		return layouts;
+	}
+
 	#renderCodeBodyLines(token: Token, codeIndent: string): string[] {
 		const bodyLines: string[] = [];
 		const tokenText = "text" in token && typeof token.text === "string" ? token.text : "";
@@ -1626,7 +1795,13 @@ export class Markdown implements Component {
 		};
 	}
 
-	#renderToken(token: Token, width: number, nextTokenType?: string, styleContext?: InlineStyleContext): string[] {
+	#renderToken(
+		token: Token,
+		width: number,
+		nextTokenType?: string,
+		styleContext?: InlineStyleContext,
+		tokenKey = "root",
+	): string[] {
 		const lines: string[] = [];
 
 		// Display math block (own-line `$$…$$` / `\[…\]`): stack `\frac` vertically
@@ -1728,7 +1903,7 @@ export class Markdown implements Component {
 			}
 
 			case "table": {
-				const tableLines = this.#renderTable(token as TableToken, width, nextTokenType, styleContext);
+				const tableLines = this.#renderTable(token as TableToken, width, nextTokenType, styleContext, tokenKey);
 				lines.push(...tableLines);
 				break;
 			}
@@ -1741,20 +1916,59 @@ export class Markdown implements Component {
 				const quoteContentWidth = Math.max(1, width - 2);
 				const quoteTokens = token.tokens || [];
 				const renderedQuoteLines: string[] = [];
+				const blockquoteSpecStart = this.#activeTableRenderSpecs?.length ?? 0;
 
 				for (let i = 0; i < quoteTokens.length; i++) {
 					const quoteToken = quoteTokens[i];
 					const nextQuoteToken = quoteTokens[i + 1];
-					renderedQuoteLines.push(
-						...this.#renderToken(quoteToken, quoteContentWidth, nextQuoteToken?.type, quoteInlineStyleContext),
+					const quoteTokenRowStart = renderedQuoteLines.length;
+					const quoteSpecStart = this.#activeTableRenderSpecs?.length ?? 0;
+					const quoteTokenLines = this.#renderToken(
+						quoteToken,
+						quoteContentWidth,
+						nextQuoteToken?.type,
+						quoteInlineStyleContext,
+						`${tokenKey}/quote:${i}`,
 					);
+					renderedQuoteLines.push(...quoteTokenLines);
+
+					const tableSpecs = this.#activeTableRenderSpecs;
+					if (tableSpecs !== undefined) {
+						for (let specIndex = quoteSpecStart; specIndex < tableSpecs.length; specIndex++) {
+							const spec = tableSpecs[specIndex]!;
+							if (spec.startRow < 0) {
+								// Direct child tables initially have no row coordinates. Their
+								// structural line count excludes any inter-block blank.
+								spec.startRow = quoteTokenRowStart;
+								spec.endRow = quoteTokenRowStart + Math.min(quoteTokenLines.length, spec.lineCount);
+							} else {
+								// A nested blockquote already mapped the table into its own
+								// returned rows; translate those rows into this quote's input.
+								spec.startRow += quoteTokenRowStart;
+								spec.endRow += quoteTokenRowStart;
+							}
+						}
+					}
 				}
 
 				while (renderedQuoteLines.length > 0 && renderedQuoteLines[renderedQuoteLines.length - 1] === "") {
 					renderedQuoteLines.pop();
 				}
 
-				lines.push(...this.#applyQuoteBorder(renderedQuoteLines, width));
+				const quoteRowOffsets: number[] = [];
+				const borderedQuoteLines = this.#applyQuoteBorder(renderedQuoteLines, width, quoteRowOffsets);
+				const tableSpecs = this.#activeTableRenderSpecs;
+				if (tableSpecs !== undefined) {
+					for (let specIndex = blockquoteSpecStart; specIndex < tableSpecs.length; specIndex++) {
+						const spec = tableSpecs[specIndex]!;
+						if (spec.startRow < 0 || spec.endRow <= spec.startRow) continue;
+						const relativeStart = Math.min(renderedQuoteLines.length, spec.startRow);
+						const relativeEnd = Math.min(renderedQuoteLines.length, spec.endRow);
+						spec.startRow = quoteRowOffsets[relativeStart]!;
+						spec.endRow = quoteRowOffsets[relativeEnd]!;
+					}
+				}
+				lines.push(...borderedQuoteLines);
 				if (nextTokenType && nextTokenType !== "space") {
 					lines.push(""); // Add spacing after blockquotes (unless space token follows)
 				}
@@ -1801,7 +2015,7 @@ export class Markdown implements Component {
 	 * Wrap already-rendered lines in the blockquote border and quote styling.
 	 * `width` is the full content width; the border reserves two cells.
 	 */
-	#applyQuoteBorder(renderedLines: string[], width: number): string[] {
+	#applyQuoteBorder(renderedLines: string[], width: number, sourceRowOffsets?: number[]): string[] {
 		const quoteStyle = (text: string) => this.#theme.quote(this.#theme.italic(text));
 		const quoteStylePrefix = this.#getStylePrefix(quoteStyle);
 		const applyQuoteStyle = (line: string): string => {
@@ -1813,11 +2027,13 @@ export class Markdown implements Component {
 		};
 		const quoteContentWidth = Math.max(1, width - 2);
 		const lines: string[] = [];
+		sourceRowOffsets?.push(0);
 		for (const quoteLine of renderedLines) {
 			const styledLine = applyQuoteStyle(quoteLine);
 			for (const wrappedLine of wrapTextWithAnsi(styledLine, quoteContentWidth)) {
 				lines.push(this.#theme.quoteBorder(`${this.#theme.symbols.quoteBorder} `) + wrappedLine);
 			}
+			sourceRowOffsets?.push(lines.length);
 		}
 		return lines;
 	}
@@ -2149,6 +2365,7 @@ export class Markdown implements Component {
 		availableWidth: number,
 		nextTokenType?: string,
 		styleContext?: InlineStyleContext,
+		tableKey = "table",
 	): string[] {
 		const lines: string[] = [];
 		const numCols = token.header.length;
@@ -2263,6 +2480,17 @@ export class Markdown implements Component {
 			}
 		}
 
+		const lockedLayout = this.#lockedTableLayouts.get(tableKey);
+		if (
+			lockedLayout !== undefined &&
+			lockedLayout.availableWidth === availableWidth &&
+			lockedLayout.columnWidths.length === numCols &&
+			lockedLayout.columnWidths.every(width => Number.isFinite(width) && width >= 1) &&
+			lockedLayout.columnWidths.reduce((total, width) => total + width, borderOverhead) <= availableWidth
+		) {
+			columnWidths = lockedLayout.columnWidths.slice();
+		}
+
 		const t = this.#theme.symbols.table;
 		const h = t.horizontal;
 		const v = t.vertical;
@@ -2316,7 +2544,16 @@ export class Markdown implements Component {
 
 		// Render bottom border
 		const bottomBorderCells = columnWidths.map(w => h.repeat(w));
-		lines.push(`${t.bottomLeft}${h}${bottomBorderCells.join(`${h}${t.teeUp}${h}`)}${h}${t.bottomRight}`);
+		const bottomBorder = `${t.bottomLeft}${h}${bottomBorderCells.join(`${h}${t.teeUp}${h}`)}${h}${t.bottomRight}`;
+		lines.push(bottomBorder);
+		this.#activeTableRenderSpecs?.push({
+			key: tableKey,
+			availableWidth,
+			columnWidths: columnWidths.slice(),
+			lineCount: lines.length,
+			startRow: -1,
+			endRow: -1,
+		});
 
 		if (nextTokenType && nextTokenType !== "space") {
 			lines.push(""); // Add spacing after table

package/src/latex-block.ts

@@ -11,7 +11,8 @@
 // fractions and `\binom`, stretch delimiters (`\left…\right`, tall bare parens,
 // matrix brackets), render matrix/cases/array environments as baseline-aligned
 // grids, place big-operator limits (`\sum`, `\lim`, `\int\limits`) above and
-// below the symbol, draw radicals, raise/lower block scripts, and
+// below the symbol, draw radicals, raise/lower block scripts, draw labeled
+// horizontal braces (`\underbrace{x}_{lbl}`), stack `\overset`/`\underset`, and
 // align `&` columns in `align`-family environments. Flat runs — symbols, fonts,
 // colors, inline scripts — are delegated to `latexToUnicode`.
 //
@@ -126,6 +127,25 @@ const INTEGRAL_OPERATORS: Record<string, true> = {
 	smallint: true,
 };
 
+// Horizontal brace/bracket decorations drawn as a rule row beside the content,
+// with an optional limits-style label beyond the rule (`\underbrace{x}_{lbl}`).
+interface HBraceSpec {
+	left: string;
+	mid: string;
+	center: string;
+	right: string;
+	over: boolean;
+}
+
+const HBRACE_COMMANDS: Record<string, HBraceSpec> = {
+	overbrace: { left: "╭", mid: "─", center: "┴", right: "╮", over: true },
+	underbrace: { left: "╰", mid: "─", center: "┬", right: "╯", over: false },
+	overbracket: { left: "┌", mid: "─", center: "─", right: "┐", over: true },
+	underbracket: { left: "└", mid: "─", center: "─", right: "┘", over: false },
+	overparen: { left: "╭", mid: "─", center: "─", right: "╮", over: true },
+	underparen: { left: "╰", mid: "─", center: "─", right: "╯", over: false },
+};
+
 // Vertical delimiter piece characters: `only` for single-line content, then
 // top/mid/bot columns for stretched forms; `axis` replaces `mid` at the
 // baseline row (the brace point).
@@ -363,6 +383,31 @@ function limitsBox(glyph: Box, sub: Box | null, sup: Box | null): Box {
 	return { lines, baseline, width };
 }
 
+/**
+ * `\underbrace{content}_{label}` / `\overbrace{content}^{label}`: the content
+ * with a drawn horizontal brace beside it and the label centered beyond the
+ * brace. The baseline stays on the content so neighbors align with it.
+ */
+function hbraceBox(content: Box, spec: HBraceSpec, label: Box | null): Box {
+	const braceWidth = Math.max(content.width, 3);
+	const width = Math.max(braceWidth, label?.width ?? 0);
+	const lead = (braceWidth - 3) >> 1;
+	const brace = center(
+		spec.left + spec.mid.repeat(lead) + spec.center + spec.mid.repeat(braceWidth - 3 - lead) + spec.right,
+		width,
+	);
+	const contentLines = content.lines.map(line => center(line, width));
+	const labelLines = label === null ? [] : label.lines.map(line => center(line, width));
+	if (spec.over) {
+		return {
+			lines: [...labelLines, brace, ...contentLines],
+			baseline: labelLines.length + 1 + content.baseline,
+			width,
+		};
+	}
+	return { lines: [...contentLines, brace, ...labelLines], baseline: content.baseline, width };
+}
+
 /**
  * Attach block scripts to `base` as one shared right-hand column: the
  * superscript ends level with the base's top row (raised one row above a
@@ -878,6 +923,59 @@ function parseExpr(src: string, ctx: Ctx = ROOT_CTX): Box {
 				i = bottom.end;
 				continue;
 			}
+			if (name && HBRACE_COMMANDS[name]) {
+				flush();
+				const spec = HBRACE_COMMANDS[name];
+				const arg = readArg(src, j);
+				// Limits-style scripts: the brace-side script is the label; an
+				// opposite-side script attaches as a regular corner script.
+				let subText: string | null = null;
+				let supText: string | null = null;
+				let m = arg.end;
+				for (;;) {
+					let n = m;
+					while (src[n] === " ") n++;
+					if (src[n] === "_" && subText === null) {
+						const s = readArg(src, n + 1);
+						subText = s.text;
+						m = s.end;
+						continue;
+					}
+					if (src[n] === "^" && supText === null) {
+						const s = readArg(src, n + 1);
+						supText = s.text;
+						m = s.end;
+						continue;
+					}
+					break;
+				}
+				const labelText = spec.over ? supText : subText;
+				const otherText = spec.over ? subText : supText;
+				let box = hbraceBox(
+					parseExpr(arg.text, inner()),
+					spec,
+					labelText === null ? null : parseExpr(labelText, inner()),
+				);
+				if (otherText !== null) {
+					const other = parseExpr(otherText, inner());
+					box = attachScripts(box, spec.over ? other : null, spec.over ? null : other);
+				}
+				boxes.push(paint(box));
+				i = m;
+				continue;
+			}
+			if (name === "overset" || name === "underset" || name === "stackrel") {
+				flush();
+				const anno = readArg(src, j);
+				const base = readArg(src, anno.end);
+				const annoBox = parseExpr(anno.text, inner());
+				const baseBox = parseExpr(base.text, inner());
+				boxes.push(
+					paint(limitsBox(baseBox, name === "underset" ? annoBox : null, name === "underset" ? null : annoBox)),
+				);
+				i = base.end;
+				continue;
+			}
 			if (name === "sqrt") {
 				let k = j;
 				while (src[k] === " ") k++;
@@ -1108,8 +1206,18 @@ function parseExpr(src: string, ctx: Ctx = ROOT_CTX): Box {
 				const flat = latexToUnicode(raw);
 				return flat.startsWith("^") || flat.startsWith("_");
 			};
+			// Multi-letter script words (`N_{turns}`) would convert per-char into
+			// Unicode glyphs of uneven height and read ragged; box them too.
+			// Commands are stripped: their output (`\prime` → ′) is not letters.
+			const ragged = (raw: string | undefined): boolean => {
+				if (raw === undefined) return false;
+				const letters = scriptArgOf(raw)
+					.replace(/\\[A-Za-z]+/g, "")
+					.match(/[A-Za-z]/g);
+				return letters !== null && letters.length >= 2;
+			};
 			const tall = (supBox !== null && supBox.lines.length > 1) || (subBox !== null && subBox.lines.length > 1);
-			if (tall || unconvertible(supText) || unconvertible(subText)) {
+			if (tall || unconvertible(supText) || unconvertible(subText) || ragged(supText) || ragged(subText)) {
 				// Block script (`x^{\frac{1}{2}}`, `x^q`): raise/lower the boxes
 				// against the run or box they follow.
 				flush();