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

package/src/chrome/message-frame.ts

@@ -14,7 +14,11 @@ import { Markdown } from "../components/markdown";
 import { Spacer } from "../components/spacer";
 import { Text } from "../components/text";
 import { type Component, Container } from "../tui";
-import { getMarkdownTheme, type Theme, type ThemeColor, theme } from "../theme/index";
+import { getMarkdownTheme, getThemeEpoch, type Theme, type ThemeColor, theme } from "../theme/index";
+import { card, col, md, span } from "../native/describe";
+import { type NativeNode, type NativeUiEvent, rootToggleExpanded } from "../native/node";
+import { Memo } from "../native/memo";
+import { colorTone } from "../native/tone";
 /** Message shape consumed by the shared frame. */
 export interface FramedMessage {
 	customType: string;
@@ -44,6 +48,8 @@ export interface FramedMessageOptions<M extends FramedMessage> {
 	/** Collapse the markdown body to this many lines when `expanded` is false. Omit to never collapse. */
 	readonly collapseAfterLines?: number;
 	readonly customRenderer?: FramedRenderer<M>;
+	/** Semantic role of the native card. */
+	readonly role: string;
 }
 
 /**
@@ -57,6 +63,8 @@ export class FramedMessageComponent<M extends FramedMessage> extends Container {
 	#customComponent: Component | undefined;
 	#expanded = false;
 	#disposed = false;
+	#version = 0;
+	readonly #native = new Memo();
 
 	constructor(options: FramedMessageOptions<M>) {
 		super();
@@ -86,8 +94,51 @@ export class FramedMessageComponent<M extends FramedMessage> extends Container {
 		this.#customComponent = undefined;
 	}
 
+	/**
+	 * The extension renderer's component when it supplied one; otherwise a
+	 * card with the type tag as its head and the markdown body, clamped by the
+	 * terminal while collapsed.
+	 */
+	override describe(): NativeNode {
+		const key = [this.#version, this.#expanded, getThemeEpoch()];
+		return this.#native.get(key, () => {
+			if (this.#customComponent) return col([this.#customComponent], { role: this.#options.role });
+			const hideHeader =
+				typeof this.#options.hideHeader === "function" ? this.#options.hideHeader() : this.#options.hideHeader;
+			// The role icon (Tern's named icon) replaces the nerd glyph.
+			const tag = this.#options.message.customType;
+			const collapseAfterLines = this.#options.collapseAfterLines;
+			return card(
+				{
+					role: this.#options.role,
+					tone: colorTone(this.#options.borderColor),
+					head: hideHeader ? undefined : [span(tag, "customMessageLabel strong")],
+					collapsible: collapseAfterLines !== undefined,
+					collapsed: collapseAfterLines !== undefined ? !this.#expanded : undefined,
+					preview: collapseAfterLines !== undefined ? { lines: collapseAfterLines } : undefined,
+				},
+				[md(this.#messageText())],
+			);
+		});
+	}
+
+	handleNativeEvent(event: NativeUiEvent): void {
+		const expanded = rootToggleExpanded(event);
+		if (expanded !== undefined) this.setExpanded(expanded);
+	}
+
+	#messageText(): string {
+		const content = this.#options.message.content;
+		if (typeof content === "string") return content;
+		return content
+			.filter((part): part is TextContent => part.type === "text")
+			.map(part => part.text)
+			.join("\n");
+	}
+
 	#rebuild(): void {
 		if (this.#disposed) return;
+		this.#version++;
 		let nextCustomComponent: Component | undefined;
 		const customRenderer = this.#options.customRenderer;
 		if (customRenderer) {
@@ -138,15 +189,7 @@ export class FramedMessageComponent<M extends FramedMessage> extends Container {
 			this.#box.addChild(new Spacer(1));
 		}
 
-		let text: string;
-		if (typeof this.#options.message.content === "string") {
-			text = this.#options.message.content;
-		} else {
-			text = this.#options.message.content
-				.filter((content): content is TextContent => content.type === "text")
-				.map(content => content.text)
-				.join("\n");
-		}
+		let text = this.#messageText();
 
 		const collapseAfterLines = this.#options.collapseAfterLines;
 		if (!this.#expanded && collapseAfterLines !== undefined) {

package/src/chrome/message-notice.ts

@@ -1,8 +1,13 @@
 import { Box } from "../components/box";
 import { Spacer } from "../components/spacer";
 import { Text } from "../components/text";
+import type { TspPreview, TspText } from "@oh-my-pi/pi-wire";
 import { type Component, Container } from "../tui";
 import { type ThemeColor, theme } from "../theme";
+import { card, node, text, withHidden } from "../native/describe";
+import { type NativeChild, type NativeNode, type NativeUiEvent, rootToggleExpanded } from "../native/node";
+import { Memo } from "../native/memo";
+import { colorTone } from "../native/tone";
 
 const NO_LINES: readonly string[] = [];
 
@@ -18,6 +23,19 @@ export interface MessageNoticePresentation {
 	readonly body?: Component | readonly Component[];
 }
 
+/** Semantic notice content for native terminals: the card head and body, never pre-styled rows. */
+export interface MessageNoticeNativePresentation {
+	readonly head: TspText;
+	readonly body?: readonly NativeChild[];
+	/** Body clamp while collapsed; set to make the notice collapsible. */
+	readonly preview?: TspPreview;
+	/**
+	 * Draw as an inline notice (a named icon and one line, the body a
+	 * disclosure below it) instead of a toned card.
+	 */
+	readonly inline?: { readonly icon: string };
+}
+
 function isComponentList(value: Component | readonly Component[]): value is readonly Component[] {
 	return Array.isArray(value);
 }
@@ -25,6 +43,10 @@ function isComponentList(value: Component | readonly Component[]): value is read
 /** Presentation policy for a transcript notice. */
 export interface MessageNoticeOptions {
 	readonly presentation: (context: MessageNoticeContext) => MessageNoticePresentation;
+	/** Card content for native terminals; the full content, since collapse is the terminal's. */
+	readonly nativePresentation: () => MessageNoticeNativePresentation;
+	/** Semantic role of the native card (`omp.notice.<name>`). */
+	readonly role: string;
 	readonly severity?: ThemeColor;
 	readonly background?: (text: string) => string;
 	readonly leadingSpace?: boolean;
@@ -39,6 +61,8 @@ export class MessageNoticeComponent extends Container {
 	readonly #box: Box;
 	#expanded = false;
 	#toolActivityVisible = true;
+	#version = 0;
+	readonly #native = new Memo();
 
 	constructor(options: MessageNoticeOptions) {
 		super();
@@ -69,6 +93,7 @@ export class MessageNoticeComponent extends Container {
 
 	/** Rebuild the presentation after controller-owned state changes. */
 	refresh(): void {
+		this.#version++;
 		for (const child of this.#box.children) child.dispose?.();
 		this.#box.clear();
 		const presentation = this.#options.presentation({ expanded: this.#expanded });
@@ -100,4 +125,50 @@ export class MessageNoticeComponent extends Container {
 		if (!this.#toolActivityVisible) return NO_LINES;
 		return super.render(width);
 	}
+
+	/** A severity-toned card; collapse is local to the terminal and mirrored through {@link handleNativeEvent}. */
+	override describe(): NativeNode {
+		const key = [this.#version, this.#expanded, this.#toolActivityVisible];
+		return this.#native.get(key, () => {
+			const presentation = this.#options.nativePresentation();
+			if (presentation.inline) {
+				const body = presentation.body ?? [];
+				const head = node(
+					"row",
+					{ gap: "sm" },
+					[node("icon", { name: presentation.inline.icon }), text(presentation.head, { truncate: "end" })],
+					"head",
+				);
+				const notice = node(
+					"section",
+					{
+						role: this.#options.role,
+						tone: colorTone(this.#options.severity ?? "warning"),
+						collapsible: body.length > 0,
+						collapsed: body.length > 0 ? !this.#expanded : undefined,
+					},
+					[head, ...body],
+				);
+				return withHidden(notice, !this.#toolActivityVisible);
+			}
+			const collapsible = presentation.preview !== undefined;
+			const notice = card(
+				{
+					role: this.#options.role,
+					tone: colorTone(this.#options.severity ?? "warning"),
+					head: presentation.head,
+					collapsible,
+					collapsed: collapsible ? !this.#expanded : undefined,
+					preview: presentation.preview,
+				},
+				presentation.body ?? [],
+			);
+			return withHidden(notice, !this.#toolActivityVisible);
+		});
+	}
+
+	handleNativeEvent(event: NativeUiEvent): void {
+		const expanded = rootToggleExpanded(event);
+		if (expanded !== undefined) this.setExpanded(expanded);
+	}
 }

package/src/chrome/overlay-box.ts

@@ -6,6 +6,9 @@
  * (rounded corners, sharp tee/cross junctions) and the `border`/`accent` theme
  * colors so all outlined overlays read identically.
  */
+import type { DescribeContext, NativeChild, NativeNode } from "../native/node";
+import { node } from "../native/describe";
+import { overlayCard } from "../native/overlay";
 import { type Component, visibleWidth } from "../tui";
 import { Ellipsis, truncateToWidth } from "../utils";
 import { padToWidth } from "../render/utils";
@@ -169,11 +172,23 @@ export class PanelRows implements Component {
 	}
 }
 
-/** Sentinel child rendered by {@link OverlayPanel} as a `├───┤` section rule. */
+const RULE_NODE: NativeNode = node("rule");
+
+/** Sentinel child rendered by {@link OverlayPanel} as a `├───┤` section rule (a `rule` natively). */
 export class PanelDivider implements Component {
 	render(): readonly string[] {
 		return NO_LINES;
 	}
+
+	describe(): NativeNode {
+		return RULE_NODE;
+	}
+}
+
+interface OverlayPanelNativeMemo {
+	title: string;
+	children: readonly Component[];
+	node: NativeNode;
 }
 
 interface OverlayPanelMemo {
@@ -195,14 +210,26 @@ function collapseTitle(title: string): string {
  * so inline overlays share the chrome of fullscreen overlays. The top border
  * is exactly one row — `routeMouse` offsets written for a one-line top rule
  * stay valid — and content is inset two columns on each side.
+ *
+ * Natively the panel is a root `card` (`head` = title, `role` =
+ * `omp.overlay.<name>`) over its children; the frame is the terminal's.
+ * Subclasses whose body is not a plain child list override `describe`.
  */
 export class OverlayPanel implements Component {
 	children: Component[] = [];
 	#title: string;
+	readonly #role: string;
 	#memo: OverlayPanelMemo | undefined;
+	#nativeMemo: OverlayPanelNativeMemo | undefined;
 
-	constructor(title = "") {
+	constructor(title = "", role = "omp.overlay") {
 		this.#title = collapseTitle(title);
+		this.#role = role;
+	}
+
+	/** The `role` of the panel's native root card. */
+	get nativeRole(): string {
+		return this.#role;
 	}
 
 	get title(): string {
@@ -263,6 +290,22 @@ export class OverlayPanel implements Component {
 		return result;
 	}
 
+	describe(_cx: DescribeContext): NativeNode | null {
+		const memo = this.#nativeMemo;
+		if (
+			memo !== undefined &&
+			memo.title === this.#title &&
+			memo.children.length === this.children.length &&
+			this.children.every((child, i) => memo.children[i] === child)
+		) {
+			return memo.node;
+		}
+		const children: NativeChild[] = [...this.children];
+		const result = overlayCard(this.#role, this.#title, children);
+		this.#nativeMemo = { title: this.#title, children: [...this.children], node: result };
+		return result;
+	}
+
 	render(width: number): readonly string[] {
 		width = Number.isFinite(width) ? Math.max(0, Math.trunc(width)) : 0;
 		const innerWidth = Math.max(1, width - 4);

package/src/chrome/qrcode.ts

@@ -510,6 +510,34 @@ export interface QrRenderOptions {
 const ANSI_RESET = "\x1b[0m";
 const ANSI_QR_ROW_PREFIX = "\x1b[47m\x1b[30m"; // white background, black foreground
 
+/**
+ * Render a QR symbol as plain half-block rows (no escapes) for a terminal that
+ * draws text in its own foreground color. `inkLight` draws the *light*
+ * modules (quiet zone included) as ink: on a dark background with a light
+ * foreground that yields the dark-on-light symbol cameras expect.
+ */
+export function renderQrText(qr: QrCode, inkLight: boolean, options?: QrRenderOptions): string[] {
+	const margin = Math.max(0, options?.margin ?? 4);
+	const dim = qr.size + margin * 2;
+	const ink = (gx: number, gy: number): boolean => {
+		const x = gx - margin;
+		const y = gy - margin;
+		const dark = x >= 0 && x < qr.size && y >= 0 && y < qr.size && qr.module(x, y);
+		return gy < dim && dark !== inkLight;
+	};
+	const lines: string[] = [];
+	for (let gy = 0; gy < dim; gy += 2) {
+		let row = "";
+		for (let gx = 0; gx < dim; gx++) {
+			const top = ink(gx, gy);
+			const bottom = ink(gx, gy + 1);
+			row += top ? (bottom ? "█" : "▀") : bottom ? "▄" : " ";
+		}
+		lines.push(row);
+	}
+	return lines;
+}
+
 /**
  * Render a QR symbol as ANSI half-block rows: each text row packs two module
  * rows via `▀`/`▄`/`█`, drawn black-on-white so a phone camera reads dark

package/src/chrome/segment-track.ts

@@ -10,6 +10,8 @@
  */
 import { type ThemeColor, theme } from "../theme/index";
 import { BG_RESET, FG_RESET } from "../theme/color";
+import type { NativeNode } from "../native/node";
+import { node, row } from "../native/describe";
 export interface TrackSegment {
 	label: string;
 }
@@ -52,6 +54,30 @@ export function resolveSegmentPalette(count: number): ThemeColor[] {
 	return palette;
 }
 
+/**
+ * Native {@link renderSegmentTrack}: a row of position-colored labels, the
+ * active one roled `omp.track.active` so the terminal fills it as a chip in
+ * its own color. No caps or separators travel; the terminal draws them.
+ */
+export function describeSegmentTrack(segments: readonly TrackSegment[], activeIndex: number): NativeNode {
+	const palette = resolveSegmentPalette(segments.length);
+	return row(
+		segments.map((segment, index) =>
+			node(
+				"text",
+				{
+					spans: [{ t: segment.label, s: palette[index % palette.length] }],
+					wrap: "none",
+					role: index === activeIndex ? "omp.track.active" : "omp.track.item",
+				},
+				undefined,
+				`${index}`,
+			),
+		),
+		{ gap: "sm", align: "center", role: "omp.track" },
+	);
+}
+
 /**
  * Render `segments` as a colored chip track with `activeIndex` filled. Returns
  * a single line of styled text with no surrounding caption or arrows — callers

package/src/chrome/selector-helpers.ts

@@ -6,7 +6,7 @@
  * replace.
  */
 import { centeredViewportRange, scrollOffsetForRow, viewportOverflows } from "../components/scroll-viewport";
-import { extractPrintableText, matchesKey } from "../keys";
+import { matchesKey } from "../keys";
 import { ScrollView } from "../components/scroll-view";
 import { theme } from "../theme/index";
 /**
@@ -72,22 +72,6 @@ export function clampSelection(
 	return { selectedIndex: selected, scrollOffset: scroll };
 }
 
-/**
- * Classify a key event for search-query text entry. Returns the single
- * printable character to append to the query, or `null` when the key is not a
- * searchable character: non-printable or multi-byte.
- */
-export function searchableChar(data: string): string | null {
-	const printableText = extractPrintableText(data);
-	if (printableText && printableText.length === 1) {
-		const printableCharCode = printableText.charCodeAt(0);
-		if (printableCharCode > 32 && printableCharCode < 127) {
-			return printableText;
-		}
-	}
-	return null;
-}
-
 /**
  * Handle the shared tab-cycling keys: Tab/Right advance to the next tab,
  * Shift+Tab/Left to the previous. Invokes `switchTab` with the direction and

package/src/chrome/status-notice.ts

@@ -0,0 +1,46 @@
+import { Spacer } from "../components/spacer";
+import { Text } from "../components/text";
+import { node } from "../native/describe";
+import type { NativeNode } from "../native/node";
+import { styledSpans } from "../native/spans";
+import { Container } from "../tui";
+
+/** How long a native status toast stays up (ms). */
+const TOAST_TTL = 2400;
+
+/**
+ * A transient status notice (`showStatus`: "Thinking blocks: hidden", "Copied
+ * to clipboard"). The ANSI render appends a blank row and the dim line to the
+ * transcript; a native terminal shows it as a toast instead, so notices never
+ * pile up in the history. Updating the text re-shows the toast.
+ */
+export class StatusNotice extends Container {
+	readonly #text: Text;
+	#message: string;
+	#native: NativeNode | undefined;
+
+	constructor(message: string, styleFn?: (text: string) => string) {
+		super();
+		this.#message = message;
+		this.#text = new Text(message, 1, 0).setStyleFn(styleFn);
+		this.addChild(new Spacer(1));
+		this.addChild(this.#text);
+	}
+
+	setMessage(message: string, styleFn?: (text: string) => string): void {
+		this.#text.setStyleFn(styleFn);
+		this.#text.setText(message);
+		if (message !== this.#message) this.#native = undefined;
+		this.#message = message;
+	}
+
+	override describe(): NativeNode {
+		if (this.#native) return this.#native;
+		// Callers may pass pre-styled text; a toast takes plain text.
+		const plain = styledSpans(this.#message)
+			.map(run => run.t)
+			.join("");
+		this.#native = node("toast", { text: plain, ttl: TOAST_TTL, role: "omp.toast.status" });
+		return this.#native;
+	}
+}

package/src/chrome/streaming-panel.ts

@@ -1,6 +1,9 @@
 import { Spacer } from "../components/spacer";
 import { Text } from "../components/text";
 import { type Component, Container } from "../tui";
+import { col, span, text } from "../native/describe";
+import type { NativeChild, NativeNode } from "../native/node";
+import { plainText } from "../native/spans";
 
 /** One refresh of a streaming overlay's presentation. */
 export interface StreamingPanelPresentation {
@@ -18,11 +21,21 @@ class StreamingPanelFooter implements Component {
 	readonly #line: string | (() => string);
 	#renderedLine: string | undefined;
 	#text: Text | undefined;
+	#native: { line: string; node: NativeNode } | undefined;
 
 	constructor(line: string | (() => string)) {
 		this.#line = line;
 	}
 
+	/** The footer line as muted text, re-read each describe because action availability can change. */
+	describe(): NativeNode {
+		const line = plainText(typeof this.#line === "function" ? this.#line() : this.#line);
+		if (this.#native?.line !== line) {
+			this.#native = { line, node: text([span(line, "muted")], { wrap: "word", role: "omp.panel.footer" }) };
+		}
+		return this.#native.node;
+	}
+
 	render(width: number): readonly string[] {
 		const line = typeof this.#line === "function" ? this.#line() : this.#line;
 		if (!this.#text || line !== this.#renderedLine) {
@@ -44,6 +57,7 @@ class StreamingPanelFooter implements Component {
  */
 export class StreamingPanelContent extends Container {
 	readonly #presentation: () => StreamingPanelPresentation;
+	#native: NativeNode = col([]);
 
 	constructor(presentation: () => StreamingPanelPresentation) {
 		super();
@@ -56,14 +70,24 @@ export class StreamingPanelContent extends Container {
 		this.disposeChildren();
 		this.addChild(new Spacer(1));
 		const presentation = this.#presentation();
+		const sections: NativeChild[] = [];
 		for (const section of presentation.sections) {
 			if (!section) continue;
 			const children = isComponentList(section) ? section : [section];
 			if (children.length === 0) continue;
 			for (const child of children) this.addChild(child);
 			this.addChild(new Spacer(1));
+			sections.push(col(children));
 		}
-		this.addChild(new StreamingPanelFooter(presentation.footer));
+		const footer = new StreamingPanelFooter(presentation.footer);
+		this.addChild(footer);
+		sections.push(footer);
+		this.#native = col(sections, { gap: "sm" });
+	}
+
+	/** The sections as a spaced stack followed by the footer; spacing is the terminal's. */
+	override describe(): NativeNode {
+		return this.#native;
 	}
 
 	override invalidate(): void {

package/src/chrome/tool-activity.ts

@@ -1,4 +1,6 @@
 import { type Component, Container } from "../tui";
+import { col } from "../native/describe";
+import type { NativeNode } from "../native/node";
 export interface ToolActivityComponent {
 	setToolActivityVisible(visible: boolean): void;
 }
@@ -9,6 +11,7 @@ export function isToolActivityComponent(component: Component): component is Comp
 
 export class ToolActivityContainer extends Container implements ToolActivityComponent {
 	#visible = true;
+	#native: { children: readonly Component[]; visible: boolean; node: NativeNode } | undefined;
 
 	constructor(component: Component | Component[]) {
 		super();
@@ -41,4 +44,21 @@ export class ToolActivityContainer extends Container implements ToolActivityComp
 		if (!this.#visible) return [];
 		return super.render(width);
 	}
+
+	/** The wrapped children; hidden tool activity stays mounted so toggling it is one prop change. */
+	override describe(): NativeNode {
+		const cached = this.#native;
+		const children = this.children;
+		if (
+			cached?.visible === this.#visible &&
+			cached.children.length === children.length &&
+			cached.children.every((child, index) => child === children[index])
+		) {
+			return cached.node;
+		}
+		const snapshot = children.slice();
+		const node = col(snapshot, this.#visible ? { role: "omp.activity" } : { role: "omp.activity", hidden: true });
+		this.#native = { children: snapshot, visible: this.#visible, node };
+		return node;
+	}
 }