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

package/src/components/image.ts

@@ -108,10 +108,10 @@ function nextImageIdSeed(): number {
  * Bounds how many inline images render as live terminal graphics at once.
  *
  * Terminal graphics protocols — Kitty especially — keep every transmitted image
- * in a per-terminal store and re-draw placements as content scrolls; text-clear
- * escapes (`CSI 2 J` / `CSI 3 J`) do not remove them. Unbounded, a session that
- * shows many images piles up placements plus store memory and leaves ghosts in
- * scrollback.
+ * in a per-screen store and re-draw placements as content scrolls; placements
+ * that left the viewport survive text-clear escapes (`CSI 2 J`). Unbounded, a
+ * session that shows many images piles up placements plus store memory and
+ * leaves ghosts in scrollback.
  *
  * The budget keeps the most recent `cap` images live and demotes older ones to
  * their text fallback. Demotion needs a full redraw (so off-screen rows are
@@ -165,10 +165,16 @@ export class ImageBudget {
 	 * {@link forgetTransmitted}.
 	 */
 	#resetPurgeIds: number[] = [];
-	/** Image ids whose data is believed to be loaded in the terminal's store. */
-	#transmitted = new Set<number>();
-	/** Transmit sequences (full base64) to write once, before this frame's placements. */
-	#pendingTransmits = new Map<number, string>();
+	/**
+	 * Image ids whose data is believed to be loaded in each screen's store.
+	 * kitty and Ghostty keep the normal and alternate buffers' graphics apart
+	 * and wipe the alternate store on every `?1049h`, so data sent while one
+	 * buffer was active is unknown to the other: a placement there resolves
+	 * only after its own transmit.
+	 */
+	#transmitted: Record<Surface, Set<number>> = { screen: new Set(), alt: new Set() };
+	/** Transmit sequences (full base64) to write once per surface, before that frame's placements. */
+	#pendingTransmits: Record<Surface, Map<number, string>> = { screen: new Map(), alt: new Map() };
 	// True while the in-flight pass is a partial/throwaway pass (the
 	// non-multiplexer resize viewport fast path) that walks only the visible
 	// tail, bottom-up. Such a pass cannot derive display order from observe()
@@ -258,6 +264,8 @@ export class ImageBudget {
 	beginAltScreenLifecycle(): void {
 		resetSurfaceSplit(this.#altSplit);
 		this.#liveIds.alt.clear();
+		// `?1049h` hands over an empty graphics store as well as a cleared grid.
+		this.#transmitted.alt.clear();
 	}
 
 	/**
@@ -354,9 +362,10 @@ export class ImageBudget {
 	 */
 	limitResidentImages(): void {
 		this.#liveIds[this.#surface] = new Set(this.#passIds.filter(id => this.#passShowsLive(id)));
-		if (this.#cap <= 0 || this.#transmitted.size <= this.#cap) return;
-		for (const id of this.#transmitted) {
-			if (this.#transmitted.size <= this.#cap) break;
+		const transmitted = this.#transmitted[this.#surface];
+		if (this.#cap <= 0 || transmitted.size <= this.#cap) return;
+		for (const id of transmitted) {
+			if (transmitted.size <= this.#cap) break;
 			this.#retire(id);
 		}
 	}
@@ -384,15 +393,17 @@ export class ImageBudget {
 	}
 
 	/**
-	 * Drop `imageId` from the terminal's image store: queue its `d=I` (or cancel
-	 * a transmit that never went out) and forget its placement ledger and key.
+	 * Drop `imageId` from the painted surface's image store: queue its `d=I` (or
+	 * cancel a transmit that never went out) and, once no surface holds its data,
+	 * forget its placement ledger and key.
 	 *
 	 * The single gate on every destruction path. `d=I` removes an image's
-	 * placements everywhere, scrollback included, and a frame diff only rewrites
-	 * rows whose text changed — so a graphic some standing frame still shows
-	 * cannot be repaired once deleted, and must never be a candidate. Refuses
-	 * when the in-flight pass renders the image live, or when the frame on any
-	 * surface this pass is not repainting does. Returns whether it was retired.
+	 * placements everywhere on its screen, scrollback included, and a frame diff
+	 * only rewrites rows whose text changed — so a graphic some standing frame
+	 * still shows cannot be repaired once deleted, and must never be a
+	 * candidate. Refuses when the in-flight pass renders the image live, or when
+	 * the frame on any surface this pass is not repainting does. Returns whether
+	 * it was retired.
 	 */
 	#retire(imageId: number): boolean {
 		if (this.#passShowsLive(imageId)) return false;
@@ -401,13 +412,19 @@ export class ImageBudget {
 		}
 		// A transmit queued by a discarded discovery pass never reached the
 		// terminal, so cancel it instead of transmitting then purging.
-		if (!this.#pendingTransmits.delete(imageId)) this.#purgeIds.push(imageId);
-		this.#transmitted.delete(imageId);
-		this.#deletePlacementState(imageId);
+		if (!this.#pendingTransmits[this.#surface].delete(imageId)) this.#purgeIds.push(imageId);
+		this.#transmitted[this.#surface].delete(imageId);
+		if (!this.#isTransmitted(imageId)) this.#deletePlacementState(imageId);
 		this.#forgetKeyForId(imageId);
 		return true;
 	}
 
+	/** Whether any screen's store is believed to hold `imageId`'s data. */
+	#isTransmitted(imageId: number): boolean {
+		for (const surface of SURFACES) if (this.#transmitted[surface].has(imageId)) return true;
+		return false;
+	}
+
 	/**
 	 * Image ids a destructive reset must delete explicitly, alongside its `d=A`.
 	 * Emit only from that reset's repaint; clears the queue.
@@ -427,25 +444,28 @@ export class ImageBudget {
 		return ids;
 	}
 
-	/** All image ids believed to be loaded in the terminal store; clears tracking. */
+	/** All image ids believed to be loaded in any screen's store; clears tracking. */
 	takeAllTransmittedIds(): readonly number[] {
-		if (this.#transmitted.size === 0) return EMPTY_IDS;
-		const ids = [...this.#transmitted];
-		this.#transmitted.clear();
+		const ids = new Set<number>();
+		for (const surface of SURFACES) {
+			for (const id of this.#transmitted[surface]) ids.add(id);
+			this.#transmitted[surface].clear();
+			this.#pendingTransmits[surface].clear();
+		}
+		if (ids.size === 0) return EMPTY_IDS;
 		this.#purgeIds = [];
 		this.#resetPurgeIds = [];
-		this.#pendingTransmits.clear();
 		this.#keyToId.clear();
 		this.#idToKey.clear();
 		this.#placementState.clear();
 		this.#watchedPlacements.clear();
 		for (const surface of SURFACES) this.#liveIds[surface].clear();
-		return ids;
+		return [...ids];
 	}
 
-	/** Whether `imageId`'s data still needs to be transmitted to the terminal. */
+	/** Whether `imageId`'s data still needs to be transmitted to the surface the in-flight pass paints. */
 	shouldTransmit(imageId: number): boolean {
-		return !this.#transmitted.has(imageId);
+		return !this.#transmitted[this.#surface].has(imageId);
 	}
 
 	/**
@@ -566,18 +586,20 @@ export class ImageBudget {
 	}
 
 	/**
-	 * Queue a one-time transmit for `imageId`. No-op if already transmitted, so a
-	 * repeated call (e.g. a width-change re-render) never re-sends the data.
+	 * Queue a one-time transmit for `imageId` on the surface the in-flight pass
+	 * paints. No-op if that surface already holds the data, so a repeated call
+	 * (e.g. a width-change re-render) never re-sends it.
 	 */
 	enqueueTransmit(imageId: number, sequence: string): void {
-		if (this.#transmitted.has(imageId)) return;
-		this.#transmitted.add(imageId);
-		this.#pendingTransmits.set(imageId, sequence);
+		const transmitted = this.#transmitted[this.#surface];
+		if (transmitted.has(imageId)) return;
+		transmitted.add(imageId);
+		this.#pendingTransmits[this.#surface].set(imageId, sequence);
 	}
 
-	/** Whether a frame has image data queued but not yet written to the terminal. */
+	/** Whether the in-flight pass's surface has image data queued but not yet written. */
 	hasPendingTransmits(): boolean {
-		return this.#pendingTransmits.size > 0;
+		return this.#pendingTransmits[this.#surface].size > 0;
 	}
 
 	/**
@@ -587,33 +609,38 @@ export class ImageBudget {
 	 * observe pass only then — a partial tree walk would under-count display order.
 	 */
 	get quiescent(): boolean {
-		if (this.#pendingTransmits.size > 0 || this.#purgeIds.length > 0) return false;
+		if (this.#purgeIds.length > 0) return false;
+		for (const surface of SURFACES) if (this.#pendingTransmits[surface].size > 0) return false;
 		for (const split of [this.#screenSplit, this.#altSplit]) {
 			if (split.lastTotal !== 0 || split.planned !== split.onTerminal) return false;
 		}
 		return true;
 	}
 
-	/** Transmit sequences to write before this frame's placements; clears the queue. */
+	/** Transmit sequences to write before this frame's placements on its surface; clears that queue. */
 	takeTransmits(): readonly string[] {
-		if (this.#pendingTransmits.size === 0) return EMPTY_TRANSMITS;
-		const sequences = [...this.#pendingTransmits.values()];
-		this.#pendingTransmits.clear();
+		const pending = this.#pendingTransmits[this.#surface];
+		if (pending.size === 0) return EMPTY_TRANSMITS;
+		const sequences = [...pending.values()];
+		pending.clear();
 		return sequences;
 	}
 
 	/**
-	 * Drop transmit tracking so every still-live image re-enqueues its data
-	 * (`a=t`) on the next render. Recovers when the terminal dropped the original
-	 * transmit — e.g. Ghostty discarding graphics sent during its post-startup
-	 * window — where a placement-only replay can never bind a Unicode placeholder.
-	 * Pair with a component invalidate + forced repaint so the data and placement
-	 * re-emit together; keeps no base64 in budget state (the transmit-once design).
+	 * Drop the normal screen's transmit tracking so every still-live image
+	 * re-enqueues its data (`a=t`) on the next render. Recovers when the terminal
+	 * dropped the original transmit — e.g. Ghostty discarding graphics sent during
+	 * its post-startup window — where a placement-only replay can never bind a
+	 * Unicode placeholder. Pair with a component invalidate + forced repaint so
+	 * the data and placement re-emit together; keeps no base64 in budget state
+	 * (the transmit-once design).
 	 */
 	forgetTransmitted(): void {
-		if (this.#transmitted.size === 0 && this.#pendingTransmits.size === 0) return;
-		for (const id of this.#transmitted) {
-			if (!this.#pendingTransmits.has(id)) this.#resetPurgeIds.push(id);
+		const transmitted = this.#transmitted.screen;
+		const pending = this.#pendingTransmits.screen;
+		if (transmitted.size === 0 && pending.size === 0) return;
+		for (const id of transmitted) {
+			if (!pending.has(id)) this.#resetPurgeIds.push(id);
 		}
 		// The ids go to #resetPurgeIds, drained only by the destructive repaint
 		// itself — never to #purgeIds, which any frame drains. That is how a
@@ -624,8 +651,8 @@ export class ImageBudget {
 		// placements from it, and erasing placeholder text does not remove the
 		// prototype either. Forgetting drops the id from tracking, so without an
 		// explicit `d=I` no later sweep can ever find that placement again.
-		this.#transmitted.clear();
-		this.#pendingTransmits.clear();
+		transmitted.clear();
+		pending.clear();
 	}
 
 	/**
@@ -641,7 +668,7 @@ export class ImageBudget {
 	 * deleting every placement it ever made including scrollback copies.
 	 */
 	#forgetKeyForId(id: number): void {
-		if (this.#transmitted.has(id)) return;
+		if (this.#isTransmitted(id)) return;
 		const key = this.#idToKey.get(id);
 		if (key === undefined) return;
 		this.#idToKey.delete(id);

package/src/components/input.ts

@@ -3,6 +3,7 @@ import { getKeybindings } from "../keybindings";
 import { extractPrintableText } from "../keys";
 import { KillRing } from "../kill-ring";
 import { type Component, CURSOR_MARKER, type Focusable } from "../tui";
+import { cursorColumnWindow } from "./scroll-viewport";
 import {
 	getSegmenter,
 	getWordNavKind,
@@ -422,12 +423,13 @@ export class Input implements Component, Focusable {
 	}
 
 	render(width: number): readonly string[] {
+		width = Number.isFinite(width) ? Math.max(0, Math.trunc(width)) : 0;
 		// Calculate visible window
 		const prompt = this.prompt;
 		const availableWidth = width - visibleWidth(prompt);
 
 		if (availableWidth <= 0) {
-			return [prompt];
+			return [sliceWithWidth(prompt, 0, width, true).text];
 		}
 
 		let cursorIndex = this.#cursor;
@@ -440,32 +442,9 @@ export class Input implements Component, Focusable {
 		}
 		const displayValue = this.#cursor >= this.#value.length ? `${visibleValue} ` : visibleValue;
 
-		const totalCols = visibleWidth(displayValue);
-		const cursorCols = visibleWidth(displayValue.slice(0, cursorIndex));
-
-		// Width of the grapheme at the cursor, for ensuring it fits in the viewport.
-		const cursorIter = segmenter.segment(displayValue.slice(cursorIndex))[Symbol.iterator]();
-		const cursorG = cursorIter.next().value?.segment ?? " ";
-		const cursorGWidth = visibleWidth(cursorG);
-
-		const maxStart = Math.max(0, totalCols - availableWidth);
-		let startCol = 0;
-		if (totalCols > availableWidth) {
-			const half = Math.floor(availableWidth / 2);
-			startCol = Math.max(0, Math.min(maxStart, cursorCols - half));
-
-			// Ensure the cursor grapheme is inside the viewport (and fits fully if wide).
-			const maxCursorRel = Math.max(0, availableWidth - cursorGWidth);
-			const cursorRel = cursorCols - startCol;
-			if (cursorRel > maxCursorRel) {
-				startCol = Math.max(0, Math.min(maxStart, cursorCols - maxCursorRel));
-			}
-		}
-
-		const visibleText = sliceWithWidth(displayValue, startCol, availableWidth, true).text;
-		const prefixText = sliceWithWidth(displayValue, startCol, Math.max(0, cursorCols - startCol), true).text;
-		let cursorDisplay = prefixText.length;
-		cursorDisplay = Math.max(0, Math.min(cursorDisplay, visibleText.length));
+		const window = cursorColumnWindow(displayValue, cursorIndex, availableWidth);
+		const visibleText = window.text;
+		const cursorDisplay = window.cursorIndex;
 
 		// Build the visible line and insert the cursor marker at the buffer cursor.
 		const graphemes = [...segmenter.segment(visibleText.slice(cursorDisplay))];

package/src/components/key-value-list.ts

@@ -0,0 +1,88 @@
+import type { Component } from "../tui";
+import { Ellipsis, getWidthConfigEpoch, replaceTabs, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../utils";
+
+/** One label/value entry in a {@link KeyValueList}. */
+export interface KeyValueRow {
+	readonly label: string;
+	readonly value: string;
+	readonly labelStyle?: (text: string) => string;
+	readonly valueStyle?: (text: string) => string;
+}
+
+/** Explicit sizing and wrapping policy for a key/value list. */
+export interface KeyValueListOptions {
+	readonly indent?: string;
+	readonly labelWidth: number;
+	readonly gap?: string;
+	readonly minValueWidth?: number;
+	readonly labelOverflow?: "allow" | "truncate";
+}
+
+function finiteWidth(width: number): number {
+	return Number.isFinite(width) ? Math.max(0, Math.trunc(width)) : 0;
+}
+
+function singleLine(text: string): string {
+	return replaceTabs(text).replace(/[\r\n]+/g, " ");
+}
+
+/** A bounded ANSI-aware label/value list with replaceable rows and aligned wrapped continuations. */
+export class KeyValueList implements Component {
+	#rows: readonly KeyValueRow[];
+	readonly #options: KeyValueListOptions;
+	#cache: { width: number; epoch: number; lines: readonly string[] } | undefined;
+
+	constructor(rows: readonly KeyValueRow[], options: KeyValueListOptions) {
+		this.#rows = rows;
+		this.#options = options;
+	}
+
+	setRows(rows: readonly KeyValueRow[]): boolean {
+		if (this.#rows === rows) return false;
+		this.#rows = rows;
+		this.#cache = undefined;
+		return true;
+	}
+
+	invalidate(): void {
+		this.#cache = undefined;
+	}
+
+	render(width: number): readonly string[] {
+		const renderWidth = finiteWidth(width);
+		const epoch = getWidthConfigEpoch();
+		if (this.#cache?.width === renderWidth && this.#cache.epoch === epoch) return this.#cache.lines;
+		const indent = singleLine(this.#options.indent ?? "");
+		const gap = singleLine(this.#options.gap ?? " ");
+		const labelWidth = finiteWidth(this.#options.labelWidth);
+		const minimumValueWidth = Math.max(1, finiteWidth(this.#options.minValueWidth ?? 1));
+		const lines: string[] = [];
+		for (const row of this.#rows) {
+			let label = singleLine(row.label);
+			const indentAndGapWidth = visibleWidth(indent) + visibleWidth(gap);
+			const constrainedLabelWidth = Math.max(0, renderWidth - indentAndGapWidth - minimumValueWidth);
+			const renderedLabelWidth = Math.min(labelWidth, constrainedLabelWidth);
+			if (
+				visibleWidth(label) > renderedLabelWidth &&
+				(this.#options.labelOverflow === "truncate" || renderedLabelWidth < labelWidth)
+			) {
+				label = truncateToWidth(label, renderedLabelWidth);
+			}
+			const labelPadding = " ".repeat(Math.max(0, renderedLabelWidth - visibleWidth(label)));
+			const rawLabelCell = `${label}${labelPadding}`;
+			const labelCell = row.labelStyle?.(rawLabelCell) ?? rawLabelCell;
+			const prefixWidth = visibleWidth(indent) + visibleWidth(rawLabelCell) + visibleWidth(gap);
+			const valueWidth = Math.max(1, renderWidth - prefixWidth);
+			const rawValue = singleLine(row.value);
+			const value = row.valueStyle?.(rawValue) ?? rawValue;
+			const wrapped = wrapTextWithAnsi(value, valueWidth);
+			const continuation = " ".repeat(prefixWidth);
+			lines.push(truncateToWidth(`${indent}${labelCell}${gap}${wrapped[0] ?? ""}`, renderWidth, Ellipsis.Omit));
+			for (const extra of wrapped.slice(1)) {
+				lines.push(truncateToWidth(`${continuation}${extra}`, renderWidth, Ellipsis.Omit));
+			}
+		}
+		this.#cache = { width: renderWidth, epoch, lines };
+		return lines;
+	}
+}

package/src/components/layout/geometry.ts

@@ -0,0 +1,202 @@
+import type { MouseRoutable } from "../../mouse";
+import type { Component } from "../../tui";
+import { padding, truncateToWidth, visibleWidth } from "../../utils";
+
+/** Alignment within space allocated by a layout component. */
+export type LayoutAlignment = "start" | "center" | "end";
+
+/** Insets reserved inside a layout child's allocated rectangle. */
+export interface LayoutInsets {
+	top?: number;
+	right?: number;
+	bottom?: number;
+	left?: number;
+}
+
+/** Insets normalized to finite, non-negative terminal-cell counts. */
+export interface NormalizedLayoutInsets {
+	top: number;
+	right: number;
+	bottom: number;
+	left: number;
+}
+
+/** Rectangle in coordinates local to a layout component. */
+export interface LayoutRect {
+	row: number;
+	col: number;
+	width: number;
+	height: number;
+}
+
+/** Lazy layout child, evaluated only when the child is visible. */
+export type LayoutRenderer = (width: number, height: number | undefined) => readonly string[];
+
+/** A concrete component or a lazy renderer used as a layout child. */
+export type LayoutContent = Component | LayoutRenderer;
+
+/** Static text or a late-bound layout decoration, useful for theme-colored rules. */
+export type LayoutDecoration = string | (() => string);
+
+/** A component whose parent may assign a local row budget before rendering. */
+export interface HeightConstrainedComponent extends Component {
+	setHeight(height: number | undefined): void;
+}
+
+/** One fixed or growing constraint consumed by {@link allocateLayoutSpace}. */
+export interface LayoutAllocation {
+	fixed?: number;
+	grow?: number;
+	min?: number;
+	max?: number;
+}
+
+/** Clamp an external size to a finite, non-negative integer cell count. */
+export function layoutSize(value: number | undefined, fallback = 0): number {
+	const resolved = value === undefined || !Number.isFinite(value) ? fallback : value;
+	return Number.isFinite(resolved) ? Math.max(0, Math.floor(resolved)) : 0;
+}
+
+/** Normalize an optional external size while preserving `undefined`. */
+export function optionalLayoutSize(value: number | undefined): number | undefined {
+	return value === undefined ? undefined : layoutSize(value);
+}
+
+/** Clamp a proportional layout input to a finite, non-negative number. */
+export function layoutRatio(value: number | undefined, fallback: number): number {
+	const resolved = value === undefined || !Number.isFinite(value) ? fallback : value;
+	return Number.isFinite(resolved) ? Math.max(0, resolved) : 0;
+}
+
+/** Resolve static or late-bound layout decoration text. */
+export function layoutDecorationText(decoration: LayoutDecoration | undefined): string {
+	return typeof decoration === "function" ? decoration() : (decoration ?? "");
+}
+
+function allocationMaximum(item: LayoutAllocation): number {
+	return item.max === undefined ? Number.MAX_SAFE_INTEGER : Math.max(layoutSize(item.min), layoutSize(item.max));
+}
+
+/**
+ * Allocate bounded integer cells across fixed and growing children. When the
+ * minimums cannot fit, later children collapse first so output stays bounded.
+ */
+export function allocateLayoutSpace(items: readonly LayoutAllocation[], available: number): number[] {
+	available = layoutSize(available);
+	const sizes = items.map(item => {
+		const minimum = layoutSize(item.min);
+		const maximum = allocationMaximum(item);
+		return item.fixed === undefined ? minimum : Math.max(minimum, Math.min(maximum, layoutSize(item.fixed)));
+	});
+	const used = sizes.reduce((sum, size) => sum + size, 0);
+	if (used > available) {
+		let overflow = used - available;
+		for (let index = sizes.length - 1; index >= 0 && overflow > 0; index--) {
+			const reduction = Math.min(sizes[index] ?? 0, overflow);
+			sizes[index] = (sizes[index] ?? 0) - reduction;
+			overflow -= reduction;
+		}
+		return sizes;
+	}
+
+	let remaining = available - used;
+	let flexible = items
+		.map((item, index) => ({ item, index }))
+		.filter(({ item }) => item.fixed === undefined && layoutSize(item.grow) > 0);
+	while (remaining > 0 && flexible.length > 0) {
+		const totalWeight = flexible.reduce((sum, { item }) => sum + layoutSize(item.grow), 0);
+		let granted = 0;
+		for (const { item, index } of flexible) {
+			const maximum = allocationMaximum(item);
+			const capacity = maximum - (sizes[index] ?? 0);
+			if (capacity <= 0) continue;
+			const proportional = Math.floor((remaining * layoutSize(item.grow)) / totalWeight);
+			const share = Math.min(capacity, Math.max(1, proportional), remaining - granted);
+			if (share <= 0) continue;
+			sizes[index] = (sizes[index] ?? 0) + share;
+			granted += share;
+			if (granted === remaining) break;
+		}
+		if (granted === 0) break;
+		remaining -= granted;
+		flexible = flexible.filter(({ item, index }) => {
+			const maximum = allocationMaximum(item);
+			return (sizes[index] ?? 0) < maximum;
+		});
+	}
+	return sizes;
+}
+
+/** Normalize every inset to a finite, non-negative integer cell count. */
+export function layoutInsets(insets: LayoutInsets | undefined): NormalizedLayoutInsets {
+	return {
+		top: layoutSize(insets?.top),
+		right: layoutSize(insets?.right),
+		bottom: layoutSize(insets?.bottom),
+		left: layoutSize(insets?.left),
+	};
+}
+
+/** Compare optional inset objects by their normalized terminal geometry. */
+export function equalLayoutInsets(left: LayoutInsets | undefined, right: LayoutInsets | undefined): boolean {
+	return (
+		layoutSize(left?.top) === layoutSize(right?.top) &&
+		layoutSize(left?.right) === layoutSize(right?.right) &&
+		layoutSize(left?.bottom) === layoutSize(right?.bottom) &&
+		layoutSize(left?.left) === layoutSize(right?.left)
+	);
+}
+
+/** Offset content within spare cells according to an alignment. */
+export function layoutAlignmentOffset(space: number, alignment: LayoutAlignment): number {
+	if (space <= 0 || alignment === "start") return 0;
+	return alignment === "end" ? space : Math.floor(space / 2);
+}
+
+/** Narrow a concrete-or-lazy child to a concrete component. */
+export function isLayoutComponent(content: LayoutContent): content is Component {
+	return typeof content !== "function";
+}
+
+/** Narrow a layout child to a component accepting a row budget. */
+export function isHeightConstrainedComponent(content: LayoutContent): content is HeightConstrainedComponent {
+	return isLayoutComponent(content) && "setHeight" in content && typeof content.setHeight === "function";
+}
+
+/** Narrow a layout child to a mouse-routable component. */
+export function isLayoutMouseRoutable(content: LayoutContent): content is Component & MouseRoutable {
+	return isLayoutComponent(content) && "routeMouse" in content && typeof content.routeMouse === "function";
+}
+
+/** Return concrete children once each, preserving their first layout order. */
+export function uniqueLayoutComponents(contents: readonly LayoutContent[]): readonly Component[] {
+	const seen = new Set<Component>();
+	const components: Component[] = [];
+	for (const content of contents) {
+		if (!isLayoutComponent(content) || seen.has(content)) continue;
+		seen.add(content);
+		components.push(content);
+	}
+	return components;
+}
+
+/** Fit one ANSI-styled row to an exact terminal-cell width. */
+export function fitLayoutLine(line: string, width: number): string {
+	width = layoutSize(width);
+	if (width === 0) return "";
+	const lineWidth = visibleWidth(line);
+	const clipped = lineWidth > width ? truncateToWidth(line, width) : line;
+	const clippedWidth = lineWidth > width ? visibleWidth(clipped) : lineWidth;
+	return clipped + padding(Math.max(0, width - clippedWidth));
+}
+
+/** Render a concrete or lazy child with an optional local height budget. */
+export function renderLayoutContent(
+	content: LayoutContent,
+	width: number,
+	height: number | undefined,
+): readonly string[] {
+	if (typeof content === "function") return content(layoutSize(width), optionalLayoutSize(height));
+	if (isHeightConstrainedComponent(content)) content.setHeight(optionalLayoutSize(height));
+	return content.render(layoutSize(width));
+}