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

package/src/render/tool-card.ts

@@ -1,10 +1,18 @@
+import type { TspSpan, TspText } from "@oh-my-pi/pi-wire";
 import { Text } from "../components/text";
+import { compactText, rowsText, styledSpans } from "../native/spans";
+import { sameItems } from "../native/memo";
+import { colorTone } from "../native/tone";
+import { span } from "../native/describe";
+import type { DescribeContext, NativeChild, NativeNode } from "../native/node";
 import type { Theme, ThemeColor } from "../theme/theme";
 import type { Component } from "../tui";
 import { getPaddingX } from "../utils";
 import {
 	CachedOutputBlock,
+	describeOutputBlock,
 	markFramedBlockComponent,
+	type NativeOutputBlockSection,
 	outputBlockContentWidth,
 	type OutputBlockOptions,
 } from "./output-block";
@@ -75,6 +83,39 @@ function isRenderedLines(value: readonly string[] | Component): value is readonl
 	return Array.isArray(value);
 }
 
+/** Header spans for a structured status line; the status icon is the card's status chip. */
+function statusSpans(status: StatusLineOptions, theme: Theme): TspSpan[] {
+	const flatten = (text: string): string => text.replace(/\r\n?|\n/g, " ");
+	const spans: TspSpan[] = [];
+	if (status.iconOverride) spans.push(...styledSpans(status.iconOverride), span(" "));
+	spans.push(span(flatten(status.title), status.titleColor ?? "accent"));
+	if (status.description) spans.push(span(": "), span(flatten(status.description), "muted"));
+	if (status.badge) {
+		const label = `${theme.format.bracketLeft}${flatten(status.badge.label)}${theme.format.bracketRight}`;
+		spans.push(span(" "), span(label, status.badge.color));
+	}
+	const meta = status.meta?.map(flatten).filter(value => value.trim().length > 0) ?? [];
+	if (meta.length > 0) spans.push(span(" "), span(meta.join(theme.sep.dot), "dim"));
+	return spans;
+}
+
+/** Last description of a card, reused while the snapshot's inputs are unchanged. */
+interface NativeCardMemo {
+	head: string;
+	meta: string | undefined;
+	phase: ToolCardPhase | undefined;
+	applyBg: boolean | undefined;
+	borderColor: ThemeColor | undefined;
+	/** Per slot: label plus resolved content (component or rows array) and its described child. */
+	slots: readonly {
+		label: string | undefined;
+		separator: boolean;
+		content: readonly string[] | Component;
+		child: NativeChild;
+	}[];
+	node: NativeNode;
+}
+
 function resolveContent(content: ToolCardContent, width: number): { lines: readonly string[]; component?: Component } {
 	const resolved = typeof content === "function" ? content(width) : content;
 	if (isRenderedLines(resolved)) return { lines: resolved };
@@ -96,6 +137,7 @@ export class ToolCard implements Component {
 	#plainKey = "";
 	#renderedChildren: Component[] = [];
 	#disposed = false;
+	#native: NativeCardMemo | undefined;
 
 	constructor(theme: Theme, options: ToolCardOptions, build: (context: ToolCardBuildContext) => ToolCardSnapshot) {
 		this.#theme = theme;
@@ -216,6 +258,100 @@ export class ToolCard implements Component {
 		return this.#plainText.render(width);
 	}
 
+	/**
+	 * A `card` (flat `inset` for plain cards) with the state's tone and status
+	 * chip, head from the header/status line, and body slots: components as
+	 * children, pre-rendered rows as unwrapped text, labelled sections as
+	 * `section`s. The builder gets the surface width as its only width.
+	 */
+	describe(cx: DescribeContext): NativeNode {
+		const snapshot = this.#build({ width: cx.cols, contentWidth: cx.cols, contentWidthFor: () => cx.cols });
+		const previous = this.#native;
+		const slotInputs: { label: string | undefined; separator: boolean; content: ToolCardContent }[] = [];
+		if (snapshot.body) slotInputs.push({ label: undefined, separator: false, content: snapshot.body });
+		for (const section of snapshot.sections ?? []) {
+			slotInputs.push({ label: section.label, separator: section.separator === true, content: section.content });
+		}
+		if (snapshot.footer)
+			slotInputs.push({ label: undefined, separator: slotInputs.length > 0, content: snapshot.footer });
+
+		const nextChildren: Component[] = [];
+		const slots = slotInputs.map((input, index) => {
+			const content = typeof input.content === "function" ? input.content(cx.cols) : input.content;
+			const prior = previous?.slots[index];
+			let child: NativeChild;
+			if (isRenderedLines(content)) {
+				child =
+					prior !== undefined && isRenderedLines(prior.content) && sameItems(prior.content, content)
+						? prior.child
+						: rowsText(content);
+			} else {
+				child = content;
+				if (!nextChildren.includes(content)) nextChildren.push(content);
+			}
+			return { label: input.label, separator: input.separator, content, child };
+		});
+		for (const child of this.#renderedChildren) {
+			if (!nextChildren.includes(child)) child.dispose?.();
+		}
+		this.#renderedChildren = nextChildren;
+
+		const head = snapshot.header ?? (snapshot.status ? JSON.stringify(snapshot.status) : "");
+		if (
+			previous !== undefined &&
+			previous.head === head &&
+			previous.meta === snapshot.headerMeta &&
+			previous.phase === snapshot.phase &&
+			previous.applyBg === snapshot.applyBg &&
+			previous.borderColor === snapshot.borderColor &&
+			previous.slots.length === slots.length &&
+			slots.every((slot, index) => {
+				const prior = previous.slots[index]!;
+				return prior.label === slot.label && prior.separator === slot.separator && prior.child === slot.child;
+			})
+		) {
+			return previous.node;
+		}
+
+		const headSpans: TspText | undefined = snapshot.header
+			? compactText(styledSpans(snapshot.header))
+			: snapshot.status
+				? statusSpans(snapshot.status, this.#theme)
+				: undefined;
+		const sections: NativeOutputBlockSection[] = slots.map((slot, index) => ({
+			label: slot.label === undefined ? undefined : compactText(styledSpans(slot.label)),
+			separator: slot.separator,
+			body: [slot.child],
+			key: String(index),
+		}));
+		const state = toolCardState(snapshot.phase);
+		const plain = this.#options.variant === "plain";
+		const described = describeOutputBlock({
+			head: headSpans,
+			meta: snapshot.headerMeta ? compactText(styledSpans(snapshot.headerMeta)) : undefined,
+			state,
+			role: "omp.tool",
+			tone:
+				snapshot.borderColor !== undefined
+					? (colorTone(snapshot.borderColor) ?? "neutral")
+					: plain && snapshot.applyBg === false
+						? "neutral"
+						: undefined,
+			sections,
+			inset: plain || undefined,
+		});
+		this.#native = {
+			head,
+			meta: snapshot.headerMeta,
+			phase: snapshot.phase,
+			applyBg: snapshot.applyBg,
+			borderColor: snapshot.borderColor,
+			slots,
+			node: described,
+		};
+		return described;
+	}
+
 	get debugChildren(): readonly Component[] {
 		return this.#renderedChildren;
 	}
@@ -236,6 +372,7 @@ export class ToolCard implements Component {
 	}
 
 	invalidate(): void {
+		this.#native = undefined;
 		this.#block.invalidate();
 		this.#lastBlockOptions = undefined;
 		this.#plainKey = "";

package/src/render/tree-list.ts

@@ -2,6 +2,10 @@
  * Hierarchical tree list rendering helper.
  */
 
+import type { TspTreeNode } from "@oh-my-pi/pi-wire";
+import { styledSpans } from "../native/spans";
+import { node, span } from "../native/describe";
+import type { NativeNode } from "../native/node";
 import type { Theme } from "../theme/theme";
 import { visibleWidth } from "../utils";
 import { TreeView } from "../components/tree-view";
@@ -169,6 +173,41 @@ export function renderTreeList<T>(options: TreeListOptions<T>, theme: Theme): st
 	return renderTreeListRows(roots, theme);
 }
 
+/**
+ * The native form of {@link renderTreeList}: a flat `tree` whose branch
+ * gutters are the terminal's. The collapsed item cap (and the caller's
+ * trailing summary) are kept as a muted "… N more" node; the visual line
+ * budget (`maxCollapsedLines`) is layout and is left to the terminal.
+ */
+export function describeTreeList<T>(options: TreeListOptions<T>, theme: Theme): NativeNode {
+	const { items, expanded = false, maxCollapsed = 8, itemType = "item", truncateFrom = "end", renderItem } = options;
+	const itemNode = (index: number): TspTreeNode => {
+		const rendered = renderItem(items[index], {
+			index,
+			isLast: index === items.length - 1,
+			depth: 0,
+			theme,
+			prefix: "",
+			continuePrefix: "",
+		});
+		return { id: `i${index}`, label: styledSpans(Array.isArray(rendered) ? rendered.join("\n") : rendered) };
+	};
+	const summaryNode = (text: string): TspTreeNode => ({ id: "more", label: [span(text, "muted")] });
+	const nodes: TspTreeNode[] = [];
+	if (!expanded && options.trailingSummary !== undefined) {
+		for (let index = 0; index < items.length; index++) nodes.push(itemNode(index));
+		if (options.trailingSummary !== "") nodes.push(summaryNode(options.trailingSummary));
+		return node("tree", { nodes });
+	}
+	const shown = expanded ? items.length : Math.min(items.length, maxCollapsed);
+	const hidden = items.length - shown;
+	const start = truncateFrom === "start" ? items.length - shown : 0;
+	if (hidden > 0 && truncateFrom === "start") nodes.push(summaryNode(formatMoreItems(hidden, itemType)));
+	for (let index = start; index < start + shown; index++) nodes.push(itemNode(index));
+	if (hidden > 0 && truncateFrom === "end") nodes.push(summaryNode(formatMoreItems(hidden, itemType)));
+	return node("tree", { nodes });
+}
+
 /**
  * Emit pre-rendered item/summary roots through the shared keyed hierarchy.
  * Roots are siblings in display order, so the first N-1 rows draw `├` and the

package/src/render/width-aware-text.ts

@@ -1,4 +1,6 @@
 import { Text } from "../components/text";
+import { col } from "../native/describe";
+import type { DescribeContext, NativeNode } from "../native/node";
 import type { Component } from "../tui";
 import { getPaddingX } from "../utils";
 
@@ -23,6 +25,8 @@ export class WidthAwareText implements Component {
 	#cachedContentWidth = -1;
 	#cachedText: string | undefined;
 	#ignoreTight = false;
+	#nativeCols = -1;
+	#native: NativeNode | undefined;
 
 	constructor(format: (contentWidth: number) => string, paddingX = 1, paddingY = 1) {
 		this.#format = format;
@@ -56,6 +60,22 @@ export class WidthAwareText implements Component {
 		this.#cachedText = undefined;
 	}
 
+	/**
+	 * The inner `Text` as the only child, fed the formatter's output. The
+	 * formatter is width-bound by contract, so it runs once per surface width
+	 * (the only width a describer knows) and again on `reformat()`.
+	 */
+	describe(cx: DescribeContext): NativeNode {
+		if (this.#cachedText === undefined || cx.cols !== this.#nativeCols) {
+			this.#nativeCols = cx.cols;
+			this.#cachedContentWidth = -1;
+			this.#cachedText = this.#format(Math.max(1, cx.cols));
+			this.#inner.setText(this.#cachedText);
+		}
+		this.#native ??= col([this.#inner]);
+		return this.#native;
+	}
+
 	render(width: number): readonly string[] {
 		const paddingX = this.#ignoreTight ? this.#paddingX : getPaddingX(this.#paddingX);
 		const contentWidth = Math.max(1, width - paddingX * 2);

package/src/setup/scenes/composer.ts

@@ -8,6 +8,9 @@ import { renderComposerShapePreview } from "../../overlays/composer-shape-previe
 import { getComposerShapeOptions } from "../../overlays/composer-shape-registry";
 import { editorKey } from "../../chrome/keybinding-hints";
 import { getSelectListTheme, theme } from "../../theme/theme";
+import { ansi, col, span, text } from "../../native/describe";
+import type { DescribeContext, NativeNode } from "../../native/node";
+import { Memo } from "../../native/memo";
 import type { SetupScene, SetupSceneController, SetupSceneHost } from "./types";
 
 class ComposerSceneController implements SetupSceneController {
@@ -19,6 +22,7 @@ class ComposerSceneController implements SetupSceneController {
 	#currentShape: ComposerShape = "band";
 	#committing = false;
 	#step: WizardStep | undefined;
+	#native = new Memo();
 
 	readonly #host: SetupSceneHost;
 
@@ -52,6 +56,7 @@ class ComposerSceneController implements SetupSceneController {
 	}
 
 	invalidate(): void {
+		this.#native.clear();
 		if (this.#step) this.#step.invalidate();
 		else this.#selectList.invalidate();
 	}
@@ -106,6 +111,30 @@ class ComposerSceneController implements SetupSceneController {
 		return this.#step.render(width);
 	}
 
+	/**
+	 * Intro, the shape list, and the live preview. The preview is omp's own
+	 * composer chrome for the highlighted shape — exactly what the classic
+	 * renderer paints — so it travels as `ansi` rendered at the surface width.
+	 */
+	describe(cx: DescribeContext): NativeNode {
+		const confirm = editorKey("tui.select.confirm");
+		return this.#native.get([this.#currentShape, cx.cols, confirm], () =>
+			col(
+				[
+					text([span(`Select a layout; live preview updates below. Press ${confirm} to confirm.`, "muted")]),
+					this.#selectList,
+					col([
+						text([span("Preview:", "muted")]),
+						ansi(renderComposerShapePreview(this.#currentShape, cx.cols, this.#host.ctx.statusLine).join("\n"), {
+							cols: cx.cols,
+						}),
+					]),
+				],
+				{ gap: "sm", role: "omp.setup.composer" },
+			),
+		);
+	}
+
 	async #commit(shape: ComposerShape): Promise<void> {
 		if (this.#committing) return;
 		this.#committing = true;

package/src/setup/scenes/glyph.ts

@@ -4,6 +4,9 @@ import { type SelectItem, SelectList } from "../../components/select-list";
 import { Text } from "../../components/text";
 import { WizardStep } from "../../components/wizard-step";
 import { getSelectListTheme, type SymbolPreset, setSymbolPreset, theme } from "../../theme/theme";
+import { col, span, text } from "../../native/describe";
+import type { NativeNode } from "../../native/node";
+import { Memo } from "../../native/memo";
 import type { SetupScene, SetupSceneController, SetupSceneHost } from "./types";
 
 const GLYPH_PRESETS = ["nerd", "unicode", "ascii"] as const satisfies readonly SymbolPreset[];
@@ -34,6 +37,7 @@ class GlyphSceneController implements SetupSceneController {
 	#previewRequest = 0;
 	#committing = false;
 	#step: WizardStep | undefined;
+	#native = new Memo();
 
 	readonly #host: SetupSceneHost;
 
@@ -53,6 +57,7 @@ class GlyphSceneController implements SetupSceneController {
 	}
 
 	invalidate(): void {
+		this.#native.clear();
 		if (this.#step) this.#step.invalidate();
 		else this.#selectList.invalidate();
 	}
@@ -92,6 +97,16 @@ class GlyphSceneController implements SetupSceneController {
 		return this.#step.render(width);
 	}
 
+	/** Hint line over the preset list; the list (sample glyphs as item detail) describes itself. */
+	describe(): NativeNode {
+		return this.#native.get([this.#selectList], () =>
+			col(
+				[text([span("If a row shows boxes, tofu, or misaligned icons, pick another.", "muted")]), this.#selectList],
+				{ gap: "sm", role: "omp.setup.glyph" },
+			),
+		);
+	}
+
 	async #commit(preset: SymbolPreset): Promise<void> {
 		if (this.#committing) return;
 		this.#committing = true;

package/src/setup/scenes/model.ts

@@ -6,7 +6,10 @@ import { buildBrowserItems, ModelBrowser, resolveRoleAssignments, sortModelItems
 import { BROWSER_FRAME_ROWS } from "../../overlays/model-picker";
 import { formatKeyHint } from "../../app-keybindings";
 import { theme } from "../../theme/theme";
-import type { SetupScene, SetupSceneController, SetupSceneHost } from "./types";
+import { col, node, span, text } from "../../native/describe";
+import type { NativeNode } from "../../native/node";
+import { Memo } from "../../native/memo";
+import type { SetupScene, SetupSceneController, SetupSceneHost, StyledLine } from "./types";
 
 const MAX_VISIBLE_MODELS = 10;
 
@@ -14,10 +17,12 @@ class ModelSceneController implements SetupSceneController {
 	title = "Choose your default model";
 	subtitle = "Search configured models and save the model used for new sessions.";
 	#browser: ModelBrowser;
-	#status: string | undefined;
+	/** Intro override; `busy` while discovering or saving (a spinner on the native path). */
+	#status: (StyledLine & { readonly busy: boolean }) | undefined;
 	#selecting = false;
 	#disposed = false;
 	#step: WizardStep | undefined;
+	#native = new Memo();
 
 	readonly #host: SetupSceneHost;
 
@@ -32,7 +37,7 @@ class ModelSceneController implements SetupSceneController {
 	}
 
 	async onMount(): Promise<void> {
-		this.#status = theme.fg("muted", "Discovering available models…");
+		this.#status = { text: "Discovering available models…", color: "muted", busy: true };
 		this.#host.requestRender();
 		await this.#refreshModels();
 	}
@@ -42,6 +47,7 @@ class ModelSceneController implements SetupSceneController {
 	}
 
 	invalidate(): void {
+		this.#native.clear();
 		if (this.#step) this.#step.invalidate();
 		else this.#browser.invalidate();
 	}
@@ -58,9 +64,14 @@ class ModelSceneController implements SetupSceneController {
 	}
 
 	render(width: number, maxLines?: number): readonly string[] {
+		const status = this.#status;
 		const intro = new Text(
-			this.#status ??
-				theme.fg("muted", `Type to search. ${formatKeyHint("enter")} saves the highlighted model as your default.`),
+			status
+				? theme.fg(status.color, status.text)
+				: theme.fg(
+						"muted",
+						`Type to search. ${formatKeyHint("enter")} saves the highlighted model as your default.`,
+					),
 			0,
 			0,
 		);
@@ -82,6 +93,23 @@ class ModelSceneController implements SetupSceneController {
 		return this.#step.render(width);
 	}
 
+	/** Intro (a spinner while models load or the choice saves) over the model browser, which describes itself. */
+	describe(): NativeNode {
+		const status = this.#status;
+		const enter = formatKeyHint("enter");
+		return this.#native.get([status, enter], () => {
+			let intro: NativeNode;
+			if (status?.busy) {
+				intro = node("spinner", { label: [span(status.text, status.color)] });
+			} else if (status) {
+				intro = text([span(status.text, status.color)]);
+			} else {
+				intro = text([span(`Type to search. ${enter} saves the highlighted model as your default.`, "muted")]);
+			}
+			return col([{ ...intro, key: "intro" }, this.#browser], { gap: "sm", role: "omp.setup.model" });
+		});
+	}
+
 	#syncModels(): void {
 		const { available, all, current } = this.#host.ctx.getModels();
 		const source = this.#host.ctx.modelSource;
@@ -109,7 +137,7 @@ class ModelSceneController implements SetupSceneController {
 			this.#host.requestRender();
 		} catch (error) {
 			if (this.#disposed) return;
-			this.#status = theme.fg("error", error instanceof Error ? error.message : String(error));
+			this.#status = { text: error instanceof Error ? error.message : String(error), color: "error", busy: false };
 			this.#host.requestRender();
 		}
 	}
@@ -117,7 +145,7 @@ class ModelSceneController implements SetupSceneController {
 	async #select(model: Model, selector: string): Promise<void> {
 		if (this.#selecting) return;
 		this.#selecting = true;
-		this.#status = theme.fg("muted", `Saving ${selector} as the default model…`);
+		this.#status = { text: `Saving ${selector} as the default model…`, color: "muted", busy: true };
 		this.#host.requestRender();
 		try {
 			await this.#host.ctx.selectModel(model, selector);
@@ -125,7 +153,7 @@ class ModelSceneController implements SetupSceneController {
 		} catch (error) {
 			if (this.#disposed) return;
 			this.#selecting = false;
-			this.#status = theme.fg("error", error instanceof Error ? error.message : String(error));
+			this.#status = { text: error instanceof Error ? error.message : String(error), color: "error", busy: false };
 			this.#host.requestRender();
 		}
 	}

package/src/setup/scenes/outro.ts

@@ -1,11 +1,38 @@
 import { centerLine } from "../../utils";
 import { padToWidth } from "../../render/utils";
-import { gradientLogo, PI_LOGO } from "../../prompt/welcome";
+import { gradientLogo, logoNode, PI_LOGO } from "../../prompt/welcome";
 import { theme } from "../../theme/theme";
+import { col, node, span, text } from "../../native/describe";
+import type { NativeNode } from "../../native/node";
+import { Memo } from "../../native/memo";
 import { renderStarfield, SETUP_TICK_MS } from "./splash";
 
 export const SETUP_OUTRO_MS = 1200;
 
+const outroMemo = new Memo();
+
+/**
+ * Native outro: the shimmering mark, the saved confirmation, and an
+ * indeterminate progress bar standing in for the timed sweep. A click sends
+ * the `continue` action.
+ */
+export function describeSetupOutro(): NativeNode {
+	const saved = `${theme.status.success} Setup saved`;
+	return outroMemo.get([saved], () =>
+		col(
+			[
+				node("spacer", { grow: 1 }),
+				logoNode(PI_LOGO, true),
+				text([span(saved, "success strong")], { wrap: "none" }),
+				text([span("Handing off to the normal CLI…", "muted")], { wrap: "none" }),
+				node("progress", { value: null, max: { w: "48ch" } }),
+				node("spacer", { grow: 1 }),
+			],
+			{ align: "center", gap: "sm", grow: 1, role: "omp.setup.outro", actions: { click: "continue" } },
+		),
+	);
+}
+
 export function renderSetupOutro(width: number, height: number, elapsedMs: number): string[] {
 	const frame = Math.floor(elapsedMs / SETUP_TICK_MS);
 	const lines = renderStarfield(width, height, frame + 1000);