jeopi-tui 16.2.13

package/src/kitty-graphics.ts

@@ -0,0 +1,171 @@
+/**
+ * Kitty graphics: Unicode placeholder placement (`U=1` + U+10EEEE), with
+ * runtime feature state and env overrides.
+ *
+ * Unicode placeholders let a transmitted image be displayed by writing ordinary
+ * text cells — the placeholder char U+10EEEE plus row/column combining
+ * diacritics — instead of a cursor-positioned `a=p` direct placement. The image
+ * then participates in the normal text grid, so it survives horizontal slicing,
+ * reflow and overlapping draws (each cell names its own row+column, so a sliced
+ * row still maps to the correct sub-region). See kitty
+ * `docs/graphics-protocol.rst` "Unicode placeholders for relative placements".
+ *
+ * This module is intentionally free of `./terminal-capabilities` imports so the
+ * dependency stays one-way (capabilities → kitty-graphics) and no import cycle
+ * forms. Protocol gating (`imageProtocol === Kitty`) lives in the caller.
+ */
+
+/** Kitty Unicode placeholder base character (U+10EEEE, Plane 16 PUA). */
+export const KITTY_PLACEHOLDER = "\u{10eeee}";
+
+/**
+ * Row/column diacritics (Unicode combining class 230, no decomposition) used to
+ * name a placeholder cell's row and column. Index `i` → codepoint. Derived from
+ * kitty `gen/rowcolumn-diacritics.txt` (Unicode 6.0.0 NSM set). 297 entries, so
+ * a single image can address up to 297 rows/columns without ID-high-byte tricks.
+ */
+const ROWCOLUMN_DIACRITICS: readonly number[] = [
+	0x305, 0x30d, 0x30e, 0x310, 0x312, 0x33d, 0x33e, 0x33f, 0x346, 0x34a, 0x34b, 0x34c, 0x350, 0x351, 0x352, 0x357,
+	0x35b, 0x363, 0x364, 0x365, 0x366, 0x367, 0x368, 0x369, 0x36a, 0x36b, 0x36c, 0x36d, 0x36e, 0x36f, 0x483, 0x484,
+	0x485, 0x486, 0x487, 0x592, 0x593, 0x594, 0x595, 0x597, 0x598, 0x599, 0x59c, 0x59d, 0x59e, 0x59f, 0x5a0, 0x5a1,
+	0x5a8, 0x5a9, 0x5ab, 0x5ac, 0x5af, 0x5c4, 0x610, 0x611, 0x612, 0x613, 0x614, 0x615, 0x616, 0x617, 0x657, 0x658,
+	0x659, 0x65a, 0x65b, 0x65d, 0x65e, 0x6d6, 0x6d7, 0x6d8, 0x6d9, 0x6da, 0x6db, 0x6dc, 0x6df, 0x6e0, 0x6e1, 0x6e2,
+	0x6e4, 0x6e7, 0x6e8, 0x6eb, 0x6ec, 0x730, 0x732, 0x733, 0x735, 0x736, 0x73a, 0x73d, 0x73f, 0x740, 0x741, 0x743,
+	0x745, 0x747, 0x749, 0x74a, 0x7eb, 0x7ec, 0x7ed, 0x7ee, 0x7ef, 0x7f0, 0x7f1, 0x7f3, 0x816, 0x817, 0x818, 0x819,
+	0x81b, 0x81c, 0x81d, 0x81e, 0x81f, 0x820, 0x821, 0x822, 0x823, 0x825, 0x826, 0x827, 0x829, 0x82a, 0x82b, 0x82c,
+	0x82d, 0x951, 0x953, 0x954, 0xf82, 0xf83, 0xf86, 0xf87, 0x135d, 0x135e, 0x135f, 0x17dd, 0x193a, 0x1a17, 0x1a75,
+	0x1a76, 0x1a77, 0x1a78, 0x1a79, 0x1a7a, 0x1a7b, 0x1a7c, 0x1b6b, 0x1b6d, 0x1b6e, 0x1b6f, 0x1b70, 0x1b71, 0x1b72,
+	0x1b73, 0x1cd0, 0x1cd1, 0x1cd2, 0x1cda, 0x1cdb, 0x1ce0, 0x1dc0, 0x1dc1, 0x1dc3, 0x1dc4, 0x1dc5, 0x1dc6, 0x1dc7,
+	0x1dc8, 0x1dc9, 0x1dcb, 0x1dcc, 0x1dd1, 0x1dd2, 0x1dd3, 0x1dd4, 0x1dd5, 0x1dd6, 0x1dd7, 0x1dd8, 0x1dd9, 0x1dda,
+	0x1ddb, 0x1ddc, 0x1ddd, 0x1dde, 0x1ddf, 0x1de0, 0x1de1, 0x1de2, 0x1de3, 0x1de4, 0x1de5, 0x1de6, 0x1dfe, 0x20d0,
+	0x20d1, 0x20d4, 0x20d5, 0x20d6, 0x20d7, 0x20db, 0x20dc, 0x20e1, 0x20e7, 0x20e9, 0x20f0, 0x2cef, 0x2cf0, 0x2cf1,
+	0x2de0, 0x2de1, 0x2de2, 0x2de3, 0x2de4, 0x2de5, 0x2de6, 0x2de7, 0x2de8, 0x2de9, 0x2dea, 0x2deb, 0x2dec, 0x2ded,
+	0x2dee, 0x2def, 0x2df0, 0x2df1, 0x2df2, 0x2df3, 0x2df4, 0x2df5, 0x2df6, 0x2df7, 0x2df8, 0x2df9, 0x2dfa, 0x2dfb,
+	0x2dfc, 0x2dfd, 0x2dfe, 0x2dff, 0xa66f, 0xa67c, 0xa67d, 0xa6f0, 0xa6f1, 0xa8e0, 0xa8e1, 0xa8e2, 0xa8e3, 0xa8e4,
+	0xa8e5, 0xa8e6, 0xa8e7, 0xa8e8, 0xa8e9, 0xa8ea, 0xa8eb, 0xa8ec, 0xa8ed, 0xa8ee, 0xa8ef, 0xa8f0, 0xa8f1, 0xaab0,
+	0xaab2, 0xaab3, 0xaab7, 0xaab8, 0xaabe, 0xaabf, 0xaac1, 0xfe20, 0xfe21, 0xfe22, 0xfe23, 0xfe24, 0xfe25, 0xfe26,
+	0x10a0f, 0x10a38, 0x1d185, 0x1d186, 0x1d187, 0x1d188, 0x1d189, 0x1d1aa, 0x1d1ab, 0x1d1ac, 0x1d1ad, 0x1d242, 0x1d243,
+	0x1d244,
+];
+
+/** Largest row/column index expressible with the diacritic table (one cell each). */
+export const KITTY_PLACEHOLDER_MAX_CELLS = ROWCOLUMN_DIACRITICS.length;
+
+export interface KittyGraphicsFeatures {
+	/** Display images via Unicode placeholders instead of direct `a=p` placement. */
+	unicodePlaceholders: boolean;
+}
+
+/**
+ * Whether the detected terminal renders Kitty Unicode placeholders (`U=1` +
+ * U+10EEEE with row/column diacritics).
+ *
+ * Only `kitty` (the protocol's origin) and `ghostty` ship a working
+ * implementation; WezTerm advertises Kitty graphics but treats placeholder
+ * cells as literal PUA glyphs (see wezterm/wezterm#986, "placeholder support"
+ * still unchecked), and the tmux/screen fallback can land on any outer
+ * terminal. Enabling placeholders on those paths emits a `columns × rows`
+ * grid of U+10EEEE per image per frame; the cells render as boxed fallback
+ * glyphs and re-emit on every repaint, which is exactly the
+ * "stuck/laggy scrolling + ASCII artifact" symptom reported in #1877.
+ *
+ * `PI_NO_KITTY_PLACEHOLDERS=1` forces off (e.g. for tmux passthrough to a
+ * non-supporting outer terminal); `PI_KITTY_PLACEHOLDERS=1` forces on (e.g.
+ * for a wezterm nightly that has merged placeholder support).
+ */
+export function detectKittyUnicodePlaceholdersSupport(terminalId: string, env: NodeJS.ProcessEnv = Bun.env): boolean {
+	const offRaw = env.PI_NO_KITTY_PLACEHOLDERS?.trim().toLowerCase();
+	if (offRaw === "1" || offRaw === "true" || offRaw === "on" || offRaw === "yes" || offRaw === "y") return false;
+	const force = env.PI_KITTY_PLACEHOLDERS?.trim().toLowerCase();
+	if (force === "1" || force === "true" || force === "on" || force === "yes" || force === "y") return true;
+	if (force === "0" || force === "false" || force === "off" || force === "no" || force === "n") return false;
+	return terminalId === "kitty" || terminalId === "ghostty";
+}
+
+let features: KittyGraphicsFeatures = {
+	// Off until `terminal-capabilities` seeds it from the detected terminal id —
+	// the default-on path corrupts wezterm and tmux-passthrough sessions.
+	unicodePlaceholders: false,
+};
+
+export function getKittyGraphics(): Readonly<KittyGraphicsFeatures> {
+	return features;
+}
+
+export function setKittyGraphics(partial: Partial<KittyGraphicsFeatures>): void {
+	features = { ...features, ...partial };
+}
+
+/** Whether a `columns`×`rows` placeholder grid fits within the diacritic table. */
+export function kittyPlaceholdersFit(columns: number, rows: number): boolean {
+	return columns >= 1 && rows >= 1 && columns <= KITTY_PLACEHOLDER_MAX_CELLS && rows <= KITTY_PLACEHOLDER_MAX_CELLS;
+}
+
+function diacritic(index: number): string {
+	const cp = ROWCOLUMN_DIACRITICS[index];
+	return cp === undefined ? "" : String.fromCodePoint(cp);
+}
+
+/**
+ * Virtual placement APC (`a=p,U=1`): tells the terminal that placeholder cells
+ * carrying image id `i` should display the transmitted image, scaled to fit the
+ * `c`×`r` cell box. Re-emitting with a stable `placementId` replaces in place.
+ */
+export function encodeKittyVirtualPlacement(opts: {
+	imageId: number;
+	placementId?: number;
+	columns: number;
+	rows: number;
+}): string {
+	const params = ["a=p", "U=1", "q=2", `i=${opts.imageId}`];
+	if (opts.placementId) params.push(`p=${opts.placementId}`);
+	params.push(`c=${opts.columns}`, `r=${opts.rows}`);
+	return `\x1b_G${params.join(",")}\x1b\\`;
+}
+
+/**
+ * Build the placeholder cell grid as one string per row. The image id is carried
+ * in each row's foreground color and the placement id (if any) in its underline
+ * color; every cell names its explicit row+column diacritic (robust to slicing,
+ * unlike left-inheritance). Returns exactly `rows` strings.
+ */
+export function encodeKittyPlaceholderGrid(opts: {
+	imageId: number;
+	placementId?: number;
+	columns: number;
+	rows: number;
+}): string[] {
+	const fg = `\x1b[38;2;${(opts.imageId >> 16) & 0xff};${(opts.imageId >> 8) & 0xff};${opts.imageId & 0xff}m`;
+	const underline = opts.placementId
+		? `\x1b[58:2::${(opts.placementId >> 16) & 0xff}:${(opts.placementId >> 8) & 0xff}:${opts.placementId & 0xff}m`
+		: "";
+	const reset = "\x1b[39;59m";
+	const lead = fg + underline;
+	const out: string[] = [];
+	for (let r = 0; r < opts.rows; r++) {
+		const rowDiacritic = diacritic(r);
+		let row = lead;
+		for (let c = 0; c < opts.columns; c++) {
+			row += KITTY_PLACEHOLDER + rowDiacritic + diacritic(c);
+		}
+		out.push(row + reset);
+	}
+	return out;
+}
+
+/**
+ * Full placeholder render: the virtual-placement APC prefixes line 0, and every
+ * line carries placeholder cells. Returns exactly `rows` lines (no cursor moves).
+ */
+export function renderKittyPlaceholderLines(opts: {
+	imageId: number;
+	placementId?: number;
+	columns: number;
+	rows: number;
+}): string[] {
+	const grid = encodeKittyPlaceholderGrid(opts);
+	if (grid.length > 0) {
+		grid[0] = encodeKittyVirtualPlacement(opts) + grid[0];
+	}
+	return grid;
+}

package/src/latex-block.ts

@@ -0,0 +1,461 @@
+// Two-dimensional layout for *display* LaTeX math: stacks `\frac` numerator over
+// denominator with a horizontal bar, aligning surrounding text to the bar's row.
+//
+//       −b ± √(b² − 4ac)
+//   x = ────────────────
+//              2a
+//
+// Only display blocks (`$$…$$`, `\[…\]`) use this; inline `$…$` stays single-line
+// (`½`, `(a+b)/c`). Everything that is not a fraction — symbols, scripts, roots,
+// matrices, environments — is delegated to `latexToUnicode`, so this engine only
+// adds the vertical stacking the flat string form can't express.
+
+import { latexToUnicode } from "./latex-to-unicode";
+import { visibleWidth } from "./utils";
+
+/**
+ * A rectangular block of rendered text. Every entry in `lines` is padded to
+ * exactly `width` visible columns; `baseline` is the row that aligns with the
+ * surrounding text when boxes are placed side by side (e.g. the fraction bar).
+ */
+interface Box {
+	lines: string[];
+	baseline: number;
+	width: number;
+}
+
+const BAR = "─";
+const FRAC_COMMANDS: Record<string, true> = { frac: true, dfrac: true, tfrac: true, cfrac: true };
+
+// Display "wrapper" environments whose body is an expression (possibly with `\\`
+// row breaks and `&` alignment). Their bodies are parsed so fractions inside
+// stack; grid/structure environments (matrix/array/cases) stay opaque and are
+// rendered flat by `latexToUnicode`.
+const DISPLAY_ROW_ENVIRONMENTS: Record<string, true> = {
+	equation: true,
+	eqnarray: true,
+	align: true,
+	aligned: true,
+	alignat: true,
+	alignedat: true,
+	flalign: true,
+	split: true,
+	gather: true,
+	gathered: true,
+	gatheredat: true,
+	multline: true,
+	displaymath: true,
+	math: true,
+};
+
+function spaces(n: number): string {
+	return n > 0 ? " ".repeat(n) : "";
+}
+
+/** Pad `line` on the right to `width` visible columns. */
+function padRight(line: string, width: number): string {
+	return line + spaces(width - visibleWidth(line));
+}
+
+/** Pad `line` symmetrically (left-biased) to `width` visible columns. */
+function center(line: string, width: number): string {
+	const extra = width - visibleWidth(line);
+	if (extra <= 0) return line;
+	const left = extra >> 1;
+	return spaces(left) + line + spaces(extra - left);
+}
+
+/** A single rendered string (possibly multi-line) as a baseline-centered box. */
+function textBox(text: string): Box {
+	const raw = text.split("\n");
+	let width = 0;
+	for (const line of raw) width = Math.max(width, visibleWidth(line));
+	return { lines: raw.map(line => padRight(line, width)), baseline: (raw.length - 1) >> 1, width };
+}
+
+/** Place boxes side by side, aligning their baselines. */
+function hconcat(boxes: Box[]): Box {
+	if (boxes.length === 1) return boxes[0];
+	let above = 0;
+	let below = 0;
+	for (const b of boxes) {
+		above = Math.max(above, b.baseline);
+		below = Math.max(below, b.lines.length - 1 - b.baseline);
+	}
+	const height = above + below + 1;
+	const lines: string[] = [];
+	let width = 0;
+	for (const b of boxes) width += b.width;
+	for (let row = 0; row < height; row++) {
+		let line = "";
+		for (const b of boxes) {
+			const local = row - (above - b.baseline);
+			line += local >= 0 && local < b.lines.length ? b.lines[local] : spaces(b.width);
+		}
+		lines.push(line);
+	}
+	return { lines, baseline: above, width };
+}
+
+/** Stack `num` over `den`, separated by a bar; the bar becomes the baseline. */
+function fracBox(num: Box, den: Box): Box {
+	const width = Math.max(num.width, den.width) + 2;
+	const lines = [
+		...num.lines.map(line => center(line, width)),
+		BAR.repeat(width),
+		...den.lines.map(line => center(line, width)),
+	];
+	return { lines, baseline: num.lines.length, width };
+}
+
+/** Stack boxes vertically (left-aligned), e.g. the rows of an aligned block. */
+function vconcat(boxes: Box[]): Box {
+	if (boxes.length === 1) return boxes[0];
+	let width = 0;
+	for (const b of boxes) width = Math.max(width, b.width);
+	const lines: string[] = [];
+	for (const b of boxes) for (const line of b.lines) lines.push(padRight(line, width));
+	return { lines, baseline: (lines.length - 1) >> 1, width };
+}
+
+interface Span {
+	text: string;
+	end: number;
+}
+
+/** Read a balanced `{…}` beginning at `i` (which must point at `{`). */
+function readBraceGroup(src: string, i: number): Span {
+	let depth = 0;
+	let out = "";
+	let j = i;
+	for (; j < src.length; j++) {
+		const c = src[j];
+		if (c === "\\") {
+			out += c + (src[j + 1] ?? "");
+			j++;
+			continue;
+		}
+		if (c === "{") {
+			depth++;
+			if (depth > 1) out += c;
+			continue;
+		}
+		if (c === "}") {
+			depth--;
+			if (depth === 0) {
+				j++;
+				break;
+			}
+			out += c;
+			continue;
+		}
+		out += c;
+	}
+	return { text: out, end: j };
+}
+
+/**
+ * Read one fraction argument: a `{…}` group, a single char, or a `\command`
+ * together with its attached `[…]`/`{…}` arguments (or whole `\begin…\end`
+ * block), so e.g. `\frac\sqrt{a}{b}` reads `\sqrt{a}` as the numerator.
+ */
+function readArg(src: string, i: number): Span {
+	while (src[i] === " ") i++;
+	if (i >= src.length) return { text: "", end: i };
+	if (src[i] === "{") return readBraceGroup(src, i);
+	if (src[i] !== "\\") return { text: src[i], end: i + 1 };
+	let j = i + 1;
+	let name = "";
+	while (/[A-Za-z]/.test(src[j] ?? "")) {
+		name += src[j];
+		j++;
+	}
+	if (name === "begin") {
+		const env = consumeEnvironment(src, i);
+		if (env) return env;
+	}
+	if (!name) return { text: src.slice(i, i + 2), end: i + 2 }; // non-letter command (\,, \{, …)
+	let end = j;
+	while (src[end] === "[" || src[end] === "{") {
+		if (src[end] === "{") end = readBraceGroup(src, end).end;
+		else {
+			const close = src.indexOf("]", end);
+			end = close === -1 ? src.length : close + 1;
+		}
+	}
+	return { text: src.slice(i, end), end };
+}
+
+interface EnvParts {
+	env: string;
+	bodyStart: number;
+	bodyEnd: number;
+	end: number;
+}
+
+/** Locate a `\begin{env}…\end{env}` block (balanced) starting at the backslash. */
+function readEnvironment(src: string, start: number): EnvParts | null {
+	let i = start + 6; // past "\begin"
+	while (src[i] === " ") i++;
+	if (src[i] !== "{") return null;
+	const nameGroup = readBraceGroup(src, i);
+	let k = nameGroup.end;
+	let depth = 1;
+	let bodyEnd = src.length;
+	while (k < src.length && depth > 0) {
+		if (src.startsWith("\\begin", k)) {
+			depth++;
+			k += 6;
+			continue;
+		}
+		if (src.startsWith("\\end", k)) {
+			depth--;
+			if (depth === 0) bodyEnd = k;
+			k += 4;
+			while (src[k] === " ") k++;
+			if (src[k] === "{") k = readBraceGroup(src, k).end;
+			if (depth === 0) break;
+			continue;
+		}
+		k++;
+	}
+	return { env: nameGroup.text.trim(), bodyStart: nameGroup.end, bodyEnd, end: k };
+}
+
+/** The full `\begin{env}…\end{env}` substring as an inline run. */
+function consumeEnvironment(src: string, start: number): Span | null {
+	const env = readEnvironment(src, start);
+	return env ? { text: src.slice(start, env.end), end: env.end } : null;
+}
+
+/** Split an environment body on top-level `\\` row breaks (depth-aware). */
+function splitRows(body: string): string[] {
+	const rows: string[] = [];
+	let braceDepth = 0;
+	let envDepth = 0;
+	let last = 0;
+	let i = 0;
+	while (i < body.length) {
+		if (body.startsWith("\\begin", i)) {
+			envDepth++;
+			i += 6;
+			continue;
+		}
+		if (body.startsWith("\\end", i)) {
+			envDepth--;
+			i += 4;
+			continue;
+		}
+		const c = body[i];
+		if (c === "\\") {
+			if (body[i + 1] === "\\" && braceDepth === 0 && envDepth === 0) {
+				rows.push(body.slice(last, i));
+				i += 2;
+				while (body[i] === " ") i++;
+				if (body[i] === "[") {
+					const close = body.indexOf("]", i);
+					i = close === -1 ? body.length : close + 1;
+				}
+				last = i;
+				continue;
+			}
+			i += 2; // skip escaped char / second backslash so `\{`/`\\` never skew depth
+			continue;
+		}
+		if (c === "{") braceDepth++;
+		else if (c === "}") braceDepth--;
+		i++;
+	}
+	rows.push(body.slice(last));
+	return rows;
+}
+
+/**
+ * Render a `\begin{env}…\end{env}` block. Expression "wrapper" environments
+ * (`equation`, `align`, `gather`, …) have their rows parsed so fractions stack;
+ * grid/structure environments (matrix/array/cases) render flat via
+ * `latexToUnicode`.
+ */
+function parseEnvironment(src: string, start: number): { box: Box; end: number } | null {
+	const env = readEnvironment(src, start);
+	if (env === null) return null;
+	const base = env.env.endsWith("*") ? env.env.slice(0, -1) : env.env;
+	if (!DISPLAY_ROW_ENVIRONMENTS[base]) {
+		return { box: textBox(latexToUnicode(src.slice(start, env.end))), end: env.end };
+	}
+	let bodyStart = env.bodyStart;
+	if (base === "alignat" || base === "alignedat" || base === "gatheredat") {
+		// These carry a required column-count argument `{n}` before the body.
+		let p = bodyStart;
+		while (src[p] === " " || src[p] === "\n") p++;
+		if (src[p] === "{") bodyStart = readBraceGroup(src, p).end;
+	}
+	const rows = splitRows(src.slice(bodyStart, env.bodyEnd))
+		.map(row => row.trim())
+		.filter(row => row !== "")
+		.map(row => parseExpr(row));
+	return { box: rows.length > 0 ? vconcat(rows) : textBox(""), end: env.end };
+}
+
+/** Append a script (`^`/`_`) and its argument to the inline run verbatim. */
+function readScript(src: string, i: number): Span {
+	let out = src[i];
+	i++;
+	while (src[i] === " ") {
+		out += src[i];
+		i++;
+	}
+	if (src[i] === "{") {
+		const group = readBraceGroup(src, i);
+		return { text: `${out}{${group.text}}`, end: group.end };
+	}
+	if (src[i] === "\\") {
+		let j = i + 1;
+		if (/[A-Za-z]/.test(src[j] ?? "")) while (/[A-Za-z]/.test(src[j] ?? "")) j++;
+		else j++;
+		return { text: out + src.slice(i, j), end: j };
+	}
+	if (i < src.length) return { text: out + src[i], end: i + 1 };
+	return { text: out, end: i };
+}
+
+/**
+ * Parse a math fragment into a layout box, stacking top-level fractions (and
+ * fractions nested inside other fractions' arguments). Non-fraction runs —
+ * including scripts, roots, environments, and command arguments — are gathered
+ * into inline strings and rendered through `latexToUnicode`.
+ */
+function parseExpr(src: string): Box {
+	const boxes: Box[] = [];
+	let inline = "";
+	const flush = (): void => {
+		if (inline) {
+			boxes.push(textBox(latexToUnicode(inline)));
+			inline = "";
+		}
+	};
+	let i = 0;
+	while (i < src.length) {
+		const c = src[i];
+		if (c === "\\") {
+			let j = i + 1;
+			let name = "";
+			while (j < src.length && /[A-Za-z]/.test(src[j])) {
+				name += src[j];
+				j++;
+			}
+			if (name && FRAC_COMMANDS[name]) {
+				flush();
+				const num = readArg(src, j);
+				const den = readArg(src, num.end);
+				boxes.push(fracBox(parseExpr(num.text), parseExpr(den.text)));
+				i = den.end;
+				continue;
+			}
+			if (name === "begin") {
+				const env = parseEnvironment(src, i);
+				if (env) {
+					flush();
+					boxes.push(env.box);
+					i = env.end;
+					continue;
+				}
+			}
+			if (!name) {
+				// Non-letter command (`\\`, `\,`, `\{`, …): keep the 2-char token inline.
+				inline += `\\${src[j] ?? ""}`;
+				i = j + 1;
+				continue;
+			}
+			// Other command: keep it and its bracket/brace arguments inline so a
+			// `{…}` argument is never mistaken for a top-level stacking group.
+			inline += `\\${name}`;
+			i = j;
+			while (src[i] === "[" || src[i] === "{") {
+				if (src[i] === "{") {
+					const group = readBraceGroup(src, i);
+					inline += `{${group.text}}`;
+					i = group.end;
+				} else {
+					const close = src.indexOf("]", i);
+					const end = close === -1 ? src.length : close + 1;
+					inline += src.slice(i, end);
+					i = end;
+				}
+			}
+			continue;
+		}
+		if (c === "^" || c === "_") {
+			const script = readScript(src, i);
+			inline += script.text;
+			i = script.end;
+			continue;
+		}
+		if (c === "{") {
+			const group = readBraceGroup(src, i);
+			flush();
+			boxes.push(parseExpr(group.text));
+			i = group.end;
+			continue;
+		}
+		inline += c;
+		i++;
+	}
+	flush();
+	if (boxes.length === 0) return textBox("");
+	return hconcat(boxes);
+}
+
+/** Split on top-level `\n` row separators (outside braces and environments). */
+function splitLines(src: string): string[] {
+	const lines: string[] = [];
+	let braceDepth = 0;
+	let envDepth = 0;
+	let last = 0;
+	let i = 0;
+	while (i < src.length) {
+		if (src.startsWith("\\begin", i)) {
+			envDepth++;
+			i += 6;
+			continue;
+		}
+		if (src.startsWith("\\end", i)) {
+			envDepth--;
+			i += 4;
+			continue;
+		}
+		const c = src[i];
+		if (c === "\\") {
+			i += 2; // escaped char / second backslash — never a logical-line break
+			continue;
+		}
+		if (c === "{") braceDepth++;
+		else if (c === "}") braceDepth--;
+		else if (c === "\n" && braceDepth === 0 && envDepth === 0) {
+			lines.push(src.slice(last, i));
+			last = i + 1;
+		}
+		i++;
+	}
+	lines.push(src.slice(last));
+	return lines;
+}
+
+/**
+ * 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 function latexToBlock(src: string): string[] {
+	if (typeof src !== "string" || src.trim() === "") return [];
+	const rows = splitLines(src.trim())
+		.map(line => line.trim())
+		.filter(line => line !== "")
+		.map(line => parseExpr(line));
+	if (rows.length === 0) return [];
+	let lines = vconcat(rows).lines;
+	while (lines.length > 1 && lines[lines.length - 1].trim() === "") lines = lines.slice(0, -1);
+	while (lines.length > 1 && lines[0].trim() === "") lines = lines.slice(1);
+	return lines;
+}