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

package/src/components/layout/split-pane.ts

@@ -1,4 +1,7 @@
 import type { MouseRoutable, SgrMouseEvent } from "../../mouse";
+import type { TspProps } from "@oh-my-pi/pi-wire";
+import { col, node, row } from "../../native/describe";
+import type { DescribeContext, NativeNode } from "../../native/node";
 import type { Component } from "../../tui";
 import { visibleWidth } from "../../utils";
 import {
@@ -11,6 +14,9 @@ import {
 	type LayoutRect,
 	layoutRatio,
 	layoutSize,
+	nativeLayoutChild,
+	nativeLayoutGap,
+	nativeSlotProps,
 	optionalLayoutSize,
 	uniqueLayoutComponents,
 } from "./geometry";
@@ -88,6 +94,16 @@ export class SplitPane implements Component, MouseRoutable {
 	#measureMemo: SplitMeasureMemo | undefined;
 	#rowMode: "split" | PaneSide = "split";
 	#rowLeftWidth = -1;
+	#native:
+		| {
+				leftSize: SplitPaneSize;
+				rightMinWidth: number;
+				narrowPane: PaneSide | undefined;
+				divider: LayoutDecoration | undefined;
+				height: number | undefined;
+				node: NativeNode;
+		  }
+		| undefined;
 
 	constructor(options: SplitPaneOptions) {
 		this.#left = options.left;
@@ -268,6 +284,55 @@ export class SplitPane implements Component, MouseRoutable {
 		return geometry;
 	}
 
+	/**
+	 * Two flex slots in a `row`: the left pane fixed (`ch`) or a fraction of
+	 * the width within its bounds, the right pane growing from its minimum.
+	 * With a narrow pane configured the row may wrap, stacking the panes on
+	 * narrow terminals instead of hiding one.
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		const cached = this.#native;
+		if (
+			cached?.leftSize === this.#leftSize &&
+			cached.rightMinWidth === this.#rightMinWidth &&
+			cached.narrowPane === this.#narrowPane &&
+			cached.divider === this.#divider &&
+			cached.height === this.#height
+		) {
+			return cached.node;
+		}
+		const size = this.#leftSize;
+		const leftProps: TspProps<"col"> =
+			size.fixed !== undefined
+				? nativeSlotProps("w", { fixed: size.fixed })
+				: {
+						...nativeSlotProps("w", { grow: 0, min: size.min, max: size.max }),
+						basis: layoutRatio(size.ratio, 0.5),
+					};
+		const rightProps = nativeSlotProps("w", { grow: 1, min: this.#rightMinWidth });
+		const height = this.#height;
+		const described = row(
+			[
+				node("col", leftProps, [nativeLayoutChild(this.#left)], "left"),
+				node("col", rightProps, [nativeLayoutChild(this.#right)], "right"),
+			],
+			{ gap: nativeLayoutGap(this.#divider), align: this.#align, wrap: this.#narrowPane !== undefined },
+		);
+		const result =
+			height === undefined
+				? described
+				: col([described], { min: { h: `${height}lines` }, max: { h: `${height}lines` } });
+		this.#native = {
+			leftSize: size,
+			rightMinWidth: this.#rightMinWidth,
+			narrowPane: this.#narrowPane,
+			divider: this.#divider,
+			height,
+			node: result,
+		};
+		return result;
+	}
+
 	/** Translate a split-local point into pane-local coordinates. */
 	locate(line: number, col: number): SplitPaneHit | undefined {
 		const panes: readonly [PaneSide, LayoutContent, LayoutRect | undefined][] = [

package/src/components/layout/stack.ts

@@ -1,4 +1,6 @@
 import type { MouseRoutable, SgrMouseEvent } from "../../mouse";
+import { col } from "../../native/describe";
+import type { DescribeContext, NativeNode } from "../../native/node";
 import type { Component } from "../../tui";
 import { padding } from "../../utils";
 import {
@@ -13,6 +15,8 @@ import {
 	type LayoutInsets,
 	type LayoutRect,
 	layoutSize,
+	nativeLayoutChild,
+	nativeSlotProps,
 	optionalLayoutSize,
 	renderLayoutContent,
 	uniqueLayoutComponents,
@@ -76,6 +80,7 @@ export class Stack implements Component, MouseRoutable {
 	#frames: LayoutRect[] = [];
 	#memo: StackMemo | undefined;
 	#ignoreTight = false;
+	#native: { children: StackChild[]; height: number | undefined; node: NativeNode } | undefined;
 
 	constructor(options: StackOptions) {
 		this.#children = options.children.map(child => ({ ...child, padding: { ...child.padding } }));
@@ -141,6 +146,28 @@ export class Stack implements Component, MouseRoutable {
 		}
 	}
 
+	/**
+	 * A `col` of slots carrying each child's height bounds (fixed → min = max
+	 * `lines`, else grow/min/max); an exact stack height bounds the column.
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		const cached = this.#native;
+		if (cached?.children === this.#children && cached.height === this.#height) return cached.node;
+		const slots = this.#children.map(child =>
+			col(
+				[nativeLayoutChild(child.content)],
+				nativeSlotProps("h", { fixed: child.height, grow: child.grow, min: child.minHeight, max: child.maxHeight }),
+			),
+		);
+		const height = this.#height;
+		const described = col(
+			slots,
+			height === undefined ? undefined : { min: { h: `${height}lines` }, max: { h: `${height}lines` } },
+		);
+		this.#native = { children: this.#children, height, node: described };
+		return described;
+	}
+
 	/** 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++) {

package/src/components/loader.ts

@@ -1,13 +1,99 @@
+import type { TspProps } from "@oh-my-pi/pi-wire";
+import { elapsed, kbd, keyed, node, row, span, text } from "../native/describe";
+import { plainText } from "../native/spans";
+import type { DescribeContext, NativeChild, NativeNode, NativeUiEvent } from "../native/node";
+import { isNativeRendering } from "../native/state";
+import { describeShimmer, type ShimmerPalette, shimmerEnabled } from "../theme/shimmer";
 import type { TUI } from "../tui";
 import { getPaddingX, padding, sliceByColumn, visibleWidth } from "../utils";
 import { Text } from "./text";
 
+const DEFAULT_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 const RENDER_INTERVAL_MS = 1000 / 30;
 /** Milliseconds between spinner-frame advances; exported so time-derived spinners elsewhere tick at the Loader cadence. */
 export const SPINNER_ADVANCE_MS = 80;
 const RENDER_BACKPRESSURE_MULTIPLIER = 9;
 const MAX_BACKPRESSURE_FRAME_COST_MS = 200;
 
+/** Native repaint cadence of a retry countdown ring (the terminal eases the ring between frames). */
+const RETRY_METER_REPAINT_MS = 500;
+
+/** A working-row variant (§6.5): a retry countdown, or context compaction. */
+export type WorkingRowVariant =
+	| {
+			readonly kind: "retry";
+			readonly attempt: number;
+			readonly max: number;
+			/** The wait before the attempt, in ms, counted from the row's `startedAt`. */
+			readonly delayMs: number;
+	  }
+	| { readonly kind: "compaction" };
+
+/** What the dock's working row (§8.1, role `omp.working`) shows. */
+export interface WorkingRowSpec {
+	/** The intent, or the variant's label ("Retrying · attempt 1 of 3", "Compacting context…"). */
+	readonly label: string;
+	/** Epoch ms the work started: the `elapsed` origin and the retry countdown start. */
+	readonly startedAt: number;
+	readonly variant?: WorkingRowVariant;
+	/** Shimmer palette of the label (a session-accented intent). */
+	readonly palette?: ShimmerPalette;
+	/** Live tok/s, docked before the stop control. */
+	readonly rate?: number;
+	/** Key id that interrupts (`escape`); undefined hides the stop control (Esc would not cancel). */
+	readonly interruptKey?: string;
+}
+
+/** A key id as tooltip keys: `escape` reads `esc`, the rest as bound. */
+function titleKey(key: string): string {
+	return key === "escape" ? "esc" : key;
+}
+
+/**
+ * The dock's working row: `starburst` spinner (or a retry countdown ring),
+ * the intent shimmering, `·`, the elapsed time, a grow spacer, then the stop
+ * control whose click sends `interrupt`. Compaction adds an indeterminate
+ * `progress` before the stop control; a retry says "Cancel".
+ */
+export function describeWorkingRow(spec: WorkingRowSpec, cx: DescribeContext, now = Date.now()): NativeNode {
+	const variant = spec.variant;
+	const children: NativeChild[] = [];
+	if (variant?.kind === "retry" && cx.supports("meter")) {
+		const remaining = Math.max(0, variant.delayMs - (now - spec.startedAt));
+		const value = variant.delayMs > 0 ? Math.round((remaining / variant.delayMs) * 100) / 100 : 0;
+		children.push(node("meter", { value, style: "ring", size: "sm" }, undefined, "countdown"));
+	} else {
+		children.push(node("spinner", { style: "starburst", tone: "accent" }, undefined, "spinner"));
+	}
+	const label = describeShimmer([{ text: spec.label, palette: spec.palette }], "label");
+	children.push(
+		node(label.k, { ...label.p, role: "omp.working.label" } as TspProps, label.c, label.key),
+		node("text", { text: "·", role: "omp.working.sep" }, undefined, "sep"),
+		keyed(elapsed(now - spec.startedAt), "elapsed"),
+		node("row", { grow: 1 }, undefined, "fill"),
+	);
+	if (variant?.kind === "compaction") children.push(node("progress", { value: null }, undefined, "progress"));
+	if (spec.rate !== undefined) children.push(node("rate", { value: spec.rate, unit: "tok/s" }, undefined, "rate"));
+	if (spec.interruptKey !== undefined) {
+		const verb = variant?.kind === "retry" ? "Cancel" : "Stop";
+		children.push(
+			node(
+				"row",
+				{
+					role: "omp.working.stop",
+					gap: "xs",
+					align: "center",
+					title: `${verb}  ${titleKey(spec.interruptKey)}`,
+					actions: { click: "interrupt" },
+				},
+				[kbd(titleKey(spec.interruptKey)), text(verb)],
+				"stop",
+			),
+		);
+	}
+	return row(children, { role: "omp.working", align: "center", gap: "sm" });
+}
+
 type ColorFn = (str: string) => string;
 
 /**
@@ -20,7 +106,7 @@ export type LoaderMessageColorFn = ColorFn & {
 
 /** Animates a spinner and colorized message while asynchronous work is pending. */
 export class Loader extends Text {
-	#frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+	#frames = DEFAULT_SPINNER_FRAMES;
 	#currentFrame = 0;
 	#intervalId?: NodeJS.Timeout;
 	#ui: TUI | null = null;
@@ -37,6 +123,10 @@ export class Loader extends Text {
 	#layoutFrames: readonly string[];
 	#layoutFrame: string;
 	#trailer?: () => string | undefined;
+	#native?: { message: string; trailer: string; shimmer: boolean; node: NativeNode };
+	#working?: { spec: () => WorkingRowSpec; interrupt: () => void };
+	#workingNative?: { key: string; node: NativeNode };
+	#nativeTimer?: NodeJS.Timeout;
 
 	constructor(
 		ui: TUI,
@@ -136,10 +226,93 @@ export class Loader extends Text {
 		return lines;
 	}
 
+	/**
+	 * A `spinner` (or the static glyph of a one-frame loader, e.g. an interrupt
+	 * key hint) followed by the message, shimmering when the message colorizer
+	 * animates, and the right-docked trailer. The terminal clocks the motion.
+	 * Function messages are re-read whenever the engine revisits the loader.
+	 */
+	override describe(cx: DescribeContext): NativeNode {
+		if (this.#working) return this.#describeWorking(cx);
+		const message = plainText(this.#resolveMessage());
+		const trailer = plainText(this.#trailer?.() ?? "");
+		const shimmer = this.messageColorFn.animated === true && shimmerEnabled();
+		const cached = this.#native;
+		if (cached && cached.message === message && cached.trailer === trailer && cached.shimmer === shimmer) {
+			return cached.node;
+		}
+		const indicator =
+			this.#frames.length > 1
+				? node("spinner", this.#frames === DEFAULT_SPINNER_FRAMES ? { style: "braille" } : {})
+				: text([span(plainText(this.#frames[0] ?? "").trim(), "muted")], { wrap: "none" });
+		const label = shimmer
+			? describeShimmer([{ text: message }], "message")
+			: node("text", { spans: [span(message, "muted")] }, undefined, "message");
+		const children: NativeChild[] = [row([indicator, label], { gap: "sm", align: "baseline" })];
+		if (trailer) children.push(text(trailer, { wrap: "none", truncate: "end" }));
+		const described = row(children, { justify: "between", role: "omp.loader" });
+		this.#native = { message, trailer, shimmer, node: described };
+		return described;
+	}
+
+	/**
+	 * Describe as the dock's working row ({@link describeWorkingRow}) instead
+	 * of a spinner line; `spec` is re-read whenever the engine revisits the
+	 * loader and `interrupt` answers a click on its stop control.
+	 */
+	setWorkingRow(spec: () => WorkingRowSpec, interrupt: () => void): void {
+		this.#working = { spec, interrupt };
+		this.#workingNative = undefined;
+		this.#startNativeCountdown();
+	}
+
+	/** A click on the working row's stop control. */
+	handleNativeEvent(event: NativeUiEvent): void {
+		if (event.type === "action" && event.act === "interrupt") this.#working?.interrupt();
+	}
+
+	#describeWorking(cx: DescribeContext): NativeNode {
+		const spec = this.#working!.spec();
+		const now = Date.now();
+		const variant = spec.variant;
+		const countdown =
+			variant?.kind === "retry" && cx.supports("meter")
+				? Math.round((Math.max(0, variant.delayMs - (now - spec.startedAt)) / Math.max(1, variant.delayMs)) * 100)
+				: -1;
+		const key = [
+			spec.label,
+			spec.startedAt,
+			variant?.kind,
+			variant?.kind === "retry" ? `${variant.attempt}/${variant.max}` : "",
+			countdown,
+			spec.rate,
+			spec.interruptKey,
+			spec.palette?.mid,
+			shimmerEnabled(),
+		].join("\u0000");
+		const cached = this.#workingNative;
+		if (cached?.key === key) return cached.node;
+		const described = describeWorkingRow(spec, cx, now);
+		this.#workingNative = { key, node: described };
+		return described;
+	}
+
+	/** A TSP terminal clocks the spinner and timer, but a retry ring's fill is omp's: repaint it while counting down. */
+	#startNativeCountdown(): void {
+		if (this.#nativeTimer || !isNativeRendering() || this.#working?.spec().variant?.kind !== "retry") return;
+		this.#nativeTimer = setInterval(() => this.#requestPaint(), RETRY_METER_REPAINT_MS);
+		this.#nativeTimer.unref?.();
+	}
+
 	start() {
 		this.#lastSpinnerTick = performance.now();
 		this.#syncText();
 		this.#requestPaint();
+		// The TSP terminal animates the described spinner; nothing to repaint.
+		if (isNativeRendering()) {
+			this.#startNativeCountdown();
+			return;
+		}
 		const intervalMs = this.messageColorFn.animated === true ? RENDER_INTERVAL_MS : SPINNER_ADVANCE_MS;
 		this.#scheduleTick(intervalMs, intervalMs);
 	}
@@ -149,6 +322,10 @@ export class Loader extends Text {
 			clearTimeout(this.#intervalId);
 			this.#intervalId = undefined;
 		}
+		if (this.#nativeTimer) {
+			clearInterval(this.#nativeTimer);
+			this.#nativeTimer = undefined;
+		}
 	}
 
 	/** Lifecycle teardown: stop the animation timer. Idempotent. */
@@ -174,6 +351,11 @@ export class Loader extends Text {
 	#scheduleTick(intervalMs: number, delayMs: number): void {
 		const timer = setTimeout(() => {
 			if (this.#intervalId !== timer) return;
+			if (isNativeRendering()) {
+				// A TSP surface opened mid-animation: the terminal clocks it from here.
+				this.#intervalId = undefined;
+				return;
+			}
 			const startedAt = performance.now();
 			const elapsed = startedAt - this.#lastSpinnerTick;
 			const shouldAdvanceSpinner = elapsed >= SPINNER_ADVANCE_MS;

package/src/components/markdown.ts

@@ -10,6 +10,9 @@ import {
 import { mathBlockAt, mathSpanAt, mathStartIndex } from "@oh-my-pi/pi-utils/math-delimiters";
 import { latexToBlock } from "../latex-block";
 import { isBareMathEnvironment, latexToUnicode } from "../latex-to-unicode";
+import { plainText } from "../native/spans";
+import { md } from "../native/describe";
+import type { DescribeContext, NativeNode } from "../native/node";
 import type { SymbolTheme } from "../symbols";
 import { TERMINAL } from "../terminal-capabilities";
 import type { Component } from "../tui";
@@ -1817,6 +1820,7 @@ export class Markdown implements Component {
 	// B+ capture plumbing: #renderContentLines records the last rendered paragraph row.
 	#lastTailCapture?: { kind: "paragraph"; open: boolean; rowInput: string; rowRaw: string };
 	#ignoreTight = false;
+	#native?: { text: string; stream: boolean; node: NativeNode };
 	setIgnoreTight(ignore: boolean): this {
 		this.#ignoreTight = ignore;
 		this.invalidate();
@@ -1913,6 +1917,23 @@ export class Markdown implements Component {
 		this.#cachedLines = undefined;
 	}
 
+	/**
+	 * The unrendered source as an `md` node, `stream` while the streaming
+	 * (transient) cache is on. Append-only growth yields a fresh node of the
+	 * same kind and key whose text extends the previous one, which the
+	 * reconciler sends as `text append`.
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		const stream = this.#transientRenderCache;
+		const cached = this.#native;
+		if (cached?.text === this.#text && cached.stream === stream) return cached.node;
+		// Sources are model text; OSC 8 / SGR bytes a caller spliced in are the terminal's to style, not ours.
+		const source = this.#text.includes("\x1b") ? plainText(this.#text) : this.#text;
+		const described = md(source, stream ? { stream: true } : undefined);
+		this.#native = { text: this.#text, stream, node: described };
+		return described;
+	}
+
 	/**
 	 * Width-independent source prefix of the last render ending at a frozen
 	 * Markdown block boundary. Only meaningful while streaming (transient

package/src/components/metric.ts

@@ -1,3 +1,6 @@
+import { styleSpans } from "../native/spans";
+import { node, text } from "../native/describe";
+import type { DescribeContext, NativeNode } from "../native/node";
 import type { Component } from "../tui";
 import { Ellipsis, getWidthConfigEpoch, truncateToWidth, visibleWidth } from "../utils";
 import { Text } from "./text";
@@ -85,6 +88,7 @@ export class MetricRow implements Component {
 	readonly #options: MetricRowOptions;
 	readonly #text: Text;
 	#cache: { width: number; epoch: number; source: readonly string[]; lines: readonly string[] } | undefined;
+	#native: NativeNode | undefined;
 
 	constructor(metrics: readonly MetricSpec[], options: MetricRowOptions = {}) {
 		this.#metrics = metrics;
@@ -96,12 +100,47 @@ export class MetricRow implements Component {
 		if (this.#metrics === metrics) return false;
 		this.#metrics = metrics;
 		this.#cache = undefined;
+		this.#native = undefined;
 		return true;
 	}
 
 	invalidate(): void {
 		this.#text.invalidate();
 		this.#cache = undefined;
+		this.#native = undefined;
+	}
+
+	/**
+	 * `drop` overflow becomes a transparent `status` strip whose segments keep
+	 * the metric priorities (the terminal drops the lowest first); the other
+	 * modes are one text run that wraps or truncates.
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		if (this.#native) return this.#native;
+		const options = this.#options;
+		if (options.overflow === "drop") {
+			const segs: NativeNode[] = [];
+			this.#metrics.forEach((metric, index) => {
+				const formatted = formatMetric(metric);
+				if (formatted === undefined) return;
+				segs.push(
+					node(
+						"seg",
+						{ side: "left", priority: metric.priority ?? 0, spans: styleSpans(formatted, options.style) },
+						undefined,
+						String(index),
+					),
+				);
+			});
+			this.#native = node("status", { transparent: true }, segs);
+			return this.#native;
+		}
+		const joined = formatMetricRow(this.#metrics, { separator: options.separator });
+		this.#native =
+			options.overflow === "wrap"
+				? text(styleSpans(joined, options.style), { wrap: "word" })
+				: text(styleSpans(joined, options.style), { wrap: "none", truncate: "end" });
+		return this.#native;
 	}
 
 	render(width: number): readonly string[] {

package/src/components/progress-bar.ts

@@ -1,3 +1,6 @@
+import { compactText, styledSpans } from "../native/spans";
+import { node } from "../native/describe";
+import type { DescribeContext, NativeNode } from "../native/node";
 import type { Component } from "../tui";
 import { Ellipsis, getWidthConfigEpoch, truncateToWidth, visibleWidth } from "../utils";
 
@@ -87,6 +90,7 @@ export class ProgressBar implements Component {
 	#value: number | undefined;
 	readonly #options: ProgressBarOptions;
 	#cache: { width: number; epoch: number; value: number | undefined; lines: readonly string[] } | undefined;
+	#native: NativeNode | undefined;
 
 	constructor(value: number | undefined, options: ProgressBarOptions) {
 		this.#value = value;
@@ -97,11 +101,35 @@ export class ProgressBar implements Component {
 		if (Object.is(this.#value, value)) return false;
 		this.#value = value;
 		this.#cache = undefined;
+		this.#native = undefined;
 		return true;
 	}
 
 	invalidate(): void {
 		this.#cache = undefined;
+		this.#native = undefined;
+	}
+
+	/** A native `progress` bar (indeterminate when the value is unknown); prefix, suffix and percentage label it. */
+	describe(_cx: DescribeContext): NativeNode {
+		if (this.#native) return this.#native;
+		const options = this.#options;
+		const fraction = progressFraction(this.#value, options.min, options.max);
+		const parts: string[] = [];
+		// Frame punctuation (`[`, `]`, `▕`) around the bar is the terminal's chrome now; only wording labels it.
+		const frame = /^[^\p{L}\p{N}]+|[^\p{L}\p{N}%)]+$/gu;
+		const prefix = singleLine(options.prefix ?? "").replace(frame, "");
+		const suffix = singleLine(options.suffix ?? "").replace(frame, "");
+		if (prefix) parts.push(prefix);
+		if (suffix) parts.push(suffix);
+		if (fraction !== undefined && options.showPercentage === true) {
+			parts.push(singleLine(options.formatPercentage?.(fraction) ?? `${Math.round(fraction * 100)}%`));
+		}
+		this.#native = node("progress", {
+			value: fraction ?? null,
+			label: parts.length > 0 ? compactText(styledSpans(parts.join(" "))) : undefined,
+		});
+		return this.#native;
 	}
 
 	render(width: number): readonly string[] {

package/src/components/scroll-view.ts

@@ -1,4 +1,7 @@
 import { matchesKey } from "../keys";
+import { rowsText } from "../native/spans";
+import { col } from "../native/describe";
+import type { DescribeContext, NativeNode } from "../native/node";
 import type { Component } from "../tui";
 import { Ellipsis, getWidthConfigEpoch, padding, replaceTabs, truncateToWidth, visibleWidth } from "../utils";
 import {
@@ -126,6 +129,7 @@ export class ScrollView implements Component {
 	#rangeSnapshot: RangeSnapshot | undefined;
 	#cache: RenderCache | undefined;
 	#disposed = false;
+	#native: { content: readonly string[] | Component; height: number; node: NativeNode } | undefined;
 
 	constructor(content: readonly string[] | Component, options: ScrollViewOptions) {
 		this.#child = isComponent(content) ? content : undefined;
@@ -400,6 +404,7 @@ export class ScrollView implements Component {
 	invalidate(): void {
 		if (this.#disposed) return;
 		this.#cache = undefined;
+		this.#native = undefined;
 		this.#child?.invalidate?.();
 	}
 
@@ -415,6 +420,24 @@ export class ScrollView implements Component {
 		child?.dispose?.();
 	}
 
+	/**
+	 * The whole content in a `col` capped at the viewport height: the
+	 * terminal scrolls it natively and draws its own scrollbar.
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		const content = this.#child ?? this.#lines;
+		const cached = this.#native;
+		if (cached?.content === content && cached.height === this.#height) return cached.node;
+		const described = this.#disposed
+			? col([], { hidden: true })
+			: col([this.#child ?? rowsText(this.#lines)], {
+					max: { h: `${this.#height}lines` },
+					hidden: this.#height === 0 ? true : undefined,
+				});
+		this.#native = { content, height: this.#height, node: described };
+		return described;
+	}
+
 	render(width: number): readonly string[] {
 		if (this.#disposed) return EMPTY_LINES;
 		const safeWidth = normalizedRows(width);

package/src/components/section.ts

@@ -1,3 +1,6 @@
+import { compactText, rowsText, styledSpans } from "../native/spans";
+import { node } from "../native/describe";
+import type { DescribeContext, NativeNode } from "../native/node";
 import type { Component } from "../tui";
 import { Ellipsis, getWidthConfigEpoch, replaceTabs, truncateToWidth, visibleWidth } from "../utils";
 
@@ -37,6 +40,7 @@ export class Section implements Component {
 	readonly #options: SectionOptions;
 	#cache: { width: number; epoch: number; child: readonly string[]; lines: readonly string[] } | undefined;
 	#disposed = false;
+	#native: { title: string; node: NativeNode } | undefined;
 
 	constructor(options: SectionOptions) {
 		this.#options = options;
@@ -53,6 +57,18 @@ export class Section implements Component {
 		if (isComponent(this.#options.body)) this.#options.body.dispose?.();
 	}
 
+	/** A `section` headed by the styled title; the rule is the terminal's. */
+	describe(_cx: DescribeContext): NativeNode {
+		const options = this.#options;
+		const rawTitle = singleLine(options.title);
+		const title = options.titleStyle?.(rawTitle) ?? rawTitle;
+		if (this.#native?.title === title) return this.#native.node;
+		const body = isComponent(options.body) ? options.body : rowsText(options.body);
+		const described = node("section", { head: compactText(styledSpans(title)) }, [body]);
+		this.#native = { title, node: described };
+		return described;
+	}
+
 	render(width: number): readonly string[] {
 		const renderWidth = finiteWidth(width);
 		const epoch = getWidthConfigEpoch();