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

package/dist/types/components/editor.d.ts

@@ -1,10 +1,21 @@
 import { type AutocompleteProvider } from "../autocomplete.js";
+import type { TspEditorDecoration, TspTone } from "@oh-my-pi/pi-wire";
+import type { DescribeContext, NativeChild, NativeNode } from "../native/node.js";
 import type { SymbolTheme } from "../symbols.js";
 import { type Component, type Focusable } from "../tui.js";
 import { type VimMode } from "../vim.js";
 import { type EditorBorderStyle, type EditorTopBorder } from "./composer/index.js";
 export type { EditorBorderStyle, EditorTopBorder };
 import { type SelectListTheme } from "./select-list.js";
+/** The TSP root an {@link Editor.describeLayout} hook builds around the `editor` node. */
+export interface NativeEditorLayout {
+    readonly role: string;
+    /** Tone of the root (`pending` while a turn runs). */
+    readonly tone?: TspTone;
+    readonly children: readonly NativeChild[];
+    /** Keypath of the `editor` node inside the root (the autocomplete's caret anchor). */
+    readonly caret: string;
+}
 export interface EditorTheme {
     borderColor: (str: string) => string;
     /** Stable accent for composer chrome that should not follow the mutable border state. */
@@ -79,6 +90,23 @@ export declare class Editor implements Component, Focusable {
      *  Width-changing output is allowed on lines without the cursor; it is truncated
      *  to the content width rather than reflowed. Cursor glyphs and inline hints are excluded. */
     decorateText: ((text: string, context: EditorTextDecorationContext) => string) | undefined;
+    /**
+     * TSP counterpart of {@link decorateText}: styled ranges over the buffer
+     * (UTF-16 offsets into the lines joined by `\n`). Called only when the text
+     * changed or the editor was invalidated since the last description.
+     */
+    describeDecorations: ((lines: readonly string[]) => readonly TspEditorDecoration[]) | undefined;
+    /** TSP code language of the buffer (`python`, `bash`): the terminal highlights it in the mono face. */
+    describeLanguage: (() => string | undefined) | undefined;
+    /**
+     * TSP chrome around the `editor` node (the prompt composer's chips, mode
+     * chip, send/stop): the root role, the children with `input` placed where
+     * the layout wants it, and the input's keypath for the caret-anchored
+     * autocomplete. Unset: a plain `omp.editor` column over the input.
+     */
+    describeLayout: ((input: NativeNode, cx: DescribeContext) => NativeEditorLayout) | undefined;
+    /** TSP placeholder for the empty buffer; natively it replaces the rotating ANSI {@link placeholder} hints. */
+    nativePlaceholder: string | undefined;
     /** Called with the selected text when Visual mode yanks, so hosts can reach the system
      *  clipboard — `packages/tui` deliberately has no clipboard dependency of its own. */
     onYank?: (text: string) => void;
@@ -203,6 +231,15 @@ export declare class Editor implements Component, Focusable {
     restoreHistoryState(restore?: () => void): void;
     invalidate(): void;
     render(width: number): readonly string[];
+    /**
+     * An `editor` node (key `input`) carrying the buffer, caret, Vim selection
+     * anchor and mode, decorations, ghost completion, placeholder, prompt and
+     * height cap; the frame, wrapping, scrolling and caret are the terminal's,
+     * so composer shapes play no part. An open autocomplete popup follows as an
+     * `overlay` anchored to the caret around the completion list. Typing and
+     * caret moves change only `text` and `cursor` on the same node.
+     */
+    describe(cx: DescribeContext): NativeNode;
     handleInput(data: string): void;
     getText(): string;
     /** Host-registered atomic chip labels mapped to their submit-time expansions. */

package/dist/types/components/form.d.ts

@@ -1,4 +1,6 @@
 import type { MouseRoutable, SgrMouseEvent } from "../mouse.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
+import { type SelectPickerOptions } from "../native/picker.js";
 import { type Component, type Focusable } from "../tui.js";
 import { Input } from "./input.js";
 import { type SelectItem, SelectList, type SelectListTheme } from "./select-list.js";
@@ -39,6 +41,8 @@ export declare class FormField implements Component, Focusable, MouseRoutable {
     #private;
     readonly control: FormControl;
     constructor(control: FormControl, options: FormFieldOptions);
+    /** Label, description, details, preview, the control, error, summary, hint and footer as one column. */
+    describe(_cx: DescribeContext): NativeNode;
     get focused(): boolean;
     get debugChildren(): readonly Component[];
     set focused(value: boolean);
@@ -95,13 +99,21 @@ export interface SelectFormFieldOptions extends Omit<FormFieldOptions, "preview"
     onCancel(): void;
     /** Schedule a frame after an asynchronous preview update settles. */
     requestRender?: () => void;
+    /** The picker sheet a long choice (> {@link PICKER_MIN_ITEMS} items) describes as; defaults to the label. */
+    picker?: SelectPickerOptions;
 }
 /** SelectList field that centralizes selection, cancellation, preview refresh, and mouse routing. */
 export declare class SelectFormField extends FormField {
     #private;
     readonly selectList: SelectList;
+    /** Number of choices (before filtering). */
+    readonly itemCount: number;
     constructor(options: SelectFormFieldOptions);
     invalidate(): void;
+    /** Long choices describe as a picker sheet where supported; the host places it (layer or prefs editor). */
+    describe(cx: DescribeContext): NativeNode;
+    /** Picker pointer events drive the list as its keys do (preview, pick, cancel). */
+    handleNativeEvent(event: NativeUiEvent): void;
 }
 /** Options for focus and input dispatch across several composable fields. */
 export interface FormOptions {
@@ -116,6 +128,8 @@ export interface FormOptions {
 export declare class Form implements Component, Focusable, MouseRoutable {
     #private;
     constructor(options: FormOptions);
+    /** The fields as one column; focus traversal stays keyboard-driven. */
+    describe(_cx: DescribeContext): NativeNode;
     get focused(): boolean;
     get debugChildren(): readonly Component[];
     set focused(value: boolean);

package/dist/types/components/image.d.ts

@@ -1,4 +1,5 @@
 import { type ImageDimensions } from "../terminal-capabilities.js";
+import type { DescribeContext, NativeNode } from "../native/node.js";
 import type { Component } from "../tui.js";
 export interface ImageTheme {
     fallbackColor: (str: string) => string;
@@ -203,5 +204,11 @@ export declare class Image implements Component {
     /** Return source metadata without exposing the encoded image buffer. */
     debugState(): Record<string, unknown>;
     invalidate(): void;
+    /**
+     * A native `image` backed by a content-addressed blob; the terminal fits
+     * it. Cell caps become `ch`/`lines` bounds. The inline-image budget and
+     * graphics protocols do not apply.
+     */
+    describe(_cx: DescribeContext): NativeNode;
     render(width: number): readonly string[];
 }

package/dist/types/components/input.d.ts

@@ -1,3 +1,4 @@
+import type { DescribeContext, NativeNode } from "../native/node.js";
 import { SpaceHoldGesture } from "../space-hold.js";
 import { type Component, type Focusable } from "../tui.js";
 /**
@@ -9,6 +10,8 @@ export declare class Input implements Component, Focusable {
     prompt: string;
     /** Render the editable value as bullets while retaining the real value internally. */
     mask: boolean;
+    /** Dim hint a native terminal shows while the value is empty. */
+    placeholder: string | undefined;
     onSubmit?: (value: string) => void;
     onEscape?: () => void;
     /** Space-bar push-to-talk; set its `handler` to enable it. */
@@ -18,12 +21,21 @@ export declare class Input implements Component, Focusable {
     /** Focusable interface - set by TUI when focus changes */
     focused: boolean;
     getValue(): string;
+    /** The caret as a UTF-16 offset into {@link getValue}. */
+    getCursor(): number;
     /** Return bounded input content and cursor state for debug inspection. */
     debugState(): Record<string, unknown>;
     setValue(value: string): void;
     setUseTerminalCursor(useTerminalCursor: boolean): void;
     getUseTerminalCursor(): boolean;
-    handleInput(data: string): void;
+    /**
+     * Apply one key: the editor's text bindings (motion, deletion, kill ring,
+     * undo), pastes and printable text. Returns whether the key was the
+     * field's: false for keys it has no binding for, and for cancel/submit
+     * without an `onEscape`/`onSubmit`, so a host (a list's search field) can
+     * route everything else on.
+     */
+    handleInput(data: string): boolean;
     /** Apply terminal paste semantics to text from non-bracketed paste transports
      *  (e.g. kitty's OSC 5522 enhanced clipboard read). Mirrors `Editor.pasteText`. */
     pasteText(text: string): void;
@@ -39,5 +51,12 @@ export declare class Input implements Component, Focusable {
     /** Drop any volatile preview, then insert `text` as a single undoable edit. */
     commitVolatileText(text: string): void;
     invalidate(): void;
+    /**
+     * An `input` with the value, the caret as a UTF-16 offset and the prompt;
+     * the terminal draws the caret, scrolls horizontally and places the IME.
+     * A masked input sends one bullet per grapheme, with the caret mapped onto
+     * them, so the secret never leaves the process.
+     */
+    describe(_cx: DescribeContext): NativeNode;
     render(width: number): readonly string[];
 }

package/dist/types/components/key-value-list.d.ts

@@ -1,3 +1,4 @@
+import type { DescribeContext, NativeNode } from "../native/node.js";
 import type { Component } from "../tui.js";
 /** One label/value entry in a {@link KeyValueList}. */
 export interface KeyValueRow {
@@ -20,5 +21,7 @@ export declare class KeyValueList implements Component {
     constructor(rows: readonly KeyValueRow[], options: KeyValueListOptions);
     setRows(rows: readonly KeyValueRow[]): boolean;
     invalidate(): void;
+    /** An aligned `kv` grid; label width and value wrapping are the terminal's. */
+    describe(_cx: DescribeContext): NativeNode;
     render(width: number): readonly string[];
 }

package/dist/types/components/layout/geometry.d.ts

@@ -1,3 +1,4 @@
+import type { TspProps, TspSpace } from "@oh-my-pi/pi-wire";
 import type { MouseRoutable } from "../../mouse.js";
 import type { Component } from "../../tui.js";
 /** Alignment within space allocated by a layout component. */
@@ -40,6 +41,21 @@ export interface LayoutAllocation {
     min?: number;
     max?: number;
 }
+/**
+ * Describe child for layout content: components describe themselves; a lazy
+ * row renderer becomes a stable adapter component the native engine renders
+ * as a `rows` fallback (it can only produce width-bound rows).
+ */
+export declare function nativeLayoutChild(content: LayoutContent): Component;
+/** Spacing step standing in for a textual gap decoration (the terminal draws no divider glyphs). */
+export declare function nativeLayoutGap(decoration: LayoutDecoration | undefined): TspSpace | undefined;
+/** Flex props for one layout slot along `axis` (`w` for rows, `h` for stacks). */
+export declare function nativeSlotProps(axis: "w" | "h", slot: {
+    fixed?: number;
+    grow?: number;
+    min?: number;
+    max?: number;
+}): TspProps<"col">;
 /** Clamp an external size to a finite, non-negative integer cell count. */
 export declare function layoutSize(value: number | undefined, fallback?: number): number;
 /** Normalize an optional external size while preserving `undefined`. */

package/dist/types/components/layout/row.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";
 import { type LayoutAlignment, type LayoutContent, type LayoutDecoration, type LayoutInsets, type LayoutRect } from "./geometry.js";
 /** One child and its horizontal sizing and alignment constraints. */
@@ -48,6 +49,12 @@ export declare class Row implements Component, MouseRoutable {
     setIgnoreTight(ignore: boolean): this;
     invalidate(): void;
     dispose(): void;
+    /**
+     * A flex `row`: each child sits in a slot carrying its width bounds
+     * (fixed → min = max `ch`, else grow/min/max). Decorations become gap
+     * spacing; clipping and the exact row budget are the terminal's.
+     */
+    describe(_cx: DescribeContext): NativeNode;
     /** Translate a row-local point into a child's local coordinates. */
     locate(line: number, col: number): RowHit | undefined;
     routeMouse(event: SgrMouseEvent, line: number, col: number): void;

package/dist/types/components/layout/split-pane.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";
 import { type LayoutAlignment, type LayoutContent, type LayoutDecoration, type LayoutRect } from "./geometry.js";
 /** Pane selected when a split collapses below its width constraints. */
@@ -70,6 +71,13 @@ export declare class SplitPane implements Component, MouseRoutable {
     setDecorations(prefix: LayoutDecoration | undefined, divider: LayoutDecoration | undefined, suffix: LayoutDecoration | undefined): void;
     /** Resolve split/narrow geometry without rendering either pane. */
     measure(width: number): SplitPaneGeometry;
+    /**
+     * 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;
     /** Translate a split-local point into pane-local coordinates. */
     locate(line: number, col: number): SplitPaneHit | undefined;
     routeMouse(event: SgrMouseEvent, line: number, col: number): void;

package/dist/types/components/layout/stack.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";
 import { type LayoutAlignment, type LayoutContent, type LayoutInsets, type LayoutRect } from "./geometry.js";
 /** One child and its vertical row-budget constraints. */
@@ -43,6 +44,11 @@ export declare class Stack implements Component, MouseRoutable {
     setIgnoreTight(ignore: boolean): this;
     invalidate(): void;
     dispose(): void;
+    /**
+     * 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;
     /** Translate a stack-local point into a child's local coordinates. */
     locate(line: number, col: number): StackHit | undefined;
     routeMouse(event: SgrMouseEvent, line: number, col: number): void;

package/dist/types/components/loader.d.ts

@@ -1,7 +1,40 @@
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
+import { type ShimmerPalette } from "../theme/shimmer.js";
 import type { TUI } from "../tui.js";
 import { Text } from "./text.js";
 /** Milliseconds between spinner-frame advances; exported so time-derived spinners elsewhere tick at the Loader cadence. */
 export declare const SPINNER_ADVANCE_MS = 80;
+/** 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;
+}
+/**
+ * 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 declare function describeWorkingRow(spec: WorkingRowSpec, cx: DescribeContext, now?: number): NativeNode;
 type ColorFn = (str: string) => string;
 /**
  * Styles Loader message fragments without changing their visible text or width.
@@ -20,6 +53,21 @@ export declare class Loader extends Text {
     /** Return the current message and animation state for debug inspection. */
     debugState(): Record<string, unknown>;
     render(width: number): readonly string[];
+    /**
+     * 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.
+     */
+    describe(cx: DescribeContext): NativeNode;
+    /**
+     * 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;
+    /** A click on the working row's stop control. */
+    handleNativeEvent(event: NativeUiEvent): void;
     start(): void;
     stop(): void;
     /** Lifecycle teardown: stop the animation timer. Idempotent. */

package/dist/types/components/markdown.d.ts

@@ -1,3 +1,4 @@
+import type { DescribeContext, NativeNode } from "../native/node.js";
 import type { SymbolTheme } from "../symbols.js";
 import type { Component } from "../tui.js";
 /** @internal exported for tests — must stay index-identical to the old regex scan. */
@@ -95,6 +96,13 @@ export declare class Markdown implements Component {
     debugState(): Record<string, unknown>;
     setText(text: string): boolean;
     invalidate(): void;
+    /**
+     * 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;
     /**
      * Width-independent source prefix of the last render ending at a frozen
      * Markdown block boundary. Only meaningful while streaming (transient

package/dist/types/components/metric.d.ts

@@ -1,3 +1,4 @@
+import type { DescribeContext, NativeNode } from "../native/node.js";
 import type { Component } from "../tui.js";
 /** One preformatted metric. Domain-specific number, cost, and quota policy stays with the caller. */
 export interface MetricSpec {
@@ -40,5 +41,11 @@ export declare class MetricRow implements Component {
     constructor(metrics: readonly MetricSpec[], options?: MetricRowOptions);
     setMetrics(metrics: readonly MetricSpec[]): boolean;
     invalidate(): void;
+    /**
+     * `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;
     render(width: number): readonly string[];
 }

package/dist/types/components/progress-bar.d.ts

@@ -1,3 +1,4 @@
+import type { DescribeContext, NativeNode } from "../native/node.js";
 import type { Component } from "../tui.js";
 /** Explicit glyph and styling policy for a progress bar. */
 export interface ProgressBarStyle {
@@ -32,5 +33,7 @@ export declare class ProgressBar implements Component {
     constructor(value: number | undefined, options: ProgressBarOptions);
     setValue(value: number | undefined): boolean;
     invalidate(): void;
+    /** A native `progress` bar (indeterminate when the value is unknown); prefix, suffix and percentage label it. */
+    describe(_cx: DescribeContext): NativeNode;
     render(width: number): readonly string[];
 }

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

@@ -1,3 +1,4 @@
+import type { DescribeContext, NativeNode } from "../native/node.js";
 import type { Component } from "../tui.js";
 import { Ellipsis } from "../utils.js";
 import { type ViewportAlignment } from "./scroll-viewport.js";
@@ -93,6 +94,11 @@ export declare class ScrollView implements Component {
     invalidate(): void;
     /** Permanently release a wrapped child's timers, subscriptions, and other resources. */
     dispose(): void;
+    /**
+     * 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;
     render(width: number): readonly string[];
 }
 export {};

package/dist/types/components/section.d.ts

@@ -1,3 +1,4 @@
+import type { DescribeContext, NativeNode } from "../native/node.js";
 import type { Component } from "../tui.js";
 /** Explicit heading/rule/spacing policy for a data section. */
 export interface SectionOptions {
@@ -15,5 +16,7 @@ export declare class Section implements Component {
     constructor(options: SectionOptions);
     invalidate(): void;
     dispose(): void;
+    /** A `section` headed by the styled title; the rule is the terminal's. */
+    describe(_cx: DescribeContext): NativeNode;
     render(width: number): readonly string[];
 }

package/dist/types/components/select-list.d.ts

@@ -1,4 +1,5 @@
 import { type MouseRoutable, type SgrMouseEvent } from "../mouse.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 import type { SymbolTheme } from "../symbols.js";
 import type { Component } from "../tui.js";
 export interface SelectItem {
@@ -7,6 +8,12 @@ export interface SelectItem {
     description?: string;
     /** Optional type-indicator glyph rendered in an aligned column before the label */
     icon?: string;
+    /** Named icon a TSP terminal draws from its own set (replaces the {@link icon} glyph natively). */
+    iconName?: string;
+    /** Native detail text when it differs from the ANSI {@link description} (which may embed {@link state}). */
+    nativeDetail?: string;
+    /** Live state drawn right-aligned natively ("demo/demo", "off"). */
+    state?: string;
     /** Dim hint text shown inline after cursor when this item is selected */
     hint?: string;
     /** Disabled rows stay visible but are skipped by navigation and cannot activate. */
@@ -101,6 +108,7 @@ export declare class SelectList implements Component, MouseRoutable {
     debugState(): Record<string, unknown>;
     /** Refit the visible row budget (hosts clamp the list to available height). */
     setMaxVisible(rows: number): void;
+    /** Replace the filter text (caret to end) and refilter. */
     setFilter(filter: string): void;
     /** Replace controlled items while retaining the selected value when possible. */
     setItems(items: readonly SelectItem[]): void;
@@ -108,6 +116,17 @@ export declare class SelectList implements Component, MouseRoutable {
     /** Select a visible item by its stable value. */
     setSelectedValue(value: string): void;
     getFilter(): string;
+    /**
+     * What a native `picker` shows: the filtered items in order, the selected
+     * and pending values, the query and its caret (UTF-16 offset).
+     */
+    pickerView(): {
+        readonly items: readonly SelectItem[];
+        readonly selected: string | null;
+        readonly pending: string | null;
+        readonly query: string;
+        readonly cursor: number;
+    };
     /** Resolve a 0-based rendered-line index to a filtered-item index. */
     hitTest(line: number): number | undefined;
     /** Highlight the item under the pointer (null clears). */
@@ -117,6 +136,20 @@ export declare class SelectList implements Component, MouseRoutable {
     /** Mouse click: select the item under the pointer and request activation. */
     clickItem(index: number): void;
     routeMouse(event: SgrMouseEvent, line: number, _col: number): void;
+    /**
+     * A `list` of `item`s keyed by item value, with the selection, the search
+     * query and the empty/no-match text, plus a status line (search query,
+     * pending confirmation, host status) under it when one applies.
+     */
+    describe(_cx: DescribeContext): NativeNode;
+    /**
+     * Mark `typed` where it leads a native item label (`{s:"mark"}`), for lists
+     * whose items were matched against text outside the list (autocomplete).
+     * The list then sends no `filter`: the marks already say what matched.
+     */
+    setNativeMark(typed: string): void;
+    /** Pointer select/activate on an item does what a click does today: select it and request activation. */
+    handleNativeEvent(event: NativeUiEvent): void;
     invalidate(): void;
     render(width: number): readonly string[];
     handleInput(keyData: string): void;

package/dist/types/components/settings-list.d.ts

@@ -1,4 +1,6 @@
 import type { SgrMouseEvent } from "../mouse.js";
+import type { TspPrefsControl, TspPrefsRow, TspPrefsSection } from "@oh-my-pi/pi-wire";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 import type { Component } from "../tui.js";
 import { FormField, type FormFieldOptions, type FormFieldTheme } from "./form.js";
 export interface SettingItem {
@@ -18,9 +20,32 @@ export interface SettingItem {
     submenu?: (currentValue: string, done: (selectedValue?: string) => void) => Component;
     /** True when the displayed setting differs from its default value. */
     changed?: boolean;
+    /** The default, as a native settings page names it in the changed dot's title. */
+    defaultLabel?: string;
     /** Render as a non-interactive section heading. Skipped by navigation and search. */
     heading?: boolean;
 }
+/** A row's open editor as a native settings page shows it (`TspPrefsProps.editing`). */
+export interface PrefsEditing {
+    row: string;
+    draft?: string;
+    cursor?: number;
+    option?: string;
+}
+/** A submenu that reports the option it highlights (multiselect toggles) to a native settings page. */
+export interface PrefsOptionSource {
+    readonly prefsOption: string | undefined;
+}
+/** Where a setting row goes on a native settings page: its section and, for search results, its page. */
+export interface PrefsSectionRef {
+    id: string;
+    title: string;
+    page?: string;
+}
+/** The section id for a section title (`"Status Line"` → `"status-line"`). */
+export declare function prefsSectionId(title: string): string;
+/** A setting as a native settings row, given its typed control; `undefined` for headings. */
+export declare function settingPrefsRow(item: SettingItem, control: TspPrefsControl): TspPrefsRow | undefined;
 export interface SettingsListTheme {
     label: (text: string, selected: boolean, changed: boolean) => string;
     value: (text: string, selected: boolean, changed: boolean) => string;
@@ -89,6 +114,36 @@ export declare class SettingsList implements Component {
     toggleSectionFocus(): boolean;
     /** True while an item submenu owns input. */
     hasOpenSubmenu(): boolean;
+    /** The open submenu and the row that opened it, if any. */
+    get openSubmenu(): {
+        id: string;
+        component: Component;
+    } | undefined;
+    /**
+     * The visible settings as native page sections: rows in list order, each
+     * in the section `sectionOf` (given the row and the heading above it) names,
+     * sections in order of their first row (ranked search results gather
+     * under their section). Rows `control` has no typed control for are left
+     * out.
+     */
+    prefsSections(sectionOf: (item: SettingItem, heading: SettingItem | undefined) => PrefsSectionRef, control: (item: SettingItem) => TspPrefsControl | undefined): TspPrefsSection[];
+    /** The row with keyboard focus, or while the section rail has focus the focused section's heading label. */
+    prefsFocus(): {
+        row?: string;
+        section?: string;
+    };
+    /**
+     * The open editor as a native page draws it: a choice's highlighted option
+     * (when `inlineMenu(id)` says the row's choices fit its popup menu), a text
+     * field's draft and cursor (dots when masked), a multiselect's highlighted
+     * option; `null` when nothing is open or the editor has no native control
+     * (the host shows that one itself).
+     */
+    prefsEditing(inlineMenu: (id: string) => boolean): PrefsEditing | null;
+    /** Applies `value` to a cycling (boolean/enum) row the way Enter does: the row shows it and `onChange` runs. */
+    applyValue(id: string, value: string): void;
+    /** Opens row `id`'s submenu the way Enter does (leaving one already open for it); returns it. */
+    openSubmenuFor(id: string): Component | undefined;
     /** Resize the visible viewport (fullscreen hosts call this every render). */
     setMaxVisible(rows: number): void;
     /** Move the selection one step for a wheel notch. */
@@ -130,6 +185,19 @@ export declare class SettingsList implements Component {
     setItems(items: SettingItem[]): void;
     invalidate(): void;
     render(width: number): readonly string[];
+    /**
+     * A `list` of setting `item`s (label, current value on the right, risk note
+     * and description as detail; headings as disabled items) keyed by setting id,
+     * with the selection and search query, plus the footer hint. An open submenu
+     * replaces the list and describes itself.
+     */
+    describe(_cx: DescribeContext): NativeNode;
+    /**
+     * Pointer actions do what a click does in the settings hosts: `select` moves
+     * the selection to the row, or activates it (Enter) when it already is the
+     * selection; `activate` selects and activates.
+     */
+    handleNativeEvent(event: NativeUiEvent): void;
     handleInput(data: string): void;
 }
 /** Construction options for a SettingsList composed as a form field. */

package/dist/types/components/spacer.d.ts

@@ -1,4 +1,7 @@
+import type { DescribeContext, NativeNode } from "../native/node.js";
 import type { Component } from "../tui.js";
+/** Terminal spacing step for a count of blank rows. */
+export declare function spaceForRows(rows: number): "none" | "sm" | "md" | "lg";
 /**
  * Spacer component that renders empty lines
  */
@@ -9,5 +12,6 @@ export declare class Spacer implements Component {
     debugState(): Record<string, unknown>;
     setLines(lines: number): void;
     invalidate(): void;
+    describe(_cx: DescribeContext): NativeNode;
     render(_width: number): readonly string[];
 }

package/dist/types/components/tab-bar.d.ts

@@ -1,3 +1,4 @@
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 import type { Component } from "../tui.js";
 /** Tab definition */
 export interface Tab {
@@ -68,6 +69,14 @@ export declare class TabBar implements Component {
     /** Move to the previous non-muted tab (wraps to last tab before first) */
     prevTab(): void;
     invalidate(): void;
+    /**
+     * A native `tabs` strip (muted tabs keep the muted token), preceded by the
+     * bar label and followed by the cycle hint when present. Shrinking to
+     * `short` labels and wrapping are the terminal's.
+     */
+    describe(_cx: DescribeContext): NativeNode;
+    /** A click on a tab activates it (muted tabs stay inert). */
+    handleNativeEvent(event: NativeUiEvent): void;
     /**
      * Handle keyboard input for tab navigation.
      * @returns true if the input was handled, false otherwise

package/dist/types/components/table.d.ts

@@ -1,3 +1,4 @@
+import type { DescribeContext, NativeNode } from "../native/node.js";
 import type { Component } from "../tui.js";
 /** One table cell. Styling is applied after alignment so padding shares the cell style. */
 export interface TableCell {
@@ -28,5 +29,11 @@ export declare class Table implements Component {
     constructor(rows: readonly (readonly TableCell[])[], columns: readonly TableColumn[], options?: TableOptions);
     setRows(rows: readonly (readonly TableCell[])[]): boolean;
     invalidate(): void;
+    /**
+     * A native `table`. Column priorities carry over unchanged (lower gives
+     * way first); truncating columns truncate at the end, the rest keep
+     * their content. Widths are the terminal's.
+     */
+    describe(_cx: DescribeContext): NativeNode;
     render(width: number): readonly string[];
 }

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

@@ -1,3 +1,4 @@
+import type { DescribeContext, NativeNode } from "../native/node.js";
 import type { Component } from "../tui.js";
 /**
  * Text component - displays multi-line text with word wrapping.
@@ -25,5 +26,10 @@ export declare class Text implements Component {
      */
     setStyleFn(styleFn?: (text: string) => string): this;
     invalidate(): void;
+    /**
+     * Wrapped text; styling re-derived from the styled source so a theme swap
+     * re-resolves tokens. A background fill becomes the node's tone.
+     */
+    describe(_cx: DescribeContext): NativeNode;
     render(width: number): readonly string[];
 }