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

package/dist/types/chat/tool-execution.d.ts

@@ -1,5 +1,7 @@
 import type { AgentTool } from "@oh-my-pi/pi-agent-core";
 import { type Component, Container, type TUI } from "../tui.js";
+import { type DescribeContext, type NativeNode, type NativeUiEvent } from "../native/node.js";
+import type { FileDiagnosticsResult } from "../tools/lsp.js";
 import { type AnimationFrame } from "../chrome/transcript-container.js";
 /** Resolves the canonical renderer key while retaining the provider's wire name in message history. */
 export declare function toolRenderName(wireName: string, tool: AgentTool | undefined): string;
@@ -51,7 +53,7 @@ export declare function stopSharedSpinnerTicker(): void;
  */
 export declare class ToolExecutionComponent extends Container {
     #private;
-    constructor(toolName: string, args: unknown, options: ToolExecutionOptions | undefined, tool: AgentTool | undefined, ui: ToolExecutionUi, _cwd?: string, _toolCallId?: string);
+    constructor(toolName: string, args: unknown, options: ToolExecutionOptions | undefined, tool: AgentTool | undefined, ui: ToolExecutionUi, _cwd?: string, toolCallId?: string);
     updateArgs(args: unknown, _toolCallId?: string): void;
     /**
      * Signal that args are complete (tool is about to execute).
@@ -129,6 +131,28 @@ export declare class ToolExecutionComponent extends Container {
      */
     stopAnimation(): void;
     setExpanded(expanded: boolean): void;
+    /** Mirrors the card collapsed or expanded in the terminal, so `Ctrl+O` and native toggles share one state. */
+    handleNativeEvent(event: NativeUiEvent): void;
+    /** Whether this call targets `filePath` (the late-diagnostics router matches with it). */
+    matchesPath(filePath: string): boolean;
+    /**
+     * Attaches LSP diagnostics that arrived after the result into this call's
+     * frame (§7.3: a diagnostics section plus a count chip in the head). Native
+     * rendering only; returns false when nothing matched, so the caller shows
+     * its standalone notice instead.
+     */
+    attachLateDiagnostics(files: readonly (FileDiagnosticsResult & {
+        readonly path: string;
+    })[]): boolean;
+    /**
+     * The tool card: `card` role `omp.tool.<name>` with the renderer's
+     * {@link NativeToolView} (head spans, body nodes), a status chip, an
+     * `elapsed` timer in the head and terminal-local collapse clamped to the
+     * view's preview. Renderers without describe hooks (and extension tools
+     * with only render hooks) get the generic card. Hidden tool activity stays
+     * mounted so toggling it is one prop change.
+     */
+    describe(cx?: DescribeContext): NativeNode;
     /** Apply the transcript allocator's current viewport reservation. */
     setTranscriptAllocation(rows: number, frame: AnimationFrame): void;
     setToolActivityVisible(visible: boolean): void;

package/dist/types/chat/transcript-actions.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Pointer actions on transcript blocks in a native terminal (a user message's
+ * hover toolbar, an error frame's action row). Blocks describe the controls;
+ * the interactive host registers the one handler that runs omp's existing
+ * commands for them, so a click and the key binding take the same path.
+ */
+export type TranscriptAction = 
+/** Retry the last failed turn (`app.retry`). */
+{
+    readonly act: "retry";
+}
+/** Open the temporary model picker (`app.model.selectTemporary`). */
+ | {
+    readonly act: "switch-model";
+}
+/** Open the transcript rewind selector. */
+ | {
+    readonly act: "rewind";
+}
+/** Resume the session stored at `path` (a welcome card's recent session). */
+ | {
+    readonly act: "resume";
+    readonly path: string;
+}
+/** Put `text` on the clipboard. */
+ | {
+    readonly act: "copy";
+    readonly text: string;
+};
+type Handler = (action: TranscriptAction) => void;
+/** Register (or clear, with `undefined`) the host's handler. */
+export declare function setTranscriptActionHandler(next: Handler | undefined): void;
+/** Run `action` through the host; false when no host handles actions. */
+export declare function runTranscriptAction(action: TranscriptAction): boolean;
+/** Whether a host handles actions (controls are only described when one does). */
+export declare function hasTranscriptActions(): boolean;
+export {};

package/dist/types/chat/transcript-entry.d.ts

@@ -1,5 +1,5 @@
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
-import type { MessageAttribution } from "@oh-my-pi/pi-ai";
+import type { ImageContent, MessageAttribution, TextContent } from "@oh-my-pi/pi-ai";
 import { type CustomMessage, type CustomMessageContent } from "./messages.js";
 /** Persisted message fields consumed by transcript rendering. */
 export interface SessionMessageEntryLike {
@@ -47,6 +47,8 @@ export declare function textContent(content: string | ReadonlyArray<{
     type: string;
     text?: string;
 }>, separator?: string): string;
+/** Well-formed image blocks in order: a `[Image #N]` marker in the text names the Nth. */
+export declare function imageContent(content: string | ReadonlyArray<TextContent | ImageContent>): ImageContent[];
 /** Join text blocks with spaces and collapse whitespace into a single-line label. */
 export declare function userMessageLabel(content: string | ReadonlyArray<{
     type: string;

package/dist/types/chat/user-message.d.ts

@@ -1,15 +1,21 @@
 import { type Component, Container } from "../tui.js";
+import type { ImageContent } from "@oh-my-pi/pi-ai";
 import type { ReactionTarget } from "./reaction.js";
+import { type NativeNode, type NativeUiEvent } from "../native/node.js";
 /** How a user bubble styles its prose and chips (see {@link userBubbleColor}). */
 export interface UserBubbleOptions {
     /** Materialized `file://` targets per attached image, indexed by chip number. */
     imageLinks?: readonly (string | undefined)[];
+    /** The message's attached images in chip order (`#1` first); a native bubble shows them. */
+    images?: readonly ImageContent[];
     /** Agent-attributed input: dim, flat prose. */
     synthetic?: boolean;
     /** Delivered into the response that was streaming; marked `*` at the bubble's top-left. */
     liveSteered?: boolean;
     /** SKILL.md path for a skill chip by name; `undefined` leaves the chip unlinked. */
     skillPath?: (name: string) => string | undefined;
+    /** When the message was sent (ms); shown beside the native hover toolbar. */
+    timestamp?: number;
 }
 /**
  * Foreground styling for prose inside a user bubble: the bubble text color with the
@@ -28,6 +34,17 @@ export declare class UserMessageComponent extends Container implements ReactionT
     #private;
     constructor(text: string, options?: UserBubbleOptions);
     setReaction(emoji: string): void;
+    /**
+     * A head-less user-toned frame with the prompt as markdown under its
+     * attached images (titled `#N` like their chips, opening the materialized
+     * file on click): the fill says "you". A quiet toolbar (time, Copy, Rewind) fades in on hover when the
+     * host handles transcript actions. The live-steering marker and the
+     * agent's reaction are chips at the bottom-right, so a reaction landing
+     * later updates the frame in place, even deep in scrollback.
+     */
+    describe(): NativeNode;
+    /** Hover toolbar clicks: omp's own copy and rewind commands. */
+    handleNativeEvent(event: NativeUiEvent): void;
     render(width: number): readonly string[];
 }
 /**
@@ -48,6 +65,14 @@ export declare class CollapsedSyntheticMessageComponent implements Component {
     constructor(text: string, imageLinks?: readonly (string | undefined)[]);
     /** ctrl+o toggle: reveal/hide the full Markdown body. */
     setExpanded(expanded: boolean): void;
+    /**
+     * A muted collapsible card whose head is the one-line summary. The
+     * (potentially huge) markdown body is only described while expanded, so
+     * collapsed history costs no layout on either side; a native toggle
+     * expands it through {@link handleNativeEvent}.
+     */
+    describe(): NativeNode;
+    handleNativeEvent(event: NativeUiEvent): void;
     setIgnoreTight(ignore: boolean): this;
     invalidate(): void;
     dispose(): void;

package/dist/types/chrome/collab-qrcode.d.ts

@@ -1,5 +1,6 @@
 import type { Component } from "../tui.js";
 import type { AnimationFrame, TranscriptPresentationTarget } from "./transcript-container.js";
+import type { DescribeContext, NativeNode } from "../native/node.js";
 /** Scheme-less display form of a collab browser deep link, OSC-8 linked. */
 export declare function collabBrowserLink(webLink: string, label?: string): string;
 /**
@@ -23,6 +24,12 @@ export declare class CollabQrCodeComponent implements Component, TranscriptPrese
     constructor(url: string);
     setTranscriptAllocation(rows: number, _frame?: AnimationFrame): void;
     render(width: number): readonly string[];
+    /**
+     * The symbol as an unwrapped monospace block plus the join link. Glyphs are
+     * drawn in the terminal's foreground, so on a dark appearance the light
+     * modules are inked to keep the dark-on-light symbol scanners expect.
+     */
+    describe(cx: DescribeContext): NativeNode;
     /** Survives emergency 1-row transcript pressure when this block is otherwise hidden. */
     renderTranscriptBlockEmergencyRow(width: number): string;
 }

package/dist/types/chrome/context-thresholds.d.ts

@@ -1,10 +1,21 @@
+import type { TspTone } from "@oh-my-pi/pi-wire";
 import type { ThemeColor } from "../theme/index.js";
 export type ContextUsageLevel = "normal" | "warning" | "purple" | "error";
 export declare function getContextUsageLevel(contextPercent: number, contextWindow: number): ContextUsageLevel;
+/**
+ * `meter` tone switches matching {@link getContextUsageLevel}: warning from the
+ * warning level, error from the error level, as shares of `contextWindow`.
+ */
+export declare function getContextMeterThresholds(contextWindow: number): {
+    warn: number;
+    bad: number;
+};
 /**
  * Format context usage as `<percent>%/<window>` when the model window is known.
  * Unknown windows render as `<tokens>/?`, because `0.0%/0` suggests a real
  * empty context instead of missing provider metadata.
  */
 export declare function formatContextUsage(contextPercent: number | null | undefined, contextWindow: number, usedTokens?: number): string;
+/** Chrome tone for a context-usage level; undefined while usage is normal. */
+export declare function getContextUsageTone(level: ContextUsageLevel): TspTone | undefined;
 export declare function getContextUsageThemeColor(level: ContextUsageLevel): ThemeColor;

package/dist/types/chrome/countdown-timer.d.ts

@@ -1,6 +1,4 @@
-/**
- * Reusable countdown timer for dialog components.
- */
+import type { NativeNode } from "../native/node.js";
 import type { TUI } from "../tui.js";
 export declare class CountdownTimer {
     #private;
@@ -8,6 +6,14 @@ export declare class CountdownTimer {
     private onTick;
     private onExpire;
     constructor(timeoutMs: number, tui: TUI | undefined, onTick: (seconds: number) => void, onExpire: () => void);
+    /**
+     * The remaining time as a terminal-clocked `elapsed` node: its age is the
+     * negative remaining time (the start lies in the future), so it counts up
+     * toward zero and freezes there at expiry. The age is taken on the first
+     * call after a (re)start, when the node is first written, and the node is
+     * reused until {@link reset}.
+     */
+    describe(): NativeNode;
     /** Reset the countdown to its initial value */
     reset(): void;
     dispose(): void;

package/dist/types/chrome/diff.d.ts

@@ -1,4 +1,16 @@
+import type { TspProps } from "@oh-my-pi/pi-wire";
 import { type Theme } from "../theme/index.js";
+import type { NativeNode } from "../native/node.js";
+/**
+ * Native `diff` node for omp's compact diff text (`+12|added`, `-12|removed`,
+ * ` 12|context`, blank or `…` rows between regions). Each contiguous region
+ * becomes one hunk; the terminal draws gutters, word emphasis and highlighting.
+ * Removed rows carry old line numbers, added rows new ones and context rows
+ * old ones, so the other side is derived from the running line delta.
+ */
+export declare function nativeDiff(diffText: string, options?: {
+    filePath?: string;
+} & TspProps<"diff">): NativeNode;
 export interface RenderDiffOptions {
     /** File path used to resolve indentation (.editorconfig + defaults) */
     filePath?: string;

package/dist/types/chrome/dynamic-border.d.ts

@@ -1,4 +1,5 @@
 import type { Component } from "../tui.js";
+import type { NativeNode } from "../native/node.js";
 /**
  * Dynamic border component that adjusts to viewport width.
  *
@@ -12,5 +13,7 @@ export declare class DynamicBorder implements Component {
     #private;
     constructor(color?: (str: string) => string);
     invalidate(): void;
+    /** Native terminals draw their own chrome; a border rule describes nothing. */
+    describe(): NativeNode;
     render(width: number): readonly string[];
 }

package/dist/types/chrome/format.d.ts

@@ -1,9 +1,15 @@
 import { type Theme } from "../theme/theme.js";
+import type { NativeNode } from "../native/node.js";
 /** Title-case a provider id for display (`openai-codex` → `Openai Codex`). */
 export declare function formatProviderName(provider: string): string;
 /** Format a millisecond duration as a coarse-grained human label. */
 export declare function formatCoarseDuration(ms: number): string;
 type ProgressBarTheme = Pick<Theme, "bold" | "fg" | "getFgAnsi">;
+/**
+ * Native {@link renderAsciiBar}: a terminal-drawn progress bar with the same
+ * percent label; `undefined` is indeterminate.
+ */
+export declare function describeAsciiBar(fraction: number | undefined): NativeNode;
 /**
  * Render an ASCII progress bar with a trailing percent label.
  * `fraction` is clamped to `[0, 1]`. `undefined` renders a dotted placeholder.

package/dist/types/chrome/message-divider.d.ts

@@ -1,5 +1,6 @@
 import type { Component } from "../tui.js";
 import { type ThemeColor } from "../theme/index.js";
+import type { NativeNode } from "../native/node.js";
 /** Presentation policy for a compact message divider. */
 export interface MessageDividerOptions {
     /** Theme-aware label, recomputed after invalidation. */
@@ -9,6 +10,16 @@ export interface MessageDividerOptions {
     readonly ruleWidth?: number;
     /** Preserve an intentionally untruncated legacy label at very narrow widths. */
     readonly truncateWhenNarrow?: boolean;
+    /** Semantic role of the native node. */
+    readonly role?: string;
+    /**
+     * Draw as an inline notice (this named icon and a one-line label without
+     * the leading glyph) instead of a labelled rule.
+     */
+    readonly native?: {
+        readonly icon: string;
+        readonly label: () => string;
+    };
 }
 /**
  * A short left-aligned rule and label surrounded by blank transcript rows.
@@ -18,5 +29,7 @@ export declare class MessageDividerComponent implements Component {
     #private;
     constructor(options: MessageDividerOptions);
     invalidate(): void;
+    /** An inline notice, else a labelled `rule`; the label is theme-aware, so it rebuilds on theme changes. */
+    describe(): NativeNode;
     render(width: number): readonly string[];
 }

package/dist/types/chrome/message-frame.d.ts

@@ -10,6 +10,7 @@
 import type { TextContent } from "@oh-my-pi/pi-ai";
 import { type Component, Container } from "../tui.js";
 import { type Theme, type ThemeColor } from "../theme/index.js";
+import { type NativeNode, type NativeUiEvent } from "../native/node.js";
 /** Message shape consumed by the shared frame. */
 export interface FramedMessage {
     customType: string;
@@ -37,6 +38,8 @@ export interface FramedMessageOptions<M extends FramedMessage> {
     /** Collapse the markdown body to this many lines when `expanded` is false. Omit to never collapse. */
     readonly collapseAfterLines?: number;
     readonly customRenderer?: FramedRenderer<M>;
+    /** Semantic role of the native card. */
+    readonly role: string;
 }
 /**
  * Behavior-owning custom message frame. It retries extension renderers whenever
@@ -49,4 +52,11 @@ export declare class FramedMessageComponent<M extends FramedMessage> extends Con
     setExpanded(expanded: boolean): void;
     invalidate(): void;
     dispose(): void;
+    /**
+     * The extension renderer's component when it supplied one; otherwise a
+     * card with the type tag as its head and the markdown body, clamped by the
+     * terminal while collapsed.
+     */
+    describe(): NativeNode;
+    handleNativeEvent(event: NativeUiEvent): void;
 }

package/dist/types/chrome/message-notice.d.ts

@@ -1,5 +1,7 @@
+import type { TspPreview, TspText } from "@oh-my-pi/pi-wire";
 import { type Component, Container } from "../tui.js";
 import { type ThemeColor } from "../theme/index.js";
+import { type NativeChild, type NativeNode, type NativeUiEvent } from "../native/node.js";
 /** Render-time state supplied to a notice presentation. */
 export interface MessageNoticeContext {
     readonly expanded: boolean;
@@ -10,9 +12,27 @@ export interface MessageNoticePresentation {
     readonly icon?: string;
     readonly body?: Component | readonly Component[];
 }
+/** Semantic notice content for native terminals: the card head and body, never pre-styled rows. */
+export interface MessageNoticeNativePresentation {
+    readonly head: TspText;
+    readonly body?: readonly NativeChild[];
+    /** Body clamp while collapsed; set to make the notice collapsible. */
+    readonly preview?: TspPreview;
+    /**
+     * Draw as an inline notice (a named icon and one line, the body a
+     * disclosure below it) instead of a toned card.
+     */
+    readonly inline?: {
+        readonly icon: string;
+    };
+}
 /** Presentation policy for a transcript notice. */
 export interface MessageNoticeOptions {
     readonly presentation: (context: MessageNoticeContext) => MessageNoticePresentation;
+    /** Card content for native terminals; the full content, since collapse is the terminal's. */
+    readonly nativePresentation: () => MessageNoticeNativePresentation;
+    /** Semantic role of the native card (`omp.notice.<name>`). */
+    readonly role: string;
     readonly severity?: ThemeColor;
     readonly background?: (text: string) => string;
     readonly leadingSpace?: boolean;
@@ -32,4 +52,7 @@ export declare class MessageNoticeComponent extends Container {
     invalidate(): void;
     dispose(): void;
     render(width: number): readonly string[];
+    /** A severity-toned card; collapse is local to the terminal and mirrored through {@link handleNativeEvent}. */
+    describe(): NativeNode;
+    handleNativeEvent(event: NativeUiEvent): void;
 }

package/dist/types/chrome/overlay-box.d.ts

@@ -6,6 +6,7 @@
  * (rounded corners, sharp tee/cross junctions) and the `border`/`accent` theme
  * colors so all outlined overlays read identically.
  */
+import type { DescribeContext, NativeNode } from "../native/node.js";
 import { type Component } from "../tui.js";
 import { type ThemeColor } from "../theme/index.js";
 /** Top border with an optional title inset into the rule. `color` recolors border and title (default border/accent). */
@@ -39,9 +40,10 @@ export declare class PanelRows implements Component {
     invalidate(): void;
     render(width: number): readonly string[];
 }
-/** Sentinel child rendered by {@link OverlayPanel} as a `├───┤` section rule. */
+/** Sentinel child rendered by {@link OverlayPanel} as a `├───┤` section rule (a `rule` natively). */
 export declare class PanelDivider implements Component {
     render(): readonly string[];
+    describe(): NativeNode;
 }
 /**
  * Rounded-box container for inline overlays (selectors, run panels). Children
@@ -49,11 +51,17 @@ export declare class PanelDivider implements Component {
  * so inline overlays share the chrome of fullscreen overlays. The top border
  * is exactly one row — `routeMouse` offsets written for a one-line top rule
  * stay valid — and content is inset two columns on each side.
+ *
+ * Natively the panel is a root `card` (`head` = title, `role` =
+ * `omp.overlay.<name>`) over its children; the frame is the terminal's.
+ * Subclasses whose body is not a plain child list override `describe`.
  */
 export declare class OverlayPanel implements Component {
     #private;
     children: Component[];
-    constructor(title?: string);
+    constructor(title?: string, role?: string);
+    /** The `role` of the panel's native root card. */
+    get nativeRole(): string;
     get title(): string;
     set title(value: string);
     addChild(component: Component): void;
@@ -70,5 +78,6 @@ export declare class OverlayPanel implements Component {
      * no rows here (their rule is border chrome).
      */
     renderContent(width: number): string[];
+    describe(_cx: DescribeContext): NativeNode | null;
     render(width: number): readonly string[];
 }

package/dist/types/chrome/qrcode.d.ts

@@ -39,6 +39,13 @@ export interface QrRenderOptions {
     /** Quiet-zone width in modules on every side (default 4, per spec). */
     margin?: number;
 }
+/**
+ * Render a QR symbol as plain half-block rows (no escapes) for a terminal that
+ * draws text in its own foreground color. `inkLight` draws the *light*
+ * modules (quiet zone included) as ink: on a dark background with a light
+ * foreground that yields the dark-on-light symbol cameras expect.
+ */
+export declare function renderQrText(qr: QrCode, inkLight: boolean, options?: QrRenderOptions): string[];
 /**
  * Render a QR symbol as ANSI half-block rows: each text row packs two module
  * rows via `▀`/`▄`/`█`, drawn black-on-white so a phone camera reads dark

package/dist/types/chrome/segment-track.d.ts

@@ -9,6 +9,7 @@
  * the ctrl+p role-cycle status so both surfaces read identically.
  */
 import { type ThemeColor } from "../theme/index.js";
+import type { NativeNode } from "../native/node.js";
 export interface TrackSegment {
     label: string;
 }
@@ -19,6 +20,12 @@ export interface TrackSegment {
  * modulo. Never returns an empty array: `accent` always resolves.
  */
 export declare function resolveSegmentPalette(count: number): ThemeColor[];
+/**
+ * Native {@link renderSegmentTrack}: a row of position-colored labels, the
+ * active one roled `omp.track.active` so the terminal fills it as a chip in
+ * its own color. No caps or separators travel; the terminal draws them.
+ */
+export declare function describeSegmentTrack(segments: readonly TrackSegment[], activeIndex: number): NativeNode;
 /**
  * Render `segments` as a colored chip track with `activeIndex` filled. Returns
  * a single line of styled text with no surrounding caption or arrows — callers

package/dist/types/chrome/selector-helpers.d.ts

@@ -31,12 +31,6 @@ export declare function clampSelection(selectedIndex: number, scrollOffset: numb
     selectedIndex: number;
     scrollOffset: number;
 };
-/**
- * Classify a key event for search-query text entry. Returns the single
- * printable character to append to the query, or `null` when the key is not a
- * searchable character: non-printable or multi-byte.
- */
-export declare function searchableChar(data: string): string | null;
 /**
  * Handle the shared tab-cycling keys: Tab/Right advance to the next tab,
  * Shift+Tab/Left to the previous. Invokes `switchTab` with the direction and

package/dist/types/chrome/status-notice.d.ts

@@ -0,0 +1,14 @@
+import type { NativeNode } from "../native/node.js";
+import { Container } from "../tui.js";
+/**
+ * A transient status notice (`showStatus`: "Thinking blocks: hidden", "Copied
+ * to clipboard"). The ANSI render appends a blank row and the dim line to the
+ * transcript; a native terminal shows it as a toast instead, so notices never
+ * pile up in the history. Updating the text re-shows the toast.
+ */
+export declare class StatusNotice extends Container {
+    #private;
+    constructor(message: string, styleFn?: (text: string) => string);
+    setMessage(message: string, styleFn?: (text: string) => string): void;
+    describe(): NativeNode;
+}

package/dist/types/chrome/streaming-panel.d.ts

@@ -1,4 +1,5 @@
 import { type Component, Container } from "../tui.js";
+import type { NativeNode } from "../native/node.js";
 /** One refresh of a streaming overlay's presentation. */
 export interface StreamingPanelPresentation {
     /** Non-empty sections separated by one blank row. */
@@ -15,5 +16,7 @@ export declare class StreamingPanelContent extends Container {
     constructor(presentation: () => StreamingPanelPresentation);
     /** Rebuild sections and the footer from controller-owned state. */
     refresh(): void;
+    /** The sections as a spaced stack followed by the footer; spacing is the terminal's. */
+    describe(): NativeNode;
     invalidate(): void;
 }

package/dist/types/chrome/tool-activity.d.ts

@@ -1,4 +1,5 @@
 import { type Component, Container } from "../tui.js";
+import type { NativeNode } from "../native/node.js";
 export interface ToolActivityComponent {
     setToolActivityVisible(visible: boolean): void;
 }
@@ -14,4 +15,6 @@ export declare class ToolActivityContainer extends Container implements ToolActi
      */
     setExpanded(expanded: boolean): void;
     render(width: number): readonly string[];
+    /** The wrapped children; hidden tool activity stays mounted so toggling it is one prop change. */
+    describe(): NativeNode;
 }

package/dist/types/chrome/transcript-container.d.ts

@@ -1,4 +1,5 @@
 import { type Component, Container, type HistoryBatch } from "../tui.js";
+import type { NativeNode } from "../native/node.js";
 /** Shared animation time supplied by the constrained transcript root. */
 export interface AnimationFrame {
     readonly tick: number;
@@ -139,6 +140,18 @@ export declare class TranscriptContainer extends Container {
      * tail rows per resize event — never the full committed ledger.
      */
     renderTail(width: number, maxRows: number): readonly string[];
+    /**
+     * The transcript's blocks for a native (TSP) surface, one component per
+     * `main` child in transcript order; ids follow component identity, so
+     * inserts, removals (rewind, displacement) and reorders become targeted ops.
+     * Finalized blocks are settled as a hint; they stay editable, so a later
+     * expansion, late result or reaction still reaches them wherever they sit.
+     * No retirement happens on this path: the whole transcript is one document.
+     * Returns the same array while the block list is unchanged.
+     */
+    nativeBlocks(): readonly Component[];
+    /** Embedded as a child (transcript viewers): a stack of the {@link nativeBlocks}. */
+    describe(): NativeNode;
     /** Full semantic render used by exports and non-terminal commands. */
     render(width: number): readonly string[];
     /** Rendered row where a child's block begins in the last full render() (transcript deep-links). */

package/dist/types/chrome/transcript-status.d.ts

@@ -1,12 +1,24 @@
+import type { NativeNode } from "../native/node.js";
+import { type ThemeColor } from "../theme/index.js";
 import { TranscriptBlock } from "./transcript-container.js";
-/** One compact transcript status row assembled from already-styled parts. */
+/** One themed run of a status row. */
+export interface TranscriptStatusPart {
+    readonly text: string;
+    readonly color: ThemeColor;
+    /** Glyph art (tree connectors) drawn only in rows; native terminals draw their own structure. */
+    readonly rowsOnly?: boolean;
+}
+/** One compact transcript status row assembled from themed parts, joined by single spaces. */
 export interface TranscriptStatusRow {
-    readonly parts: readonly (string | undefined)[];
+    readonly parts: readonly (TranscriptStatusPart | undefined)[];
     readonly indent?: number;
 }
 /** Shared compact status-pill block used by notices and background activity. */
 export declare class TranscriptStatusBlock extends TranscriptBlock {
+    #private;
     constructor(rows: readonly TranscriptStatusRow[]);
     /** Append a supplemental line such as an artifact warning. */
-    addLine(text: string, indent?: number): void;
+    addLine(parts: readonly (TranscriptStatusPart | undefined)[], indent?: number): void;
+    /** One wrapped text line per status row. */
+    describe(): NativeNode;
 }

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

@@ -1,3 +1,4 @@
+import type { DescribeContext, NativeNode } from "../native/node.js";
 import type { Component } from "../tui.js";
 /** Box-drawing glyphs plus an optional colorizer for an outline drawn around a {@link Box}. */
 export interface BoxBorder {
@@ -29,5 +30,11 @@ export declare class Box implements Component {
     setBgFn(bgFn?: (text: string) => string): void;
     setBorder(border?: BoxBorder): void;
     invalidate(): void;
+    /**
+     * A `card` when the box has a border or background: the background token
+     * picks tone/role (user message, tool state, selection), a border colour
+     * picks the ring tone. A plain `col` otherwise. Padding is the terminal's.
+     */
+    describe(_cx: DescribeContext): NativeNode;
     render(width: number): readonly string[];
 }

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

@@ -1,3 +1,4 @@
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 import type { Component } from "../tui.js";
 /** A component slot; factory slots are constructed only when their branch is first rendered. */
 export type DisclosureSlot = Component | (() => Component);
@@ -38,5 +39,13 @@ export declare class Disclosure implements Component {
     dispose(): void;
     debugState(): Record<string, unknown>;
     get debugChildren(): readonly Component[];
+    /**
+     * A collapsible `section`. The summary (and, while collapsed, the preview)
+     * form the always-visible header child; the lazily built body is the
+     * section body and is only materialized once expanded.
+     */
+    describe(_cx: DescribeContext): NativeNode;
+    /** Mirror the terminal-local toggle into the controlled state. */
+    handleNativeEvent(event: NativeUiEvent): void;
     render(width: number): readonly string[];
 }