@oh-my-pi/pi-tui 18.2.3 → 18.2.5

package/src/components/layout/stack.ts

@@ -0,0 +1,261 @@
+import type { MouseRoutable, SgrMouseEvent } from "../../mouse";
+import type { Component } from "../../tui";
+import { padding } from "../../utils";
+import {
+	allocateLayoutSpace,
+	equalLayoutInsets,
+	fitLayoutLine,
+	isLayoutMouseRoutable,
+	layoutAlignmentOffset,
+	type LayoutAlignment,
+	type LayoutContent,
+	layoutInsets,
+	type LayoutInsets,
+	type LayoutRect,
+	layoutSize,
+	optionalLayoutSize,
+	renderLayoutContent,
+	uniqueLayoutComponents,
+} from "./geometry";
+
+/** One child and its vertical row-budget constraints. */
+export interface StackChild {
+	content: LayoutContent;
+	height?: number;
+	grow?: number;
+	minHeight?: number;
+	maxHeight?: number;
+	padding?: LayoutInsets;
+	align?: LayoutAlignment;
+}
+
+/** Construction options for {@link Stack}. */
+export interface StackOptions {
+	children: readonly StackChild[];
+	height?: number;
+	align?: LayoutAlignment;
+}
+
+/** A stack hit translated into the child's local coordinates. */
+export interface StackHit {
+	index: number;
+	content: LayoutContent;
+	line: number;
+	col: number;
+	rect: LayoutRect;
+}
+
+interface StackMemo {
+	width: number;
+	height: number | undefined;
+	heights: readonly number[];
+	lines: readonly (readonly string[])[];
+	result: readonly string[];
+}
+
+function sameChild(left: StackChild, right: StackChild): boolean {
+	return (
+		left.content === right.content &&
+		left.height === right.height &&
+		left.grow === right.grow &&
+		left.minHeight === right.minHeight &&
+		left.maxHeight === right.maxHeight &&
+		left.align === right.align &&
+		equalLayoutInsets(left.padding, right.padding)
+	);
+}
+
+/**
+ * Vertical component layout with fixed and growing regions, exact height
+ * budgets, ANSI-aware clipping, padding, and local mouse translation.
+ */
+export class Stack implements Component, MouseRoutable {
+	#children: StackChild[];
+	#height: number | undefined;
+	#align: LayoutAlignment;
+	#frames: LayoutRect[] = [];
+	#memo: StackMemo | undefined;
+	#ignoreTight = false;
+
+	constructor(options: StackOptions) {
+		this.#children = options.children.map(child => ({ ...child, padding: { ...child.padding } }));
+		this.#height = optionalLayoutSize(options.height);
+		this.#align = options.align ?? "start";
+	}
+
+	/** Concrete component children exposed to the debug tree. */
+	get debugChildren(): readonly Component[] {
+		return uniqueLayoutComponents(this.#children.map(child => child.content));
+	}
+
+	/** Last-rendered content rectangle for `index`, excluding its padding. */
+	childRect(index: number): LayoutRect | undefined {
+		return this.#frames[index];
+	}
+
+	/** Replace the stack's children without recreating the layout component. */
+	setChildren(children: readonly StackChild[]): void {
+		if (
+			children.length === this.#children.length &&
+			children.every((child, index) => sameChild(child, this.#children[index]!))
+		) {
+			return;
+		}
+		this.#children = children.map(child => ({ ...child, padding: { ...child.padding } }));
+		if (this.#ignoreTight) {
+			for (const child of uniqueLayoutComponents(this.#children.map(item => item.content))) {
+				child.setIgnoreTight?.(true);
+			}
+		}
+		this.#memo = undefined;
+	}
+
+	/** Set the exact total row budget, or clear it to use natural height. */
+	setHeight(height: number | undefined): void {
+		const next = optionalLayoutSize(height);
+		if (next === this.#height) return;
+		this.#height = next;
+		this.#memo = undefined;
+	}
+
+	setIgnoreTight(ignore: boolean): this {
+		if (ignore === this.#ignoreTight) return this;
+		this.#ignoreTight = ignore;
+		for (const child of uniqueLayoutComponents(this.#children.map(item => item.content))) {
+			child.setIgnoreTight?.(ignore);
+		}
+		this.#memo = undefined;
+		return this;
+	}
+
+	invalidate(): void {
+		this.#memo = undefined;
+		for (const child of uniqueLayoutComponents(this.#children.map(item => item.content))) {
+			child.invalidate?.();
+		}
+	}
+
+	dispose(): void {
+		for (const child of uniqueLayoutComponents(this.#children.map(item => item.content))) {
+			child.dispose?.();
+		}
+	}
+
+	/** Translate a stack-local point into a child's local coordinates. */
+	locate(line: number, col: number): StackHit | undefined {
+		for (let index = 0; index < this.#frames.length; index++) {
+			const rect = this.#frames[index];
+			if (!rect) continue;
+			if (line < rect.row || line >= rect.row + rect.height || col < rect.col || col >= rect.col + rect.width)
+				continue;
+			return {
+				index,
+				content: this.#children[index]!.content,
+				line: line - rect.row,
+				col: col - rect.col,
+				rect,
+			};
+		}
+		return undefined;
+	}
+
+	routeMouse(event: SgrMouseEvent, line: number, col: number): void {
+		const hit = this.locate(line, col);
+		if (hit && isLayoutMouseRoutable(hit.content)) hit.content.routeMouse(event, hit.line, hit.col);
+	}
+
+	render(width: number): readonly string[] {
+		width = layoutSize(width);
+		const insets = this.#children.map(child => layoutInsets(child.padding));
+		let heights = this.#children.map(child => {
+			if (child.height !== undefined) return layoutSize(child.height);
+			return this.#height !== undefined && layoutSize(child.grow) > 0 ? layoutSize(child.minHeight) : -1;
+		});
+		const childLines: (readonly string[])[] = Array.from({ length: this.#children.length }, () => []);
+		const rendered = this.#children.map(() => false);
+
+		for (let index = 0; index < this.#children.length; index++) {
+			if ((heights[index] ?? -1) >= 0) continue;
+			const inset = insets[index]!;
+			const contentWidth = Math.max(0, width - inset.left - inset.right);
+			const lines =
+				contentWidth > 0 ? renderLayoutContent(this.#children[index]!.content, contentWidth, undefined) : [];
+			childLines[index] = lines;
+			rendered[index] = true;
+			heights[index] = lines.length + inset.top + inset.bottom;
+		}
+
+		const naturalTotal = heights.reduce((sum, height) => sum + Math.max(0, height), 0);
+		heights = allocateLayoutSpace(
+			this.#children.map((child, index) => ({
+				fixed:
+					child.height !== undefined || this.#height === undefined || layoutSize(child.grow) === 0
+						? heights[index]
+						: undefined,
+				grow: child.grow,
+				min: child.minHeight,
+				max: child.maxHeight,
+			})),
+			this.#height ?? naturalTotal,
+		);
+
+		for (let index = 0; index < this.#children.length; index++) {
+			if (rendered[index] || (heights[index] ?? 0) <= 0) continue;
+			const inset = insets[index]!;
+			const contentWidth = Math.max(0, width - inset.left - inset.right);
+			const contentHeight = Math.max(0, (heights[index] ?? 0) - inset.top - inset.bottom);
+			childLines[index] =
+				contentWidth > 0 ? renderLayoutContent(this.#children[index]!.content, contentWidth, contentHeight) : [];
+			rendered[index] = true;
+		}
+
+		let row = 0;
+		this.#frames = this.#children.map((_child, index) => {
+			const inset = insets[index]!;
+			const allocated = heights[index] ?? 0;
+			const rect: LayoutRect = {
+				row: row + inset.top,
+				col: inset.left,
+				width: Math.max(0, width - inset.left - inset.right),
+				height: Math.max(0, allocated - inset.top - inset.bottom),
+			};
+			row += allocated;
+			return rect;
+		});
+
+		const memo = this.#memo;
+		if (
+			memo &&
+			memo.width === width &&
+			memo.height === this.#height &&
+			memo.heights.length === heights.length &&
+			memo.heights.every((value, index) => value === heights[index]) &&
+			memo.lines.length === childLines.length &&
+			memo.lines.every((lines, index) => lines === childLines[index])
+		) {
+			return memo.result;
+		}
+
+		const result: string[] = [];
+		for (let index = 0; index < this.#children.length; index++) {
+			const child = this.#children[index]!;
+			const inset = insets[index]!;
+			const allocated = heights[index] ?? 0;
+			const viewportHeight = Math.max(0, allocated - inset.top - inset.bottom);
+			const lines = childLines[index]!;
+			const visibleHeight = Math.min(viewportHeight, lines.length);
+			const offset = layoutAlignmentOffset(viewportHeight - visibleHeight, child.align ?? this.#align);
+			for (let line = 0; line < allocated; line++) {
+				const childLine = line - inset.top - offset;
+				const content = childLine >= 0 && childLine < visibleHeight ? (lines[childLine] ?? "") : "";
+				const innerWidth = Math.max(0, width - inset.left - inset.right);
+				result.push(
+					fitLayoutLine(padding(inset.left) + fitLayoutLine(content, innerWidth) + padding(inset.right), width),
+				);
+			}
+		}
+		while (this.#height !== undefined && result.length < this.#height) result.push(padding(width));
+		this.#memo = { width, height: this.#height, heights, lines: childLines, result };
+		return result;
+	}
+}

package/src/components/markdown.ts

@@ -2061,17 +2061,8 @@ export class Markdown implements Component {
 			return EMPTY_RENDER_LINES;
 		}
 
-		// Replace tabs with spaces, then repair orphan fences in final mode.
-		const tabbed = replaceTabs(this.#text);
-		const normalizedText = this.transientRenderCache ? tabbed : repairOrphanClosingFence(tabbed);
-		if (!this.transientRenderCache && normalizedText.length < tabbed.length) {
-			// repairOrphanClosingFence deleted bytes this frame (orphan fence
-			// removed): the guard-scan memo's checked region is no longer
-			// byte-identical, and a cached false verdict may have been based
-			// on the very CR/ref-def line that was deleted. Invalidate so the
-			// next #lexTokens re-derives on the repaired buffer.
-			this.#lastScanValid = false;
-		}
+		// Fast-path inputs only: signature first, so the append-only branch below
+		// can return without scanning the whole document for tabs.
 		const signature = this.#renderSignature(width, paddingX);
 		// B+ fast path: an append-only, same-line delta re-renders ONLY the
 		// last content row (the paragraph's trailing wrapped row) with the
@@ -2197,7 +2188,20 @@ export class Markdown implements Component {
 			// Hazard → disarm until the next real render re-captures.
 			this.#fastTail = undefined;
 		}
-		// Replace tabs with 3 spaces for consistent rendering
+		// Normalize only after the append-only branch: the fast path above
+		// returns without ever reading these, so streaming frames skip the
+		// whole-document tab scan/copy (the delta-only replaceTabs inside the
+		// branch is the only tab work a streamed frame pays).
+		const tabbed = this.#text.includes("\t") ? replaceTabs(this.#text) : this.#text;
+		const normalizedText = this.transientRenderCache ? tabbed : repairOrphanClosingFence(tabbed);
+		if (!this.transientRenderCache && normalizedText.length < tabbed.length) {
+			// repairOrphanClosingFence deleted bytes this frame (orphan fence
+			// removed): the guard-scan memo's checked region is no longer
+			// byte-identical, and a cached false verdict may have been based
+			// on the very CR/ref-def line that was deleted. Invalidate so the
+			// next #lexTokens re-derives on the repaired buffer.
+			this.#lastScanValid = false;
+		}
 
 		// L2: module-level LRU — survives component disposal/recreation across
 		// session-tree navigations. Key encodes every dimension that affects the

package/src/components/menu-selection.ts

@@ -0,0 +1,248 @@
+import { fuzzyFilter } from "../fuzzy";
+
+/** Describes how a menu identifies, searches, disables, and confirms its items. */
+export interface MenuSelectionAdapter<T> {
+	/** Stable identity used to retain selection while data or filtering changes. */
+	getKey: (item: T) => string;
+	/** Searchable text used by the default fuzzy filter. */
+	getSearchText: (item: T) => string;
+	/** Disabled items remain visible but are skipped by navigation and cannot activate. */
+	isDisabled?: (item: T) => boolean;
+	/** Items returning true require two activation requests without an intervening state change. */
+	requiresConfirmation?: (item: T) => boolean;
+	/** Optional domain-specific filtering/ranking. */
+	filter?: (items: readonly T[], query: string) => readonly T[];
+}
+
+/** Result of requesting activation of the current menu item. */
+export type MenuActivation<T> =
+	| { kind: "empty" }
+	| { kind: "disabled"; item: T }
+	| { kind: "pending"; item: T }
+	| { kind: "confirmed"; item: T };
+
+/** A viewport over variable-height items. */
+export interface MenuWindow {
+	startIndex: number;
+	endIndex: number;
+	/** Number of visual rows before startIndex, for scrollbar positioning. */
+	rowOffset: number;
+	/** Total visual rows across every item. */
+	totalRows: number;
+}
+
+/**
+ * Pick a selection-centered, contiguous window whose visual rows fit `rowBudget`.
+ * A selected item taller than the budget is retained and clipped by the renderer.
+ */
+export function getMenuWindow(rowCounts: readonly number[], selectedIndex: number, rowBudget: number): MenuWindow {
+	let totalRows = 0;
+	for (const count of rowCounts) totalRows += Math.max(0, count);
+	if (rowCounts.length === 0) return { startIndex: 0, endIndex: 0, rowOffset: 0, totalRows };
+
+	const budget = Math.max(1, Math.trunc(rowBudget));
+	const selected = Math.max(0, Math.min(Math.trunc(selectedIndex), rowCounts.length - 1));
+	const selectedRows = Math.max(0, rowCounts[selected] ?? 0);
+	const targetRowsBeforeSelection = Math.floor(Math.max(0, budget - Math.min(selectedRows, budget)) / 2);
+	let startIndex = selected;
+	let rowsBeforeSelection = 0;
+	while (startIndex > 0) {
+		const cost = Math.max(0, rowCounts[startIndex - 1] ?? 0);
+		if (rowsBeforeSelection + cost > targetRowsBeforeSelection) break;
+		startIndex--;
+		rowsBeforeSelection += cost;
+	}
+
+	let endIndex = selected + 1;
+	let used = rowsBeforeSelection + selectedRows;
+	while (endIndex < rowCounts.length) {
+		const cost = Math.max(0, rowCounts[endIndex] ?? 0);
+		if (used + cost > budget) break;
+		used += cost;
+		endIndex++;
+	}
+	while (startIndex > 0) {
+		const cost = Math.max(0, rowCounts[startIndex - 1] ?? 0);
+		if (used + cost > budget) break;
+		startIndex--;
+		used += cost;
+	}
+
+	let rowOffset = 0;
+	for (let index = 0; index < startIndex; index++) rowOffset += Math.max(0, rowCounts[index] ?? 0);
+	return { startIndex, endIndex, rowOffset, totalRows };
+}
+
+/**
+ * Controlled menu data, filtering, selection, disabled-row navigation, and
+ * confirmation state. Renderers remain domain-owned and consume `visibleItems`.
+ */
+export class MenuSelection<T> {
+	#items: readonly T[];
+	#visibleItems: readonly T[];
+	#query = "";
+	#selectedIndex = -1;
+	#pendingKey: string | undefined;
+
+	constructor(
+		items: readonly T[],
+		readonly adapter: MenuSelectionAdapter<T>,
+		initialKey?: string,
+	) {
+		this.#items = items;
+		this.#visibleItems = items;
+		this.#selectedIndex = this.#findInitialIndex(initialKey);
+	}
+
+	get items(): readonly T[] {
+		return this.#items;
+	}
+
+	get visibleItems(): readonly T[] {
+		return this.#visibleItems;
+	}
+
+	get query(): string {
+		return this.#query;
+	}
+
+	get selectedIndex(): number {
+		return this.#selectedIndex;
+	}
+
+	get selectedItem(): T | undefined {
+		return this.#visibleItems[this.#selectedIndex];
+	}
+
+	get selectedKey(): string | undefined {
+		const item = this.selectedItem;
+		return item === undefined ? undefined : this.adapter.getKey(item);
+	}
+
+	get pendingKey(): string | undefined {
+		return this.#pendingKey;
+	}
+
+	isDisabled(item: T): boolean {
+		return this.adapter.isDisabled?.(item) ?? false;
+	}
+
+	isPending(item: T): boolean {
+		return this.#pendingKey === this.adapter.getKey(item);
+	}
+
+	/** Replace controlled data, retaining the selected key when it remains visible. */
+	setItems(items: readonly T[], selectedKey = this.selectedKey): boolean {
+		const previousKey = this.selectedKey;
+		this.#items = items;
+		this.#applyFilter(selectedKey);
+		this.#pendingKey = undefined;
+		return previousKey !== this.selectedKey;
+	}
+
+	/** Set the query and retain the selected key when it survives filtering. */
+	setQuery(query: string, retainSelection = true): boolean {
+		if (query === this.#query) return false;
+		const previousKey = this.selectedKey;
+		this.#query = query;
+		this.#pendingKey = undefined;
+		this.#applyFilter(retainSelection ? previousKey : undefined);
+		return previousKey !== this.selectedKey;
+	}
+
+	/** Select a visible row, coercing disabled rows to the nearest enabled row. */
+	setSelectedIndex(index: number, direction: -1 | 1 = 1): boolean {
+		const next = this.#coerceIndex(index, direction);
+		if (next === this.#selectedIndex) return false;
+		this.#selectedIndex = next;
+		this.#pendingKey = undefined;
+		return true;
+	}
+
+	setSelectedKey(key: string): boolean {
+		const index = this.#visibleItems.findIndex(item => this.adapter.getKey(item) === key);
+		return index >= 0 ? this.setSelectedIndex(index) : false;
+	}
+
+	/** Move by item count, optionally wrapping at list edges. */
+	move(delta: number, wrap = false): boolean {
+		const total = this.#visibleItems.length;
+		if (total === 0 || delta === 0) return false;
+		const direction: -1 | 1 = delta < 0 ? -1 : 1;
+		let remaining = Math.max(1, Math.abs(Math.trunc(delta)));
+		let index = this.#selectedIndex;
+		for (let attempts = 0; attempts < total && remaining > 0; attempts++) {
+			let next = index + direction;
+			if (next < 0 || next >= total) {
+				if (!wrap) break;
+				next = direction > 0 ? 0 : total - 1;
+			}
+			if (next === index) break;
+			index = next;
+			const item = this.#visibleItems[index];
+			if (item !== undefined && !this.isDisabled(item)) remaining--;
+		}
+		return index !== this.#selectedIndex && this.setSelectedIndex(index, direction);
+	}
+
+	moveToBoundary(boundary: "first" | "last"): boolean {
+		return this.setSelectedIndex(
+			boundary === "first" ? 0 : this.#visibleItems.length - 1,
+			boundary === "first" ? 1 : -1,
+		);
+	}
+
+	/** Clear a pending confirmation. Returns true only when one was cleared. */
+	cancelConfirmation(): boolean {
+		if (this.#pendingKey === undefined) return false;
+		this.#pendingKey = undefined;
+		return true;
+	}
+
+	requestActivation(index = this.#selectedIndex): MenuActivation<T> {
+		const item = this.#visibleItems[index];
+		if (item === undefined) return { kind: "empty" };
+		if (this.isDisabled(item)) return { kind: "disabled", item };
+		const key = this.adapter.getKey(item);
+		if (this.adapter.requiresConfirmation?.(item) === true && this.#pendingKey !== key) {
+			this.#pendingKey = key;
+			return { kind: "pending", item };
+		}
+		this.#pendingKey = undefined;
+		return { kind: "confirmed", item };
+	}
+
+	#applyFilter(preferredKey: string | undefined): void {
+		const query = this.#query.trim();
+		this.#visibleItems = query
+			? (this.adapter.filter?.(this.#items, query) ??
+				fuzzyFilter([...this.#items], query, item => this.adapter.getSearchText(item)))
+			: this.#items;
+		this.#selectedIndex = this.#findInitialIndex(preferredKey);
+	}
+
+	#findInitialIndex(preferredKey: string | undefined): number {
+		if (this.#visibleItems.length === 0) return -1;
+		if (preferredKey !== undefined) {
+			const preferred = this.#visibleItems.findIndex(item => this.adapter.getKey(item) === preferredKey);
+			if (preferred >= 0 && !this.isDisabled(this.#visibleItems[preferred]!)) return preferred;
+		}
+		return this.#coerceIndex(0, 1);
+	}
+
+	#coerceIndex(index: number, direction: -1 | 1): number {
+		if (this.#visibleItems.length === 0) return -1;
+		const clamped = Math.max(0, Math.min(Math.trunc(index), this.#visibleItems.length - 1));
+		const candidate = this.#visibleItems[clamped];
+		if (candidate !== undefined && !this.isDisabled(candidate)) return clamped;
+		for (let next = clamped + direction; next >= 0 && next < this.#visibleItems.length; next += direction) {
+			const item = this.#visibleItems[next];
+			if (item !== undefined && !this.isDisabled(item)) return next;
+		}
+		for (let next = clamped - direction; next >= 0 && next < this.#visibleItems.length; next -= direction) {
+			const item = this.#visibleItems[next];
+			if (item !== undefined && !this.isDisabled(item)) return next;
+		}
+		return clamped;
+	}
+}

package/src/components/metric.ts

@@ -0,0 +1,132 @@
+import type { Component } from "../tui";
+import { Ellipsis, getWidthConfigEpoch, truncateToWidth, visibleWidth } from "../utils";
+import { Text } from "./text";
+
+/** One preformatted metric. Domain-specific number, cost, and quota policy stays with the caller. */
+export interface MetricSpec {
+	/** Undefined omits the metric; an empty string and zero-like strings remain observable values. */
+	readonly value: string | undefined;
+	/** Optional icon or label placed before the value. */
+	readonly leading?: string;
+	/** Separator between `leading` and `value`. */
+	readonly separator?: string;
+	/** Higher-priority metrics survive first when a row uses `drop` overflow. */
+	readonly priority?: number;
+	/** Render-time styling for the complete metric. */
+	readonly style?: (text: string) => string;
+}
+
+/** Width behavior for an inline metric row. */
+export type MetricOverflow = "allow" | "drop" | "truncate" | "wrap";
+
+/** Presentation options shared by {@link formatMetricRow} and {@link MetricRow}. */
+export interface MetricRowOptions {
+	readonly separator?: string;
+	readonly overflow?: MetricOverflow;
+	readonly maxWidth?: number;
+	readonly paddingX?: number;
+	readonly paddingY?: number;
+	readonly style?: (text: string) => string;
+}
+
+/** Format one metric without imposing domain-specific value policy. */
+export function formatMetric(metric: MetricSpec): string | undefined {
+	if (metric.value === undefined) return undefined;
+	const text =
+		metric.leading !== undefined ? `${metric.leading}${metric.separator ?? " "}${metric.value}` : metric.value;
+	return metric.style ? metric.style(text) : text;
+}
+
+/**
+ * Join metrics in declaration order. `drop` removes the lowest-priority metric
+ * first (rightmost on ties); `truncate` clips the complete row. `wrap` is
+ * applied by {@link MetricRow}, where the component owns the available width.
+ */
+export function formatMetricRow(metrics: readonly MetricSpec[], options: MetricRowOptions = {}): string {
+	const separator = options.separator ?? " ";
+	const entries = metrics.flatMap((metric, index) => {
+		const text = formatMetric(metric);
+		return text === undefined ? [] : [{ text, index, priority: metric.priority ?? 0 }];
+	});
+	if (entries.length === 0) return "";
+
+	const maxWidth = options.maxWidth;
+	const overflow = options.overflow ?? "allow";
+	const join = (): string => entries.map(entry => entry.text).join(separator);
+	if (maxWidth === undefined || overflow === "allow" || overflow === "wrap") return join();
+
+	if (overflow === "truncate") {
+		return truncateToWidth(join(), Math.max(0, maxWidth));
+	}
+
+	while (entries.length > 1 && visibleWidth(join()) > maxWidth) {
+		let dropIndex = 0;
+		for (let i = 1; i < entries.length; i += 1) {
+			const candidate = entries[i]!;
+			const current = entries[dropIndex]!;
+			if (
+				candidate.priority < current.priority ||
+				(candidate.priority === current.priority && candidate.index > current.index)
+			) {
+				dropIndex = i;
+			}
+		}
+		entries.splice(dropIndex, 1);
+	}
+	return join();
+}
+
+/**
+ * Component form of an inline metric row. It delegates ANSI-aware wrapping,
+ * padding, theme invalidation, and stable unchanged-render arrays to {@link Text}.
+ */
+export class MetricRow implements Component {
+	#metrics: readonly MetricSpec[];
+	readonly #options: MetricRowOptions;
+	readonly #text: Text;
+	#cache: { width: number; epoch: number; source: readonly string[]; lines: readonly string[] } | undefined;
+
+	constructor(metrics: readonly MetricSpec[], options: MetricRowOptions = {}) {
+		this.#metrics = metrics;
+		this.#options = options;
+		this.#text = new Text("", options.paddingX ?? 0, options.paddingY ?? 0).setStyleFn(options.style);
+	}
+
+	setMetrics(metrics: readonly MetricSpec[]): boolean {
+		if (this.#metrics === metrics) return false;
+		this.#metrics = metrics;
+		this.#cache = undefined;
+		return true;
+	}
+
+	invalidate(): void {
+		this.#text.invalidate();
+		this.#cache = undefined;
+	}
+
+	render(width: number): readonly string[] {
+		const renderWidth = Number.isFinite(width) ? Math.max(0, Math.trunc(width)) : 0;
+		const paddingX =
+			this.#options.paddingX !== undefined && Number.isFinite(this.#options.paddingX)
+				? Math.max(0, Math.trunc(this.#options.paddingX))
+				: 0;
+		const maxWidth = Math.max(0, renderWidth - paddingX * 2);
+		this.#text.setText(
+			formatMetricRow(this.#metrics, {
+				...this.#options,
+				maxWidth,
+				overflow: this.#options.overflow === "wrap" ? "allow" : this.#options.overflow,
+			}),
+		);
+		const source = this.#text.render(renderWidth);
+		const epoch = getWidthConfigEpoch();
+		if (this.#cache?.width === renderWidth && this.#cache.epoch === epoch && this.#cache.source === source) {
+			return this.#cache.lines;
+		}
+		const lines = source.every(line => visibleWidth(line) <= renderWidth)
+			? source
+			: source.map(line => truncateToWidth(line, renderWidth, Ellipsis.Omit));
+		this.#cache = { width: renderWidth, epoch, source, lines };
+		return lines;
+	}
+}