@oh-my-pi/pi-tui 18.4.2 → 18.4.4

package/src/chrome/transcript-container.ts

@@ -1,6 +1,9 @@
 import { type Component, Container, type HistoryBatch } from "../tui";
 import * as logger from "@oh-my-pi/pi-utils/logger";
 import { popLoopPhase, pushLoopPhase } from "@oh-my-pi/pi-utils";
+import { col } from "../native/describe";
+import type { NativeNode } from "../native/node";
+import { isNativeSettled, settleNative } from "../native/settle";
 import { isToolActivityComponent } from "./tool-activity";
 
 /** Shared animation time supplied by the constrained transcript root. */
@@ -93,6 +96,12 @@ type Offered =
 	| { batch: HistoryBatch; kind: "commit"; end: number }
 	| { batch: HistoryBatch; kind: "replay" };
 
+/** Rows a progressive-append retirement offers, and the stable count they bring the head to. */
+interface AppendBatch {
+	rows: readonly string[];
+	emittedEnd: number;
+}
+
 const MAX_LIVE_BLOCKS = 256;
 /** Grace before a pressure-blocked frontier is reported; a streaming block may legitimately hold it briefly. */
 const PINNED_FRONTIER_WARN_MS = 30_000;
@@ -189,6 +198,13 @@ export class TranscriptContainer extends Container {
 	 */
 	#frameRows = new Map<TranscriptEntry, readonly string[]>();
 	#frameRowsWidth = 0;
+	/** The `children` array `#entries` last mirrored; see {@link #syncEntries}. */
+	#syncedChildren: Component[] | undefined;
+	/** Forces the next {@link #syncEntries} to compare every entry, not just the live tail. */
+	#entriesUnverified = false;
+	/** Block list handed to the native frame provider, reused while the children are unchanged. */
+	#nativeBlocks: readonly Component[] = [];
+	#nativeNode: NativeNode | undefined;
 	override addChild(component: Component): void {
 		if (isToolActivityComponent(component)) component.setToolActivityVisible(this.#toolActivityVisible);
 		super.addChild(component);
@@ -202,6 +218,9 @@ export class TranscriptContainer extends Container {
 			emitted: 0,
 			stableFrozen: false,
 		});
+		// Callers may splice a just-added block into place (insert after an
+		// anchor); re-check the whole list once instead of trusting positions.
+		this.#entriesUnverified = true;
 	}
 
 	override removeChild(component: Component): void {
@@ -639,20 +658,9 @@ export class TranscriptContainer extends Container {
 			// rows left behind here are rows dropped from the top of the viewport.
 			// `liveRows` is exact here: the append path measured every live block.
 			const overflow = liveRows - room;
-			const before = this.#renderStablePrefix(appendHead, appendHead.emitted, width);
-			let emittedEnd = appendHead.emitted;
-			let rows: readonly string[] = EMPTY_ROWS;
-			while (emittedEnd < appendHead.stableRows.length && rows.length < overflow) {
-				const after = this.#renderStablePrefix(appendHead, emittedEnd + 1, width);
-				if (!isRowPrefix(before, after) || after.length === before.length) {
-					if (emittedEnd === appendHead.emitted) {
-						this.#freezeStableRows(appendHead, EMPTY_ROWS, "semantic row render added no suffix");
-					}
-					break;
-				}
-				rows = after.slice(before.length);
-				emittedEnd += 1;
-			}
+			const { rows, emittedEnd } =
+				this.#measuredAppendBatch(appendHead, width, overflow) ??
+				this.#renderedAppendBatch(appendHead, width, overflow);
 			if (emittedEnd > appendHead.emitted) {
 				const batch: HistoryBatch = {
 					id: this.#nextBatchId++,
@@ -746,6 +754,37 @@ export class TranscriptContainer extends Container {
 		return rows.length > cap ? rows.slice(rows.length - cap) : rows;
 	}
 
+	/**
+	 * The transcript's blocks for a native (TSP) surface, one component per
+	 * `main` child in transcript order; ids follow component identity, so
+	 * inserts, removals (rewind, displacement) and reorders become targeted ops.
+	 * Finalized blocks are settled as a hint; they stay editable, so a later
+	 * expansion, late result or reaction still reaches them wherever they sit.
+	 * No retirement happens on this path: the whole transcript is one document.
+	 * Returns the same array while the block list is unchanged.
+	 */
+	nativeBlocks(): readonly Component[] {
+		this.#syncEntries();
+		const children = this.children;
+		for (const child of children) {
+			if (!isNativeSettled(child) && isFinalized(child)) settleNative(child);
+		}
+		const previous = this.#nativeBlocks;
+		if (previous.length === children.length && previous.every((child, index) => child === children[index])) {
+			return previous;
+		}
+		this.#nativeBlocks = children.slice();
+		this.#nativeNode = undefined;
+		return this.#nativeBlocks;
+	}
+
+	/** Embedded as a child (transcript viewers): a stack of the {@link nativeBlocks}. */
+	override describe(): NativeNode {
+		const blocks = this.nativeBlocks();
+		this.#nativeNode ??= col(blocks, { role: "omp.transcript" });
+		return this.#nativeNode;
+	}
+
 	/** Full semantic render used by exports and non-terminal commands. */
 	override render(width: number): readonly string[] {
 		this.#syncEntries();
@@ -840,6 +879,64 @@ export class TranscriptContainer extends Container {
 		if (memo !== undefined) return memo;
 		return this.#renderStablePrefix(entry, count, width).length;
 	}
+
+	/**
+	 * Size a progressive-append batch from the stable renders `#renderEntry`
+	 * recorded at this width, without rendering any prefix. Each recorded count
+	 * was checked to render as a byte prefix of every later one, and
+	 * `renderedStableByWidth` holds the newest, so each count's rows are a
+	 * prefix of it and the batch is one slice. Undefined when a count the walk
+	 * needs was never recorded here (published between renders, or before a
+	 * resize); the rendered walk then decides.
+	 */
+	#measuredAppendBatch(entry: TranscriptEntry, width: number, overflow: number): AppendBatch | undefined {
+		const counts = entry.stableRowCountByWidth.get(width);
+		const newest = entry.renderedStableByWidth.get(width);
+		const target = entry.stableRows.length;
+		if (counts === undefined || newest === undefined || counts.get(target) !== newest.length) return undefined;
+		const start = entry.emitted === 0 ? 0 : counts.get(entry.emitted);
+		if (start === undefined) return undefined;
+		let emittedEnd = entry.emitted;
+		let end = start;
+		while (emittedEnd < target && end - start < overflow) {
+			const next = counts.get(emittedEnd + 1);
+			if (next === undefined) return undefined;
+			if (next <= start) {
+				if (emittedEnd === entry.emitted) {
+					this.#freezeStableRows(entry, EMPTY_ROWS, "semantic row render added no suffix");
+				}
+				break;
+			}
+			end = next;
+			emittedEnd += 1;
+		}
+		return { rows: emittedEnd > entry.emitted ? newest.slice(start, end) : EMPTY_ROWS, emittedEnd };
+	}
+
+	/**
+	 * Size a progressive-append batch by rendering each further stable prefix:
+	 * extend the emitted prefix until its new rows cover `overflow`, stopping
+	 * at the first prefix that adds no row or stops extending the emitted one
+	 * (freezing the block when that is the very next prefix).
+	 */
+	#renderedAppendBatch(entry: TranscriptEntry, width: number, overflow: number): AppendBatch {
+		const before = this.#renderStablePrefix(entry, entry.emitted, width);
+		let emittedEnd = entry.emitted;
+		let after = before;
+		while (emittedEnd < entry.stableRows.length && after.length - before.length < overflow) {
+			const next = this.#renderStablePrefix(entry, emittedEnd + 1, width);
+			if (!isRowPrefix(before, next) || next.length === before.length) {
+				if (emittedEnd === entry.emitted) {
+					this.#freezeStableRows(entry, EMPTY_ROWS, "semantic row render added no suffix");
+				}
+				break;
+			}
+			after = next;
+			emittedEnd += 1;
+		}
+		return { rows: emittedEnd > entry.emitted ? after.slice(before.length) : EMPTY_ROWS, emittedEnd };
+	}
+
 	/**
 	 * Record that pressure retirement is blocked behind a not-yet-settled
 	 * frontier block, and log its identity once the episode outlives the grace
@@ -1069,12 +1166,27 @@ export class TranscriptContainer extends Container {
 		return this.#entries.length - this.#frontier;
 	}
 
+	/**
+	 * Mirror `children` into `#entries`. The container's own add/remove/clear
+	 * keep the two aligned, so the per-frame check stays off the committed
+	 * ledger: external edits to the public `children` array are caught by array
+	 * identity (replacement), length (push, removing splices), and an identity
+	 * scan of the live tail (in-place reorders and index writes). Committed
+	 * blocks are immutable history nothing reorders, and the scan skipping
+	 * them keeps this proportional to the live tail rather than the session.
+	 */
 	#syncEntries(): void {
+		const children = this.children;
 		if (
-			this.#entries.length === this.children.length &&
-			this.#entries.every((entry, index) => entry.component === this.children[index])
-		)
+			!this.#entriesUnverified &&
+			children === this.#syncedChildren &&
+			this.#entriesMatch(children, this.#frontier)
+		) {
 			return;
+		}
+		this.#entriesUnverified = false;
+		this.#syncedChildren = children;
+		if (this.#entriesMatch(children, 0)) return;
 		const existing = new Map(this.#entries.map(entry => [entry.component, entry]));
 		this.#entries = this.children.map(
 			component =>
@@ -1092,6 +1204,16 @@ export class TranscriptContainer extends Container {
 		this.#frontier = this.#entries.findIndex(entry => entry.state !== "committed");
 		if (this.#frontier < 0) this.#frontier = this.#entries.length;
 	}
+
+	/** Whether `#entries` has `children`'s length and components from `start` on. */
+	#entriesMatch(children: readonly Component[], start: number): boolean {
+		const entries = this.#entries;
+		if (entries.length !== children.length) return false;
+		for (let index = start; index < entries.length; index++) {
+			if (entries[index]!.component !== children[index]) return false;
+		}
+		return true;
+	}
 }
 
 /** Groups sibling rows into one conservative mutable semantic transcript block. */

package/src/chrome/transcript-status.ts

@@ -1,27 +1,56 @@
+import type { TspSpan } from "@oh-my-pi/pi-wire";
 import { Text } from "../components/text";
+import { col, span, text } from "../native/describe";
+import type { NativeNode } from "../native/node";
+import { type ThemeColor, theme } from "../theme";
 import { TranscriptBlock } from "./transcript-container";
 
-/** One compact transcript status row assembled from already-styled parts. */
+/** One themed run of a status row. */
+export interface TranscriptStatusPart {
+	readonly text: string;
+	readonly color: ThemeColor;
+	/** Glyph art (tree connectors) drawn only in rows; native terminals draw their own structure. */
+	readonly rowsOnly?: boolean;
+}
+
+/** One compact transcript status row assembled from themed parts, joined by single spaces. */
 export interface TranscriptStatusRow {
-	readonly parts: readonly (string | undefined)[];
+	readonly parts: readonly (TranscriptStatusPart | undefined)[];
 	readonly indent?: number;
 }
 
 /** Shared compact status-pill block used by notices and background activity. */
 export class TranscriptStatusBlock extends TranscriptBlock {
+	readonly #rows: TspSpan[][] = [];
+	#native: NativeNode | undefined;
+
 	constructor(rows: readonly TranscriptStatusRow[]) {
 		super();
-		for (const row of rows) {
-			const parts: string[] = [];
-			for (const part of row.parts) {
-				if (part) parts.push(part);
-			}
-			this.addChild(new Text(parts.join(" "), row.indent ?? 1, 0));
-		}
+		for (const row of rows) this.addLine(row.parts, row.indent);
 	}
 
 	/** Append a supplemental line such as an artifact warning. */
-	addLine(text: string, indent = 1): void {
-		this.addChild(new Text(text, indent, 0));
+	addLine(parts: readonly (TranscriptStatusPart | undefined)[], indent = 1): void {
+		const styled: string[] = [];
+		const spans: TspSpan[] = [];
+		for (const part of parts) {
+			if (!part) continue;
+			styled.push(theme.fg(part.color, part.text));
+			if (part.rowsOnly) continue;
+			if (spans.length > 0) spans.push(span(" "));
+			spans.push(span(part.text, part.color));
+		}
+		this.addChild(new Text(styled.join(" "), indent, 0));
+		this.#rows.push(spans);
+		this.#native = undefined;
+	}
+
+	/** One wrapped text line per status row. */
+	override describe(): NativeNode {
+		this.#native ??= col(
+			this.#rows.map(spans => text(spans, { wrap: "word" })),
+			{ role: "omp.status-block" },
+		);
+		return this.#native;
 	}
 }

package/src/components/box.ts

@@ -1,3 +1,7 @@
+import { backgroundChrome, colorTone, sampleBackground, sampleForeground } from "../native/tone";
+import { sameItems } from "../native/memo";
+import { card, col } from "../native/describe";
+import type { DescribeContext, NativeNode } from "../native/node";
 import type { Component } from "../tui";
 import {
 	getPaddingX,
@@ -52,6 +56,13 @@ export class Box implements Component {
 
 	// Cache for rendered output
 	#cached?: Cache;
+	#native?: {
+		children: readonly Component[];
+		bg: string | undefined;
+		border: BoxBorder | undefined;
+		borderColor: string | undefined;
+		node: NativeNode;
+	};
 
 	constructor(paddingX = 1, paddingY = 1, bgFn?: (text: string) => string, border?: BoxBorder) {
 		this.#paddingX = paddingX;
@@ -124,6 +135,46 @@ export class Box implements Component {
 		}
 	}
 
+	/**
+	 * A `card` when the box has a border or background: the background token
+	 * picks tone/role (user message, tool state, selection), a border colour
+	 * picks the ring tone. A plain `col` otherwise. Padding is the terminal's.
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		const bg = sampleBackground(this.#bgFn);
+		const border = this.#border;
+		const borderColor = border ? sampleForeground(border.color) : undefined;
+		const cached = this.#native;
+		if (
+			cached !== undefined &&
+			cached.bg === bg &&
+			cached.border === border &&
+			cached.borderColor === borderColor &&
+			sameItems(cached.children, this.children)
+		) {
+			return cached.node;
+		}
+		const children = [...this.children];
+		let described: NativeNode;
+		if (!border && !this.#bgFn) {
+			described = col(children);
+		} else {
+			const chrome = backgroundChrome(bg);
+			described = card(
+				{
+					role: chrome.role ?? "omp.panel",
+					tone: borderColor !== undefined ? (colorTone(borderColor) ?? "neutral") : (chrome.tone ?? "neutral"),
+					selected: chrome.selected,
+					// Fill without a ring: a flat inset panel.
+					inset: border ? undefined : true,
+				},
+				children,
+			);
+		}
+		this.#native = { children, bg, border, borderColor, node: described };
+		return described;
+	}
+
 	render(width: number): readonly string[] {
 		const children = this.children;
 		const count = children.length;

package/src/components/disclosure.ts

@@ -1,3 +1,5 @@
+import { node } from "../native/describe";
+import type { DescribeContext, NativeChild, NativeNode, NativeUiEvent } from "../native/node";
 import type { Component } from "../tui";
 
 /** A component slot; factory slots are constructed only when their branch is first rendered. */
@@ -48,6 +50,7 @@ export class Disclosure implements Component {
 	#ignoreTight: boolean | undefined;
 	#disposed = false;
 	#cache: RenderCache | undefined;
+	#native: { expanded: boolean; node: NativeNode } | undefined;
 	#boundedCache:
 		| {
 				source: readonly string[];
@@ -74,6 +77,7 @@ export class Disclosure implements Component {
 		if (this.#disposed || this.#expanded === expanded) return;
 		this.#expanded = expanded;
 		this.#cache = undefined;
+		this.#native = undefined;
 		this.#boundedCache = undefined;
 	}
 
@@ -131,6 +135,34 @@ export class Disclosure implements Component {
 		return children;
 	}
 
+	/**
+	 * A collapsible `section`. The summary (and, while collapsed, the preview)
+	 * form the always-visible header child; the lazily built body is the
+	 * section body and is only materialized once expanded.
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		if (this.#disposed) return DISPOSED_NODE;
+		const expanded = this.#expanded;
+		if (this.#native?.expanded === expanded) return this.#native.node;
+		const head: NativeChild[] = [];
+		const summary = this.#getSummary();
+		if (summary) head.push(summary);
+		if (!expanded) {
+			const preview = this.#getCollapsedBody();
+			if (preview) head.push(preview);
+		}
+		const children: NativeChild[] = [node("col", undefined, head, "head")];
+		if (expanded) children.push(this.#getBody());
+		const described = node("section", { collapsible: true, collapsed: !expanded }, children);
+		this.#native = { expanded, node: described };
+		return described;
+	}
+
+	/** Mirror the terminal-local toggle into the controlled state. */
+	handleNativeEvent(event: NativeUiEvent): void {
+		if (event.type === "toggle" && event.key === "") this.setExpanded(!event.collapsed);
+	}
+
 	render(width: number): readonly string[] {
 		if (this.#disposed) return EMPTY_ROWS;
 		width = Math.max(1, Math.floor(Number.isFinite(width) ? width : 1));
@@ -232,4 +264,5 @@ function rowsMatchSnapshot(rows: readonly string[], snapshot: readonly string[])
 }
 
 const EMPTY_ROWS: readonly string[] = [];
+const DISPOSED_NODE: NativeNode = node("col", { hidden: true });
 const EMPTY_COMPONENTS: readonly Component[] = [];