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

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

@@ -29,6 +29,7 @@ import type { AgentTool } from "@oh-my-pi/pi-agent-core";
 import { type Component, type TUI } from "../index.js";
 import type { MessageRenderer } from "../chat/extension-types.js";
 import { type TranscriptEntryLike as TranscriptEntry } from "../chat/transcript-entry.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 /** One alternate branch at a divergence: its root and message path root → most-recent leaf. */
 export interface BranchVariantPath {
     rootId: string;
@@ -60,5 +61,9 @@ export declare class RewindSelectorComponent implements Component {
     invalidate(): void;
     dispose(): void;
     handleInput(data: string): void;
+    /** A `picker` is its own sheet: the backend mounts it in `layer`, over the transcript. */
+    nativeSheet(cx: DescribeContext): boolean;
+    handleNativeEvent(event: NativeUiEvent): void;
+    describe(cx: DescribeContext): NativeNode;
     render(width: number): readonly string[];
 }

package/dist/types/overlays/session-info-overlay.d.ts

@@ -1,4 +1,6 @@
 import { type Component } from "../index.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
+import type { ContextUsage } from "../status-line/types.js";
 /** Terminal surface needed to size the session info viewport. */
 export interface SessionInfoOverlayHost {
     readonly terminal: {
@@ -8,10 +10,26 @@ export interface SessionInfoOverlayHost {
 /** Focused, dismissible `/session` information panel. */
 export declare class SessionInfoOverlay implements Component {
     #private;
-    constructor(host: SessionInfoOverlayHost, info: string, onClose: () => void);
+    /** The terminal draws the sheet: a centred `md` glass sheet titled Session info. */
+    readonly nativeOverlay: {
+        readonly role: "omp.overlay.sessionInfo";
+        readonly size: "md";
+        readonly anchor: "center";
+        readonly head: "Session info";
+    };
+    /** `context` adds a context-window meter to the native sheet. */
+    constructor(host: SessionInfoOverlayHost, info: string, onClose: () => void, context?: ContextUsage);
     handleInput(data: string): void;
     invalidate(): void;
     setIgnoreTight(ignore: boolean): this;
     dispose(): void;
+    /**
+     * The sheet body (the overlay is the frame): the session id in mono
+     * (click copies), each report heading as a section of key/value rows, a
+     * context meter after the leading block, and a Close button (Esc).
+     */
+    describe(cx: DescribeContext): NativeNode;
+    /** The Close button runs Esc's path. */
+    handleNativeEvent(event: NativeUiEvent): void;
     render(width: number): readonly string[];
 }

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

@@ -1,4 +1,6 @@
-import { type Component } from "../index.js";
+import { type Component, Input } from "../index.js";
+import type { TspPickerGroup, TspPickerItem } from "@oh-my-pi/pi-wire";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 /** Session lifecycle status presented by the picker. */
 export type SessionSelectorStatus = "complete" | "interrupted" | "aborted" | "error" | "pending" | "unknown";
 /** Session listing fields consumed by the picker. */
@@ -8,6 +10,7 @@ export interface SessionSelectorEntry {
     cwd: string;
     title?: string;
     modified: Date;
+    created?: Date;
     size: number;
     firstMessage: string;
     allMessagesText: string;
@@ -16,6 +19,20 @@ export interface SessionSelectorEntry {
     parentSessionPath?: string;
 }
 import { OverlayPanel } from "../chrome/overlay-box.js";
+/** The session list's part of the picker props, plus the memo keys it was built from. */
+interface SessionPickerView {
+    items: readonly TspPickerItem[];
+    itemsAdd?: readonly TspPickerItem[];
+    version: number;
+    query: string;
+    /** Search caret (UTF-16 offset into `query`). */
+    cursor: number;
+    order: readonly (string | TspPickerGroup)[];
+    hits?: Readonly<Record<string, readonly (readonly [number, number])[]>>;
+    selected: string | null;
+    current: readonly string[];
+    total: number;
+}
 /** Returns the IDs of sessions whose recorded prompts match a query, best first. */
 export type SessionHistoryMatcher = (query: string) => string[];
 /**
@@ -68,6 +85,35 @@ declare class SessionList<T extends SessionSelectorEntry> implements Component {
     handleWheel(delta: -1 | 1): void;
     /** Mouse click: select the session under the pointer and resume it. */
     selectAndConfirm(index: number): void;
+    /** Native click on a session item: the same outcome as a mouse click (select + resume). */
+    confirmSession(path: string): void;
+    /** Native row click: move the selection there, as the arrow keys would. */
+    selectSession(path: string): void;
+    /** Enter: resume the selected session. */
+    resumeSelected(): void;
+    /** Delete / Backspace on an empty query: ask the parent to confirm deleting the selected session. */
+    requestDelete(): void;
+    /** Empty the search query (the empty state's "Clear search"). */
+    clearSearch(): void;
+    get selectedSession(): T | undefined;
+    /** Label of the session at `sessionPath` in this listing, else its file name. */
+    parentLabel(sessionPath: string): string;
+    /**
+     * The session list's picker data. `items` is the whole scope and keeps its
+     * identity while typing (rebuilt when the set, pins, the live session or
+     * the minute change); a query changes only `order`, `hits` and
+     * `selected`, plus `itemsAdd` upserts for prompt-history badges. Without
+     * a query `order` groups pinned sessions, then by day (Today, Yesterday,
+     * This week, Earlier); with one it is the flat ranking.
+     */
+    pickerView(): SessionPickerView;
+    get searchInput(): Input;
+    /**
+     * The session list as a native `list` keyed `"list"`, items keyed by
+     * session path. The terminal owns scrolling and virtualization; item nodes
+     * are cached per session and the list node while nothing visible changed.
+     */
+    describeList(): NativeNode;
     invalidate(): void;
     render(width: number): readonly string[];
     handleInput(keyData: string): void;
@@ -101,6 +147,12 @@ export interface SessionSelectorOptions<T extends SessionSelectorEntry = Session
     pinnedIds?: ReadonlySet<string>;
     /** Path of the live session, or a getter so detach/newSession stays accurate. */
     currentSessionPath?: string | (() => string | undefined);
+    /**
+     * The picker is the whole program (`omp --resume`): the native picker
+     * fills the screen surface (`size:"screen"`) instead of floating as a
+     * sheet over the transcript.
+     */
+    standalone?: boolean;
 }
 /**
  * Component that renders a session selector with optional confirmation dialog
@@ -125,6 +177,17 @@ export declare class SessionSelectorComponent<T extends SessionSelectorEntry = S
      * the panel's inner width before their rows are wrapped.
      */
     render(width: number): readonly string[];
+    /** Over the transcript the picker is its own sheet (`layer`); the standalone app fills the screen surface. */
+    nativeSheet(cx: DescribeContext): boolean;
+    /**
+     * With the `picker` kind: the data-first session picker (§4.7). Otherwise
+     * scope `tabs`, loading/error message, then the search `input` and session
+     * `list` — or the delete-confirmation dialog in their place, as on the ANSI
+     * path — and the key-hint footer.
+     */
+    describe(cx: DescribeContext): NativeNode;
+    /** Picker events (root keypath); fallback: scope tab → toggle scope, click on a session → resume it, exactly like a mouse click. */
+    handleNativeEvent(event: NativeUiEvent): void;
     handleInput(keyData: string): void;
     getSessionList(): SessionList<T>;
 }

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

@@ -10,6 +10,8 @@ export type TabMetadata = {
 export declare const SETTING_TABS: SettingTab[];
 /** Tab display metadata - icon is a symbol key from theme.ts (tab.*) */
 export declare const TAB_METADATA: Record<SettingTab, TabMetadata>;
+/** One-sentence lead per tab, under the page title of the native settings page. */
+export declare const TAB_LEADS: Record<SettingTab, string>;
 /**
  * Ordered section groups per tab. Settings declare their section via `ui.group`;
  * the settings UI renders groups in this order with a heading row between them.
@@ -119,6 +121,18 @@ export declare function getAllSettingDefs(entries: readonly SettingsDisplayEntry
 export declare function getSettingsForTab(entries: readonly SettingsDisplayEntry[], tab: SettingTab): SettingDef[];
 /** Find the display definition for a host setting path. */
 export declare function getSettingDef(entries: readonly SettingsDisplayEntry[], path: string): SettingDef | undefined;
+/**
+ * The numeric value a number-like choice option stands for: its number, or
+ * -1 for `default` (the stored sentinel, see the selector's value mapping);
+ * `undefined` when the option is not numeric.
+ */
+export declare function numericOption(value: string): number | undefined;
+/**
+ * Number hint: a numeric setting whose choices are all numbers (or the
+ * `default` sentinel) edits as a stepper through those values on a native
+ * settings page. Returns the steps (number → label), else `undefined`.
+ */
+export declare function numberSteps(def: SettingDef): Record<string, string> | undefined;
 /** Format a setting's declared default for display. */
 export declare function getDisplayDefault(entries: readonly SettingsDisplayEntry[], path: string): string;
 export {};

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

@@ -6,6 +6,7 @@ import type { ContextLineMode, StatusLinePreset, StatusLineSegmentId, StatusLine
 import { type SettingsHost } from "./settings-defs.js";
 import { type ComposerPreviewStatusSource } from "./composer-shape-preview.js";
 import { type PluginSettingsHost } from "./plugin-settings.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 /**
  * Dynamic context for settings that need runtime data.
  * Some settings (like thinking level) are managed by the session, not Settings.
@@ -50,6 +51,8 @@ export interface SettingsCallbacks {
     onStatusLinePreview?: (settings: StatusLinePreviewSettings) => void;
     /** Get current rendered status line for inline preview */
     getStatusLinePreview?: () => string;
+    /** Native status bar for the inline preview (TSP terminals dock the bar; its ANSI border geometry doesn't apply) */
+    describeStatusLinePreview?: () => NativeNode;
     /** Called when plugins change */
     onPluginsChanged?: () => void | Promise<void>;
     /** Called when settings panel is closed */
@@ -69,5 +72,23 @@ export declare class SettingsSelectorComponent implements Component {
      * then a footer hint pinned above the bottom border.
      */
     render(width: number): readonly string[];
+    /**
+     * Over a live session the native page is its own sheet: the backend puts
+     * it in `layer`, where a terminal with the `aside` feature docks it at the
+     * pane's right edge with the transcript beside it. Without `aside` it
+     * fills a screen surface instead.
+     */
+    nativeSheet(cx: DescribeContext): boolean;
+    /**
+     * The native settings page (`prefs`) when the terminal draws it, else the
+     * root card of today's generic composition.
+     */
+    describe(cx: DescribeContext): NativeNode;
+    /**
+     * Native page events (the root node, see {@link #handlePrefsEvent}); in the
+     * generic composition a tab pick does what a tab click does: switch tabs (or
+     * jump, while searching), unless an open submenu owns the pointer.
+     */
+    handleNativeEvent(event: NativeUiEvent): void;
     handleInput(data: string): void;
 }

package/dist/types/overlays/show-images-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 show images selector with borders
  */
 export declare class ShowImagesSelectorComponent extends OverlayPanel {
     #private;
     constructor(currentValue: boolean, onSelect: (show: boolean) => 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;
 }

package/dist/types/overlays/snapcompact-shape-preview.d.ts

@@ -14,6 +14,7 @@
  */
 import { type Component, type ImageBudget } from "../index.js";
 import { type ShapeTarget } from "@oh-my-pi/snapcompact";
+import type { DescribeContext, NativeNode } from "../native/node.js";
 export interface SnapcompactShapePreviewOptions {
     /** Active model (api + id); resolves what `auto` maps to for this reader. */
     model?: ShapeTarget;
@@ -27,5 +28,6 @@ export declare class SnapcompactShapePreview implements Component {
     constructor(currentValue: string, options?: SnapcompactShapePreviewOptions);
     /** Track the highlighted option; the next render reflects it. */
     setValue(value: string): void;
+    describe(cx: DescribeContext): NativeNode;
     render(width: number): readonly string[];
 }

package/dist/types/overlays/stats-notice.d.ts

@@ -0,0 +1,8 @@
+import { Container } from "../tui.js";
+import type { NativeNode } from "../native/node.js";
+export declare class StatsNotice extends Container {
+    #private;
+    /** `message` is the launch status line; `url` the dashboard address. */
+    constructor(message: string, url: string);
+    describe(): NativeNode;
+}

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

@@ -1,5 +1,13 @@
 import { SelectList, type SgrMouseEvent } from "../index.js";
 import { OverlayPanel } from "../chrome/overlay-box.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
+import { type SelectPickerOptions } from "../native/picker.js";
+/**
+ * Picker options for a theme list (this selector and the settings theme
+ * submenu): a swatch `mark` seeded by the theme id, the current theme dotted,
+ * `Apply ⏎`. Moving the selection previews through the list's `onSelectionChange`.
+ */
+export declare function themePickerOptions(title: string, current: string): SelectPickerOptions;
 /**
  * Component that renders a theme selector.
  * Themes must be pre-loaded and passed to the constructor.
@@ -7,6 +15,9 @@ import { OverlayPanel } from "../chrome/overlay-box.js";
 export declare class ThemeSelectorComponent extends OverlayPanel {
     #private;
     constructor(currentTheme: string, themes: string[], onSelect: (themeName: string) => void, onCancel: () => void, onPreview: (themeName: string) => 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;
 }

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

@@ -1,12 +1,16 @@
 import type { Effort } from "@oh-my-pi/pi-ai";
 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 thinking level selector with borders
  */
 export declare class ThinkingSelectorComponent extends OverlayPanel {
     #private;
     constructor(currentLevel: Effort, availableLevels: Effort[], onSelect: (level: Effort) => 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;
 }

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

@@ -1,4 +1,4 @@
-import { type Component } from "../index.js";
+import { type Component, Input } from "../index.js";
 /** Available session-tree display filters. */
 export declare const TREE_FILTER_MODES: readonly ["default", "no-tools", "user-only", "labeled-only", "all"];
 /** Session-tree display filter. */
@@ -57,12 +57,29 @@ export interface TreeSelectorNode {
     label?: string;
 }
 import { OverlayPanel } from "../chrome/overlay-box.js";
+import type { TspPickerItem, TspText } from "@oh-my-pi/pi-wire";
+import type { DescribeContext, NativeChild, NativeNode, NativeUiEvent } from "../native/node.js";
 /** Filter mode for tree display */
 type FilterMode = TreeFilterMode;
+/** The session tree's `picker` data (see {@link TreeList.pickerView}). */
+interface TreePickerView {
+    items: readonly TspPickerItem[];
+    order: readonly string[];
+    selected: string | null;
+    current: readonly string[];
+    query: string;
+    /** UTF-16 caret into `query`. */
+    cursor: number;
+    filterMode: FilterMode;
+    total: number;
+    empty: TspText;
+}
 declare class TreeList implements Component {
     #private;
     private readonly currentLeafId;
     private readonly maxVisibleLines;
+    /** The search field; its value is the fuzzy query. */
+    readonly searchInput: Input;
     onSelect?: (entryId: string, options: {
         summarize: boolean;
     }) => void;
@@ -72,9 +89,43 @@ declare class TreeList implements Component {
     invalidate(): void;
     dispose(): void;
     getSearchQuery(): string;
+    getFilterMode(): FilterMode;
+    /** Native filter tab: switch to that mode, like its alt+key shortcut. */
+    setFilterMode(mode: string): void;
+    /** Native click on an entry: highlight it, then the same outcome as Enter. */
+    activateEntry(entryId: string): void;
+    /** Native row click: highlight the entry without switching. */
+    selectEntry(entryId: string): void;
+    /**
+     * The `tree` picker's data. `items` is every structural entry, rebuilt
+     * only when the tree or a label changes; filter modes and typing change
+     * only `order` (the visible entries) and the selection.
+     */
+    pickerView(): TreePickerView;
+    /**
+     * Preview of the selected entry: a title, its label, and its content as
+     * the transcript shows it (markdown prose, commands and output as code).
+     */
+    pickerPreview(): readonly NativeChild[];
+    /**
+     * The visible entries as a native `list` keyed `"list"`, items keyed by
+     * entry id. Selection stays omp's; the terminal scrolls and virtualizes.
+     * Branch heads carry a `branch` icon and the active path an accent bullet
+     * instead of drawn tree connectors.
+     */
+    describeList(): NativeNode;
     getSelectedNode(): TreeSelectorNode | undefined;
     updateNodeLabel(entryId: string, label: string | undefined): void;
     render(width: number): readonly string[];
+    /** Enter (`summarize` false) / Shift+Enter: switch to the selected entry. */
+    confirm(summarize: boolean): void;
+    /** Esc: clear the search first, then close. */
+    escape(): void;
+    clearSearch(): void;
+    /** Ctrl+O / Shift+Ctrl+O: default → no-tools → user-only → labeled-only → all → default. */
+    cycleFilter(delta: 1 | -1): void;
+    /** Shift+L: edit the selected entry's label. */
+    editLabel(): void;
     handleInput(keyData: string): void;
 }
 /**
@@ -83,9 +134,16 @@ declare class TreeList implements Component {
 export declare class TreeSelectorComponent extends OverlayPanel {
     #private;
     private readonly onLabelChangeCallback?;
+    /** The picker's subtitle. */
+    private readonly sessionName?;
     constructor(tree: TreeSelectorNode[], currentLeafId: string | null, terminalHeight: number, onSelect: (entryId: string, options: {
         summarize: boolean;
-    }) => void, onCancel: () => void, onLabelChangeCallback?: ((entryId: string, label: string | undefined) => void) | undefined, initialFilterMode?: FilterMode);
+    }) => void, onCancel: () => void, onLabelChangeCallback?: ((entryId: string, label: string | undefined) => void) | undefined, initialFilterMode?: FilterMode, 
+    /** The picker's subtitle. */
+    sessionName?: string | undefined);
+    describe(cx: DescribeContext): NativeNode;
+    /** Filter tab → switch mode; entry click → highlight it and switch, exactly like Enter. */
+    handleNativeEvent(event: NativeUiEvent): void;
     handleInput(keyData: string): void;
     getTreeList(): TreeList;
 }

package/dist/types/overlays/usage-dashboard.d.ts

@@ -1,5 +1,6 @@
 import { type UsageLimit, type UsageReport } from "@oh-my-pi/pi-ai";
 import { type Component } from "../index.js";
+import { type DescribeContext, type NativeNode, type NativeUiEvent } from "../native/node.js";
 /** Local calendar-day activity consumed by the usage heatmap. */
 export interface DailyActivityPoint {
     day: string;
@@ -63,6 +64,8 @@ export interface HeatmapLayout {
     cells: (number | null)[][];
     totalCost: number;
     totalRequests: number;
+    /** Local midnight of the first cell (column 0, Monday). */
+    start: Date;
 }
 export declare const HEATMAP_DAY_LABELS: string[];
 /**
@@ -79,10 +82,10 @@ export interface UsageDashboardOptions {
     reports: UsageReport[];
     unavailableAccounts?: readonly UnavailableUsageAccount[];
     /**
-     * Full classic `/usage` report for the expanded detail view; re-invoked per
-     * terminal width.
+     * Full classic `/usage` report of `reports` (the latest refresh) for the
+     * expanded detail view; re-invoked per terminal width.
      */
-    renderDetail: (width: number) => string;
+    renderDetail: (width: number, reports: UsageReport[]) => string;
     /**
      * Stream daily activity into the heatmap: push cached DB rows immediately,
      * then push again after an incremental session sync. Resolves when the sync
@@ -90,6 +93,8 @@ export interface UsageDashboardOptions {
      * the dashboard closes so an in-flight sync can stop early.
      */
     loadActivity: (push: (points: DailyActivityPoint[]) => void, signal: AbortSignal) => Promise<void>;
+    /** Re-fetch the usage reports (`r`); omitted when the host can't. Resolves null when nothing came back. */
+    refresh?: () => Promise<UsageReport[] | null>;
     requestRender: () => void;
     onClose: () => void;
 }
@@ -101,9 +106,27 @@ export interface UsageDashboardOptions {
 export declare function formatActivityErrorDetail(error: string, homeDir?: string): string;
 export declare class UsageDashboardComponent implements Component {
     #private;
+    /** The terminal draws the sheet: a large glass overlay titled Usage. */
+    readonly nativeOverlay: {
+        readonly role: "omp.overlay.usage";
+        readonly size: "lg";
+        readonly anchor: "center";
+        readonly head: "Usage";
+    };
     constructor(options: UsageDashboardOptions);
     invalidate(): void;
     dispose(): void;
     render(width: number): readonly string[];
+    /**
+     * The sheet body (the terminal's `lg` overlay is the frame): a head row
+     * (checked ago, Overview/Details tabs, Refresh), then either the provider
+     * grid of frames with window meters and the activity heatmap, or the
+     * per-provider detail tables. `meter`/`chart` fall back to
+     * `progress`/`table` on terminals without them. Rebuilt only when its
+     * inputs change.
+     */
+    describe(cx: DescribeContext): NativeNode;
+    /** Tab clicks switch views like Enter/Esc; the Refresh button runs `r`. */
+    handleNativeEvent(event: NativeUiEvent): void;
     handleInput(data: string): void;
 }

package/dist/types/overlays/usage-row.d.ts

@@ -1,5 +1,5 @@
-import type { Usage } from "@oh-my-pi/pi-ai";
-import { Container } from "../index.js";
+import type { AssistantMessage, Usage } from "@oh-my-pi/pi-ai";
+import { Container } from "../tui.js";
 /**
  * Prompt→yield wall time for a turn, from pure local timestamps: the user
  * prompt's timestamp to the response's completion time (`completedAt`, stamped
@@ -10,6 +10,40 @@ import { Container } from "../index.js";
 export declare function turnElapsedMs(turnStartedAt: number | undefined, message: {
     completedAt?: number;
 }): number | undefined;
+/** A finished turn's totals, the native `omp.turn.usage` line under its last answer. */
+export interface TurnUsageSummary {
+    /** Prompt→yield wall time; undefined when either end is unknown. */
+    readonly elapsedMs: number | undefined;
+    /**
+     * Prompt tokens: input, cache writes and orchestration input. Cache reads
+     * re-read the context each request, so they stay out (as in the status
+     * line's total).
+     */
+    readonly input: number;
+    /** Output tokens, orchestration output included. */
+    readonly output: number;
+    /** Billed cost in dollars. */
+    readonly cost: number;
+}
+/**
+ * Sums the requests of a turn. {@link add} returns the turn's summary on the
+ * message that ends the run (any stop but `toolUse`) and starts over.
+ */
+export declare class TurnUsageTally {
+    #private;
+    /** Drop a partial turn (a new prompt, a fresh run). */
+    reset(): void;
+    add(message: AssistantMessage, turnStartedAt: number | undefined): TurnUsageSummary | undefined;
+}
+/**
+ * The native turn line: `12.4s · 19K tok · $0.02 this turn` (the time drops
+ * out when unknown, the cost when nothing was billed), and its tooltip with
+ * exact counts.
+ */
+export declare function formatTurnUsage(summary: TurnUsageSummary): {
+    text: string;
+    title: string;
+};
 /** Format the metrics shared by standalone usage blocks and compact tool groups. */
 export declare function formatUsageRow(usage: Usage, durationMs?: number, ttftMs?: number, timestamp?: number, turnElapsedMs?: number): string;
 /** Whether `component` is a per-turn usage/metrics row from {@link createUsageRowBlock}. */

package/dist/types/prompt/attachment-chips.d.ts

@@ -1,4 +1,5 @@
 import { type Component, type ImageBudget } from "../index.js";
+import type { DescribeContext, NativeNode } from "../native/node.js";
 import type { CustomEditor } from "./custom-editor.js";
 /**
  * The composer attachment band: one rounded card per staged attachment, rendered directly above
@@ -15,5 +16,12 @@ export declare class AttachmentChipsBand implements Component {
     private readonly budget;
     private readonly requestRender;
     constructor(editor: CustomEditor, budget: ImageBudget, requestRender: () => void);
+    /**
+     * A wrapping `row` of chip `card`s (`omp.composer.chip`) titled with the
+     * buffer token (`<icon> #N`): images and videos show the image itself,
+     * pastes their leading lines; the caption carries pixel size or line/char
+     * count. Hidden while nothing is staged.
+     */
+    describe(_cx: DescribeContext): NativeNode;
     render(width: number): readonly string[];
 }

package/dist/types/prompt/composer-attachments.d.ts

@@ -46,8 +46,16 @@ export declare const COMPOSER_TOKEN_REGEX: RegExp;
 export declare function referencedAttachments(text: string, recorded: ReadonlyMap<string, ChipKind>): Record<ChipKind, Set<number>>;
 /** Add the registered model-chip labels to the composer placeholder matcher. */
 export declare function composerTokenRegex(mentionLabels: Iterable<string>): RegExp;
-/** Offsets image marker indices, including matching `attachment://` references. */
-export declare function shiftImageMarkers(text: string, offset: number): string;
+/** Marker for the Nth attached image or video preview: `[Image #N, WxH]`, or `[Image #N]` without dims. */
+export declare function formatVisionMarker(kind: "image" | "video", n: number, dims?: {
+    width: number;
+    height: number;
+}): string;
+/**
+ * Offsets image marker indices, including matching `attachment://` references. With `imageCount`,
+ * markers above it are left alone: like `compactImageMarkers`, they are not this text's attachments.
+ */
+export declare function shiftImageMarkers(text: string, offset: number, imageCount?: number): string;
 /**
  * Replaces valid expanded image markers with compact tokens and registers each
  * token's original marker as its atomic editor expansion.
@@ -56,8 +64,12 @@ export declare function collapseImageMarkers(text: string, imageCount: number, r
 /**
  * Drops unreferenced vision attachments from a submission and densely remaps
  * retained image/video markers. Returns `null` when no compaction is needed.
+ * With `byAppearance`, retained markers are also renumbered in the order they first
+ * appear, for editors whose images attach out of order (concurrent path loads).
  */
-export declare function compactImageMarkers(text: string, imageCount: number): {
+export declare function compactImageMarkers(text: string, imageCount: number, options?: {
+    byAppearance?: boolean;
+}): {
     text: string;
     keep: number[];
 } | null;

package/dist/types/prompt/composer.d.ts

@@ -3,6 +3,7 @@ import type { StatusLineSession } from "../status-line/host.js";
 import { type StatusLineStartupData } from "../status-line/startup.js";
 import { type Terminal } from "../terminal.js";
 import { type Component, type ResizeScrollbackMode, type TerminalFramePlan, type TerminalFrameProvider, TUI, type TUIOptions, type ViewportSize } from "../tui.js";
+import type { NativeSurface, NativeSurfaceProvider } from "../native/node.js";
 import { CustomEditor } from "./custom-editor.js";
 import type { WordCompletionMethod } from "./word-completion.js";
 import { type LspServerInfo, type RecentSession, WelcomeComponent } from "./welcome.js";
@@ -64,6 +65,13 @@ export interface RuntimeChildrenOptions {
      * settled rows it displaces retire to native scrollback.
      */
     readonly transient?: readonly Component[];
+    /**
+     * Dock order on a TSP terminal (no status strip; the composer carries its
+     * facts): the native dock stacks HUD pills, the working row and queued messages over
+     * the composer in its own order, and may add describe-only roots. Defaults
+     * to the roots below the transcript in render order.
+     */
+    readonly nativeDock?: readonly Component[];
 }
 /** Controls the first terminal paint for a composer that does not already own the terminal. */
 export interface ComposerStartOptions {
@@ -108,12 +116,21 @@ export declare const PINNED_HUD_TOGGLE_ID = "@omp:toggle-pinned-hud";
  * It owns the terminal, welcome header, and editor; InteractiveMode later supplies authoritative
  * data and mounts the session-aware runtime children without replacing the visible header.
  */
-export declare class Composer implements TerminalFrameProvider {
+export declare class Composer implements TerminalFrameProvider, NativeSurfaceProvider {
     #private;
     readonly ui: TUI;
     constructor(options?: ComposerOptions);
     /** Compose the bounded mutable viewport and the next ordered history append. */
     renderFrame(viewport: ViewportSize): TerminalFramePlan;
+    /**
+     * Describe the whole surface for a TSP terminal. `main` is the flowing
+     * document: the header (welcome, extras) and every transcript block as its
+     * own component child. `dock` is the live chrome below the transcript in
+     * render order: pending messages, HUDs, the working row, the editor and the
+     * status line. There is no history/viewport split: retirement, resize
+     * replay and hover bands are ANSI concerns.
+     */
+    describeSurface(): NativeSurface;
     /**
      * Candidate subagent ids under a mutable-viewport line, for click-to-focus.
      * Empty when the line has no click target (chrome, separators, retired rows