@oh-my-pi/pi-tui 17.4.2 → 18.0.1

package/CHANGELOG.md

@@ -2,6 +2,73 @@
 
 ## [Unreleased]
 
+## [18.0.1] - 2026-08-23
+
+### Added
+
+- Collapsed individual skill commands into a `/skill:` namespace entry to declutter suggestions
+- Added `TUI.renderNow()` for terminal-safe synchronous priority frames that retain resize debounce, output-backlog, and image deferral safeguards.
+
+### Changed
+
+- Improved slash command autocompletion to chain suggestions after selecting a namespace
+- Replaced the native-scrollback inference API (`NativeScrollback*` interfaces and the scrollback rebuild/resize settings hooks) with explicit `TerminalFramePlan` history batches.
+- Post-resize repaints now recover the reflowed viewport anchor with a cursor-position report (DSR) instead of trusting stale grid coordinates, so a settled resize no longer duplicates the editor/status rows on screen.
+- History appends that overflow the screen erase the old live viewport first, so a scroll can only push committed rows and blanks into scrollback, never an unfinished frame.
+
+### Fixed
+
+- Fixed the resize live-region erase wiping visible history rows when the terminal height grows: cursor-relative addressing tracks the reflowed viewport top on grow, while the bottom-preserving bound still guards height shrinks.
+- Fixed consecutive prompt submissions being skipped by persistent history, allowing the latest project metadata to replace the previous entry without duplicating editor navigation history.
+- Fixed the history drain stalling on idle screens: accepting a batch now pumps the next frame, so a large resumed transcript retires to terminal history instead of pinning the live viewport in its emergency aggregate.
+- Fixed fuzzy matching so a qualifying whole-word hit is not hidden by an earlier mid-word occurrence ([#8465](https://github.com/can1357/oh-my-pi/pull/8465) by [@Mustaqeem66](https://github.com/Mustaqeem66)).
+- Fixed stray characters appearing in the terminal viewport during title updates
+- Fixed editor input lag when autocomplete providers are slow by keeping only the latest pending lookup.
+- Fixed pasting an image in kitty occasionally spraying base64 text into the composer alongside the image attachment: a kitty OSC 5522 clipboard packet torn by the incomplete-escape flush is now discarded up to its terminator instead of being replayed as keystrokes.
+- Fixed Kitty OSC 66 headings activating before the host explicitly enables text sizing.
+- Markdown streaming renderer now scans only the mutable tail (not the full document) for reference-link definitions and CR on every frame, eliminating the O(n²) `RegExp.test` cost that accounted for ~26% CPU during active streaming ([#9048](https://github.com/can1357/oh-my-pi/issues/9048)).
+
+## [18.0.0] - 2026-08-22
+
+### Breaking Changes
+
+- Changed native macOS spelling and completion functions to return Promises.
+- Updated `EditorTextAssistProvider.tryAutocorrect` signature to receive editor state instead of raw text.
+- Updated `Editor.decorateText` signature to provide line and column context instead of raw text.
+
+### Added
+
+- Added `EditorTextAssistProvider` with spelling suggestion support (`ctrl+.`), word replacement choices, and async autocorrection handling.
+- Added `Terminal.pendingOutputBytes` and an output-backpressure render gate to drop stale frames on slow terminals.
+- Added `deferInput` startup option and `enableInput()` across `Terminal`, `TUI`, and `TUIStartOptions` to improve startup responsiveness.
+- Added icon support and customizable theming to autocomplete and select lists.
+- Added `MarkdownTheme.createHighlightStream` for incremental syntax highlighting of completed lines in streaming Markdown code blocks.
+- Added `maxDescriptionRows` option to `SelectList` layouts to truncate wrapped descriptions with an ellipsis.
+- Added `commandUsage` ranking callback support to `CombinedAutocompleteProvider` to prioritize frequently used slash commands.
+- Added `Editor.viewportRowsProvider` to constrain autocomplete dropdowns within the available terminal height.
+- Added `Editor.setTheme()` to dynamically change themes without recreating the editor or losing draft content.
+
+### Changed
+
+- Adjusted word completion to skip appending a trailing space when the following character is punctuation.
+- Increased default autocomplete dropdown height from 5 to 10 items.
+
+### Fixed
+
+- Fixed TUI freezing during large repaints on slow or occluded terminals by moving stdout writes to an off-thread writer.
+
+## [17.4.4] - 2026-08-22
+
+### Added
+
+- Added `setResizeScrollback()` / `ResizeScrollbackMode` (`PI_TUI_RESIZE_SCROLLBACK` env initializer) controlling what a settled in-place width resize does to native scrollback, which the host rewraps naively at the old width: `append` replays the transcript at the settled width below the old-wrap history, `rebuild` clears pane history first (ED3) so it holds exactly one current-width copy, and `preserve` repaints the viewport only with zero history growth. The raw engine defaults to `preserve`; the coding agent's `tui.resizeScrollback` setting (default `append`) governs interactive sessions.
+
+### Fixed
+
+- `visibleWidth` now measures APC sequences (Kitty graphics commands, cursor markers) as zero cells instead of counting their payload as printable text, matching the native width engine.
+- Kitty Unicode-placeholder rows with long styled prefixes (e.g. bordered thumbnail cards) are recognized as image lines again, keeping them on the verbatim render path instead of SGR coalescing/truncation.
+- Fixed multiplexer width-epoch resolution failing for every real component tree, which forced the conservative full-transcript replay (and one duplicated transcript copy in pane history) on every settled width resize: leading children without a width-epoch revision are no longer validated by width-dependent row counts (reflow is not mutation — identity plus the revision, when reported, is the stability proof), and `Markdown` now reports a width-independent mutation revision so it can sit above an epoch source ([#8193](https://github.com/can1357/oh-my-pi/issues/8193), [#7026](https://github.com/can1357/oh-my-pi/issues/7026)).
+
 ## [17.4.2] - 2026-08-21
 
 ### Added

package/README.md

@@ -539,7 +539,7 @@ interface Terminal {
 **Built-in implementations:**
 
 - `ProcessTerminal` - Uses `process.stdin/stdout`
-- `VirtualTerminal` - For testing (uses ghostty-web)
+- `VirtualTerminal` - For testing (uses kitty-vt-wasm)
 
 ## Utilities
 

package/dist/types/autocomplete.d.ts

@@ -10,6 +10,8 @@ export interface AutocompleteItem {
     value: string;
     label: string;
     description?: string;
+    /** Optional type-indicator glyph rendered in an aligned column before the label */
+    icon?: string;
     /** Dim hint text shown inline after cursor when this item is selected */
     hint?: string;
 }
@@ -18,6 +20,8 @@ export interface SlashCommand {
     name: string;
     aliases?: string[];
     description?: string;
+    /** Optional type-indicator glyph shown before the command name in autocomplete */
+    icon?: string;
     argumentHint?: string;
     /** Whether the command consumes argument text after the command name. False means the full input stays normal prompt text once args are present. */
     allowArgs?: boolean;
@@ -28,8 +32,8 @@ export interface SlashCommand {
     getInlineHint?(argumentText: string): string | null;
 }
 export interface AutocompleteProvider {
-    /** Get autocomplete suggestions for current text/cursor position */
-    getSuggestions(lines: string[], cursorLine: number, cursorCol: number): Promise<{
+    /** Get autocomplete suggestions for current text/cursor position. Expensive providers SHOULD stop when `signal` aborts. */
+    getSuggestions(lines: string[], cursorLine: number, cursorCol: number, signal?: AbortSignal): Promise<{
         items: AutocompleteItem[];
         prefix: string;
     } | null>;
@@ -64,8 +68,9 @@ export interface AutocompleteProvider {
      * Force file-path completion (called on Tab). Returns matched items plus the
      * full prefix, or null when no path token sits before the cursor. Present on
      * file-aware providers; absent on slash-only ones.
+     * Expensive providers SHOULD stop when `signal` aborts.
      */
-    getForceFileSuggestions?(lines: string[], cursorLine: number, cursorCol: number): Promise<{
+    getForceFileSuggestions?(lines: string[], cursorLine: number, cursorCol: number, signal?: AbortSignal): Promise<{
         items: AutocompleteItem[];
         prefix: string;
     } | null>;
@@ -73,7 +78,13 @@ export interface AutocompleteProvider {
     shouldTriggerFileCompletion?(lines: string[], cursorLine: number, cursorCol: number): boolean;
 }
 type CommandEntry = SlashCommand | AutocompleteItem;
+/** Optional behaviors for {@link CombinedAutocompleteProvider}. */
+export interface CombinedAutocompleteOptions {
+    /** Usage count per command name; higher counts rank earlier among equal text-match scores. */
+    commandUsage?: (name: string) => number;
+}
 export declare function scoreCommandTextMatch(lowerPrefix: string, lowerTarget: string): number;
+export declare const SKILL_NAMESPACE = "skill:";
 /**
  * Whether a mid-prompt slash token (`prose … /tok`) is skill-shaped enough to
  * surface `name` in the skill popup. Deliberately stricter than submitted
@@ -90,8 +101,8 @@ export declare function scoreCommandTextMatch(lowerPrefix: string, lowerTarget:
 export declare function midPromptSkillTokenMatches(lowerToken: string, name: string, description?: string): boolean;
 export declare class CombinedAutocompleteProvider implements AutocompleteProvider {
     #private;
-    constructor(commands?: CommandEntry[], basePath?: string);
-    getSuggestions(lines: string[], cursorLine: number, cursorCol: number): Promise<{
+    constructor(commands?: CommandEntry[], basePath?: string, options?: CombinedAutocompleteOptions);
+    getSuggestions(lines: string[], cursorLine: number, cursorCol: number, signal?: AbortSignal): Promise<{
         items: AutocompleteItem[];
         prefix: string;
     } | null>;
@@ -101,7 +112,7 @@ export declare class CombinedAutocompleteProvider implements AutocompleteProvide
         cursorCol: number;
     };
     invalidateDirCache(dir?: string): void;
-    getForceFileSuggestions(lines: string[], cursorLine: number, cursorCol: number): Promise<{
+    getForceFileSuggestions(lines: string[], cursorLine: number, cursorCol: number, signal?: AbortSignal): Promise<{
         items: AutocompleteItem[];
         prefix: string;
     } | null>;

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

@@ -23,6 +23,38 @@ interface HistoryStorage {
     add(prompt: string, cwd?: string): Promise<void>;
     getRecent(limit: number): HistoryEntry[];
 }
+/** A synchronous replacement immediately before the editor cursor. */
+export interface EditorInlineReplacement {
+    /** UTF-16 code units to remove immediately before the cursor. */
+    replaceLen: number;
+    /** Literal text inserted where the removed suffix started. */
+    insert: string;
+}
+/** Replacement candidates and the current-line span they replace. */
+export interface EditorWordReplacements {
+    line: number;
+    startCol: number;
+    endCol: number;
+    items: readonly string[];
+}
+/** Source location for one visual text segment passed to `decorateText`. */
+export interface EditorTextDecorationContext {
+    line: number;
+    startCol: number;
+    endCol: number;
+}
+/**
+ * Optional prose assistance kept separate from command/file autocomplete.
+ * Hosts independently decide whether word completion and autocorrection are enabled.
+ */
+export interface EditorTextAssistProvider {
+    /** Return ghost-text suffix for the partial word at the cursor, or `null`. */
+    getWordCompletion?(lines: string[], cursorLine: number, cursorCol: number): string | null;
+    /** Return a correction after one single-character insertion, or `null`. */
+    tryAutocorrect?(lines: string[], cursorLine: number, cursorCol: number): EditorInlineReplacement | null | Promise<EditorInlineReplacement | null>;
+    /** Return replacement candidates for the misspelled word at the cursor. */
+    getWordReplacements?(lines: string[], cursorLine: number, cursorCol: number): EditorWordReplacements | null | Promise<EditorWordReplacements | null>;
+}
 export declare class Editor implements Component, Focusable {
     #private;
     /** Focusable interface - set by TUI when focus changes */
@@ -34,9 +66,13 @@ export declare class Editor implements Component, Focusable {
     /** Optional hook that decorates displayed user text after source-text layout.
      *  Width-changing output is allowed on lines without the cursor; it is truncated
      *  to the content width rather than reflowed. Cursor glyphs and inline hints are excluded. */
-    decorateText: ((text: string) => string) | undefined;
+    decorateText: ((text: string, context: EditorTextDecorationContext) => string) | undefined;
     borderColor: (str: string) => string;
     onAutocompleteUpdate?: () => void;
+    /** Called after an async text-assist result mutates the document outside an input event, so hosts can schedule a repaint. */
+    onTextAssistApplied?: () => void;
+    /** Terminal height source for clamping the autocomplete dropdown. Hosts wire this to their Terminal's rows. */
+    viewportRowsProvider?: () => number;
     /** Optional pattern matching atomic placeholder tokens (e.g. `[Image #1, 800x600]` or
      *  `[Paste #2, +30 lines]`) that the editor treats as indivisible: a backspace or forward-delete
      *  landing on any character of a token removes the whole token instead of corrupting it into
@@ -56,7 +92,10 @@ export declare class Editor implements Component, Focusable {
     onAutocompleteCancel?: () => void;
     disableSubmit: boolean;
     constructor(theme: EditorTheme);
+    setTheme(theme: EditorTheme): void;
     setAutocompleteProvider(provider: AutocompleteProvider): void;
+    /** Install prose assistance without changing command/file autocomplete. */
+    setTextAssistProvider(provider: EditorTextAssistProvider | undefined): void;
     /**
      * Set custom content for the top border (e.g., status line).
      * Pass undefined to use the default plain border.
@@ -75,9 +114,7 @@ export declare class Editor implements Component, Focusable {
      * Use this when the top border derives from state that mutates far faster
      * than the render cadence (session events, streaming, subagent updates).
      * The TUI already throttles renders, so a provider is invoked exactly once
-     * per frame and does no work between paints. Return a logical `revision` to
-     * distinguish concurrent status mutations from pure width reflow.
-     */
+     * per frame and does no work between paints. 	 */
     setTopBorderProvider(provider: ((availableWidth: number) => EditorTopBorder | undefined) | undefined): void;
     /**
      * Show or hide the editor border chrome.
@@ -106,6 +143,7 @@ export declare class Editor implements Component, Focusable {
     setPaddingX(paddingX: number): void;
     getAutocompleteMaxVisible(): number;
     setAutocompleteMaxVisible(maxVisible: number): void;
+    /** Loads persistent prompts for navigation and enables future persistence. */
     setHistoryStorage(storage: HistoryStorage): void;
     /**
      * Add a prompt to history for up/down arrow navigation.
@@ -116,7 +154,6 @@ export declare class Editor implements Component, Focusable {
     render(width: number): readonly string[];
     handleInput(data: string): void;
     getText(): string;
-    getNativeScrollbackWidthEpochRevision(): number;
     /** Whether the buffer text equals `value`, without `getText()`'s full join —
      *  O(1) for the hot per-keystroke probes against short single-line values. */
     textEquals(value: string): boolean;

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

@@ -121,11 +121,8 @@ export declare class ImageBudget {
      * Restart every placement epoch after a destructive history clear (`CSI 3 J`
      * full paint). The clear destroys all placement cells — scrollback rows are
      * gone and the replay rewrites the viewport — so no archive remains to
-     * protect. Reverting to epoch 1 lets the replay's placements replace the
-     * terminal's stale registry entries; the returned list names every image
-     * and the highest epoch it reached so the caller can delete all of its
-     * registry entries explicitly (`d=i` keeps the transmitted data) — an image
-     * absent from the replay never re-places, so even its epoch-1 entry must go.
+     * protect. Reverting to epoch 1 lets the replay recreate every visible
+     * placement after the terminal-wide cleanup.
      */
     resetPlacementEpochs(): ReadonlyArray<{
         imageId: number;

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

@@ -1,5 +1,5 @@
 import type { SymbolTheme } from "../symbols.js";
-import type { Component, NativeScrollbackCommittedRows, NativeScrollbackReplay, NativeScrollbackWidthEpoch } from "../tui.js";
+import type { Component } from "../tui.js";
 /** @internal exported for tests — must stay index-identical to the old regex scan. */
 export declare function mathStartIndex(src: string): number | undefined;
 /** @internal exported for tests — must stay index-identical to the old regex scan. */
@@ -26,6 +26,14 @@ export interface DefaultTextStyle {
     /** Underline text */
     underline?: boolean;
 }
+/**
+ * Stateful incremental code highlighter carrying parser state across pushes.
+ * Produced per streaming fence by {@link MarkdownTheme.createHighlightStream}.
+ */
+export interface HighlightStreamSession {
+    /** Highlight the next chunk and advance parser state. */
+    push(chunk: string): string;
+}
 /**
  * Theme functions for markdown elements.
  * Each function takes text and returns styled text with ANSI codes.
@@ -46,6 +54,14 @@ export interface MarkdownTheme {
     strikethrough: (text: string) => string;
     underline: (text: string) => string;
     highlightCode?: (code: string, lang?: string) => string[];
+    /**
+     * Create a stateful incremental highlighter for one streaming code fence.
+     * `push` receives newline-terminated complete lines (only the final push
+     * may omit the trailing newline) and must return highlighted ANSI text for
+     * exactly the pushed chunk, byte-identical to highlighting the concatenated
+     * text through `highlightCode`. Return null when `lang` is unsupported.
+     */
+    createHighlightStream?: (lang?: string) => HighlightStreamSession | null;
     /**
      * Resolve a mermaid ASCII rendering by fenced block source text.
      * Return null to fall back to fenced code rendering.
@@ -53,7 +69,7 @@ export interface MarkdownTheme {
     resolveMermaidAscii?: (source: string, maxWidth?: number) => string | null;
     symbols: SymbolTheme;
 }
-export declare class Markdown implements Component, NativeScrollbackCommittedRows, NativeScrollbackReplay, NativeScrollbackWidthEpoch {
+export declare class Markdown implements Component {
     #private;
     setIgnoreTight(ignore: boolean): this;
     constructor(text: string, paddingX: number, paddingY: number, theme: MarkdownTheme, defaultTextStyle?: DefaultTextStyle, codeBlockIndent?: number);
@@ -61,28 +77,6 @@ export declare class Markdown implements Component, NativeScrollbackCommittedRow
     invalidate(): void;
     get transientRenderCache(): boolean;
     set transientRenderCache(value: boolean);
-    /**
-     * Rows at the top of the most recent render() (top padding + rendered
-     * frozen-token prefix) whose bytes are settled: byte-stable at this
-     * width/theme for as long as the text keeps growing append-only. Hosts
-     * feed this to transcript commit gating (see the coding agent's
-     * `FinalizableBlock.getTranscriptBlockSettledRows`). 0 outside streaming
-     * (`transientRenderCache`) mode, after a text rewind (re-earned on the new
-     * lineage), and on cache-served non-streaming renders.
-     */
-    getLastRenderSettledRows(): number;
-    captureNativeScrollbackWidthEpoch(): unknown;
-    resolveNativeScrollbackWidthEpoch(boundary: unknown): number | undefined;
-    getNativeScrollbackWidthEpochRows(): number | undefined;
-    isNativeScrollbackWidthEpochAppendOnly(boundary: unknown): boolean;
-    /**
-     * Freeze every table whose first physical row is already part of the native
-     * scrollback prefix. The recorded widths came from the exact frame that was
-     * just emitted, so the next streamed delta cannot retroactively widen it.
-     */
-    setNativeScrollbackCommittedRows(rows: number): void;
-    /** A destructive replay removes the immutable tape this layout was guarding. */
-    prepareNativeScrollbackReplay(): void;
     render(width: number): readonly string[];
 }
 /**

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

@@ -5,6 +5,8 @@ export interface SelectItem {
     value: string;
     label: string;
     description?: string;
+    /** Optional type-indicator glyph rendered in an aligned column before the label */
+    icon?: string;
     /** Dim hint text shown inline after cursor when this item is selected */
     hint?: string;
 }
@@ -15,6 +17,8 @@ export interface SelectListTheme {
     scrollInfo: (text: string) => string;
     noMatch: (text: string) => string;
     symbols: SymbolTheme;
+    /** Style for the type-icon column on unselected rows. Defaults to plain text. */
+    icon?: (text: string) => string;
     /** Hover band applied to the full row under the mouse pointer. */
     hovered?: (text: string) => string;
 }
@@ -39,6 +43,11 @@ export interface SelectListLayoutOptions {
      * wrap unevenly.
      */
     wrapDescription?: boolean;
+    /**
+     * Cap wrapped descriptions at this many visual rows; the last kept row is
+     * ellipsized. Only meaningful with `wrapDescription`.
+     */
+    maxDescriptionRows?: number;
 }
 export declare class SelectList implements Component, MouseRoutable {
     #private;

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

@@ -14,7 +14,6 @@ export declare class Text implements Component {
     constructor(text?: string, paddingX?: number, paddingY?: number, customBgFn?: (text: string) => string);
     getText(): string;
     setText(text: string): boolean;
-    getNativeScrollbackWidthEpochRevision(): number;
     setCustomBgFn(customBgFn?: (text: string) => string): void;
     /**
      * Supply a foreground styler applied to the text at render time (e.g. a

package/dist/types/keybindings.d.ts

@@ -25,6 +25,7 @@ export interface Keybindings {
     "tui.editor.yank": true;
     "tui.editor.yankPop": true;
     "tui.editor.undo": true;
+    "tui.editor.spellingSuggestions": true;
     "tui.input.newLine": true;
     "tui.input.submit": true;
     "tui.input.tab": true;
@@ -129,6 +130,10 @@ export declare const TUI_KEYBINDINGS: {
         readonly defaultKeys: ["ctrl+-", "ctrl+_"];
         readonly description: "Undo";
     };
+    readonly "tui.editor.spellingSuggestions": {
+        readonly defaultKeys: "ctrl+.";
+        readonly description: "Show spelling replacements";
+    };
     readonly "tui.input.newLine": {
         readonly defaultKeys: ["shift+enter", "ctrl+j"];
         readonly description: "Insert newline";

package/dist/types/terminal-capabilities.d.ts

@@ -21,7 +21,7 @@ export declare class TerminalInfo {
     readonly deccara: boolean;
     readonly supportsScreenToScrollback: boolean;
     /** Renders the Kitty OSC 66 text-sizing protocol (scaled spans). Kitty only. */
-    readonly textSizing: boolean;
+    readonly supportsTextSizing: boolean;
     /**
      * Hangul Compatibility Jamo (U+3131..=U+318E) cell width. Ghostty follows
      * UAX#11 (2 cells); Warp paints 1; "platform" keeps the OS default
@@ -30,7 +30,7 @@ export declare class TerminalInfo {
     readonly hangulJamoWidth: HangulCompatibilityJamoWidth;
     constructor(id: TerminalId, imageProtocol: ImageProtocol | null, trueColor: boolean, hyperlinks: boolean, notifyProtocol?: NotifyProtocol, deccara?: boolean, supportsScreenToScrollback?: boolean, 
     /** Renders the Kitty OSC 66 text-sizing protocol (scaled spans). Kitty only. */
-    textSizing?: boolean, 
+    supportsTextSizing?: boolean, 
     /**
      * Hangul Compatibility Jamo (U+3131..=U+318E) cell width. Ghostty follows
      * UAX#11 (2 cells); Warp paints 1; "platform" keeps the OS default
@@ -167,6 +167,7 @@ export interface RuntimeTerminal extends TerminalInfo {
     hyperlinks: boolean;
     deccara: boolean;
     supportsScreenToScrollback: boolean;
+    /** Whether OSC 66 text sizing is currently enabled. */
     textSizing: boolean;
 }
 export declare const TERMINAL: RuntimeTerminal;
@@ -184,7 +185,7 @@ export declare function setTerminalDeccara(enabled: boolean): void;
 export declare function setTerminalScreenToScrollback(enabled: boolean): void;
 /**
  * Enable/disable OSC 66 text-sizing at runtime. The coding-agent calls this from
- * the `tui.textSizing` setting (gated on the terminal's static `textSizing`
+ * the `tui.textSizing` setting (gated on the terminal's static `supportsTextSizing`
  * capability); tests flip it directly to exercise the scaled-heading path.
  */
 export declare function setTerminalTextSizing(enabled: boolean): void;
@@ -282,6 +283,12 @@ export declare function encodeKittyPlacementLine(options: {
  * this is the only way to actually purge a placed image.
  */
 export declare function encodeKittyDeleteImage(imageId: number): string;
+/**
+ * Delete every Kitty image and placement in the terminal. Used only by an
+ * explicit destructive display reset: text erases leave untracked placements
+ * painted, so per-image bookkeeping cannot guarantee a clean viewport.
+ */
+export declare function encodeKittyDeleteAllImages(): string;
 /**
  * Delete a single placement of an image (`d=i`, lowercase): removes its cells
  * and registry entry but keeps the transmitted data, so a later `a=p` under a

package/dist/types/terminal.d.ts

@@ -51,6 +51,16 @@ export declare class OutputBacklogGuard {
 }
 /** Record alternate-screen state (called by the TUI on `?1049h`/`?1049l` writes). */
 export declare function setAltScreenActive(active: boolean): void;
+/**
+ * Route an out-of-band escape sequence (e.g. an OSC title update) through the
+ * active terminal's output path. While a TUI owns stdout, frame paints go
+ * through the off-thread write pump and can split across multiple write(2)
+ * calls; a direct main-thread `process.stdout.write` can land between two of
+ * them — mid escape sequence — and the host terminal then prints the payload
+ * as literal text at the cursor position. Returns false when no terminal has
+ * started, in which case the caller owns stdout and may write directly.
+ */
+export declare function writeThroughActiveTerminal(data: string): boolean;
 /**
  * Emergency terminal restore - call this from signal/crash handlers
  * Resets terminal state without requiring access to the ProcessTerminal instance
@@ -58,10 +68,30 @@ export declare function setAltScreenActive(active: boolean): void;
 export declare function emergencyTerminalRestore(): void;
 /** Terminal-reported appearance (dark/light mode). */
 export type TerminalAppearance = "dark" | "light";
+/** Options for {@link Terminal.start}. */
+export interface TerminalStartOptions {
+    /**
+     * Paint-only start: skip raw mode, stdin ownership, and every probe that
+     * elicits a response on stdin. The host tty keeps cooked-mode line editing
+     * (kernel echo lands at the hardware cursor), and typed bytes stay queued
+     * in the kernel until {@link Terminal.enableInput} takes ownership and
+     * replays them through `onInput`. Used for the startup prepaint so typing
+     * echoes even while module loading blocks the event loop.
+     */
+    deferInput?: boolean;
+}
 /** Identity of an accepted explicit terminal appearance refresh request. */
 export type TerminalAppearanceRequestToken = number;
 export interface Terminal {
-    start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => void): void;
+    start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => void, options?: TerminalStartOptions): void;
+    /**
+     * Take ownership of stdin after a `deferInput` start: enable raw mode,
+     * attach input handlers, and run the capability probes start() skipped.
+     * Bytes the user typed in cooked mode meanwhile are replayed through
+     * `onInput`. No-op when input was never deferred. Optional so custom
+     * Terminals built against older pi-tui versions keep working.
+     */
+    enableInput?(): void;
     stop(): void;
     /**
      * Drain stdin before exiting to prevent Kitty key release events from
@@ -73,6 +103,14 @@ export interface Terminal {
     write(data: string): void;
     get columns(): number;
     get rows(): number;
+    /**
+     * Output bytes accepted but not yet delivered to the terminal, when the
+     * implementation can report it. The renderer skips composing new frames
+     * while this backlog is deep, so a slow terminal receives only fresh
+     * frames instead of a queue of stale ones. Optional so custom Terminals
+     * built against older pi-tui versions keep working.
+     */
+    readonly pendingOutputBytes?: number;
     get kittyProtocolActive(): boolean;
     get kittyEnableSequence(): string | null;
     readonly keyboardEnhancementEnterSequence?: string | null;
@@ -158,11 +196,13 @@ export declare class ProcessTerminal implements Terminal {
      */
     refreshAppearance(requestToken?: TerminalAppearanceRequestToken): TerminalAppearanceRequestToken | void;
     onPrivateModeReport(callback: (mode: number, supported: boolean, confirmed?: boolean) => void): void;
-    start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => void): void;
+    start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => void, options?: TerminalStartOptions): void;
+    enableInput(): void;
     drainInput(maxMs?: number, idleMs?: number): Promise<void>;
     stop(): void;
     write(data: string): void;
     get columns(): number;
+    get pendingOutputBytes(): number;
     get rows(): number;
     moveBy(lines: number): void;
     hideCursor(force?: boolean): void;