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

package/dist/types/components/tree-view.d.ts

@@ -1,3 +1,4 @@
+import type { DescribeContext, NativeNode } from "../native/node.js";
 import type { Theme } from "../theme/theme.js";
 import type { Component } from "../tui.js";
 import { type ScrollViewTheme } from "./scroll-view.js";
@@ -125,6 +126,14 @@ export declare class TreeView<T, K extends TreeKey = string> implements Componen
     /** Move to the next row in `direction` satisfying a domain predicate. */
     moveSelectionWhere(predicate: (item: T, row: TreeRow<T, K>) => boolean, direction: -1 | 1): void;
     render(width: number): readonly string[];
+    /**
+     * A native disclosure `tree` over the filtered rows, nested by hierarchy
+     * (a filtered-out ancestor lifts its visible descendants to the nearest
+     * visible one). Gutters, windowing and the scrollbar are the terminal's;
+     * the selected row is marked with the `mark` token. Rows whose body is a
+     * component can't be tree labels, so such a tree stays on `rows`.
+     */
+    describe(_cx: DescribeContext): NativeNode | null;
     /** Render lines plus budget/window metadata for adapters that append an ellipsis. */
     renderWithState(width: number): TreeViewRenderResult;
 }

package/dist/types/components/truncated-text.d.ts

@@ -1,3 +1,4 @@
+import type { DescribeContext, NativeNode } from "../native/node.js";
 import type { Component } from "../tui.js";
 /**
  * Text component that truncates to fit viewport width
@@ -8,5 +9,7 @@ export declare class TruncatedText implements Component {
     /** Return bounded source text and the last-known truncation state. */
     debugState(): Record<string, unknown>;
     invalidate(): void;
+    /** First line only, clamped to one visual line with an end ellipsis. */
+    describe(_cx: DescribeContext): NativeNode;
     render(width: number): readonly string[];
 }

package/dist/types/components/wizard-step.d.ts

@@ -1,4 +1,5 @@
 import type { MouseRoutable, SgrMouseEvent } from "../mouse.js";
+import type { DescribeContext, NativeNode } from "../native/node.js";
 import type { Component } from "../tui.js";
 /** Semantic role of a wizard step's primary interactive content. */
 export type WizardStepKind = "input" | "choice" | "confirm" | "async" | "custom";
@@ -56,5 +57,10 @@ export declare class WizardStep implements Component, MouseRoutable {
     dispose(): void;
     handleInput(data: string): void;
     routeMouse(event: SgrMouseEvent, line: number, col: number): void;
+    /**
+     * The slots in order as a spaced `col`; the height budget and optional
+     * preview collapse are the terminal's (it scrolls instead of clipping).
+     */
+    describe(_cx: DescribeContext): NativeNode;
     render(width: number): readonly string[];
 }

package/dist/types/hotkeys-markdown.d.ts

@@ -1,7 +1,31 @@
 import { type KeybindingsManager } from "./app-keybindings.js";
+import type { NativeNode, NativeUiEvent } from "./native/node.js";
+import type { Component } from "./tui.js";
 /** Effective keybinding operations used to render the hotkey reference. */
 export interface HotkeysMarkdownBindings {
     keybindings: Pick<KeybindingsManager, "getDisplayString" | "getKeys" | "matchesCanonical">;
 }
 /** Build the platform-aware Markdown reference for effective application hotkeys. */
 export declare function buildHotkeysMarkdown(bindings: HotkeysMarkdownBindings): string;
+/**
+ * `/hotkeys` under a native terminal: a large sheet "Keyboard shortcuts" with
+ * one section per group, each a two-column table whose key cells carry `key`
+ * spans (Tern draws them as keycaps). Esc (or Close) dismisses it. Terminals
+ * without the native surface get the transcript markdown panel instead.
+ */
+export declare class HotkeysSheetComponent implements Component {
+    #private;
+    readonly nativeOverlay: {
+        readonly role: "omp.overlay.hotkeys";
+        readonly size: "lg";
+        readonly head: "Keyboard shortcuts";
+    };
+    constructor(bindings: HotkeysMarkdownBindings, onClose: () => void);
+    describe(): NativeNode;
+    /** The markdown reference, for a terminal that falls back to rows. */
+    render(width: number): readonly string[];
+    invalidate(): void;
+    handleInput(data: string): void;
+    /** Close runs what Esc runs. */
+    handleNativeEvent(event: NativeUiEvent): void;
+}

package/dist/types/index.d.ts

@@ -42,6 +42,11 @@ export * from "./kitty-graphics.js";
 export * from "./latex-block.js";
 export * from "./latex-to-unicode.js";
 export * from "./mouse.js";
+export * from "./native/blobs.js";
+export * from "./native/describe.js";
+export type * from "./native/node.js";
+export * from "./native/settle.js";
+export * from "./native/state.js";
 export * from "./stdin-buffer.js";
 export type * from "./symbols.js";
 export * from "./terminal.js";

package/dist/types/latex-block.d.ts

@@ -1,3 +1,10 @@
+import type { NativeNode } from "./native/node.js";
+/**
+ * The native form of {@link latexToBlock}: the TeX source as a `math` node
+ * the terminal typesets (display style by default, `display: false` for
+ * inline `$…$` math).
+ */
+export declare function describeLatex(src: string, display?: boolean): NativeNode;
 /**
  * Render a display LaTeX math fragment to lines with full 2-D layout: stacked
  * fractions, stretchy delimiters, matrix grids, operator limits, drawn

package/dist/types/native/apply.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Reference document applier: applies TSP frames to a node tree the way the
+ * spec says the terminal does (§5.1). Ops are validated and applied one by
+ * one; a rejected op is reported and skipped without affecting the rest of
+ * the frame. `settle` is recorded as a hint and never restricts later ops.
+ *
+ * Used by tests, the debug server's `doc` op, and the TSP test harness.
+ */
+import { type TspFrame, type TspNode } from "@oh-my-pi/pi-wire";
+/** One rejected op. */
+export interface TspApplyError {
+    /** Frame sequence number. */
+    s: number;
+    /** Op index inside the frame. */
+    op: number;
+    msg: string;
+}
+/** A surface document: the root (id = surface id) plus an id index. */
+export declare class TspDocument {
+    #private;
+    readonly surface: string;
+    constructor(surface: string);
+    /** Currently focused node id. */
+    get focus(): string | null;
+    get suspended(): boolean;
+    /** Ids that received a `settle` hint and no later op. */
+    get settled(): ReadonlySet<string>;
+    /** Number of nodes, including the root. */
+    get size(): number;
+    has(id: string): boolean;
+    /** `x keep:true`: drop the live-only regions (`dock`, `layer`) and focus; `main` stays. */
+    close(): void;
+    /** Apply a frame op by op; returns the rejected ops. */
+    applyFrame(frame: TspFrame): TspApplyError[];
+    /** Snapshot of the whole document (root included) as wire nodes. */
+    snapshot(): TspNode;
+    /** Snapshot of one subtree, or undefined for an unknown id. */
+    get(id: string): TspNode | undefined;
+}

package/dist/types/native/backend.d.ts

@@ -0,0 +1,94 @@
+import { type TspFrame, type TspNode } from "@oh-my-pi/pi-wire";
+import type { Terminal } from "../terminal.js";
+import type { Component, OverlayOptions } from "../tui.js";
+import { type TspHello } from "./encode.js";
+import type { DescribeContext, NativeSurface } from "./node.js";
+/** A visible TUI overlay, bottom to top. */
+export interface NativeOverlay {
+    readonly component: Component;
+    readonly options: OverlayOptions | undefined;
+    /** Keyboard focus is inside this overlay. */
+    readonly focused: boolean;
+}
+/** What the backend needs from the TUI. */
+export interface NativeHost {
+    readonly terminal: Terminal;
+    /** `main`/`dock` content: the frame provider's surface, or the TUI children. */
+    describeSurface(cx: DescribeContext): NativeSurface;
+    /** Visible overlays, bottom to top. */
+    overlays(): readonly NativeOverlay[];
+    /** Component receiving keyboard input. */
+    focused(): Component | null;
+    requestRender(): void;
+    /** The terminal switched appearance. */
+    appearanceChanged(dark: boolean): void;
+    /** Reduce Motion toggled. */
+    motionChanged(reduce: boolean): void;
+    /** Theme-derived output changed (symbol preset): drop render and describe caches. */
+    invalidate(): void;
+}
+export interface NativeBackendOptions {
+    /** Keep the reference document and recent frames for debugging. */
+    readonly mirror?: boolean;
+    /** Append every TSP message to this JSONL file. Defaults to `PI_TUI_TSP_RECORD`. */
+    readonly recordPath?: string;
+    /** Log the `rows` fallback count per frame. Defaults to `PI_TUI_NATIVE_STATS=1`. */
+    readonly stats?: boolean;
+    readonly now?: () => number;
+}
+/**
+ * The reply a v1 terminal is assumed to give before its real `hello` arrives
+ * (the `TERM_PROGRAM=tern` optimistic start): the whole vocabulary, the
+ * default APC limit and credits, the terminal's width, the appearance omp
+ * already detected, and full motion.
+ */
+export declare function assumedTspHello(terminal: Terminal): TspHello;
+export declare class NativeBackend {
+    #private;
+    constructor(host: NativeHost, hello: TspHello, options?: NativeBackendOptions);
+    /** The terminal's hello reply. */
+    get hello(): TspHello;
+    /** Describe context shared by every surface. */
+    get context(): DescribeContext;
+    /** `rows` fallback nodes in the last frame. */
+    get fallbackCount(): number;
+    /**
+     * Open the inline surface and send the first frame. Native rendering is
+     * announced only once the surface is open: Tern drops the shell's title
+     * when a command's first surface opens, so the tab title set on the change
+     * has to follow the `o`.
+     */
+    start(): void;
+    /**
+     * Close every surface. The inline transcript stays in scrollback unless
+     * `keep` is false (a revoked optimistic start: rows repaint from scratch).
+     */
+    stop(keep?: boolean): void;
+    /**
+     * After a stop/start cycle (external editor, suspend): adopt the closed
+     * inline surface so the transcript continues in place instead of being
+     * printed again. A `gone` reply for it opens a fresh surface.
+     */
+    resume(hello: TspHello): void;
+    /**
+     * The terminal's real `hello` reply after an optimistic start: adopt its
+     * APC limit, credits, cell size, kinds, appearance and motion preference.
+     * A width the terminal already reported in a `resize` event wins over the
+     * reply's. A different vocabulary or motion preference re-describes every
+     * component, so kinds the terminal lacks fall back.
+     */
+    confirm(hello: TspHello): void;
+    /** SIGWINCH: refresh the width used for `rows` fallback until the terminal reports one. */
+    noteTerminalColumns(columns: number): void;
+    /** Reconcile and send a frame, unless the target surface is out of credits. */
+    render(): void;
+    /**
+     * Handle one complete `ESC _ tsp;…` input string (events and late replies).
+     * Returns false when `sequence` isn't TSP.
+     */
+    handleInput(sequence: string): boolean;
+    /** Reference document of the live surface (mirror mode only). */
+    document(): TspNode | undefined;
+    /** Last sent frames, oldest first (mirror mode only). */
+    recentFrames(count?: number): readonly TspFrame[];
+}

package/dist/types/native/blobs.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Content-addressed binary blobs (images) for `image` nodes.
+ *
+ * `describe()` registers the bytes and puts the returned id in `image.p.blob`;
+ * the native backend uploads each referenced blob once per surface with verb
+ * `b` before the frame that first references it.
+ */
+import type { TspProps } from "@oh-my-pi/pi-wire";
+import type { NativeNode } from "./node.js";
+export interface NativeBlob {
+    readonly id: string;
+    readonly mime: string;
+    readonly bytes: Uint8Array;
+}
+/** Register `bytes` and return their content address (sha256 hex) for `image.p.blob`. */
+export declare function registerNativeBlob(bytes: Uint8Array, mime: string): string;
+/** A registered blob by id. */
+export declare function getNativeBlob(id: string): NativeBlob | undefined;
+/**
+ * An `image` node for a base64 payload: the bytes are registered as a blob and
+ * the pixel size probed from the header. Decoding and hashing cost real time,
+ * so callers cache the node per payload ({@link NativeImageCache}).
+ */
+export declare function base64ImageNode(data: string, mimeType: string, p?: Omit<TspProps<"image">, "blob" | "w" | "h">, key?: string): NativeNode;
+/** `image` nodes for base64 payloads, one per slot key, rebuilt only when the slot's payload changes. */
+export declare class NativeImageCache {
+    #private;
+    get(key: string, data: string, mimeType: string): NativeNode;
+}

package/dist/types/native/describe.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Builders for {@link NativeNode}s, so `describe()` implementations read as
+ * a tree instead of object literals.
+ *
+ * @example
+ * describe() {
+ *   return card({ role: "omp.tool.bash", status: "running", head: [span("Bash", "toolTitle")] }, [
+ *     ansi(this.#output, { follow: true, preview: { lines: 10 } }),
+ *   ]);
+ * }
+ */
+import type { TspKind, TspProps, TspSpan, TspText } from "@oh-my-pi/pi-wire";
+import type { NativeChild, NativeNode } from "./node.js";
+/** A node of any kind. */
+export declare function node<K extends TspKind>(k: K, p?: TspProps<K>, c?: readonly NativeChild[], key?: string): NativeNode;
+/** One styled span; `s` is a space-separated list of semantic or theme tokens. */
+export declare function span(t: string, s?: string, extra?: Omit<TspSpan, "t" | "s">): TspSpan;
+/** Plain or styled text. */
+export declare function text(content: TspText, p?: Omit<TspProps<"text">, "text" | "spans">): NativeNode;
+/** Vertical stack. */
+export declare function col(c: readonly NativeChild[], p?: TspProps<"col">): NativeNode;
+/** Horizontal flex row. */
+export declare function row(c: readonly NativeChild[], p?: TspProps<"row">): NativeNode;
+/** Card with an optional header, status and collapsible body. */
+export declare function card(p: TspProps<"card">, c: readonly NativeChild[]): NativeNode;
+/** Markdown source in omp's dialect. */
+export declare function md(source: string, p?: Omit<TspProps<"md">, "text">): NativeNode;
+/** Highlighted code. */
+export declare function code(source: string, p?: Omit<TspProps<"code">, "text">): NativeNode;
+/** Raw terminal output rendered as a mini terminal. */
+export declare function ansi(output: string, p?: Omit<TspProps<"ansi">, "text">): NativeNode;
+/** Unified diff. */
+export declare function diff(unified: string, p?: Omit<TspProps<"diff">, "text">): NativeNode;
+/** A mounted, empty, invisible node for components that describe nothing. */
+export declare const EMPTY_NODE: NativeNode;
+/** `described` with a sibling identity key (the layout builders only take props). */
+export declare function keyed(described: NativeNode, key: string): NativeNode;
+/** `described` mounted but not laid out when `hidden` (cheap visibility toggles keep ids and view state). */
+export declare function withHidden(described: NativeNode, hidden: boolean): NativeNode;
+/** Stable node key for an arbitrary identity string; keys join into `/` keypaths, so identities are hashed. */
+export declare function stableKey(identity: string): string;
+/** Drop absent entries (`undefined`, `null`, `false`) from a child list. */
+export declare function compact<T>(items: readonly (T | undefined | null | false)[]): T[];
+/** A `kv` grid from label/value pairs with muted labels, skipping empty values; undefined when nothing is left. */
+export declare function kv(pairs: readonly (readonly [string, TspText | undefined])[]): NativeNode | undefined;
+/** One list `item`, keyed by the value select/activate events report back. */
+export declare function item(key: string, p: TspProps<"item">): NativeNode;
+/** A `list` of items. */
+export declare function list(items: readonly NativeChild[], p?: TspProps<"list">, key?: string): NativeNode;
+/** Terminal-clocked elapsed counter: `age` ms already elapsed; `stopped` freezes it there. */
+export declare function elapsed(age: number, stopped?: boolean): NativeNode;
+/**
+ * Keycap for one key id (`"ctrl+o"` → keys `["ctrl", "o"]`); the terminal
+ * draws platform glyphs. A literal `+` key survives (`"+"`, `"ctrl++"`).
+ */
+export declare function kbd(key: string, nodeKey?: string): NativeNode;

package/dist/types/native/encode.d.ts

@@ -0,0 +1,50 @@
+import { type TspEvent, type TspReply, type TspVerb } from "@oh-my-pi/pi-wire";
+/** Every TSP message starts with this. */
+export declare const TSP_PREFIX = "\u001B_tsp;";
+/** The terminal's hello reply. */
+export type TspHello = Extract<TspReply, {
+    r: "hello";
+}>;
+/** A decoded terminal → program message. */
+export type TspIncoming = {
+    verb: "r";
+    reply: TspReply;
+} | {
+    verb: "e";
+    event: TspEvent;
+};
+/** Message parameters (`k=v`, ASCII, never containing `;`). */
+export type TspParams = Readonly<Record<string, string | number>>;
+/** Split `body` into pieces of at most `limit` UTF-8 bytes, never inside a code point. */
+export declare function splitUtf8(body: string, limit: number): string[];
+/**
+ * Encode one logical message, chunked when `body` exceeds `limit` UTF-8 bytes.
+ * Returns the complete byte string to write (all chunks, in order).
+ */
+export declare function encodeTspMessage(verb: TspVerb, body: string, params?: TspParams, limit?: number): string;
+/** Encode a JSON message body. */
+export declare function encodeTspJson(verb: TspVerb, value: unknown, params?: TspParams, limit?: number): string;
+/** The `hello` query; callers follow it with a DA1 sentinel. */
+export declare function encodeTspHelloQuery(version?: string): string;
+/** One decoded APC message: verb, parameters and raw body. */
+export interface TspRawMessage {
+    verb: string;
+    params: Record<string, string>;
+    body: string;
+}
+/** Split a complete `ESC _ tsp;… ESC \` string into verb, parameters and body; null when it isn't one. */
+export declare function splitTspMessage(sequence: string): TspRawMessage | null;
+/**
+ * Reassembles chunked terminal → program messages and decodes replies and
+ * events. Unknown verbs, unknown events and unknown fields are tolerated
+ * (ignored or passed through); malformed input yields null.
+ */
+export declare class TspReader {
+    #private;
+    /** Feed one complete APC string. Returns the decoded message once complete, else null. */
+    feed(sequence: string): TspIncoming | null;
+}
+/** Decode an unchunked reply/event body. Null for malformed JSON, missing fields or program → terminal verbs. */
+export declare function decodeTspBody(verb: string, body: string): TspIncoming | null;
+/** Decode one complete, unchunked terminal → program message. */
+export declare function parseTspMessage(sequence: string): TspIncoming | null;

package/dist/types/native/icons.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Icon glyph normalization for native frames.
+ *
+ * Components style icons as Private Use Area codepoints (Nerd Font glyphs)
+ * baked into text with a padding space, e.g. `{t:"<glyph> Model", s:"statusLineModel"}`.
+ * The terminal draws icons and spaces them itself, so every PUA run becomes
+ * its own span carrying the `icon` token next to the original tokens (colour
+ * survives), and the single space that padded it from the neighbouring text
+ * is dropped. Applied once, centrally, to every `TspText` field of a node's
+ * props before they go on the wire.
+ */
+import type { TspKind, TspSpan, TspText } from "@oh-my-pi/pi-wire";
+/** Spans with every PUA run split into an `icon` span; the same array when there is none. */
+export declare function normalizeIconSpans(spans: readonly TspSpan[]): readonly TspSpan[];
+/** A `TspText` with icons normalized; plain strings with icons become spans. */
+export declare function normalizeIconText(text: TspText): TspText;
+/** Props with every `TspText` field's icons normalized; the same object when nothing changed. */
+export declare function normalizeIconProps(kind: TspKind, props: Readonly<Record<string, unknown>> | undefined): Readonly<Record<string, unknown>> | undefined;

package/dist/types/native/memo.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Memoization for `describe()`: an unchanged component must hand the
+ * reconciler the same node objects, so it can skip the subtree. {@link Memo}
+ * is the one primitive; {@link OwnerMemo} keys it by an object for stateless
+ * renderers (tool describe hooks) that re-describe the same args/result.
+ */
+import type { NativeNode } from "./node.js";
+/** Element-wise identity (`Object.is`) of two arrays; `undefined` never matches. */
+export declare function sameItems<T>(a: readonly T[] | undefined, b: readonly T[]): boolean;
+/** Shallow equality of two flat prop bags built by successive describe calls. */
+export declare function sameProps<T extends object>(a: T | undefined, b: T): boolean;
+/** Keeps the last built value while every dependency is unchanged (`Object.is` per slot). */
+export declare class Memo<T = NativeNode> {
+    #private;
+    get(deps: readonly unknown[], build: () => T): T;
+    /** Forget the cached value (theme, glyph preset or keybindings changed). */
+    clear(): void;
+}
+/**
+ * One {@link Memo} per owner object, kept in a symbol slot on the owner; each
+ * instance owns its own slot, so call and result views of one object don't
+ * collide. Builds uncached without an owner or when the owner is frozen.
+ */
+export declare class OwnerMemo<T> {
+    #private;
+    get(owner: object | undefined, deps: readonly unknown[], build: () => T): T;
+}

package/dist/types/native/node.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The describe contract: how components hand the Tern Surface Protocol (TSP)
+ * backend a semantic description instead of rendered rows.
+ *
+ * A component opts in with `describe(cx)`, returning a {@link NativeNode}: a
+ * wire node without ids. Children are either nested nodes or other
+ * components; a component child is a describe boundary the reconciler visits
+ * on its own, so each component owns a stable id prefix and can be skipped
+ * when it returns the same node object it returned last time (the same
+ * reference contract as `render()`). A component without `describe` becomes a
+ * `rows` fallback node rendered through `render(cx.cols)`.
+ *
+ * See `packages/wire/src/tsp.ts` for the wire vocabulary and
+ * `crates/tern/SURFACE_PROTOCOL.md` (Stencil repository) for the spec.
+ */
+import type { TspEvent, TspKind, TspProps, TspSpan } from "@oh-my-pi/pi-wire";
+import type { Component } from "../tui.js";
+/** A described node: a wire node minus its id, with components allowed as children. */
+export type NativeNode = {
+    [K in TspKind]: {
+        readonly k: K;
+        readonly p?: TspProps<K>;
+        readonly c?: readonly NativeChild[];
+        /**
+         * Identity among its siblings inside the owning component (defaults to
+         * the child index). Give keys to children that can be inserted, removed
+         * or reordered so their ids and terminal-side view state survive.
+         */
+        readonly key?: string;
+    };
+}[TspKind];
+/** A child slot: a described node, or a component that describes itself. */
+export type NativeChild = NativeNode | Component;
+/** What a component may consult while describing itself. Never a clock: motion is terminal-clocked. */
+export interface DescribeContext {
+    /** Surface width in cells; only for `rows` fallback and ANSI wrap hints. */
+    readonly cols: number;
+    /** The terminal asked for reduced motion. */
+    readonly reduceMotion: boolean;
+    /** The terminal's appearance is dark. */
+    readonly dark: boolean;
+    /** Whether the terminal renders `kind` natively (else describe something simpler or let it fall back). */
+    supports(kind: TspKind): boolean;
+    /**
+     * Whether the terminal's `hello` advertised protocol feature `name`
+     * (`aside`: a `prefs` page in `layer` docks as a sheet at the pane's right
+     * edge, the transcript narrowed beside it).
+     */
+    feature(name: string): boolean;
+}
+/** The regions a frame provider fills when it describes a whole surface. */
+export interface NativeSurface {
+    /** The flowing document (transcript). */
+    readonly main: readonly NativeChild[];
+    /** Sticky bottom chrome while live (editor, status line, HUDs). */
+    readonly dock: readonly NativeChild[];
+}
+/**
+ * A user action on a node a component described, routed back to that
+ * component. `key` is the node's key path inside the component (`""` for the
+ * component's root node, `"body/3"` for a nested keyed child).
+ */
+export type NativeUiEvent = {
+    readonly type: "toggle";
+    readonly key: string;
+    readonly collapsed: boolean;
+} | {
+    readonly type: "select";
+    readonly key: string;
+    readonly item: string;
+} | {
+    readonly type: "activate";
+    readonly key: string;
+    readonly item: string;
+} | {
+    readonly type: "action";
+    readonly key: string;
+    readonly act: string;
+    /** Scope/tab/strip id, sort column, or the prefs row an action control belongs to. */
+    readonly value?: string;
+    readonly mods: readonly string[];
+}
+/** A typed value changed by pointer (prefs rows, picker toggles); `null` resets to the default. */
+ | {
+    readonly type: "change";
+    readonly key: string;
+    readonly item: string;
+    readonly value: boolean | number | string | readonly string[] | null;
+};
+/** The expanded state a `toggle` on the component's root node asks for, else undefined. */
+export declare function rootToggleExpanded(event: NativeUiEvent): boolean | undefined;
+/** The last segment of an event keypath (`"split/sidebar/toc"` → `"toc"`). */
+export declare function leafKey(path: string): string;
+/** Terminal-level events the backend doesn't route to a single component. */
+export type NativeTerminalEvent = Extract<TspEvent, {
+    ev: "theme" | "motion" | "visible" | "resize";
+}>;
+/** Implemented by components that react to user actions on their described nodes. */
+export interface NativeEventTarget {
+    handleNativeEvent(event: NativeUiEvent): void;
+}
+/** Implemented by frame providers (the composer) that describe the whole surface. */
+export interface NativeSurfaceProvider {
+    describeSurface(cx: DescribeContext): NativeSurface;
+}
+/** Re-exported for describe helpers. */
+export type { TspSpan };

package/dist/types/native/overlay.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Overlay chrome for `describe()`: root cards, key-hint footers, selectable
+ * lists and annotation callouts.
+ *
+ * The overlay frame itself (glass, ring, placement) is the terminal's: the
+ * engine wraps every overlay-stack component in an `overlay` node. An overlay
+ * component's root is a `card` whose `head` carries the title.
+ */
+import type { TspProps, TspSpan, TspText } from "@oh-my-pi/pi-wire";
+import type { KeyName } from "../key-hint-format.js";
+import { type Keybinding } from "../keybindings.js";
+import type { NativeChild, NativeNode } from "./node.js";
+/** One footer hint: the keys that trigger it and what it does. */
+export interface NativeHint {
+    /** Key ids (`"ctrl+o"`, `"escape"`); alternatives render side by side. */
+    readonly keys: readonly KeyName[];
+    readonly label: string;
+}
+/**
+ * A hint for the primary keys of one or more keybinding actions
+ * (`actionHint(["tui.select.up", "tui.select.down"], "navigate")`);
+ * `undefined` when every action is unbound.
+ */
+export declare function actionHint(actions: Keybinding | readonly Keybinding[], label: string): NativeHint | undefined;
+/**
+ * A wrapping row of `kbd` keycaps with muted labels: the footer hint strip of
+ * a selector. `undefined` entries (unbound actions) are skipped. Build it once
+ * per hint-set change and reuse the node (memoization contract).
+ */
+export declare function hintsRow(hints: readonly (NativeHint | undefined)[], key?: string): NativeNode;
+/** A wrapping footer: a status line (`✓ Clean`, `⚠ Cancelled`) followed by key hints. */
+export declare function statusHintsRow(status: TspText, hints: readonly (NativeHint | undefined)[]): NativeNode;
+/**
+ * Root card of an overlay. `head` is the overlay title (whitespace runs
+ * collapse; empty means no head); `role` is `omp.overlay.<name>`.
+ */
+export declare function overlayCard(role: string, head: TspText | undefined, children: readonly NativeChild[], props?: Omit<TspProps<"card">, "head" | "role">): NativeNode;
+/** A selectable list: click selects, double-click activates. */
+export declare function selectList(key: string, items: readonly NativeChild[], p: TspProps<"list">): NativeNode;
+/** The index encoded in an item key built as `<prefix><index>`, or -1 when it isn't one. */
+export declare function itemIndex(item: string, prefix: string): number;
+/** Options of an {@link actionButton}. */
+export interface ActionButtonOptions {
+    /** Sibling identity key (defaults to the action id); `leafKey(event.key)` reports it back. */
+    readonly key?: string;
+    /** Key id of the keyboard path the button mirrors, drawn as a keycap inside it (`"r"`, `"ctrl+g"`). */
+    readonly keys?: string;
+    /** `accent` = the view's hero action, `error` = destructive. */
+    readonly tone?: "accent" | "error";
+    /** Tooltip; defaults to the label plus the keycap (`"Refresh  r"`). */
+    readonly title?: string;
+    /** Target of an `open` action (URL or `file://` path). */
+    readonly href?: string;
+}
+/**
+ * A native button (role `omp.btn`): a label plus an optional keycap. A click
+ * sends `act` back as an `action` event (or runs a terminal-local `open`/`copy`),
+ * which the component routes to the same code path as the key.
+ */
+export declare function actionButton(label: string, act: string, options?: ActionButtonOptions): NativeNode;
+/** A row of {@link actionButton}s (role `omp.actions`); `null` entries become the spacer that end-aligns what follows. */
+export declare function actionBar(buttons: readonly (NativeNode | null)[], key?: string): NativeNode;
+/** Spans of an annotation callout: a dim `label:` then the note. */
+export declare function noteSpans(label: string, note: string): TspSpan[];