@oh-my-pi/pi-tui 18.10.0 → 18.10.1

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [18.10.1] - 2026-10-12
+
+### Added
+
+- `AssistantMessageComponent`'s native turn footer leads with a Copy icon (`omp.turn.copy`) and a dot instead of the clock icon; it copies the answer's text and shows when the host handles transcript actions
+
+### Changed
+
+- `UserMessageComponent`'s native hover toolbar (`omp.user.tools`) leads with Copy and Rewind icon buttons (`copy`, `rewind`) instead of text labels, then a dot and the time, like the turn usage footer
+- `ContextUsageView`'s native body (on terminals with `meter`) leads with the tokens used and the room left before auto-compaction, then one stacked bar ticked at the threshold, the breakdown as rows (`omp.context.cat`, `.cat.free`, `.cat.buffer`: swatch, name, tokens, share; the exact count in the row's `title`) and the snapcompact estimate as labelled rows (`omp.context.snap`); the blocks meter and legend `kv` are gone, and `contextUsageHead` no longer repeats the window size
+- `AskDialogComponent`'s native root is `omp.editor.ask` (collapsed: `omp.editor.ask.hidden`, the countdown, the question as `omp.ask.summary`, Skip and Show): a chosen answer is the `accent`-toned row (a check also carries the check icon) instead of the highlighted one; multi-select Other… is `omp.ask.other.check`; the question tabs check answered questions and say their keys in the strip's `title`; the countdown moves from the head to the action bar beside Hide; the preview is `omp.ask.preview`; the Review tab leads with `omp.ask.notice` and lists answers (`omp.ask.answers`) by question name with inline code mono and no `(Recommended)` suffix; option descriptions run inline code mono, notes ride the row's detail as `em`; Submit/Next's tooltip names only Enter (and Space on a multi-select)
+- `MCPAddWizard`'s native sheet asks one question per step: a phase strip (`omp.mcpAdd.progress` of `omp.mcpAdd.phase`, toned done/current/upcoming and `neutral` when no auth was needed), the question and its lead (`omp.mcpAdd.title`, `omp.mcpAdd.tag` for optional fields, `omp.mcpAdd.lead`), then a mono field with a placeholder and its rule or refusal (`omp.mcpAdd.field`, `tone: "error"`; `omp.mcpAdd.note`), choice rows with icons and mono tags (`omp.mcpAdd.choices`), status lines (`omp.mcpAdd.status`, `omp.mcpAdd.checks`, `omp.mcpAdd.error`) or the review rows (`omp.mcpAdd.summary`). Cancel, Back and Continue / Save server buttons run Ctrl+C, Esc and Enter instead of a key-hint strip. The connection test shows its own busy step, the OAuth client secret field is masked, and the review saves on Enter (no Yes/No choice)
+- `ReportPanel`'s native body carries the role `omp.report.body`
+- `HookInputComponent` describes a dock sheet (`omp.overlay.hook-input` col) like `HookEditorComponent`'s: the title's first line (`omp.hook-input.title`, the countdown as `omp.hook-input.timer`) over its further lines (`omp.hook-input.detail`), the field (`omp.hook-input.field`, `tone: "error"` while a submit was refused) with its placeholder, and Cancel / Submit buttons that run Esc / Enter; the key legend under the field is terminal-only
+- `JobsSheet`'s native body is a master–detail split (`omp.jobs.split`: `omp.jobs.master` | `omp.jobs.detail`): the job list grouped Running / Recent (`omp.jobs.group` labels), each row a type icon tinted by status with its duration, beside the selected job's status pill, live elapsed and Cancel job (`omp.jobs.status`), its task title or command (`omp.jobs.title` / `omp.jobs.command`), facts (`omp.jobs.facts`: agent, directory, pids, exit code, artifact) and output (`omp.jobs.out`, `omp.jobs.nooutput`); the footer counts running and recent jobs (`omp.jobs.summary`), and no jobs shows an empty state (`omp.jobs.empty`). Task jobs no longer draw an `agent` node here
+- `BtwHistoryPanel`'s native sheet is centered and reads like a mail reader: the questions as two-line rows (`omp.btw.history`, list `omp.btw.list` / `omp.btw.list.idle` while the answer has the keys) beside the selected thread (`omp.btw.reader` › `omp.btw.thread` › `omp.btw.turn`: `omp.btw.question` / `omp.btw.followup`, `omp.btw.meta`, `omp.btw.answer`, `omp.btw.error`), the follow-up field under the last answer (`omp.btw.composer`), and footer buttons Stop answer, Copy answer, Close and Follow up (Cancel and Send while composing) in place of the focus labels and key-hint strip; an empty history is an `md` sheet (`omp.btw.empty`)
+
+### Fixed
+
+- `CountdownTimer`'s native `elapsed` no longer sends `stopped: 0`, which froze every native countdown (extension input, selector and editor prompts) at zero from the start
+- The native backend's focus now reaches a field inside an `overlay`/`picker` sheet hoisted into the layer from a dock component (the MCP add wizard, login), so that field shows the live caret and focus ring
+- `MCPAddWizard` keeps a refused name or URL in its field, clears a stale refusal on Back, ignores a connection test that settles after the user stepped back, and Edit OAuth settings after a failed sign-in opens the settings again instead of doing nothing
+
 ## [18.10.0] - 2026-10-12
 
 ### Breaking Changes
@@ -2780,108 +2803,4 @@
 - Reserved cursor space for zero padding and corrected end-of-line cursor rendering to prevent wrap glitches
 - Corrected editor end-of-line cursor rendering assertion to use includes() instead of endsWith()
 
-## [8.2.0] - 2026-01-24
-
-### Added
-
-- Added mermaid diagram rendering engine (renderMermaidToPng) with mmdc CLI integration
-- Added terminal graphics encoding (iTerm2/Kitty) for mermaid diagrams with automatic width scaling
-- Added mermaid block extraction and deduplication utilities (extractMermaidBlocks)
-
-### Changed
-
-- Updated TypeScript configuration for better publish-time configuration handling with tsconfig.publish.json
-- Migrated file system operations from synchronous to asynchronous APIs in autocomplete provider for non-blocking I/O
-- Migrated node module imports from named to namespace imports across all packages for consistency with project guidelines
-
-### Fixed
-
-- Fixed crash when terminal becomes unavailable (EIO errors) by exiting gracefully instead of throwing
-- Fixed potential errors during emergency terminal restore when terminal is already dead
-- Fixed autocomplete race condition by tracking request ID to prevent stale suggestion results
-
-## [6.8.3] - 2026-01-21
-
-### Added
-
-- Added undo support in the editor via `Ctrl+-`
-- Added `Alt+Delete` as a delete-word-forward shortcut
-- Added configurable code block indentation for Markdown rendering
-- Added undo support in the editor via `Ctrl+-`.
-- Added configurable code block indentation for Markdown rendering.
-- Added `Alt+Delete` as a delete-word-forward shortcut.
-
-### Changed
-
-- Improved fuzzy matching to handle alphanumeric swaps
-- Normalized keybinding definitions to lowercase internally
-- Improved fuzzy matching to handle alphanumeric swaps.
-- Normalized keybinding definitions to lowercase internally.
-
-### Fixed
-
-- Added legacy terminal support for `Ctrl+` symbol key combinations
-- Added legacy terminal support for `Ctrl+` symbol key combinations.
-
-## [6.8.1] - 2026-01-20
-
-### Fixed
-
-- Fixed viewport tracking after partial renders to prevent autocomplete list artifacts
-
-## [5.6.7] - 2026-01-18
-
-### Added
-
-- Added configurable editor padding via `editorPaddingX` theme option
-- Added `setMaxHeight()` method to limit editor height with scrolling
-- Added Emacs-style kill ring for text deletion operations
-- Added `Alt+D` keybinding to delete words forward
-- Added `Ctrl+Y` keybinding to yank from kill ring
-- Added `waitForRender()` method to await pending renders
-- Added Focusable interface and hardware cursor marker support for IME positioning
-- Added support for shifted symbol keys in keybindings
-
-### Changed
-
-- Updated tab bar rendering to wrap text across multiple lines when content exceeds available width
-- Expanded Kitty keyboard protocol coverage for non-Latin layouts and legacy Alt sequences
-- Improved cursor positioning with safer bounds checking
-- Updated editor layout to respect configurable padding
-- Refactored scrolling logic for better viewport management
-
-### Fixed
-
-- Fixed key detection for shifted symbol characters
-- Fixed backspace handling with additional codepoint support
-- Fixed Alt+letter key combinations for better recognition
-
-## [5.3.1] - 2026-01-15
-
-### Fixed
-
-- Fixed rendering issues on Windows by preventing re-entrant renders
-
-## [5.1.0] - 2026-01-14
-
-### Added
-
-- Added `pageUp` and `pageDown` key support with `selectPageUp`/`selectPageDown` editor actions
-- Added `isPageUp()` and `isPageDown()` helper functions
-- Added `SizeValue` type for CSS-like overlay sizing (absolute or percentage strings like `"50%"`)
-- Added `OverlayHandle` interface with `hide()`, `setHidden()`, `isHidden()` methods for overlay visibility control
-- Added `visible` callback to `OverlayOptions` for dynamic visibility based on terminal dimensions
-- Added `pad` parameter to `truncateToWidth()` for padding result with spaces to exact width
-
-### Changed
-
-- Changed `OverlayOptions` to use `SizeValue` type for `width`, `maxHeight`, `row`, and `col` properties
-- Changed `showOverlay()` to return `OverlayHandle` for controlling overlay visibility
-- Removed `widthPercent`, `maxHeightPercent`, `rowPercent`, `colPercent` from `OverlayOptions` (use percentage strings instead)
-
-### Fixed
-
-- Fixed numbered list items showing "1." for all items when code blocks break list continuity
-- Fixed width overflow protection in overlay compositing to prevent TUI crashes
-
-Older entries are archived in [packages/tui/CHANGELOG.md@60347ef0f214](https://github.com/can1357/oh-my-pi/blob/60347ef0f214fa63df596d143477268da3f0c904/packages/tui/CHANGELOG.md).
+Older entries are archived in [packages/tui/CHANGELOG.md@89ad0a77d575](https://github.com/can1357/oh-my-pi/blob/89ad0a77d575f01398d3c0a57bc3a22111bef36a/packages/tui/CHANGELOG.md).

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

@@ -105,7 +105,7 @@ export declare class AssistantMessageComponent extends Container {
      * tags it `↺ rewound` (the ANSI render leaves it as it stopped).
      */
     markRewound(): void;
-    /** Mirrors a thinking section collapsed or expanded in the terminal. */
+    /** Mirrors a thinking section collapsed or expanded in the terminal; runs its controls' clicks. */
     handleNativeEvent(event: NativeUiEvent): void;
     /** Width-independent stable identities for the streamed leading thinking run. */
     getTranscriptStableRows(): readonly TranscriptStableRow[];

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

@@ -39,8 +39,9 @@ export declare class UserMessageComponent extends Container implements ReactionT
     /**
      * 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
+     * file on click): the fill says "you". A quiet footer like a turn's usage line
+     * (`⧉ ⏪ · 09:45`: Copy, Rewind, the time sent) fades in at its bottom-left 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.
      */

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

@@ -8,8 +8,9 @@ export declare class CountdownTimer {
     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
+     * negative remaining time (the start lies in the future), so it counts down
+     * to zero and holds there at expiry (no `stopped`: that would freeze it at
+     * zero from the start). 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}.
      */

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

@@ -2,6 +2,7 @@ import { type Focusable, type TUI } from "../index.js";
 import { type KeybindingsManager } from "../app-keybindings.js";
 import { type Theme } from "../theme/theme.js";
 import type { CodeReviewAnnotation, CodeReviewOverlayResult, ReviewDiffFile, TextReviewAnnotation, TextReviewOverlayResult, TextReviewSource } from "./annotation-types.js";
+import type { TspSpan } from "@oh-my-pi/pi-wire";
 import { type NativeNode, type NativeUiEvent } from "../native/node.js";
 export declare const CONTINUE_CODE_REVIEW_ACTION = "Continue with LLM review";
 export declare const PASTE_CODE_REVIEW_ACTION = "Paste annotations into prompt";
@@ -21,6 +22,12 @@ export interface TextReviewOverlayCallbacks extends AnnotationOverlayCallbacks {
 }
 /** Splits a text source into the overlay's 1-based annotatable lines. */
 export declare function splitTextLines(text: string): string[];
+/** The native sheet: full-pane glass, titled by the review kind with what is under review after it. */
+interface NativeSheet {
+    readonly role: "omp.overlay.codeReview" | "omp.overlay.annotateText";
+    readonly size: "full";
+    readonly head: TspSpan[];
+}
 /** A fullscreen, annotated diff picker that only relies on public OMP APIs. */
 export declare class AnnotationOverlay implements Focusable {
     #private;
@@ -44,7 +51,19 @@ export declare class AnnotationOverlay implements Focusable {
      */
     replaceTextSource(text: string): number;
     handleInput(data: string): void;
+    /**
+     * The terminal draws the frame: a full-pane glass sheet titled `Code review`
+     * (or `Annotate text`), then what is under review as a quieter subtitle.
+     */
+    get nativeOverlay(): NativeSheet;
+    /**
+     * The sheet's body: the file rail (totals over the changed files) beside
+     * the current file's diff (text: its numbered lines), the note composer
+     * docked under the lines while a note is open, and a footer of key hints
+     * and the actions.
+     */
     describe(): NativeNode;
     handleNativeEvent(event: NativeUiEvent): void;
     render(width: number): readonly string[];
 }
+export {};

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

@@ -101,10 +101,15 @@ export declare class AskDialogComponent implements Component {
     render(width: number): readonly string[];
     /**
      * In the dock, in the composer's place and framed as the composer is: a
-     * `col` with the prompt editor's root role (`omp.editor`), so the terminal
-     * gives it the composer's insets and spacing. Not a modal `overlay` sheet:
-     * one anchored at the bottom covered the transcript rows that explain the
-     * question and blocked scrolling until the question was answered.
+     * `col` with an `omp.editor.*` root role (`omp.editor.ask`, collapsed
+     * `omp.editor.ask.hidden`), so the terminal draws the composer's shell
+     * around it. Not a modal `overlay` sheet: one anchored at the bottom
+     * covered the transcript rows that explain the question and blocked
+     * scrolling until the question was answered.
+     *
+     * Anatomy: the question tabs (several questions), the question, its
+     * answers as radio/check rows, and the action bar as the footer (the
+     * countdown, Hide, then Note, Skip and the primary Submit/Next).
      */
     describe(cx: DescribeContext): NativeNode;
     /**

package/dist/types/overlays/btw-history-panel.d.ts

@@ -40,12 +40,8 @@ export declare class BtwHistoryPanel implements Component, Focusable {
     /** Enhanced clipboard pastes belong only to the active composer. */
     pasteText(text: string): void;
     handleInput(data: string): void;
-    /** A large glass sheet titled "BTW history". */
-    readonly nativeOverlay: {
-        readonly role: "omp.overlay.btwHistory";
-        readonly size: "lg";
-        readonly head: "BTW history";
-    };
+    /** A large glass sheet (the list beside the reader), palette-sized while there is nothing to list. */
+    get nativeOverlay(): NonNullable<Component["nativeOverlay"]>;
     describe(): NativeNode;
     handleNativeEvent(event: NativeUiEvent): void;
     render(width: number): readonly string[];

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

@@ -10,7 +10,7 @@
 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";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 /**
  * `prefix` and `question` flattened onto one line, wrapped to the terminal's width and cut to
  * {@link MAX_PROMPT_TITLE_ROWS} rows (the last ends in `…` when cut). For terminal rendering only:
@@ -58,8 +58,13 @@ export declare class HookEditorComponent extends OverlayPanel implements Focusab
     /** Focus state mirrored to the nested editor during rendering. */
     focused: boolean;
     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. */
+    /**
+     * A sheet in the composer's place: the title (or, answering a question, the question under the
+     * prompt's name) over a hairline, the editor, and Open in editor · Cancel · Submit.
+     */
     describe(_cx: DescribeContext): NativeNode;
+    /** The action bar's buttons run what their keys run. */
+    handleNativeEvent(event: NativeUiEvent): void;
     /** 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. */

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

@@ -1,9 +1,9 @@
 /**
- * Simple text input component for hooks.
+ * One-line text prompt an extension (hook) asks the user.
  */
 import { type TUI } from "../index.js";
 import { OverlayPanel } from "../chrome/overlay-box.js";
-import type { DescribeContext, NativeNode } from "../native/node.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 export interface HookInputOptions {
     tui?: TUI;
     timeout?: number;
@@ -11,13 +11,21 @@ export interface HookInputOptions {
 }
 export declare class HookInputComponent extends OverlayPanel {
     #private;
-    constructor(title: string, _placeholder: string | undefined, onSubmit: (value: string) => void, onCancel: () => void, opts?: HookInputOptions);
+    constructor(title: string, placeholder: string | undefined, onSubmit: (value: string) => void, onCancel: () => void, opts?: HookInputOptions);
     handleInput(keyData: string): void;
     /** Route non-bracketed paste transports (e.g. kitty's OSC 5522 enhanced clipboard)
      *  into the inner field, mirroring bracketed-paste semantics. Pasting counts as
      *  interaction, so the timeout countdown resets like any keystroke. */
     pasteText(text: string): void;
+    /** Submit and Cancel run what Enter and the interrupt key run. */
+    handleNativeEvent(event: NativeUiEvent): void;
     dispose(): void;
-    /** A card over the form, headed by the title plus the countdown `elapsed` while a timeout runs. */
+    /**
+     * A sheet in the composer's place, built like the extension editor's: the
+     * title's first line (the countdown at its end while a timeout runs) over
+     * any further lines as detail, the field written on the sheet (tinted, the
+     * reason under it, while a submit was refused), and Cancel · Submit, whose
+     * keys live in their tooltips.
+     */
     describe(_cx: DescribeContext): NativeNode;
 }

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

@@ -42,12 +42,13 @@ export interface JobsSheetSource {
 }
 /**
  * The jobs pill's sheet: a centred `lg` glass sheet titled Background jobs.
- * A selectable list of every job (running first) sits over the selected
- * job's detail: status and live elapsed (a task job's `agent` node), cwd,
- * live pids, exit code, the full command and a tail-following output pane.
- * It re-reads the session every frame, so the caller re-renders it on a
- * timer while it is open. ↑/↓ select, X cancels the selected running job,
- * Esc or Close dismisses; nothing enters the transcript.
+ * A master–detail split (it stacks in a narrow pane): the selectable job list,
+ * grouped Running / Recent, beside the selected job's detail — a status pill
+ * with live elapsed and Cancel job, its command or task, facts (agent, cwd,
+ * live pids, exit code, artifact) and a tail-following output pane. With no
+ * jobs it shows an empty state. It re-reads the session every frame, so the
+ * caller re-renders it on a timer while it is open. ↑/↓ select, X cancels the
+ * selected running job, Esc or Close dismisses; nothing enters the transcript.
  */
 export declare class JobsSheet implements Component {
     #private;
@@ -58,7 +59,7 @@ export declare class JobsSheet implements Component {
         readonly head: "Background jobs";
     };
     constructor(source: JobsSheetSource);
-    describe(cx: DescribeContext): NativeNode;
+    describe(_cx: DescribeContext): NativeNode;
     /** Rows for a terminal without the native surface: one per job, then the selected job's facts and output tail. */
     render(width: number): readonly string[];
     invalidate(): void;

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

@@ -40,9 +40,14 @@ export declare class LoginDialogComponent extends OverlayPanel {
     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.
+     * dock; the `overlay` hoists into the terminal's layer). Top to bottom: one
+     * sentence saying what to do, the device code as a large click-to-copy
+     * well, the sign-in link as a read-only field with Copy, the questions
+     * (answered ones as label/value lines, the live one as a field), and the
+     * flow's status — finished stages checked, the current one spinning. The
+     * footer holds Cancel and one primary action: Continue while a field waits
+     * for an answer (Open sign-in page then leads the footer as a plain
+     * button), else Open sign-in page.
      */
     describe(): NativeNode;
     /** Cancel and Continue run what Esc and Enter run. */

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

@@ -83,8 +83,16 @@ 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);
+    /**
+     * The sheet: the phase strip, the step's title and lead, its body (field,
+     * status, summary), its choices, and a footer whose buttons run what
+     * Escape, Enter and Ctrl+C run.
+     */
     describe(_cx: DescribeContext): NativeNode;
-    /** A click on a choice is Enter on it, exactly as highlighting it with the arrows and pressing Enter. */
+    /**
+     * A click on a choice is Enter on it, exactly as highlighting it with the
+     * arrows and pressing Enter; the footer's buttons run what their keys run.
+     */
     handleNativeEvent(event: NativeUiEvent): void;
     handleInput(keyData: string): void;
 }

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

@@ -41,6 +41,11 @@ export declare class PauseScreenComponent implements Component, OverlayFocusOwne
         readonly anchor: "center";
         readonly head: "Paused";
     };
+    /**
+     * The sheet: a hero (the pause glyph beside the live hold clock and the
+     * session it holds), what the hold means as four facts, and a footer that
+     * reassures and resumes. The resume keys live in the button's tooltip.
+     */
     describe(): NativeNode;
     /** Resume runs what Esc/Enter/Space run. */
     handleNativeEvent(event: NativeUiEvent): void;

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

@@ -55,7 +55,11 @@ export declare class ReportPanel extends OverlayPanel {
     render(width: number): readonly string[];
     /** Text mode: rows the whole box takes at `width` when nothing caps it. */
     heightAt(width: number): number;
-    /** The sheet body (the overlay is the frame, and its body the scroller): the report, then Close (Esc). */
+    /**
+     * The sheet body (the overlay is the frame, and its body the scroller): the
+     * report as `omp.report.body`, which the terminal sets on the reading
+     * measure, then Close (Esc) as the sheet's footer.
+     */
     describe(): NativeNode;
     invalidate(): void;
     /**

package/dist/types/overlays/reset-usage-selector.d.ts

@@ -1,6 +1,6 @@
 import type { UsageResetCreditDetail } from "@oh-my-pi/pi-ai";
 import { OverlayPanel } from "../chrome/overlay-box.js";
-import type { NativeNode, NativeUiEvent } from "../native/node.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 /** One account row with its redeemable rate-limit reset credits. */
 export interface ResetUsageAccount {
     label: string;
@@ -33,11 +33,13 @@ export declare class ResetUsageSelectorComponent extends OverlayPanel {
     #private;
     constructor(accounts: ResetUsageAccount[], onSelect: (account: ResetUsageAccount) => void, onCancel: () => void);
     handleInput(keyData: string): void;
-    describe(): NativeNode;
+    describe(cx: DescribeContext): NativeNode;
     /**
-     * A click (or double-click) on an account highlights it and presses Enter:
-     * moving to another account drops a pending confirmation, so spending a
-     * reset still takes a second activation of the same account.
+     * Picker: a row click selects, a double-click or `Spend reset` presses
+     * Enter (so spending still takes a second activation, on the confirm
+     * strip), the strip's `Keep` drops the confirmation and `Close` cancels.
+     * Card list: a click (or double-click) on an account highlights it and
+     * presses Enter.
      */
     handleNativeEvent(event: NativeUiEvent): void;
 }

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

@@ -1,5 +1,6 @@
 import { type SgrMouseEvent } from "../index.js";
 import { OverlayPanel } from "../chrome/overlay-box.js";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 /** Stored account identity rendered and matched by the session account picker. */
 export interface SessionPinAccount {
     position: number;
@@ -17,6 +18,9 @@ export interface SessionPinAccount {
 export declare class SessionAccountSelectorComponent extends OverlayPanel {
     #private;
     constructor(providerName: string, accounts: readonly SessionPinAccount[], onSelect: (account: SessionPinAccount) => void, onCancel: () => void);
+    describe(cx: DescribeContext): NativeNode | null;
+    /** Picker pointer events drive the list exactly as its keys do. */
+    handleNativeEvent(event: NativeUiEvent): void;
     /** Forward keyboard navigation and cancellation when the wrapper owns focus. */
     handleInput(keyData: string): void;
     /** Route mouse selection through the title rows into the account list. */

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

@@ -24,9 +24,13 @@ export declare class SessionInfoOverlay implements Component {
     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).
+     * The sheet body (the overlay is the frame), in three tiers: who the session
+     * is (the id and file as copyable mono fields), how full its context window
+     * is (a meter under a right-aligned figure), then the report's sections as
+     * headed groups. Groups of plain counts (Messages, Tokens, Cost) share a
+     * two-column stats grid with right-aligned figures and their Total set off
+     * last; the rest (Provider, servers) are key/value rows. A Close button (Esc)
+     * ends it.
      */
     describe(cx: DescribeContext): NativeNode;
     /** The Close button runs Esc's path. */

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

@@ -122,12 +122,12 @@ export declare class UsageDashboardComponent implements Component {
     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, then Close like the other report sheets.
-     * `meter`/`chart` fall back to `progress`/`table` on terminals without
-     * them. Rebuilt only when its inputs change.
+     * The sheet body (the terminal's `lg` overlay is the frame): a toolbar
+     * (Overview/Details, freshness, Refresh), then either the overview — a
+     * strip of headline figures, the quota rows per provider, the activity
+     * calendar — or the per-provider detail tables, then Close like the other
+     * report sheets. `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`; Close closes from either view. */

package/dist/types/status-line/context-usage.d.ts

@@ -155,7 +155,7 @@ export declare function computeNonMessageBreakdown(session: NonMessageTokenSourc
  * session and model.
  */
 export declare function computeContextBreakdown(session: ContextUsageSession, options: ContextUsageOptions): ContextBreakdown;
-/** The `/context` title: the model and its window once a model is selected. */
+/** The `/context` title: the model once one is selected (the body leads with its window). */
 export declare function contextUsageHead(breakdown: ContextBreakdown): TspText;
 /**
  * Native context-usage panel for terminals without `meter`: the cell grid as

package/dist/types/tools/grouped-file-output.d.ts

@@ -121,9 +121,12 @@ export declare function numberedCode(lines: readonly NumberedLine[], opts?: {
  * header's suffix or the match count as a chip), then its lines as
  * {@link numberedCode} with match lines marked and `…` between non-adjacent
  * runs. Unnumbered body lines stay plain `code`. `maxFiles` keeps only the
- * first files (the caller says how many were left out).
+ * first files (the caller says how many were left out). `file` owns the lines
+ * before any header: a single-file search prints none, yet its lines get the
+ * same file row as a directory search's.
  */
 export declare function describeGroupedOutput(lines: readonly string[], options?: {
     lang?: (path: string) => string | undefined;
     maxFiles?: number;
+    file?: string;
 }): NativeNode[];

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "18.10.0",
+	"version": "18.10.1",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": {
@@ -41,14 +41,14 @@
 		"gen:glyphs": "bun scripts/gen-glyphs.ts"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.10.0",
-		"@oh-my-pi/pi-agent-core": "18.10.0",
-		"@oh-my-pi/pi-ai": "18.10.0",
-		"@oh-my-pi/pi-catalog": "18.10.0",
-		"@oh-my-pi/pi-natives": "18.10.0",
-		"@oh-my-pi/pi-utils": "18.10.0",
-		"@oh-my-pi/pi-wire": "18.10.0",
-		"@oh-my-pi/snapcompact": "18.10.0"
+		"@oh-my-pi/omptype": "18.10.1",
+		"@oh-my-pi/pi-agent-core": "18.10.1",
+		"@oh-my-pi/pi-ai": "18.10.1",
+		"@oh-my-pi/pi-catalog": "18.10.1",
+		"@oh-my-pi/pi-natives": "18.10.1",
+		"@oh-my-pi/pi-utils": "18.10.1",
+		"@oh-my-pi/pi-wire": "18.10.1",
+		"@oh-my-pi/snapcompact": "18.10.1"
 	},
 	"devDependencies": {
 		"kitty-vt-wasm": "^0.2.0"