@linxiraos/pi-tui 1.0.0 → 1.0.2

package/src/components/markdown.ts

@@ -11,13 +11,19 @@ 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, NativeScrollbackCommittedRows, NativeScrollbackReplay } from "../tui";
+import type {
+	Component,
+	NativeScrollbackCommittedRows,
+	NativeScrollbackReplay,
+	NativeScrollbackWidthEpoch,
+} from "../tui";
 import {
 	applyBackgroundToLine,
 	Ellipsis,
 	encodeTextSized,
 	getPaddingX,
 	getSegmenter,
+	isOsc66Line,
 	padding,
 	replaceTabs,
 	truncateToWidth,
@@ -37,17 +43,78 @@ function normalizeOsc8Terminators(text: string): string {
 	return text.replace(OSC8_ST_PREFIX_REGEX, "$1\x07");
 }
 
-// OSC 66 (Kitty text-sizing) heading spans are emitted as a single indivisible
-// unit by the H1 render path. Like image-protocol lines, they must bypass
-// ANSI wrapping and width padding: re-wrapping splits/normalizes the sized span
-// (recomputing the explicit `w=` cell count and hoisting SGR out of the OSC
-// payload), and padding would append trailing cells past the doubled glyph.
-const OSC66_LINE_PREFIX = "\x1b]66;";
+const MARKDOWN_FENCE_LINE = /^ {0,3}(`{3,}|~{3,})[ \t]*(.*)$/;
+const MARKDOWN_HEADING_LINE = /^ {0,3}#{1,6}[ \t]+\S/;
+const FENCED_SOURCE_INTRO = /\b(?:code|example|markdown|output|snippet|source)\s*:?\s*$/i;
+
+function isGfmTableDelimiter(line: string, headerLine: string | undefined): boolean {
+	if (!headerLine || !line.includes("|") || !headerLine.includes("|")) return false;
+	const delimiterCells = line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|");
+	const headerCells = headerLine.trim().replace(/^\|/, "").replace(/\|$/, "").split("|");
+	return (
+		delimiterCells.length >= 2 &&
+		headerCells.length === delimiterCells.length &&
+		delimiterCells.every(cell => /^:?-{3,}:?$/.test(cell.trim())) &&
+		headerCells.every(cell => cell.trim().length > 0)
+	);
+}
+
+/**
+ * Gemini can emit a bare closing fence without its opener, then continue with
+ * headings and tables. CommonMark must interpret that lone fence as an opener,
+ * which turns the rest of an otherwise valid report into one raw code block.
+ *
+ * Repair only the unambiguous rich-document shape at final render: one
+ * unmatched bare fence after prose, followed by both an ATX heading and a GFM
+ * table delimiter. Keep ordinary incomplete code blocks, fenced Markdown
+ * examples, and every matched fence untouched.
+ */
+function repairOrphanClosingFence(text: string): string {
+	const lines = text.split("\n");
+	let open: { index: number; marker: string; info: string } | undefined;
+	for (let index = 0; index < lines.length; index++) {
+		const match = MARKDOWN_FENCE_LINE.exec(lines[index]!);
+		if (!match) continue;
+		const marker = match[1]!;
+		const info = match[2]!.trim();
+		if (!open) {
+			open = { index, marker, info };
+			continue;
+		}
+		if (marker[0] === open.marker[0] && marker.length >= open.marker.length && info === "") {
+			open = undefined;
+		}
+	}
+	if (open?.info !== "") return text;
 
-function isOsc66Line(line: string): boolean {
-	return line.includes(OSC66_LINE_PREFIX);
+	let previous = "";
+	for (let index = open.index - 1; index >= 0; index--) {
+		previous = lines[index]!.trim();
+		if (previous) break;
+	}
+	if (!previous || previous.endsWith(":") || FENCED_SOURCE_INTRO.test(previous)) return text;
+
+	let hasHeading = false;
+	let hasTableDelimiter = false;
+	for (let index = open.index + 1; index < lines.length; index++) {
+		const line = lines[index]!;
+		hasHeading ||= MARKDOWN_HEADING_LINE.test(line);
+		hasTableDelimiter ||= isGfmTableDelimiter(line, lines[index - 1]);
+		if (hasHeading && hasTableDelimiter) {
+			lines.splice(open.index, 1);
+			return lines.join("\n");
+		}
+	}
+	return text;
 }
 
+// OSC 66 (Kitty text-sizing) heading spans are emitted as a single indivisible
+// unit by the H1 render path. Like image-protocol lines, they bypass ANSI
+// wrapping and width padding (see `isOsc66Line` in ../utils): re-wrapping
+// splits/normalizes the sized span (recomputing the explicit `w=` cell count
+// and hoisting SGR out of the OSC payload), and padding would append trailing
+// cells past the doubled glyph.
+
 function normalizeHtmlEntitiesForTerminal(raw: string): string {
 	const parseCodePoint = (value: number): string => {
 		if (Number.isFinite(value) && value >= 0 && value <= 0x10ffff) {
@@ -1412,7 +1479,9 @@ interface RenderedTableLayout extends TableLayoutLock {
 	endRow: number;
 }
 
-export class Markdown implements Component, NativeScrollbackCommittedRows, NativeScrollbackReplay {
+export class Markdown
+	implements Component, NativeScrollbackCommittedRows, NativeScrollbackReplay, NativeScrollbackWidthEpoch
+{
 	#text: string;
 	#paddingX: number; // Left/right padding
 	#paddingY: number; // Top/bottom padding
@@ -1450,6 +1519,16 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 	// exposure to 0 and re-earns it — the exposure is hard-monotone within a
 	// text lineage.
 	#settledExposedText?: string;
+	// Semantic source state that produced the most recent render. Unlike #text,
+	// it does not advance when streaming updates arrive before the next paint.
+	#lastRenderedText?: string;
+	#lastRenderedTransientRenderCache = false;
+	#lastRenderedHasMutableTrailingRow = false;
+	#widthEpochBoundaries = new WeakMap<
+		object,
+		{ text: string; transientRenderCache: boolean; hasMutableTrailingRow: boolean }
+	>();
+
 	// True while #renderStreamingContentLines renders the frozen token range:
 	// frozen code blocks highlight even in transient mode so their bytes match
 	// the finalized render (they render once into the prefix line cache, so
@@ -1545,6 +1624,56 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 		return this.#lastRenderSettledRows;
 	}
 
+	captureNativeScrollbackWidthEpoch(): unknown {
+		if (this.#lastRenderedText === undefined) return undefined;
+		const marker = {};
+		this.#widthEpochBoundaries.set(marker, {
+			text: this.#lastRenderedText,
+			transientRenderCache: this.#lastRenderedTransientRenderCache,
+			hasMutableTrailingRow: this.#lastRenderedHasMutableTrailingRow,
+		});
+		return marker;
+	}
+
+	resolveNativeScrollbackWidthEpoch(boundary: unknown): number | undefined {
+		if (typeof boundary !== "object" || boundary === null || this.#cachedWidth === undefined) return undefined;
+		const captured = this.#widthEpochBoundaries.get(boundary);
+		if (captured === undefined) return undefined;
+		const snapshot = new Markdown(
+			captured.text,
+			this.#paddingX,
+			this.#paddingY,
+			this.#theme,
+			this.#defaultTextStyle,
+			this.#codeBlockIndent,
+		);
+		snapshot.#ignoreTight = this.#ignoreTight;
+		snapshot.#transientRenderCache = captured.transientRenderCache;
+		return Math.max(
+			0,
+			snapshot.render(this.#cachedWidth).length - this.#paddingY - (captured.hasMutableTrailingRow ? 1 : 0),
+		);
+	}
+
+	getNativeScrollbackWidthEpochRows(): number | undefined {
+		return this.#cachedLines === undefined ? undefined : this.#widthEpochRows(this.#cachedLines.length);
+	}
+
+	isNativeScrollbackWidthEpochAppendOnly(boundary: unknown): boolean {
+		if (typeof boundary !== "object" || boundary === null) return true;
+		return this.#widthEpochBoundaries.get(boundary)?.hasMutableTrailingRow !== true;
+	}
+
+	#widthEpochRows(renderedRows: number): number {
+		return Math.max(0, renderedRows - this.#paddingY - (this.#transientRenderCache ? 1 : 0));
+	}
+
+	#recordLastRenderedState(hasContentRows: boolean): void {
+		this.#lastRenderedText = this.#text;
+		this.#lastRenderedTransientRenderCache = this.#transientRenderCache;
+		this.#lastRenderedHasMutableTrailingRow = this.#transientRenderCache && hasContentRows;
+	}
+
 	/**
 	 * 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
@@ -1644,6 +1773,7 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 		// Returning the cached reference is load-bearing: parents memoize their
 		// concatenation on reference equality.
 		if (this.#cachedLines && this.#cachedText === this.#text && this.#cachedWidth === width) {
+			this.#recordLastRenderedState(this.#cachedLines.length > 0);
 			return this.#cachedLines;
 		}
 
@@ -1660,11 +1790,14 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 			this.#cachedText = this.#text;
 			this.#cachedWidth = width;
 			this.#cachedLines = EMPTY_RENDER_LINES;
+			this.#recordLastRenderedState(false);
 			return EMPTY_RENDER_LINES;
 		}
 
 		// Replace tabs with 3 spaces for consistent rendering
-		const normalizedText = replaceTabs(this.#text);
+		const normalizedText = this.transientRenderCache
+			? replaceTabs(this.#text)
+			: repairOrphanClosingFence(replaceTabs(this.#text));
 		const signature = this.#renderSignature(width, paddingX);
 
 		// L2: module-level LRU — survives component disposal/recreation across
@@ -1695,6 +1828,7 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 				this.#cachedText = this.#text;
 				this.#cachedWidth = width;
 				this.#cachedLines = cached.lines;
+				this.#recordLastRenderedState(cached.lines.length > 0);
 				return cached.lines;
 			}
 		}
@@ -1738,6 +1872,7 @@ export class Markdown implements Component, NativeScrollbackCommittedRows, Nativ
 				})),
 			});
 		}
+		this.#recordLastRenderedState(contentLines.length > 0);
 
 		return result;
 	}

package/src/components/text.ts

@@ -25,11 +25,14 @@ export class Text implements Component {
 	#paddingY: number; // Top/bottom padding
 	#customBgFn?: (text: string) => string;
 	#styleFn?: (text: string) => string;
+	#widthEpochRevision = 0;
 
 	#ignoreTight = false;
 
 	setIgnoreTight(ignore: boolean): this {
+		if (this.#ignoreTight === ignore) return this;
 		this.#ignoreTight = ignore;
+		this.#widthEpochRevision++;
 		this.invalidate();
 		return this;
 	}
@@ -60,15 +63,21 @@ export class Text implements Component {
 		this.#cachedWidth = undefined;
 		this.#cachedWidthEpoch = undefined;
 		this.#cachedLines = undefined;
+		this.#widthEpochRevision++;
 		return true;
 	}
 
+	getNativeScrollbackWidthEpochRevision(): number {
+		return this.#widthEpochRevision;
+	}
+
 	setCustomBgFn(customBgFn?: (text: string) => string): void {
 		this.#customBgFn = customBgFn;
 		this.#cachedText = undefined;
 		this.#cachedWidth = undefined;
 		this.#cachedWidthEpoch = undefined;
 		this.#cachedLines = undefined;
+		this.#widthEpochRevision++;
 	}
 
 	/**
@@ -83,6 +92,7 @@ export class Text implements Component {
 		this.#cachedWidth = undefined;
 		this.#cachedWidthEpoch = undefined;
 		this.#cachedLines = undefined;
+		this.#widthEpochRevision++;
 		return this;
 	}
 

package/src/latex-block.ts

@@ -146,6 +146,16 @@ const HBRACE_COMMANDS: Record<string, HBraceSpec> = {
 	underparen: { left: "╰", mid: "─", center: "─", right: "╯", over: false },
 };
 
+/**
+ * Number of required arguments each display command consumes. Shared by
+ * {@link readArg} and {@link splitLines} so nested command atoms consume exactly
+ * their own arguments while preserving any outer command's pending arity.
+ */
+const COMMAND_ARITY: Record<string, number> = { overset: 2, underset: 2, stackrel: 2, sqrt: 1 };
+for (const name in FRAC_COMMANDS) COMMAND_ARITY[name] = 2;
+for (const name in BINOM_COMMANDS) COMMAND_ARITY[name] = 2;
+for (const name in HBRACE_COMMANDS) COMMAND_ARITY[name] = 1;
+
 // 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).
@@ -516,11 +526,13 @@ function readBraceGroup(src: string, i: number): Span {
 
 /**
  * Read one command 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.
+ * together with its arguments (or whole `\begin…\end` block). Commands whose
+ * arity is known consume exactly that many arguments, including across source
+ * whitespace, so `\frac\sqrt {a} {b}` reads `\sqrt {a}` as the numerator and
+ * leaves `{b}` for the denominator.
  */
 function readArg(src: string, i: number): Span {
-	while (src[i] === " ") i++;
+	while (src[i] === " " || src[i] === "\t" || src[i] === "\n") 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 };
@@ -535,6 +547,22 @@ function readArg(src: string, i: number): Span {
 		if (env) return env;
 	}
 	if (!name) return { text: src.slice(i, i + 2), end: i + 2 }; // non-letter command (\,, \{, …)
+
+	const arity = COMMAND_ARITY[name];
+	if (arity !== undefined) {
+		let end = j;
+		// Optional command arguments (e.g. the degree in `\sqrt[3]{x}`) do not
+		// consume a required-argument slot.
+		for (;;) {
+			while (src[end] === " " || src[end] === "\t" || src[end] === "\n") end++;
+			if (src[end] !== "[") break;
+			const close = src.indexOf("]", end);
+			end = close === -1 ? src.length : close + 1;
+		}
+		for (let arg = 0; arg < arity; arg++) end = readArg(src, end).end;
+		return { text: src.slice(i, end), end };
+	}
+
 	let end = j;
 	while (src[end] === "[" || src[end] === "{") {
 		if (src[end] === "{") end = readBraceGroup(src, end).end;
@@ -1271,6 +1299,80 @@ function parseExpr(src: string, ctx: Ctx = ROOT_CTX): Box {
 	return hconcat(boxes);
 }
 
+/**
+ * Count the command arguments still owed at the end of `seg` — non-zero when
+ * the row ends mid-construct (`\frac{a}` awaiting its denominator, or
+ * `\frac`/`x^` awaiting any argument). Pending arities form a stack: an
+ * unbraced nested command consumes one outer argument, then retains its own
+ * pending arguments without discarding the outer command's remaining arity.
+ * Used to keep a command joined to an argument written on the next source line
+ * while still treating an ordinary next row (`a\n{b+c}`) as a real row break.
+ */
+function bracesOwed(seg: string): number {
+	const pending: number[] = [];
+	const consumeArg = (): void => {
+		const top = pending.length - 1;
+		if (top < 0) return;
+		if (pending[top] === 1) pending.pop();
+		else pending[top]--;
+	};
+
+	let i = 0;
+	while (i < seg.length) {
+		const c = seg[i];
+		if (c === "\\") {
+			let j = i + 1;
+			let name = "";
+			while (j < seg.length && /[A-Za-z]/.test(seg[j])) name += seg[j++];
+			// A command plus its immediately attached `[…]`/`{…}` groups is one
+			// atom for an enclosing argument, matching readArg. Consume that outer
+			// argument first, then retain only the command's own missing arguments
+			// in a nested frame. Attached groups beyond the known arity still stay
+			// part of the atom and cannot consume another outer argument.
+			consumeArg();
+			const arity = name ? (COMMAND_ARITY[name] ?? 0) : 0;
+			let attached = 0;
+			if (name) {
+				while (seg[j] === "[" || seg[j] === "{") {
+					if (seg[j] === "{") {
+						j = readBraceGroup(seg, j).end;
+						if (attached < arity) attached++;
+					} else {
+						const close = seg.indexOf("]", j);
+						j = close === -1 ? seg.length : close + 1;
+					}
+				}
+			} else {
+				j = i + 2; // non-letter command (`\,`, `\{`, …)
+			}
+			const missing = arity - attached;
+			if (missing > 0) pending.push(missing);
+			i = j;
+			continue;
+		}
+		if (c === "{") {
+			i = readBraceGroup(seg, i).end;
+			consumeArg();
+			continue;
+		}
+		if (c === "^" || c === "_") {
+			pending.push(1);
+			i++;
+			continue;
+		}
+		if (c === " " || c === "\t" || c === "\n") {
+			i++;
+			continue;
+		}
+		consumeArg(); // a bare atom satisfies one pending argument
+		i++;
+	}
+
+	let owed = 0;
+	for (const remaining of pending) owed += remaining;
+	return owed;
+}
+
 /** Split on top-level `\n` and `\\` row separators (outside braces and environments). */
 function splitLines(src: string): string[] {
 	const lines: string[] = [];
@@ -1308,8 +1410,16 @@ function splitLines(src: string): string[] {
 		if (c === "{") braceDepth++;
 		else if (c === "}") braceDepth--;
 		else if (c === "\n" && braceDepth === 0 && envDepth === 0) {
-			lines.push(src.slice(last, i));
-			last = i + 1;
+			// A top-level newline is a row break UNLESS the current row ends with a
+			// command still awaiting an argument (e.g. `\frac{num}\n{den}`,
+			// `\frac{num}\n\sqrt{x}`, or `x^\n2`). Splitting there would sever the
+			// command from its argument, so keep both in one segment; latexToBlock
+			// collapses the interior newline to a space before parsing. A row that
+			// merely opens with a braced group (`a\n{b+c}`) stays a break.
+			if (bracesOwed(src.slice(last, i)) === 0) {
+				lines.push(src.slice(last, i));
+				last = i + 1;
+			}
 		}
 		i++;
 	}
@@ -1327,7 +1437,7 @@ function splitLines(src: string): string[] {
 export function latexToBlock(src: string): string[] {
 	if (typeof src !== "string" || src.trim() === "") return [];
 	const rows = splitLines(src.trim())
-		.map(line => line.trim())
+		.map(line => line.replace(/[ \t]*\n[ \t]*/g, " ").trim())
 		.filter(line => line !== "")
 		.map(line => parseExpr(line));
 	if (rows.length === 0) return [];

package/src/terminal-capabilities.ts

@@ -731,6 +731,80 @@ export function encodeKittyPlacement(options: {
 	return wrapTmuxPassthroughIfNeeded(`\x1b_G${params.join(",")}\x1b\\`);
 }
 
+/**
+ * Exact shape of the direct-placement line {@link Image} emits as its block's
+ * last row: optional `ESC 7` + `CUU(rows-1)` prefix, the {@link encodeKittyPlacement}
+ * APC, optional `ESC 8` suffix. tmux-passthrough-wrapped lines deliberately do
+ * not match (passthrough placements stay untouched).
+ */
+const KITTY_DIRECT_PLACEMENT_LINE =
+	/^(?:\x1b7(?:\x1b\[(\d+)A)?)?\x1b_Ga=p,q=2,C=1,i=(\d+)(?:,p=(\d+))?(?:,c=(\d+))?(?:,r=(\d+))?\x1b\\(?:\x1b8)?$/;
+
+export interface ParsedKittyPlacementLine {
+	imageId: number;
+	placementId: number | undefined;
+	columns: number;
+	rows: number;
+}
+
+/**
+ * Parse a frame line that consists solely of a Kitty direct placement (the
+ * last line of an {@link Image} block). Returns null for anything else —
+ * placeholder grids, tmux-wrapped placements, sixel/iTerm2 payloads — so
+ * callers fall back to writing the line verbatim.
+ */
+export function parseKittyDirectPlacementLine(line: string): ParsedKittyPlacementLine | null {
+	const m = KITTY_DIRECT_PLACEMENT_LINE.exec(line);
+	if (!m) return null;
+	const columns = m[4] !== undefined ? Number(m[4]) : 0;
+	const rows = m[5] !== undefined ? Number(m[5]) : 0;
+	if (columns <= 0 || rows <= 0) return null;
+	return {
+		imageId: Number(m[2]),
+		placementId: m[3] !== undefined ? Number(m[3]) : undefined,
+		columns,
+		rows,
+	};
+}
+
+/**
+ * Rebuild an {@link Image} direct-placement line for the viewport row it is
+ * written at. The component-rendered line encodes `CUU(rows-1)`, which clamps
+ * at the viewport top once the block's leading rows have scrolled out — the
+ * placement then re-anchors the full image shifted down over foreign rows.
+ * Anchor at the block's first *visible* row instead, clipping the source
+ * rectangle (`y=`/`h=`, image pixels) to the visible bottom slice.
+ */
+export function encodeKittyPlacementLine(options: {
+	imageId: number;
+	placementId: number;
+	columns: number;
+	/** Total cell rows of the image block. */
+	rows: number;
+	/** Viewport row the block's last line is being written at. */
+	screenRow: number;
+	/** Source image height in pixels, for the clipped source rectangle. */
+	imageHeightPx: number;
+}): string {
+	// Without a source pixel height the slice cannot be expressed — emit the
+	// component's own full form (status quo) rather than squashing the whole
+	// image into the reduced row count.
+	const clippable = options.imageHeightPx > 0;
+	const hiddenRows = clippable ? Math.max(0, options.rows - 1 - options.screenRow) : 0;
+	const visibleRows = options.rows - hiddenRows;
+	const params: string[] = ["a=p", "q=2", "C=1", `i=${options.imageId}`, `p=${options.placementId}`];
+	params.push(`c=${options.columns}`, `r=${visibleRows}`);
+	if (hiddenRows > 0) {
+		const srcY = Math.floor((options.imageHeightPx * hiddenRows) / options.rows);
+		params.push(`y=${srcY}`, `h=${Math.max(1, options.imageHeightPx - srcY)}`);
+	}
+	// No tmux passthrough: inside tmux the component's own line arrives
+	// wrapped, never parses, and never reaches this rewrite.
+	const apc = `\x1b_G${params.join(",")}\x1b\\`;
+	const cuu = visibleRows - 1;
+	return cuu > 0 ? `\x1b7\x1b[${cuu}A${apc}\x1b8` : apc;
+}
+
 /**
  * Kitty graphics delete command for a single image id. Uses `d=I` (capital)
  * which removes the image and every one of its placements — on screen *and* in
@@ -742,6 +816,16 @@ export function encodeKittyDeleteImage(imageId: number): string {
 	return wrapTmuxPassthroughIfNeeded(`\x1b_Ga=d,d=I,i=${imageId},q=2\x1b\\`);
 }
 
+/**
+ * Delete a single placement of an image (`d=i`, lowercase): removes its cells
+ * and registry entry but keeps the transmitted data, so a later `a=p` under a
+ * fresh placement id needs no retransmit. Used to clear stale placement-epoch
+ * entries after a destructive history clear.
+ */
+export function encodeKittyDeletePlacement(imageId: number, placementId: number): string {
+	return wrapTmuxPassthroughIfNeeded(`\x1b_Ga=d,d=i,i=${imageId},p=${placementId},q=2\x1b\\`);
+}
+
 export function encodeITerm2(
 	base64Data: string,
 	options: {