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

package/src/overlays/btw-history-panel.ts

@@ -34,6 +34,10 @@ import { bottomBorder, row, topBorder } from "../chrome/overlay-box";
 import { padToWidth } from "../render/utils";
 import { SplitPane } from "../components/layout/split-pane";
 import { clampSelection, contentRowWidth, padLinesToHeight, renderScrollableList } from "../chrome/selector-helpers";
+import type { TspSpan } from "@oh-my-pi/pi-wire";
+import type { NativeChild, NativeNode, NativeUiEvent } from "../native/node";
+import { col, md, node, span, text } from "../native/describe";
+import { actionHint, hintsRow, type NativeHint, statusHintsRow } from "../native/overlay";
 
 interface BtwHistoryPanelOptions {
 	records: readonly BtwHistoryRecord[];
@@ -63,6 +67,20 @@ interface RenderedTurn {
 	width: number;
 }
 
+/** The visible inputs of the last native description; any change rebuilds it. */
+interface BtwHistoryNativeMemo {
+	records: readonly BtwHistoryRecord[];
+	selectedId: string | undefined;
+	focus: "list" | "answer";
+	focused: boolean;
+	composer: FollowUpComposer | undefined;
+	notice: string | undefined;
+	followUpPending: boolean;
+	canFollowUp: boolean;
+	copied: boolean;
+	node: NativeNode;
+}
+
 const STATUS: Record<BtwHistoryRecord["status"], { label: string; color: ThemeColor }> = {
 	running: { label: "Running", color: "accent" },
 	complete: { label: "Complete", color: "success" },
@@ -89,6 +107,7 @@ export class BtwHistoryPanel implements Component, Focusable {
 	#detailDirty = true;
 	#lastCopiedId: string | undefined;
 	#lastCopiedText: string | undefined;
+	#native: BtwHistoryNativeMemo | undefined;
 	readonly #detail = new ScrollView([], {
 		height: 1,
 		scrollbar: "auto",
@@ -190,6 +209,7 @@ export class BtwHistoryPanel implements Component, Focusable {
 		this.#turns = [];
 		this.#composer?.input.invalidate();
 		this.#detailDirty = true;
+		this.#native = undefined;
 		this.#split.invalidate();
 		this.#labels.invalidate();
 	}
@@ -340,6 +360,168 @@ export class BtwHistoryPanel implements Component, Focusable {
 		this.#options.requestRender();
 	}
 
+	/** A large glass sheet titled "BTW history". */
+	readonly nativeOverlay = { role: "omp.overlay.btwHistory", size: "lg", head: "BTW history" } as const;
+
+	describe(): NativeNode {
+		const record = this.#selected();
+		const composer = this.#composer;
+		const canFollowUp = record !== undefined && this.#canFollowUp(record);
+		const copied = record !== undefined && this.#isCopied(record);
+		const memo = this.#native;
+		if (
+			memo?.records === this.#records &&
+			memo.selectedId === this.#selectedId &&
+			memo.focus === this.#focus &&
+			memo.focused === this.#focused &&
+			memo.composer === composer &&
+			memo.notice === composer?.notice &&
+			memo.followUpPending === this.#followUpPending &&
+			memo.canFollowUp === canFollowUp &&
+			memo.copied === copied
+		) {
+			return memo.node;
+		}
+		const children: NativeChild[] = [
+			node(
+				"row",
+				{ gap: "md", align: "start" },
+				[
+					node(
+						"section",
+						{ head: this.#describeFocusLabel("list"), basis: 0.42, max: { w: "46ch" } },
+						[this.#describeList()],
+						"history",
+					),
+					node(
+						"section",
+						{ head: this.#describeFocusLabel("answer"), grow: 1 },
+						[this.#describeDetail(record, copied)],
+						"details",
+					),
+				],
+				"body",
+			),
+		];
+		if (composer) {
+			composer.input.focused = this.#focused;
+			const lines: NativeChild[] = [
+				text([span(`Topic: ${sanitizeDisplayLine(record?.question ?? "")}`, "dim")], { truncate: "end" }),
+			];
+			if (composer.notice) {
+				lines.push(text([span(composer.notice, this.#followUpPending ? "dim" : "warning")], { wrap: "word" }));
+			}
+			lines.push(composer.input);
+			children.push(node("col", undefined, lines, "composer"));
+		}
+		children.push({ ...this.#describeFooter(record, canFollowUp, copied), key: "footer" });
+		// The sheet is the frame (`nativeOverlay`): a borderless column.
+		const described = col(children, { gap: "md" });
+		this.#native = {
+			records: this.#records,
+			selectedId: this.#selectedId,
+			focus: this.#focus,
+			focused: this.#focused,
+			composer,
+			notice: composer?.notice,
+			followUpPending: this.#followUpPending,
+			canFollowUp,
+			copied,
+			node: described,
+		};
+		return described;
+	}
+
+	handleNativeEvent(event: NativeUiEvent): void {
+		if ((event.type !== "select" && event.type !== "activate") || this.#composer) return;
+		const index = this.#records.findIndex(record => record.id === event.item);
+		if (index === -1) return;
+		this.#select(index);
+		this.#focus = "list";
+		// Enter on a history row opens the follow-up composer.
+		if (event.type === "activate") this.openFollowUp(event.item);
+		this.#options.requestRender();
+	}
+
+	#describeFocusLabel(focus: "list" | "answer"): TspSpan[] {
+		const label = focus === "list" ? `History (${this.#records.length})` : "Details";
+		return this.#focus === focus ? [span(`${theme.nav.cursor} ${label}`, "accent strong")] : [span(label, "muted")];
+	}
+
+	#describeList(): NativeNode {
+		const items = this.#records.map(record => {
+			const status = STATUS[getBtwLatestTurn(record).status];
+			return node(
+				"item",
+				{
+					label: sanitizeDisplayLine(record.question),
+					detail: [span(this.#timeFormat.format(record.createdAt), "dim")],
+					value: [span(status.label, status.color)],
+				},
+				undefined,
+				record.id,
+			);
+		});
+		return node(
+			"list",
+			{
+				selected: this.#selectedId ?? null,
+				empty: [span("No side questions yet. Use /btw QUESTION to start one.", "muted")],
+			},
+			items,
+			"records",
+		);
+	}
+
+	#describeDetail(record: BtwHistoryRecord | undefined, copied: boolean): NativeNode {
+		if (!record)
+			return text([span("No side questions yet. Use /btw QUESTION to start one.", "muted")], { wrap: "word" });
+		const children: NativeChild[] = [];
+		if (copied)
+			children.push(node("text", { spans: [span("✓ Copied to clipboard", "success")] }, undefined, "copied"));
+		const turns = getBtwTurns(record);
+		for (let index = 0; index < turns.length; index++) {
+			if (index > 0) children.push(node("rule", undefined, undefined, `rule-${index}`));
+			children.push(this.#describeTurn(turns[index]!, `turn-${index}`));
+		}
+		return col(children, { gap: "md" });
+	}
+
+	#describeTurn(turn: BtwHistoryTurn, key: string): NativeNode {
+		const status = STATUS[turn.status];
+		const answer = turn.answer.trim()
+			? md(sanitizeDisplayText(turn.answer), { stream: turn.status === "running" })
+			: text([span(turn.status === "running" ? "Waiting for response…" : "No answer text.", "dim")]);
+		const children: NativeChild[] = [
+			text([span(`${status.label} · ${this.#dateFormat.format(turn.createdAt)}`, status.color)], { wrap: "word" }),
+			node("section", { head: [span("Question", "accent strong")] }, [md(sanitizeDisplayText(turn.question))]),
+			node("section", { head: [span("Answer", "accent strong")] }, [answer]),
+		];
+		if (turn.error) children.push(text([span(sanitizeErrorLine(turn.error), "error")], { wrap: "word" }));
+		if (turn.status === "interrupted") children.push(text([span("Not resumed in this view.", "muted")]));
+		return node("col", { gap: "sm" }, children, key);
+	}
+
+	#describeFooter(record: BtwHistoryRecord | undefined, canFollowUp: boolean, copied: boolean): NativeNode {
+		if (this.#composer) {
+			return hintsRow([
+				actionHint("tui.input.submit", this.#followUpPending ? "starting…" : "send"),
+				actionHint("tui.select.cancel", "cancel"),
+			]);
+		}
+		const latest = record ? getBtwLatestTurn(record) : undefined;
+		const hints: (NativeHint | undefined)[] = [
+			actionHint("tui.select.cancel", latest?.status === "running" ? "cancel" : "close"),
+			{ keys: ["tab", "ctrl+/"], label: "switch pane" },
+			actionHint(["tui.select.up", "tui.select.down"], this.#focus === "list" ? "select" : "scroll"),
+		];
+		if (canFollowUp) hints.push({ keys: ["f", "enter"], label: "follow up" });
+		if (record && getBtwCopyText(record) !== undefined) {
+			hints.push({ keys: ["c"], label: copied ? "copy again" : "copy answer" });
+		}
+		return copied ? statusHintsRow([span("✓ copied", "success")], hints) : hintsRow(hints);
+	}
+
 	#renderList(width: number, height: number): readonly string[] {
 		const rowSpan = width < 36 && height >= 2 ? 2 : 1;
 		this.#listHeight = Math.max(1, Math.floor(height / rowSpan));

package/src/overlays/btw-panel.ts

@@ -4,8 +4,11 @@ import { getMarkdownTheme, theme } from "../theme/theme";
 import { sanitizeErrorLine } from "../chrome/error-block";
 import { OverlayPanel } from "../chrome/overlay-box";
 import { StreamingPanelContent } from "../chrome/streaming-panel";
-import { interruptKey } from "../chrome/keybinding-hints";
+import { boundKeys, interruptKey } from "../chrome/keybinding-hints";
 import { formatKeyHint } from "../app-keybindings";
+import type { NativeNode } from "../native/node";
+import { col, md, node, span, text } from "../native/describe";
+import { hintsRow, type NativeHint, statusHintsRow } from "../native/overlay";
 
 type BtwPanelState = "running" | "complete" | "branching" | "aborted" | "error";
 
@@ -27,12 +30,15 @@ export class BtwPanelComponent extends OverlayPanel {
 	#closed = false;
 	#copied = false;
 	#baseTitle: string;
+	readonly #question: string;
 	readonly #content: StreamingPanelContent;
+	#native: { node: NativeNode; canFollowUp: boolean; canBranch: boolean } | undefined;
 
 	constructor(options: BtwPanelComponentOptions) {
 		const baseTitle = `/btw ${replaceTabs(options.question)}`;
-		super(baseTitle);
+		super(baseTitle, "omp.overlay.btw");
 		this.#baseTitle = baseTitle;
+		this.#question = replaceTabs(options.question);
 		this.#tui = options.tui;
 		this.#canBranch = options.canBranch;
 		this.#canFollowUp = options.canFollowUp;
@@ -121,7 +127,67 @@ export class BtwPanelComponent extends OverlayPanel {
 		this.#closed = true;
 	}
 
+	override invalidate(): void {
+		this.#native = undefined;
+		super.invalidate();
+	}
+
+	override describe(): NativeNode {
+		const canFollowUp = this.#canFollowUp?.() ?? false;
+		const canBranch = this.#canBranch?.() ?? this.isBranchable();
+		const memo = this.#native;
+		if (memo && memo.canFollowUp === canFollowUp && memo.canBranch === canBranch) return memo.node;
+		// Inline in the dock, styled as a sheet by role: a borderless column headed by the question.
+		const title = text([span("/btw", "accent"), span(` ${this.#question}`)], { truncate: "end", lines: 1 });
+		const live = this.#state === "running" || this.#state === "branching";
+		const head = node("row", { role: "omp.sheet.head", gap: "sm", align: "center" }, [
+			...(live ? [node("spinner", {})] : []),
+			title,
+		]);
+		const described = col([head, this.#describeBody(), this.#describeFooter(canFollowUp, canBranch)], {
+			role: this.nativeRole,
+			gap: "sm",
+			tone: this.#state === "error" ? "error" : this.#state === "aborted" ? "warning" : undefined,
+		});
+		this.#native = { node: described, canFollowUp, canBranch };
+		return described;
+	}
+
+	#describeBody(): NativeNode {
+		if (this.#state === "error") {
+			return text([span(sanitizeErrorLine(this.#errorMessage ?? "Unknown error"), "error")], { wrap: "word" });
+		}
+		const answer = this.#visibleAnswer;
+		if (answer) return md(answer, { stream: this.#state === "running" });
+		const waiting = this.#state === "running" ? `${theme.status.pending} Waiting for response…` : "No text returned.";
+		return text([span(waiting, "dim")]);
+	}
+
+	#describeFooter(canFollowUp: boolean, canBranch: boolean): NativeNode {
+		const esc: NativeHint = { keys: boundKeys("app.interrupt", ["escape"]).slice(0, 1), label: "to close" };
+		switch (this.#state) {
+			case "running":
+				return hintsRow([{ ...esc, label: "to cancel" }]);
+			case "complete": {
+				const hints: NativeHint[] = [];
+				if (this.isCopyable()) hints.push({ keys: ["c"], label: this.#copied ? "to copy again" : "to copy" });
+				if (canFollowUp) hints.push({ keys: ["f"], label: "to follow up" });
+				if (canBranch) hints.push({ keys: ["b"], label: "to branch" });
+				hints.push(esc);
+				if (!this.#copied) return hintsRow(hints);
+				return statusHintsRow([span("✓ Copied to clipboard", "success")], hints);
+			}
+			case "branching":
+				return text([span(`${theme.status.pending} Branching to chat…`, "muted")]);
+			case "aborted":
+				return statusHintsRow([span(`${theme.status.warning} Cancelled`, "warning")], [esc]);
+			case "error":
+				return statusHintsRow([span(`${theme.status.error} Error`, "error")], [esc]);
+		}
+	}
+
 	#rebuild(): void {
+		this.#native = undefined;
 		this.#content.refresh();
 		// Component-scoped: a rebuild replaces only this panel's own children
 		// (streaming deltas arrive per token, and a full compose would re-walk

package/src/overlays/cleanse-panel.ts

@@ -5,7 +5,13 @@ import { replaceTabs } from "../render/render-utils";
 import { theme } from "../theme/theme";
 import { OverlayPanel } from "../chrome/overlay-box";
 import { StreamingPanelContent, type StreamingPanelPresentation } from "../chrome/streaming-panel";
-import { interruptKey } from "../chrome/keybinding-hints";
+import { boundKeys, interruptKey } from "../chrome/keybinding-hints";
+import type { TspTone } from "@oh-my-pi/pi-wire";
+import type { DescribeContext, NativeNode } from "../native/node";
+import { col, node, span, text } from "../native/describe";
+import { hintsRow, type NativeHint, statusHintsRow } from "../native/overlay";
+import { plainText } from "../native/spans";
+import { isNativeRendering } from "../native/state";
 import type {
 	CleanseBoardModel,
 	CleanseCheckerDescriptor,
@@ -29,12 +35,26 @@ interface CleansePanelComponentOptions {
 /** Terminal state of the run, mirrored into the footer once the core settles. */
 type CleansePanelOutcome = CleansePanelRunStatus | "error";
 
+/** Tone of the finished sheet per outcome. */
+const OUTCOME_TONE: Record<CleansePanelOutcome, TspTone> = {
+	clean: "success",
+	unresolved: "warning",
+	unsupported: "warning",
+	cancelled: "warning",
+	error: "error",
+};
+
 export class CleansePanelComponent extends OverlayPanel {
 	readonly interactive = true;
 
 	readonly #tui: TUI;
 	readonly #model: CleanseBoardModel;
 	readonly #logLines: string[] = [];
+	/** Semantic twins of {@link #logLines}, keyed by a running sequence so scrolled-off entries keep their ids. */
+	readonly #nativeLog: NativeNode[] = [];
+	#logSeq = 0;
+	readonly #request: string | undefined;
+	#native: NativeNode | undefined;
 	#outcome: CleansePanelOutcome | undefined;
 	#errorMessage: string | undefined;
 	#frame = 0;
@@ -43,28 +63,39 @@ export class CleansePanelComponent extends OverlayPanel {
 	readonly #content: StreamingPanelContent;
 
 	constructor(options: CleansePanelComponentOptions) {
-		super(options.request ? `/cleanse ${replaceTabs(options.request)}` : "/cleanse");
+		super(options.request ? `/cleanse ${replaceTabs(options.request)}` : "/cleanse", "omp.overlay.cleanse");
 		this.#tui = options.tui;
 		this.#model = options.model;
+		this.#request = options.request === undefined ? undefined : replaceTabs(options.request);
 		this.#content = new StreamingPanelContent(() => this.#presentation());
 		this.addChild(this.#content);
-		this.#timer = setInterval(() => {
-			this.#frame = (this.#frame + 1) % theme.getSpinnerFrames("activity").length;
-			this.#rebuild();
-		}, SPINNER_INTERVAL_MS);
-		this.#timer.unref?.();
+		// The spinner frame only repaints; a native terminal clocks the described spinners itself.
+		if (!isNativeRendering()) {
+			this.#timer = setInterval(() => {
+				this.#frame = (this.#frame + 1) % theme.getSpinnerFrames("activity").length;
+				this.#rebuild();
+			}, SPINNER_INTERVAL_MS);
+			this.#timer.unref?.();
+		}
 		this.#rebuild();
 	}
 
-	log(text: string): void {
-		this.#logLines.push(text);
-		if (this.#logLines.length > MAX_LOG_LINES) this.#logLines.splice(0, this.#logLines.length - MAX_LOG_LINES);
-		this.#rebuild();
+	log(line: string): void {
+		this.#pushLog(line, text(replaceTabs(line), { wrap: "word" }));
 	}
 
 	/** Permanent line styled as a failure (the core's stderr-equivalent). */
-	logError(text: string): void {
-		this.log(theme.fg("error", text));
+	logError(line: string): void {
+		this.#pushLog(theme.fg("error", line), text([span(replaceTabs(line), "error")], { wrap: "word" }));
+	}
+
+	#pushLog(line: string, described: NativeNode | undefined): void {
+		this.#logLines.push(line);
+		if (this.#logLines.length > MAX_LOG_LINES) this.#logLines.splice(0, this.#logLines.length - MAX_LOG_LINES);
+		const entry = described ?? text(plainText(line), { wrap: "word" });
+		this.#nativeLog.push({ ...entry, key: `log-${this.#logSeq++}` });
+		if (this.#nativeLog.length > MAX_LOG_LINES) this.#nativeLog.splice(0, this.#nativeLog.length - MAX_LOG_LINES);
+		this.#rebuild();
 	}
 
 	phase(text: string | undefined): void {
@@ -78,7 +109,8 @@ export class CleansePanelComponent extends OverlayPanel {
 	}
 
 	checkerFinished(check: CleanseCheckResult, durationMs: number): void {
-		this.log(this.#model.checkerFinished(check, durationMs));
+		const line = this.#model.checkerFinished(check, durationMs);
+		this.#pushLog(line, this.#model.lastSettled);
 	}
 
 	repairFinished(): void {
@@ -93,10 +125,13 @@ export class CleansePanelComponent extends OverlayPanel {
 
 	agentProgress(name: string, progress: AgentProgress): void {
 		this.#model.agentProgress(name, progress);
+		// The ANSI view picks progress up on its next spinner repaint; natively nothing else repaints.
+		if (isNativeRendering()) this.#rebuild();
 	}
 
 	agentFinished(outcome: CleanseAgentOutcome, assignment: CleanseAssignment): void {
-		this.log(this.#model.agentFinished(outcome, assignment));
+		const line = this.#model.agentFinished(outcome, assignment);
+		this.#pushLog(line, this.#model.lastSettled);
 	}
 
 	/** Stop the live area; the panel stays mounted until the user dismisses it. */
@@ -144,7 +179,62 @@ export class CleansePanelComponent extends OverlayPanel {
 		};
 	}
 
+	override invalidate(): void {
+		this.#native = undefined;
+		super.invalidate();
+	}
+
+	override describe(cx: DescribeContext): NativeNode {
+		if (this.#native) return this.#native;
+		// Inline in the dock, styled as a sheet by role: a borderless column headed by the request.
+		const title =
+			this.#request === undefined
+				? [span("/cleanse", "accent")]
+				: [span("/cleanse", "accent"), span(` ${this.#request}`)];
+		const head = node(
+			"row",
+			{ role: "omp.sheet.head", gap: "sm", align: "center" },
+			[...(this.#outcome === undefined ? [node("spinner", {})] : []), text(title, { truncate: "end", lines: 1 })],
+			"head",
+		);
+		const body: NativeNode[] = [head];
+		if (this.#nativeLog.length > 0) body.push(node("col", undefined, [...this.#nativeLog], "log"));
+		const live = this.#liveClosed ? undefined : this.#model.describeLive(cx);
+		if (live) body.push({ ...live, key: "live" });
+		if (this.#errorMessage) {
+			body.push(
+				node("text", { spans: [span(replaceTabs(this.#errorMessage), "error")], wrap: "word" }, undefined, "error"),
+			);
+		}
+		body.push({ ...this.#describeFooter(), key: "footer" });
+		this.#native = col(body, {
+			role: this.nativeRole,
+			gap: "sm",
+			tone: this.#outcome === undefined ? undefined : OUTCOME_TONE[this.#outcome],
+		});
+		return this.#native;
+	}
+
+	#describeFooter(): NativeNode {
+		const esc: NativeHint = { keys: boundKeys("app.interrupt", ["escape"]).slice(0, 1), label: "dismiss" };
+		switch (this.#outcome) {
+			case undefined:
+				return hintsRow([{ ...esc, label: "cancel /cleanse" }]);
+			case "clean":
+				return statusHintsRow([span(`${theme.status.success} Clean`, "success")], [esc]);
+			case "unresolved":
+				return statusHintsRow([span(`${theme.status.warning} Diagnostics remain`, "warning")], [esc]);
+			case "unsupported":
+				return statusHintsRow([span(`${theme.status.warning} No runnable checker`, "warning")], [esc]);
+			case "cancelled":
+				return statusHintsRow([span(`${theme.status.warning} Cancelled`, "warning")], [esc]);
+			case "error":
+				return statusHintsRow([span(`${theme.status.error} Error`, "error")], [esc]);
+		}
+	}
+
 	#rebuild(): void {
+		this.#native = undefined;
 		this.#content.refresh();
 		this.#tui.requestRender();
 	}

package/src/overlays/codex-reset-fireworks.ts

@@ -9,6 +9,11 @@ import {
 } from "../index";
 import { type ThemeColor, theme } from "../theme/theme";
 import { formatKeyHint } from "../app-keybindings";
+import type { TspSpan } from "@oh-my-pi/pi-wire";
+import type { NativeNode, NativeUiEvent } from "../native/node";
+import { col, node, span, text } from "../native/describe";
+import { actionBar, actionButton } from "../native/overlay";
+import { isNativeRendering } from "../native/state";
 
 const FRAME_INTERVAL_MS = 85;
 const FRAME_COUNT = 34;
@@ -256,6 +261,40 @@ function drawBurst(
 	if (age <= 2) setCell(canvas, centerX, centerY, age === 0 ? "@" : "+", "white", 12);
 }
 
+/**
+ * The celebration for a TSP terminal: the banner's title as a terminal-clocked
+ * shimmer between pulsing sparks, over the event's subtitle. The particle sky
+ * is ANSI-only art.
+ */
+function describeCodexResetFireworks(event: CodexResetFireworksEvent): NativeNode {
+	const title = event.kind === "unscheduled-weekly-reset" ? "OpenAI reset" : "Saved reset";
+	const subtitle =
+		event.kind === "unscheduled-weekly-reset"
+			? "Weekly usage cleared early"
+			: event.added === 1
+				? `New reset banked · ${event.available} available`
+				: `${event.added} resets banked · ${event.available} available`;
+	const spark = (glyph: string, color: FireworkColor): TspSpan =>
+		span(glyph, FIREWORK_THEME_COLORS[color], { fx: "pulse" });
+	// The sheet is the frame (Tern bursts confetti from the pane's top edge for this role).
+	return col(
+		[
+			text([spark("✦ ", "pink"), spark("✧ ", "cyan"), spark("✦", "gold")]),
+			node("shimmer", {
+				text: title,
+				palette: {
+					low: FIREWORK_THEME_COLORS.violet,
+					mid: FIREWORK_THEME_COLORS.gold,
+					high: FIREWORK_THEME_COLORS.white,
+				},
+			}),
+			text([span(subtitle, FIREWORK_THEME_COLORS.cyan)]),
+			actionBar([null, actionButton("Close", "close", { keys: "escape" })]),
+		],
+		{ align: "center", gap: "sm" },
+	);
+}
+
 function renderCanvas(canvas: Array<Array<CanvasCell | undefined>>): string[] {
 	return canvas.map(row => {
 		let output = "";
@@ -300,6 +339,7 @@ class CodexResetFireworksComponent implements Component {
 	#done = Promise.withResolvers<void>();
 	#frame = 0;
 	#disposed = false;
+	#native: NativeNode | undefined;
 
 	constructor(
 		readonly host: CodexResetFireworksHost,
@@ -307,11 +347,14 @@ class CodexResetFireworksComponent implements Component {
 	) {}
 
 	run(): Promise<void> {
-		this.#timer ??= setInterval(() => {
-			if (this.#disposed) return;
-			this.#frame = (this.#frame + 1) % FRAME_COUNT;
-			this.host.ui.requestRender();
-		}, FRAME_INTERVAL_MS);
+		// Frames only repaint the particle sky; a native terminal clocks the described shimmer.
+		if (!isNativeRendering()) {
+			this.#timer ??= setInterval(() => {
+				if (this.#disposed) return;
+				this.#frame = (this.#frame + 1) % FRAME_COUNT;
+				this.host.ui.requestRender();
+			}, FRAME_INTERVAL_MS);
+		}
 		this.host.ui.requestRender();
 		return this.#done.promise;
 	}
@@ -330,6 +373,23 @@ class CodexResetFireworksComponent implements Component {
 		if (matchesKey(data, "escape") || matchesKey(data, "esc")) this.#done.resolve();
 	}
 
+	/** Close runs what Esc runs. */
+	handleNativeEvent(event: NativeUiEvent): void {
+		if (event.type === "action" && event.act === "close") this.#done.resolve();
+	}
+
+	/** A glass sheet at the pane's top edge. */
+	readonly nativeOverlay = { role: "omp.overlay.fireworks", anchor: "top", size: "md" } as const;
+
+	invalidate(): void {
+		this.#native = undefined;
+	}
+
+	describe(): NativeNode {
+		this.#native ??= describeCodexResetFireworks(this.event);
+		return this.#native;
+	}
+
 	render(width: number): readonly string[] {
 		const height = Math.max(1, Math.floor(this.host.ui.terminal.rows * 0.33));
 		return renderCodexResetFireworks(width, height, this.#frame, this.event);

package/src/overlays/composer-shape-preview.ts

@@ -17,8 +17,10 @@ import {
 	truncateToWidth,
 	visibleWidth,
 } from "../index";
-import type { ComposerShape } from "./composer-shape-registry";
+import { type ComposerShape, getComposerShapeOptions } from "./composer-shape-registry";
 import { theme } from "../theme/theme";
+import type { NativeNode } from "../native/node";
+import { col, node, span, text } from "../native/describe";
 
 /**
  * Real status renderer the preview borrows rows from — structurally satisfied
@@ -120,6 +122,7 @@ export function renderComposerShapePreview(
 export class ComposerShapePreview implements Component {
 	#shape: ComposerShape;
 	#options: ComposerShapePreviewOptions;
+	#native: { shape: ComposerShape; node: NativeNode } | undefined;
 
 	constructor(initialValue: ComposerShape = "band", options: ComposerShapePreviewOptions = {}) {
 		this.#shape = initialValue;
@@ -132,6 +135,28 @@ export class ComposerShapePreview implements Component {
 		this.#options.requestRender?.();
 	}
 
+	/**
+	 * A TSP terminal draws the composer itself, so the shape's glyph chrome has
+	 * no native twin: the preview names the shape over a read-only prompt.
+	 */
+	describe(): NativeNode {
+		const memo = this.#native;
+		if (memo?.shape === this.#shape) return memo.node;
+		const option = getComposerShapeOptions().find(candidate => candidate.value === this.#shape);
+		const caption = [span(option?.label ?? this.#shape, "strong")];
+		if (option?.description) caption.push(span(` · ${option.description}`, "muted"));
+		const described = col(
+			[
+				text([span("Preview:", "muted")]),
+				node("editor", { placeholder: "Ask anything, edit files, run tools", readonly: true, maxLines: 1 }),
+				text(caption, { wrap: "word" }),
+			],
+			{ role: "omp.preview.composer-shape", gap: "xs" },
+		);
+		this.#native = { shape: this.#shape, node: described };
+		return described;
+	}
+
 	render(width: number): readonly string[] {
 		const lines = renderComposerShapePreview(this.#shape, width, this.#options.status);
 		return ["", theme.fg("muted", "Preview:"), ...lines];