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

package/dist/types/overlays/error-banner.d.ts

@@ -1,4 +1,5 @@
 import { Container } from "../index.js";
+import type { NativeNode, NativeUiEvent } from "../native/node.js";
 /**
  * A persistent error banner pinned above the editor. Unlike the transcript
  * "Error: …" line (which scrolls away as the conversation grows), this stays in
@@ -9,5 +10,13 @@ import { Container } from "../index.js";
  * overflow row reveals the full body inline in the transcript.
  */
 export declare class ErrorBannerComponent extends Container {
+    #private;
     constructor(message: string);
+    /**
+     * An error-tinted strip pinned above the composer: the message's first line
+     * (the transcript's error frame keeps the full message and its actions)
+     * and a Details button that unfolds the rest here.
+     */
+    describe(): NativeNode;
+    handleNativeEvent(event: NativeUiEvent): void;
 }

package/dist/types/overlays/extensions/extension-list.d.ts

@@ -33,6 +33,7 @@ export declare class ExtensionList implements Component {
     getSelectedExtension(): Extension | null;
     /** Get the currently selected kind header (for preview purposes) */
     getSelectedKind(): ExtensionKind | null;
+    /** Replace the search text (caret to end) and refilter. */
     setSearchQuery(query: string): void;
     clearSearch(): void;
     invalidate(): void;

package/dist/types/overlays/history-search.d.ts

@@ -2,6 +2,8 @@
 export interface HistorySearchEntry {
     prompt: string;
     created_at: number;
+    /** Project folder the prompt was typed in. */
+    cwd?: string;
 }
 /** Searchable prompt history supplied by the host. */
 export interface HistorySource {
@@ -9,8 +11,24 @@ export interface HistorySource {
     getRecent(limit: number): HistorySearchEntry[];
 }
 import { OverlayPanel } from "../chrome/overlay-box.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 export declare class HistorySearchComponent extends OverlayPanel {
     #private;
     constructor(historyStorage: HistorySource, onSelect: (prompt: string) => void, onCancel: () => void);
     handleInput(keyData: string): void;
+    /**
+     * With the `picker` kind: a `size:"md"` sheet of past prompts (first line
+     * with hits, age, folder) as a keyed child the reconciler hoists into
+     * `layer`, since the selector replaces the editor in the dock. Otherwise
+     * the query field (the `Input`, which describes itself as `input`), the
+     * results as a `list` keyed by entry (filter = query, age as the item
+     * value), and the key hints.
+     */
+    describe(cx: DescribeContext): NativeNode;
+    /**
+     * Picker: a row click highlights, a second click or `Insert` inserts it
+     * (Enter), `Close` cancels (Esc), `Clear search` empties the query.
+     * List: picking a result does what highlighting it and pressing Enter does.
+     */
+    handleNativeEvent(event: NativeUiEvent): void;
 }

package/dist/types/overlays/hook-editor.d.ts

@@ -7,13 +7,31 @@
  *   (Ctrl+Q / Ctrl+Enter) submits, bordered popup
  * - Prompt-style (ask): Enter submits, Shift+Enter inserts newline, legacy ask chrome
  */
+import type { ImageContent } from "@oh-my-pi/pi-ai";
 import { type Focusable, type TUI } from "../index.js";
 import { OverlayPanel } from "../chrome/overlay-box.js";
+import type { DescribeContext, NativeNode } from "../native/node.js";
 export interface HookEditorOptions {
     /** Edit text with the host's configured external editor. */
     externalEditor?: (text: string) => Promise<string | null>;
     /** When true, use prompt-style keybindings with the legacy ask prompt chrome. */
     promptStyle?: boolean;
+    /** Allow clipboard images to be attached to this prompt. */
+    acceptImages?: boolean;
+    /** Images already represented by markers in the prefilled text. */
+    images?: readonly ImageContent[];
+    /**
+     * With `acceptImages`, called for an empty bracketed paste, which is how terminals that own
+     * the paste key send an image-only clipboard (#3601). Same signature as
+     * `CustomEditor.onPasteImage`; the host calls `beginPaste` before its first await.
+     */
+    onPasteImage?: () => Promise<boolean>;
+    /**
+     * With `acceptImages`, called for each path of a bracketed paste made only of image paths.
+     * Same signature as `CustomEditor.onPasteImagePath`; calls are not awaited in turn, so images
+     * attach as they finish loading and are renumbered in text order on submit.
+     */
+    onPasteImagePath?: (path: string) => void | Promise<void>;
     /**
      * Max rows the inner Editor may occupy. When omitted, the editor is
      * bounded to the current terminal height minus the component's chrome
@@ -27,12 +45,21 @@ export declare class HookEditorComponent extends OverlayPanel implements Focusab
     #private;
     /** Focus state mirrored to the nested editor during rendering. */
     focused: boolean;
-    constructor(tui: TUI, title: string, prefill: string | undefined, onSubmit: (value: string) => void, onCancel: () => void, options?: HookEditorOptions);
+    constructor(tui: TUI, title: string, prefill: string | undefined, onSubmit: (value: string, images?: ImageContent[]) => void, onCancel: () => void, options?: HookEditorOptions);
+    /** The editor (which describes itself) under the title and detail lines, with the key hints below. */
+    describe(_cx: DescribeContext): NativeNode;
     /** Keep the nested editor's software/hardware cursor mode aligned with the dialog focus target. */
     setUseTerminalCursor(useTerminalCursor: boolean): void;
     /** Render the dialog after forwarding its focus state to the nested editor. */
     render(width: number): readonly string[];
     handleInput(keyData: string): void;
+    /** Whether this prompt opted into clipboard image attachments. */
+    get acceptsImages(): boolean;
+    /** Attach an image; returns its `[Image #N, WxH]` marker for the caller to deliver. */
+    attachImage(image: ImageContent, dims?: {
+        width: number;
+        height: number;
+    }): string | undefined;
     /** Reserve ordered clipboard delivery. Completion accepts nonempty text once, or releases on undefined. */
     beginPaste(): (text: string | undefined) => boolean;
     dispose(): void;

package/dist/types/overlays/hook-input.d.ts

@@ -3,6 +3,7 @@
  */
 import { type TUI } from "../index.js";
 import { OverlayPanel } from "../chrome/overlay-box.js";
+import type { DescribeContext, NativeNode } from "../native/node.js";
 export interface HookInputOptions {
     tui?: TUI;
     timeout?: number;
@@ -17,4 +18,6 @@ export declare class HookInputComponent extends OverlayPanel {
      *  interaction, so the timeout countdown resets like any keystroke. */
     pasteText(text: string): void;
     dispose(): void;
+    /** A card over the form, headed by the title plus the countdown `elapsed` while a timeout runs. */
+    describe(_cx: DescribeContext): NativeNode;
 }

package/dist/types/overlays/hook-selector.d.ts

@@ -4,6 +4,7 @@
  */
 import { type TUI } from "../index.js";
 import { OverlayPanel } from "../chrome/overlay-box.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 /** One segment of a {@link HookSelectorSlider} — a label and an optional
  *  detail line (e.g. the resolved model name) shown beneath the track while
  *  the segment is active. Segment colors come from the track's theme palette,
@@ -68,4 +69,13 @@ export declare class HookSelectorComponent extends OverlayPanel {
     handleInput(keyData: string): void;
     render(width: number): readonly string[];
     dispose(): void;
+    /**
+     * A plain option list is a picker sheet. Otherwise a card headed by the
+     * title (plus the countdown `elapsed` when a timeout runs), the extra title
+     * lines, the slider as `tabs`, the options as a `list` keyed by original
+     * option index, the search query while typing, and the key hints.
+     */
+    describe(cx: DescribeContext): NativeNode;
+    /** Pointer pick of an option does what highlighting it and pressing Enter does; a tab pick moves the slider. */
+    handleNativeEvent(event: NativeUiEvent): void;
 }

package/dist/types/overlays/hub-frame.d.ts

@@ -1,3 +1,5 @@
+import type { TspText } from "@oh-my-pi/pi-wire";
+import type { NativeChild, NativeNode } from "../native/node.js";
 /** A scope row shared by fullscreen hubs, with hub-specific kinds and metadata. */
 export interface SidebarEntry<TKind extends string> {
     id: string;
@@ -32,6 +34,22 @@ export interface SidebarStyle {
 }
 /** Cycle a strip's selection for directional and tab input, returning whether it handled the key. */
 export declare function moveStripSelection(strip: StripState<StripChip<unknown>>, data: string): boolean;
+/**
+ * Native sidebar: a `list` whose `item`s are keyed by entry id (the `item` of
+ * `select`/`activate` events), separators as `rule`s. Scrolling and clipping
+ * are the terminal's; `style` supplies icon, annotation and muting.
+ */
+export declare function describeHubSidebar<TEntry extends SidebarEntry<string>>(entries: readonly TEntry[], selectedId: string, style: (entry: TEntry, index: number) => Pick<SidebarStyle, "icon" | "annotation" | "muted">, key?: string): NativeNode;
+/**
+ * Native footer chip strip: a `tabs` node whose tab ids are the chip indices
+ * (`select` events carry the index as `item`), with an optional prefix label.
+ */
+export declare function describeHubChips(strip: StripState<StripChip<unknown>>, prefix?: TspText, key?: string): NativeNode;
+/**
+ * Native fullscreen hub: a root card titled `title` over a sidebar/body row and
+ * a footer. The split geometry, ring and dividers are the terminal's.
+ */
+export declare function describeHubFrame(role: string, title: TspText, sidebar: NativeChild, body: NativeChild, footer: NativeChild): NativeNode;
 /** Persistent fullscreen split frame, sidebar viewport, and footer chip renderer. */
 export declare class HubFrame {
     #private;

package/dist/types/overlays/jobs-panel.d.ts

@@ -0,0 +1,24 @@
+import { type Component, Container } from "../tui.js";
+import type { DescribeContext, NativeNode } from "../native/node.js";
+/** One async job as the session snapshots it. */
+export interface JobsPanelJob {
+    readonly id: string;
+    readonly type: string;
+    readonly status: "running" | "completed" | "failed" | "cancelled";
+    readonly label: string;
+    readonly startTime: number;
+    readonly endTime?: number;
+    /** Registry id of the subagent a task job runs. */
+    readonly agentId?: string;
+}
+/** Running and recently settled jobs. */
+export interface JobsPanelSnapshot {
+    readonly running: readonly JobsPanelJob[];
+    readonly recent: readonly JobsPanelJob[];
+}
+/** The `/jobs` block: `ansi` renders in the terminal, the snapshot describes the native frame. */
+export declare class JobsPanel extends Container {
+    #private;
+    constructor(snapshot: JobsPanelSnapshot, nowMs: number, ansi: readonly Component[]);
+    describe(cx: DescribeContext): NativeNode;
+}

package/dist/types/overlays/login-dialog.d.ts

@@ -1,6 +1,7 @@
 import type { OAuthPrompt } from "@oh-my-pi/pi-ai/oauth/types";
 import { type TUI } from "../index.js";
 import { OverlayPanel } from "../chrome/overlay-box.js";
+import type { NativeNode, NativeUiEvent } from "../native/node.js";
 /**
  * Login dialog component - replaces editor during OAuth login flow
  */
@@ -37,6 +38,15 @@ export declare class LoginDialogComponent extends OverlayPanel {
      * Called by onProgress callback
      */
     showProgress(message: string): void;
+    /**
+     * A glass sheet over the composer (the dialog replaces the editor in the
+     * dock; the `overlay` hoists into the terminal's layer): numbered steps —
+     * open or copy the sign-in link, the device code, the live wait, the paste
+     * field — and Cancel.
+     */
+    describe(): NativeNode;
+    /** Cancel and Continue run what Esc and Enter run. */
+    handleNativeEvent(event: NativeUiEvent): void;
     /** Route non-bracketed paste transports into the active login input. */
     pasteText(text: string): void;
     handleInput(data: string): void;

package/dist/types/overlays/logout-account-selector.d.ts

@@ -1,4 +1,5 @@
 import { OverlayPanel } from "../chrome/overlay-box.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 export interface LogoutAccount {
     credentialId: number;
     provider: string;
@@ -12,4 +13,7 @@ export declare class LogoutAccountSelectorComponent extends OverlayPanel {
     #private;
     constructor(providerName: string, accounts: LogoutAccount[], onSelect: (account: LogoutAccount) => void, onCancel: () => void);
     handleInput(keyData: string): void;
+    describe(cx: DescribeContext): NativeNode;
+    /** A click (or double-click) on an account highlights it and logs it out, like Enter. */
+    handleNativeEvent(event: NativeUiEvent): void;
 }

package/dist/types/overlays/mcp-add-wizard.d.ts

@@ -1,4 +1,5 @@
 import { OverlayPanel } from "../chrome/overlay-box.js";
+import { type DescribeContext, type NativeNode, type NativeUiEvent } from "../native/node.js";
 type Scope = "user" | "project";
 /** Authentication fields produced by the wizard. */
 interface MCPAddWizardAuth {
@@ -82,6 +83,9 @@ interface MCPAddWizardOAuthOptions {
 export declare class MCPAddWizard extends OverlayPanel {
     #private;
     constructor(deps: MCPAddWizardDeps, onComplete: (name: string, config: MCPAddWizardConfig, scope: Scope) => void, onCancel: () => void, onOAuth?: (authUrl: string, tokenUrl: string, clientId: string, clientSecret: string, scopes: string, options?: MCPAddWizardOAuthOptions) => Promise<MCPAddWizardOAuthResult>, onTestConnection?: (config: MCPAddWizardConfig) => Promise<void>, onRender?: () => void, initialName?: string);
+    describe(_cx: DescribeContext): NativeNode;
+    /** A click on a choice is Enter on it, exactly as highlighting it with the arrows and pressing Enter. */
+    handleNativeEvent(event: NativeUiEvent): void;
     handleInput(keyData: string): void;
 }
 export {};

package/dist/types/overlays/model-browser.d.ts

@@ -4,6 +4,8 @@ import type { Component } from "../tui.js";
 import type { SgrMouseEvent } from "../mouse.js";
 import { type ConfiguredThinkingLevel } from "../thinking.js";
 import { type ThemeColor } from "../theme/theme.js";
+import type { TspPickerColumn, TspPickerGroup, TspPickerItem } from "@oh-my-pi/pi-wire";
+import type { NativeChild, NativeNode, NativeUiEvent } from "../native/node.js";
 /** Canonical display ordering of built-in model roles. */
 export type ModelRole = "default" | "smol" | "slow" | "vision" | "plan" | "commit" | "tiny" | "memory" | "task" | "advisor" | "image" | "web" | "speech" | "dictation" | "judge";
 export declare const MODEL_ROLE_IDS: ModelRole[];
@@ -151,6 +153,10 @@ export declare function rankModelItems(query: string, items: ReadonlyArray<Model
  * Mirrors the spacing already used for `status.success` in model-hub.
  */
 export declare function formatRoleChip(role: string, assignment: RoleAssignment, settings: ModelBrowserSource): string;
+/** Fact columns of a model picker (Stencil `NATIVE_REDESIGN.md` §4.7); the lowest priority hides first. */
+export declare const MODEL_PICKER_COLUMNS: readonly TspPickerColumn[];
+/** The omp theme token of a thinking level's dot (`thinkingHigh`); none for inherit and auto. */
+export declare function thinkingDotToken(level: ConfiguredThinkingLevel): string | undefined;
 /**
  * The fuzzy haystack for a model row: the displayed `provider/id`, plus `free`
  * for zero-cost models so the cost column's own word is searchable even when
@@ -161,6 +167,30 @@ export declare function formatRoleChip(role: string, assignment: RoleAssignment,
  * past its cap, so a query-dependent haystack would thrash that cache.
  */
 export declare function modelSearchText({ provider, id, model }: ModelBrowserItem): string;
+/** A model browser's visible rows as picker `order` plus the query's hit ranges. */
+export interface ModelPickerOrder {
+    readonly order: readonly (string | TspPickerGroup)[];
+    readonly hits: Readonly<Record<string, readonly (readonly [number, number])[]>> | undefined;
+    /** Selectable rows in `order`. */
+    readonly count: number;
+}
+/**
+ * A model picker's catalogue props: `items` as last sent whole, plus the
+ * rows changed or added since (`itemsAdd`) and the ids gone (`itemsDel`), so
+ * a discovery refresh that touches a few rows does not resend a thousand.
+ */
+export interface ModelPickerCatalogue {
+    readonly items: readonly TspPickerItem[];
+    readonly itemsAdd?: readonly TspPickerItem[];
+    readonly itemsDel?: readonly string[];
+}
+/** How {@link ModelBrowser.pickerOrder} heads its rows. */
+export interface ModelPickerGrouping {
+    /** One group per provider after the Recent block (the unfiltered All models view). */
+    readonly providers: boolean;
+    /** Label of the rows after the Recent block when they are not split by provider; null drops every head. */
+    readonly rest: string | null;
+}
 /** Behavior switches for {@link ModelBrowser}. */
 export interface ModelBrowserOptions {
     /** Render the dim `provider/` prefix before model ids. Default true. */
@@ -205,6 +235,8 @@ export declare class ModelBrowser implements Component {
     /** Total rendered height for the current `maxVisible` (host layout budgeting). */
     get renderedRows(): number;
     get query(): string;
+    /** Caret into {@link query} (UTF-16 offset), for native picker `cursor`. */
+    get cursor(): number;
     setQuery(query: string): void;
     getSelected(): ModelBrowserItem | undefined;
     get visibleCount(): number;
@@ -231,4 +263,41 @@ export declare class ModelBrowser implements Component {
     clearHover(): void;
     render(width: number): string[];
     invalidate(): void;
+    /**
+     * `col[search row, list, detail]`: the query field (the embedded `Input`),
+     * every visible model as a keyed `item` (the terminal virtualizes and
+     * scrolls), and the selection's facts and role chips.
+     */
+    describe(): NativeNode;
+    /** List `select`/`activate` on a model = highlight it, then Enter. */
+    handleNativeEvent(event: NativeUiEvent): void;
+    /** Base rows of the current scope, before the query (the head's "of N"). */
+    get baseCount(): number;
+    /** The selected row's selector, null when nothing selectable is selected. */
+    get pickerSelected(): string | null;
+    /**
+     * Picker rows for `catalogue`: the same object while the catalogue, roles
+     * and row inputs are unchanged, so typing and scope hops never resend it.
+     * A rebuilt catalogue that differs in a few rows (a provider refresh, a
+     * role moving) keeps the last whole `items` and patches it.
+     */
+    pickerItems(catalogue: readonly ModelBrowserItem[]): ModelPickerCatalogue;
+    /**
+     * The visible rows as picker `order`: the Recent block (recent and
+     * role-assigned models, the ANSI separator's upper side) under "Recent",
+     * then the rest per provider or under `grouping.rest`. Memoized per
+     * result list and query, so selection moves reuse it.
+     */
+    pickerOrder(grouping: ModelPickerGrouping): ModelPickerOrder;
+    /**
+     * Preview children for the selection. `full` (the model hub's side pane):
+     * title, copyable id, badges, a fact grid, every role the model can fill
+     * (held ones on) and the description. `compact` (the quick picker's strip
+     * below the list): one inline fact line and the held-role chips.
+     */
+    pickerPreview(mode: "full" | "compact", current?: string): readonly NativeChild[];
+    /** Preview children for any model row (the hub's Roles view previews assigned models with it); unmemoized. */
+    modelPreview(item: ModelBrowserItem, mode: "full" | "compact", current: string | undefined): NativeChild[];
+    /** A picker row click: `select` highlights it, `activate` also runs Enter's path. False when not a visible row. */
+    routePickerItem(selector: string, activate: boolean): boolean;
 }

package/dist/types/overlays/model-hub.d.ts

@@ -1,5 +1,6 @@
 import type { KeysApi, Model } from "@oh-my-pi/pi-ai";
 import type { Component, TUI } from "../tui.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 import type { ModelBrowserSource, ModelBrowserRegistry } from "./model-browser.js";
 import { type ConfiguredThinkingLevel } from "../thinking.js";
 /** Live preferences and selector operations supplied by the host. */
@@ -52,6 +53,8 @@ export interface ModelHubCallbacks {
 export interface ModelHubOptions {
     /** Preselect this provider's sidebar entry (e.g. when reopening after /login). */
     initialProviderId?: string;
+    /** `provider/id` of the session's model, marked current in the native picker. */
+    currentSelector?: string;
 }
 /** Test hook: forget which providers were auto-refreshed this process. */
 export declare function resetProviderAutoRefreshGuard(): void;
@@ -69,4 +72,8 @@ export declare class ModelHubComponent implements Component {
     refreshAfterExternalMutation(): void;
     handleInput(data: string): void;
     render(width: number): readonly string[];
+    /** A `picker` is its own sheet: the backend mounts it in `layer` without an `overlay` wrapper. */
+    nativeSheet(cx: DescribeContext): boolean;
+    describe(cx: DescribeContext): NativeNode;
+    handleNativeEvent(event: NativeUiEvent): void;
 }

package/dist/types/overlays/model-picker.d.ts

@@ -10,6 +10,7 @@ import type { Component, TUI } from "../tui.js";
 import type { ModelBrowserRegistry, ModelBrowserSource } from "./model-browser.js";
 import type { ConfiguredThinkingLevel } from "../thinking.js";
 import type { ScopedModelItem } from "./model-hub.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 /** Configured role resolved to a concrete model. */
 export interface ResolvedRoleModel {
     role: string;
@@ -19,7 +20,8 @@ export interface ResolvedRoleModel {
 }
 /** Catalog refresh capability used by the session picker. */
 export interface ModelPickerRegistry extends ModelBrowserRegistry {
-    refresh(strategy: "offline"): Promise<void>;
+    /** Bring the catalog up to date without rebuilding a current one; `true` when the picker must re-read it. */
+    refreshIfStale(): Promise<boolean>;
 }
 export interface ModelPickerCallbacks {
     /**
@@ -69,4 +71,10 @@ export declare class ModelPickerComponent implements Component {
     invalidate(): void;
     handleInput(data: string): void;
     render(width: number): string[];
+    /** A `picker` is its own sheet: the backend mounts it in `layer` without an `overlay` wrapper. */
+    nativeSheet(cx: DescribeContext): boolean;
+    /** Picker pointer events, each on the path of the key it stands for. */
+    handleNativeEvent(event: NativeUiEvent): void;
+    /** The `md` picker sheet, or the fallback card when the terminal lacks the kind. */
+    describe(cx?: DescribeContext): NativeNode;
 }

package/dist/types/overlays/move-overlay.d.ts

@@ -6,6 +6,7 @@
  * confirms — yielding the resolved directory string (or `undefined` on cancel).
  */
 import { type Component, type Focusable } from "../index.js";
+import type { NativeNode, NativeUiEvent } from "../native/node.js";
 export interface MoveOverlayResult {
     directory: string;
 }
@@ -35,5 +36,7 @@ export declare class MoveOverlay implements Component, Focusable {
     pasteText(text: string): void;
     handleInput(data: string): void;
     render(width: number): readonly string[];
+    describe(): NativeNode;
+    handleNativeEvent(event: NativeUiEvent): void;
     invalidate(): void;
 }

package/dist/types/overlays/oauth-selector.d.ts

@@ -1,6 +1,7 @@
 import type { CredentialsApi, KeysApi } from "@oh-my-pi/pi-ai";
 import { type SgrMouseEvent } from "../index.js";
 import { OverlayPanel } from "../chrome/overlay-box.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 /** Credential presence and provenance needed by the provider picker. */
 export interface OAuthSelectorAuthSource {
     readonly credentials: Pick<CredentialsApi, "has">;
@@ -26,6 +27,9 @@ export declare class OAuthSelectorComponent extends OverlayPanel {
      */
     setMaxHeight(lines: number): void;
     handleInput(keyData: string): void;
+    describe(cx: DescribeContext): NativeNode;
+    /** A click (or double-click) on a provider selects and confirms it, like the SGR click in {@link routeMouse}. */
+    handleNativeEvent(event: NativeUiEvent): void;
     /** Move the selection one step for a wheel notch (clamped, no wrap). */
     handleWheel(delta: -1 | 1): void;
     /**

package/dist/types/overlays/omfg-panel.d.ts

@@ -1,5 +1,6 @@
 import { type TUI } from "../index.js";
 import { OverlayPanel } from "../chrome/overlay-box.js";
+import type { NativeNode } from "../native/node.js";
 export type OmfgPanelState = "generating" | "validating" | "confirming" | "saving" | "saved" | "rejected" | "aborted" | "error";
 interface OmfgPanelComponentOptions {
     complaint: string;
@@ -16,5 +17,7 @@ export declare class OmfgPanelComponent extends OverlayPanel {
     markAborted(): void;
     markError(message: string): void;
     close(): void;
+    invalidate(): void;
+    describe(): NativeNode;
 }
 export {};

package/dist/types/overlays/pause-screen.d.ts

@@ -1,4 +1,5 @@
 import { type Component, type OverlayFocusOwner, type OverlayHandle, type OverlayOptions } from "../index.js";
+import type { NativeNode, NativeUiEvent } from "../native/node.js";
 /**
  * Slice of `InteractiveModeContext` the pause screen drives. Narrow so tests
  * can exercise the full engage → hold → release lifecycle without a real TUI.
@@ -32,6 +33,17 @@ export declare class PauseScreenComponent implements Component, OverlayFocusOwne
     dispose(): void;
     ownsOverlayFocusTarget(component: Component): boolean;
     handleInput(data: string): void;
+    invalidate(): void;
+    /** A glass sheet titled "Paused" (not the whole pane: the transcript stays visible, frozen). */
+    readonly nativeOverlay: {
+        readonly role: "omp.overlay.pause";
+        readonly size: "md";
+        readonly anchor: "center";
+        readonly head: "Paused";
+    };
+    describe(): NativeNode;
+    /** Resume runs what Esc/Enter/Space run. */
+    handleNativeEvent(event: NativeUiEvent): void;
     render(width: number): readonly string[];
 }
 /**

package/dist/types/overlays/plan-review-overlay.d.ts

@@ -18,6 +18,7 @@
  */
 import { type Component } from "../index.js";
 import type { HookSelectorSlider } from "./hook-selector.js";
+import { type NativeNode, type NativeUiEvent } from "../native/node.js";
 /** Serializable annotations retained by the plan-review owner between overlays. */
 export interface PlanReviewAnnotationState {
     annotations: Array<{
@@ -85,5 +86,9 @@ export declare class PlanReviewOverlay implements Component {
      *  `onPlanEdited` (the editor round-trip already persisted the file). */
     setPlanContent(planContent: string): void;
     handleInput(keyData: string): void;
+    /** The native sheet: large glass, titled by the plan's own title heading (the body never repeats it). */
+    get nativeOverlay(): NonNullable<Component["nativeOverlay"]>;
+    describe(): NativeNode;
+    handleNativeEvent(event: NativeUiEvent): void;
     render(width: number): readonly string[];
 }

package/dist/types/overlays/plan-save-overlay.d.ts

@@ -1,4 +1,5 @@
 import { type Component, type Focusable } from "../index.js";
+import type { NativeNode, NativeUiEvent } from "../native/node.js";
 /** A confirmed destination chosen from {@link PlanSaveOverlay}. */
 export interface PlanSaveOverlayResult {
     path: string;
@@ -16,4 +17,13 @@ export declare class PlanSaveOverlay implements Component, Focusable {
     pasteText(text: string): void;
     invalidate(): void;
     render(width: number): readonly string[];
+    /** A small glass sheet titled "Save and quit". */
+    readonly nativeOverlay: {
+        readonly role: "omp.overlay.planSave";
+        readonly size: "sm";
+        readonly head: "Save and quit";
+    };
+    describe(): NativeNode;
+    /** Save and Cancel run what the submit and cancel keys run. */
+    handleNativeEvent(event: NativeUiEvent): void;
 }

package/dist/types/overlays/plugin-selector.d.ts

@@ -6,6 +6,7 @@
  */
 import { SelectList, type SgrMouseEvent } from "../index.js";
 import { OverlayPanel } from "../chrome/overlay-box.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 export interface PluginSelectorCallbacks {
     onSelect: (pluginName: string, marketplace: string, scope?: "user" | "project") => void;
     onCancel: () => void;
@@ -23,6 +24,9 @@ export interface PluginItem {
 export declare class PluginSelectorComponent extends OverlayPanel {
     #private;
     constructor(marketplaceCount: number, plugins: PluginItem[], installedIds: Set<string>, callbacks: PluginSelectorCallbacks);
+    describe(cx: DescribeContext): NativeNode | null;
+    /** Picker pointer events drive the list exactly as its keys do. */
+    handleNativeEvent(event: NativeUiEvent): void;
     getSelectList(): SelectList;
     routeMouse(event: SgrMouseEvent, line: number, col: number): void;
 }

package/dist/types/overlays/plugin-settings.d.ts

@@ -7,6 +7,18 @@
  */
 import { Container } from "../index.js";
 import { OverlayPanel } from "../chrome/overlay-box.js";
+import { type PrefsEditing } from "../components/settings-list.js";
+import type { DescribeContext, NativeChild, NativeNode, NativeUiEvent } from "../native/node.js";
+import type { TspPrefsSection } from "@oh-my-pi/pi-wire";
+/** The plugins tab as a native settings page draws it (the settings selector puts it in its `prefs` node). */
+export interface PluginPrefsPage {
+    lead: string;
+    sections: TspPrefsSection[];
+    focus: string | null;
+    editing: PrefsEditing | null;
+    /** An open value editor without a native control, shown over the page. */
+    editor?: NativeChild;
+}
 /** Setting metadata consumed by the plugin settings UI. */
 export type PluginSettingSchema = {
     description?: string;
@@ -118,6 +130,12 @@ export declare class PluginListComponent extends OverlayPanel {
     #private;
     private readonly entries;
     constructor(entries: ReadonlyArray<PluginListEntry>, callbacks: PluginListCallbacks);
+    /** The installed plugins as one native page section: a row per plugin with its status and a Configure button. */
+    prefsPage(): PluginPrefsPage;
+    /** A native page event: a row click moves the selection, Configure (or a double click) opens the plugin. */
+    handlePrefsEvent(event: NativeUiEvent): void;
+    /** The plugin list (the select list describes itself) and its hints, or install guidance when empty. */
+    describe(_cx: DescribeContext): NativeNode;
     handleInput(data: string): void;
 }
 export interface PluginDetailCallbacks {
@@ -141,6 +159,10 @@ export declare class PluginDetailComponent extends OverlayPanel {
     private readonly callbacks;
     constructor(plugin: InstalledPlugin, manager: PluginSettingsManager, callbacks: PluginDetailCallbacks);
     handleInput(data: string): void;
+    /** This plugin's settings as a native page section. */
+    prefsPage(): PluginPrefsPage;
+    /** A native page event on this plugin's settings. */
+    handlePrefsEvent(event: NativeUiEvent): void;
 }
 export interface MarketplacePluginDetailCallbacks {
     parsePluginId: PluginSettingsHost["parsePluginId"];
@@ -161,6 +183,10 @@ export declare class MarketplacePluginDetailComponent extends OverlayPanel {
     private readonly callbacks;
     constructor(plugin: InstalledPluginSummary, manager: PluginSettingsManager, callbacks: MarketplacePluginDetailCallbacks);
     handleInput(data: string): void;
+    /** This plugin's settings as a native page section, with its install facts as the lead. */
+    prefsPage(): PluginPrefsPage;
+    /** A native page event on this plugin's settings. */
+    handlePrefsEvent(event: NativeUiEvent): void;
 }
 export interface PluginSettingsCallbacks {
     onClose: () => void;
@@ -176,5 +202,9 @@ export declare class PluginSettingsComponent extends Container {
     #private;
     private readonly callbacks;
     constructor(host: PluginSettingsHost, callbacks: PluginSettingsCallbacks);
+    /** The current view (list or a plugin's settings) as a native settings page. */
+    prefsPage(): PluginPrefsPage;
+    /** Routes a native page event to the current view. */
+    handlePrefsEvent(event: NativeUiEvent): void;
     handleInput(data: string): void;
 }

package/dist/types/overlays/queue-mode-selector.d.ts

@@ -1,11 +1,15 @@
 import { SelectList, type SgrMouseEvent } from "../index.js";
 import { OverlayPanel } from "../chrome/overlay-box.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 /**
  * Component that renders a queue mode selector with borders
  */
 export declare class QueueModeSelectorComponent extends OverlayPanel {
     #private;
     constructor(currentMode: "all" | "one-at-a-time", onSelect: (mode: "all" | "one-at-a-time") => void, onCancel: () => void);
+    describe(cx: DescribeContext): NativeNode | null;
+    /** Picker pointer events drive the list exactly as its keys do. */
+    handleNativeEvent(event: NativeUiEvent): void;
     getSelectList(): SelectList;
     routeMouse(event: SgrMouseEvent, line: number, col: number): void;
 }