@linxiraos/pi-tui 1.0.4 → 1.0.6

package/CHANGELOG.md

@@ -2,7 +2,20 @@
 
 ## [Unreleased]
 
-## [1.0.2] - 2026-08-15
+## [1.0.6] - 2026-08-17
+
+## [17.3.5] - 2026-08-16
+
+### Fixed
+
+- Fixed long CPU-bound event-loop stalls being misclassified as system sleep and omitted from loop-blocked diagnostics.
+- Fixed focused components with markers falling back to full-screen redraws instead of direct row updates, preserving cursor position and native scrollback across marker changes.
+
+## [17.3.4] - 2026-08-14
+
+### Fixed
+
+- Fixed a terminal Device-Attributes reply leaking into the composer as literal text (e.g. `1;22;…;52c`) when it arrived after the startup capability-probe sentinel FIFO drained, a race made observable by the added latency of an SSH/zmx PTY chain. DA1 replies (`CSI ? … c`) and split private-CSI responses are now consumed for the whole session lifetime, not only while a probe sentinel is outstanding ([#8542](https://github.com/can1357/oh-my-pi/issues/8542)).
 
 ## [17.3.3] - 2026-08-14
 
@@ -1969,7 +1982,7 @@
 
 ### Changed
 
-- Forked to @oh-my-pi scope with unified versioning across all packages
+- Forked to @linxiraos scope with unified versioning across all packages
 
 ### Fixed
 
@@ -1979,7 +1992,7 @@
 
 ## [1.337.0] - 2026-01-02
 
-Initial release under @oh-my-pi scope. See previous releases at [badlogic/pi-mono](https://github.com/badlogic/pi-mono).
+Initial release under @linxiraos scope. See previous releases at [badlogic/pi-mono](https://github.com/badlogic/pi-mono).
 
 ## [1.5.0] - 2026-01-03
 
@@ -1989,13 +2002,13 @@ Initial release under @oh-my-pi scope. See previous releases at [badlogic/pi-mon
 
 ## [1.0.1] - 2026-08-14
 
-- Reset the version to 1.0.0 and republished under the `@linxiraos/*` scope, breaking from the `@oh-my-pi` version lineage.
+- Reset the version to 1.0.0 and republished under the `@linxiraos/*` scope, breaking from the `@linxiraos` version lineage.
 
 ## [1.0.0] - 2026-08-13
 
 ### Changed
 
-- Reset the version to 1.0.0 and republished under the `@linxiraos/*` scope, breaking from the `@oh-my-pi` version lineage.
+- Reset the version to 1.0.0 and republished under the `@linxiraos/*` scope, breaking from the `@linxiraos` version lineage.
 
 ## [0.50.0] - 2026-01-26
 

package/dist/types/autocomplete.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Locate the slash that opens a slash command on the line, allowing leading
+ * whitespace. Returns the index of the `/` or `null` when the line is not a
+ * slash command. Aligns with `trimStart` semantics so the editor and provider
+ * agree on which prefixes count.
+ */
+export declare function findLeadingSlashCommandStart(text: string): number | null;
+export declare function findTrailingSlashCommandStart(text: string): number | null;
+export interface AutocompleteItem {
+    value: string;
+    label: string;
+    description?: string;
+    /** Dim hint text shown inline after cursor when this item is selected */
+    hint?: string;
+}
+type Awaitable<T> = T | Promise<T>;
+export interface SlashCommand {
+    name: string;
+    aliases?: string[];
+    description?: 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;
+    /** Dynamic display-only description for slash-command autocomplete. Must be synchronous and side-effect free. */
+    getAutocompleteDescription?: () => string | undefined;
+    getArgumentCompletions?(argumentPrefix: string): Awaitable<AutocompleteItem[] | null>;
+    /** Return inline hint text for the current argument state (shown as dim ghost text after cursor) */
+    getInlineHint?(argumentText: string): string | null;
+}
+export interface AutocompleteProvider {
+    /** Get autocomplete suggestions for current text/cursor position */
+    getSuggestions(lines: string[], cursorLine: number, cursorCol: number): Promise<{
+        items: AutocompleteItem[];
+        prefix: string;
+    } | null>;
+    /** Apply the selected item and return new text + cursor position */
+    applyCompletion(lines: string[], cursorLine: number, cursorCol: number, item: AutocompleteItem, prefix: string): {
+        lines: string[];
+        cursorLine: number;
+        cursorCol: number;
+        onApplied?: () => void;
+    };
+    /** Get inline hint text to show as dim ghost text after the cursor */
+    getInlineHint?(lines: string[], cursorLine: number, cursorCol: number): string | null;
+    /** Synchronously try to complete a slash command at the start of a line (no async I/O). */
+    /** Returns matched items and the full prefix, or null if not applicable. */
+    trySyncSlashCompletion?(textBeforeCursor: string): {
+        items: AutocompleteItem[];
+        prefix: string;
+    } | null;
+    /**
+     * Synchronously try to expand text immediately before the cursor (no async I/O).
+     * Called after every single-character insert. Implementations MUST cheaply
+     * early-return when the trailing context cannot trigger them.
+     * Returns the number of characters to delete immediately before the cursor
+     * and the literal string to insert in their place, or null to leave the
+     * buffer untouched.
+     */
+    trySyncInlineReplace?(textBeforeCursor: string): {
+        replaceLen: number;
+        insert: string;
+    } | null;
+    /**
+     * 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.
+     */
+    getForceFileSuggestions?(lines: string[], cursorLine: number, cursorCol: number): Promise<{
+        items: AutocompleteItem[];
+        prefix: string;
+    } | null>;
+    /** Whether a Tab press should attempt file completion at the cursor. */
+    shouldTriggerFileCompletion?(lines: string[], cursorLine: number, cursorCol: number): boolean;
+}
+type CommandEntry = SlashCommand | AutocompleteItem;
+export declare function scoreCommandTextMatch(lowerPrefix: string, lowerTarget: string): number;
+/**
+ * Whether a mid-prompt slash token (`prose … /tok`) is skill-shaped enough to
+ * surface `name` in the skill popup. Deliberately stricter than submitted
+ * slash-command matching: a stray `/word` in running prose must not keep the
+ * popup alive through fuzzy name/description hits, so a token only matches as
+ * - a prefix of the `skill:` namespace (incl. the bare `/` entry point),
+ * - an explicit `skill:…` query (full fuzzy name/description search), or
+ * - a prefix of the skill's bare name (`/hum` → `skill:humanizer`).
+ * Anything else yields no items, letting the caller fall through to path
+ * completion or close the popup. Shared with the editor's accept-time
+ * staleness guard so Tab/Enter never accepts a skill the refreshed popup
+ * would no longer show.
+ */
+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<{
+        items: AutocompleteItem[];
+        prefix: string;
+    } | null>;
+    applyCompletion(lines: string[], cursorLine: number, cursorCol: number, item: AutocompleteItem, prefix: string): {
+        lines: string[];
+        cursorLine: number;
+        cursorCol: number;
+    };
+    invalidateDirCache(dir?: string): void;
+    getForceFileSuggestions(lines: string[], cursorLine: number, cursorCol: number): Promise<{
+        items: AutocompleteItem[];
+        prefix: string;
+    } | null>;
+    shouldTriggerFileCompletion(lines: string[], cursorLine: number, cursorCol: number): boolean;
+    /** Get inline hint text for slash commands with subcommand hints */
+    getInlineHint(lines: string[], cursorLine: number, cursorCol: number): string | null;
+    trySyncSlashCompletion(textBeforeCursor: string): {
+        items: AutocompleteItem[];
+        prefix: string;
+    } | null;
+}
+export {};

package/dist/types/bracketed-paste.d.ts

@@ -0,0 +1,51 @@
+export type PasteResult = {
+    handled: false;
+} | {
+    handled: true;
+    pasteContent?: string;
+    remaining: string;
+};
+/**
+ * Decode tmux's re-encoded control bytes (both `extended-keys-format` variants) inside a
+ * bracketed-paste payload back to their literal byte (e.g. Ctrl+J → "\n"). Leaves the rest of
+ * the text untouched. Call before any control-character stripping so newlines/tabs survive
+ * instead of leaking the printable escape tail into the buffer.
+ */
+export declare function decodeReencodedPasteControls(text: string): string;
+/**
+ * Options for {@link BracketedPasteHandler}.
+ */
+export type BracketedPasteHandlerOptions = {
+    /**
+     * Byte cap for buffered paste content (default: 64 MiB). When exceeded,
+     * paste mode is aborted and the accumulated content is delivered as
+     * `pasteContent` on the same `process()` call so a lost/corrupted end
+     * marker cannot consume unbounded memory. Mirrors `StdinBuffer#abortPaste`
+     * — defense in depth for callers that bypass `StdinBuffer` (issue #4073
+     * case B). The normal `ProcessTerminal` path re-wraps `StdinBuffer`'s
+     * bounded paste with both markers, so this cap only fires on alternate
+     * callers.
+     */
+    byteLimit?: number;
+};
+/**
+ * Handles bracketed paste mode buffering for terminal input components.
+ *
+ * Bracketed paste mode wraps pasted content between start (\x1b[200~) and
+ * end (\x1b[201~) markers, which may arrive split across multiple chunks.
+ * This class buffers incoming data and assembles complete paste payloads.
+ */
+export declare class BracketedPasteHandler {
+    #private;
+    constructor(options?: BracketedPasteHandlerOptions);
+    /**
+     * Process incoming terminal data for bracketed paste sequences.
+     *
+     * @returns `{ handled: false }` if the data contains no paste sequence and
+     *          should be processed normally. `{ handled: true }` if the data was
+     *          consumed by paste buffering — `pasteContent` is set when a complete
+     *          paste has been assembled (or the byte cap has aborted a runaway
+     *          buffer); omitted when still buffering.
+     */
+    process(data: string): PasteResult;
+}

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

@@ -0,0 +1,31 @@
+import type { Component } from "../tui.js";
+/** Box-drawing glyphs plus an optional colorizer for an outline drawn around a {@link Box}. */
+export interface BoxBorder {
+    chars: {
+        topLeft: string;
+        topRight: string;
+        bottomLeft: string;
+        bottomRight: string;
+        horizontal: string;
+        vertical: string;
+    };
+    color?: (text: string) => string;
+}
+/**
+ * Box component - a container that applies padding and background to all children
+ */
+export declare class Box implements Component {
+    #private;
+    children: Component[];
+    setIgnoreTight(ignore: boolean): this;
+    constructor(paddingX?: number, paddingY?: number, bgFn?: (text: string) => string, border?: BoxBorder);
+    addChild(component: Component): void;
+    removeChild(component: Component): void;
+    clear(): void;
+    setPaddingX(paddingX: number): void;
+    setPaddingY(paddingY: number): void;
+    setBgFn(bgFn?: (text: string) => string): void;
+    setBorder(border?: BoxBorder): void;
+    invalidate(): void;
+    render(width: number): readonly string[];
+}

package/dist/types/components/cancellable-loader.d.ts

@@ -0,0 +1,21 @@
+import { Loader } from "./loader.js";
+/**
+ * Loader that can be cancelled with Escape.
+ * Extends Loader with an AbortSignal for cancelling async operations.
+ *
+ * @example
+ * const loader = new CancellableLoader(tui, cyan, dim, "Working...");
+ * loader.onAbort = () => done(null);
+ * doWork(loader.signal).then(done);
+ */
+export declare class CancellableLoader extends Loader {
+    #private;
+    /** Called when user presses Escape */
+    onAbort?: () => void;
+    /** AbortSignal that is aborted when user presses Escape */
+    get signal(): AbortSignal;
+    /** Whether the loader was aborted */
+    get aborted(): boolean;
+    handleInput(data: string): void;
+    dispose(): void;
+}

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

@@ -0,0 +1,166 @@
+import { type AutocompleteProvider } from "../autocomplete.js";
+import type { SymbolTheme } from "../symbols.js";
+import { type Component, type Focusable } from "../tui.js";
+import { type SelectListTheme } from "./select-list.js";
+export interface EditorTheme {
+    borderColor: (str: string) => string;
+    selectList: SelectListTheme;
+    symbols: SymbolTheme;
+    editorPaddingX?: number;
+    /** Style function for inline hint/ghost text (dim text after cursor) */
+    hintStyle?: (text: string) => string;
+}
+export interface EditorTopBorder {
+    /** The status content (already styled) */
+    content: string;
+    /** Visible width of the content */
+    width: number;
+    /** Optional logical revision that changes independently of available width. */
+    revision?: number;
+}
+interface HistoryEntry {
+    prompt: string;
+}
+interface HistoryStorage {
+    add(prompt: string, cwd?: string): Promise<void>;
+    getRecent(limit: number): HistoryEntry[];
+}
+export declare class Editor implements Component, Focusable {
+    #private;
+    /** Focusable interface - set by TUI when focus changes */
+    focused: boolean;
+    /** When set, replaces the normal cursor glyph at end-of-text with this ANSI-styled string. */
+    cursorOverride: string | undefined;
+    /** Display width of the cursorOverride glyph (needed because override may contain ANSI escapes). */
+    cursorOverrideWidth: number | undefined;
+    /** 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;
+    borderColor: (str: string) => string;
+    onAutocompleteUpdate?: () => void;
+    /** 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
+     *  stray text. MUST be a global regex; the editor recompiles a private copy so its `lastIndex`
+     *  is never shared with the caller. */
+    atomicTokenPattern: RegExp | undefined;
+    onSubmit?: (text: string) => void | Promise<void>;
+    onAltEnter?: (text: string) => void;
+    onChange?: (text: string) => void;
+    /** Called for a "marker-sized" paste — the point where the editor would otherwise collapse it
+     *  into a `[Paste #N]` token (> 10 lines or > 1000 characters). Return `true` to intercept:
+     *  the editor inserts nothing and records no undo state, leaving insertion to the host (e.g. a
+     *  "wrap in a code block / XML / attach as file" menu for very large pastes), which re-inserts
+     *  via {@link insertPaste} or {@link insertText}. Return `false` (or leave unset) for the
+     *  default collapse-to-marker behavior. `lineCount` is the sanitized paste's line count. */
+    onLargePaste?: (text: string, lineCount: number) => boolean;
+    onAutocompleteCancel?: () => void;
+    disableSubmit: boolean;
+    constructor(theme: EditorTheme);
+    setAutocompleteProvider(provider: AutocompleteProvider): void;
+    /**
+     * Set custom content for the top border (e.g., status line).
+     * Pass undefined to use the default plain border.
+     *
+     * Eager: the passed value is cached and reused every frame. Callers that
+     * mutate status upstream must recompute and call this again. Prefer
+     * {@link setTopBorderProvider} for high-frequency updates — it collapses
+     * per-event rebuilds to one per painted frame.
+     */
+    setTopBorder(content: EditorTopBorder | undefined): void;
+    /**
+     * Install a lazy provider invoked once per editor render with the current
+     * `availableWidth`. Overrides any eager content set via {@link setTopBorder}
+     * — pass `undefined` to detach and fall back to the eager slot.
+     *
+     * 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.
+     */
+    setTopBorderProvider(provider: ((availableWidth: number) => EditorTopBorder | undefined) | undefined): void;
+    /**
+     * Show or hide the editor border chrome.
+     */
+    setBorderVisible(borderVisible: boolean): void;
+    setPromptGutter(promptGutter: string | undefined): void;
+    /**
+     * Get the available width for top border content given a total terminal width.
+     * Accounts for the border characters and horizontal padding when visible.
+     */
+    getTopBorderAvailableWidth(terminalWidth: number): number;
+    /**
+     * Use the real terminal cursor instead of rendering a cursor glyph.
+     */
+    setUseTerminalCursor(useTerminalCursor: boolean): void;
+    /** Render a dedicated bottom border so terminal-local IME preedit cannot shift editor chrome. */
+    setImeSafeCursorLayout(enabled: boolean): void;
+    getUseTerminalCursor(): boolean;
+    setMaxHeight(maxHeight: number | undefined): void;
+    /** Enable/disable the right-border scrollbar. Only shown when content overflows. */
+    setScrollbarVisible(visible: boolean): void;
+    setPaddingX(paddingX: number): void;
+    getAutocompleteMaxVisible(): number;
+    setAutocompleteMaxVisible(maxVisible: number): void;
+    setHistoryStorage(storage: HistoryStorage): void;
+    /**
+     * Add a prompt to history for up/down arrow navigation.
+     * Called after successful submission.
+     */
+    addToHistory(text: string): void;
+    invalidate(): void;
+    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;
+    /**
+     * Get text with paste markers expanded to their actual content.
+     * Use this when you need the full content (e.g., for external editor).
+     */
+    getExpandedText(): string;
+    getLines(): string[];
+    getCursor(): {
+        line: number;
+        col: number;
+    };
+    moveToLineStart(): void;
+    moveToLineEnd(): void;
+    moveToMessageStart(): void;
+    moveToMessageEnd(): void;
+    /**
+     * Undo the last meaningful edit while ignoring transient text that is still present at the cursor.
+     * Used for command-like autocomplete actions whose typed trigger should not count as the edit being undone.
+     */
+    undoPastTransientText(transientText: string): void;
+    setText(text: string): void;
+    submit(): void;
+    /** Insert text at the current cursor position */
+    insertText(text: string): void;
+    /** Delete up to `count` characters immediately before the cursor on the current line.
+     *  Used to "track back" the auto-repeat spaces that the space-hold push-to-talk gesture
+     *  optimistically inserts before it recognizes the hold. Capped at the cursor column so it
+     *  never crosses a line boundary or under-runs the line. */
+    deleteBeforeCursor(count: number): void;
+    /** Show or replace a volatile speech-to-text preview at the cursor. The text is
+     *  inserted with undo suspended so a long live dictation never floods the undo
+     *  stack; finalize it with {@link commitVolatileText} or drop it with
+     *  {@link clearVolatileText}. Newlines are allowed. */
+    setVolatileText(text: string): void;
+    /** Remove the current volatile preview without committing it. */
+    clearVolatileText(): void;
+    /** Drop any volatile preview, then insert `text` as a single undoable edit. */
+    commitVolatileText(text: string): void;
+    /** Apply terminal paste semantics to text from non-bracketed paste transports. */
+    pasteText(text: string): void;
+    /** Insert `content` as a collapsed `[Paste #N]` marker (stored for expansion on submit via
+     *  {@link getExpandedText}). Hosts that intercept large pastes through {@link onLargePaste} use
+     *  this to re-insert a (possibly transformed) paste without re-triggering the interception hook. */
+    insertPaste(content: string): void;
+    isShowingAutocomplete(): boolean;
+}
+export {};

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

@@ -0,0 +1,165 @@
+import { type ImageDimensions } from "../terminal-capabilities.js";
+import type { Component } from "../tui.js";
+export interface ImageTheme {
+    fallbackColor: (str: string) => string;
+}
+export interface ImageOptions {
+    maxWidthCells?: number;
+    maxHeightCells?: number;
+    filename?: string;
+    /** Shared budget that caps how many inline images render as live graphics. */
+    budget?: ImageBudget;
+    /**
+     * Stable identity for the underlying image (e.g. `toolCallId:index`). Lets the
+     * budget hand back the same graphics id across component re-creations so a
+     * repaint replaces the placement instead of stacking a duplicate.
+     */
+    imageKey?: string;
+}
+/** Default count of inline images kept as live graphics before older ones fall back to text. */
+export declare const DEFAULT_MAX_INLINE_IMAGES = 8;
+/**
+ * Bounds how many inline images render as live terminal graphics at once.
+ *
+ * Terminal graphics protocols — Kitty especially — keep every transmitted image
+ * in a per-terminal store and re-draw placements as content scrolls; text-clear
+ * escapes (`CSI 2 J` / `CSI 3 J`) do not remove them. Unbounded, a session that
+ * shows many images piles up placements plus store memory and leaves ghosts in
+ * scrollback.
+ *
+ * The budget keeps the most recent `cap` images live and demotes older ones to
+ * their text fallback. Demotion needs a full redraw (so off-screen rows are
+ * rewritten) plus an explicit graphics purge of the demoted ids — {@link Image}
+ * reports display order via {@link observe}, and the TUI drives the purge +
+ * redraw on the frame after a new image pushes the count past the cap.
+ *
+ * `cap <= 0` disables budgeting: every image stays a live graphic.
+ */
+export declare class ImageBudget {
+    #private;
+    constructor(cap?: number, requestRender?: () => void);
+    get cap(): number;
+    get enabled(): boolean;
+    setRequestRender(requestRender: () => void): void;
+    setCap(cap: number): void;
+    /**
+     * Stable graphics id for a logical image. A non-empty `key` maps to the same
+     * id across re-creations (so repaints replace the placement); a missing key
+     * gets a fresh id every call.
+     */
+    acquireId(key?: string): number;
+    /**
+     * Begin a render pass. Called by the renderer before composing the frame.
+     * Pass `stable: true` for a partial/throwaway pass that does not walk the
+     * whole tree in display order (the resize viewport fast path): {@link observe}
+     * then replays the last committed per-id decision instead of one derived from
+     * call order, and the pass must NOT be closed with {@link endPass}.
+     */
+    beginPass(stable?: boolean): void;
+    /**
+     * Record an image in display order and report whether it must render its text
+     * fallback this frame. Called by every {@link Image} during render — including
+     * on a cache hit, so the image keeps its display-order slot.
+     *
+     * During a `stable` pass ({@link beginPass}) the call order and visible subset
+     * are not authoritative, so the decision is the committed on-terminal split
+     * (`#suppressedIds`) keyed by id — order- and partiality-independent.
+     */
+    observe(imageId: number): boolean;
+    /**
+     * End a render pass. Returns true when this frame must purge graphics and
+     * fully repaint to apply a stricter budget; read the ids via
+     * {@link takePurgeIds}.
+     */
+    endPass(): boolean;
+    /** Image ids to delete from the terminal this frame; clears the pending set. */
+    takePurgeIds(): readonly number[];
+    /** All image ids believed to be loaded in the terminal store; clears tracking. */
+    takeAllTransmittedIds(): readonly number[];
+    /** Whether `imageId`'s data still needs to be transmitted to the terminal. */
+    shouldTransmit(imageId: number): boolean;
+    /**
+     * Record a direct-placement image's source pixel geometry so the renderer
+     * can clip its placement to the visible slice at write time; cleared when
+     * the image is purged from the terminal store.
+     */
+    registerPlacementGeometry(imageId: number, widthPx: number, heightPx: number): void;
+    /**
+     * Record this frame's native-scrollback commit target (the frame-row count
+     * that is committed once the frame's writes land). Called once per rendered
+     * frame — including frames that emit no placements — so an epoch whose rows
+     * commit while its line is never rewritten is still flagged before the next
+     * re-emission.
+     */
+    observeCommitWatermark(committedTo: number): void;
+    /**
+     * End the physical-row coordinate epoch after observing its final commit
+     * watermark. Placement ids and latched archive state survive, but attachment
+     * rows do not: the next placement emit records them in the new-width frame.
+     */
+    beginPlacementCoordinateEpoch(): void;
+    /**
+     * Resolve the placement id and geometry for a direct-placement emit whose
+     * topmost attached cell sits at `attachTopFrameRow` — the first frame row
+     * the placement covers, i.e. the block's first *visible* row, not its
+     * origin (-1 when the writer has no frame-space position: alt-screen,
+     * resize, ConPTY-truncated replays). `committedTo` is this frame's commit
+     * target in the same frame-row space (-1 when unknown).
+     *
+     * Invariant: a placement id may be re-used (Kitty replace strips that id's
+     * cells everywhere, scrollback included) only while none of the cells it
+     * attached have entered native scrollback. The epoch — the `p=` id —
+     * advances exactly when the archived flag says otherwise; rewrites with no
+     * commit progression keep replacing the same id in place.
+     */
+    resolvePlacementEmit(imageId: number, attachTopFrameRow: number, committedTo: number): {
+        placementId: number;
+        widthPx: number;
+        heightPx: number;
+    } | null;
+    /**
+     * 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.
+     */
+    resetPlacementEpochs(): ReadonlyArray<{
+        imageId: number;
+        lastEpoch: number;
+    }>;
+    /**
+     * Queue a one-time transmit for `imageId`. No-op if already transmitted, so a
+     * repeated call (e.g. a width-change re-render) never re-sends the data.
+     */
+    enqueueTransmit(imageId: number, sequence: string): void;
+    /** Whether a frame has image data queued but not yet written to the terminal. */
+    hasPendingTransmits(): boolean;
+    /**
+     * True when the budget has nothing in flight: no live images observed on
+     * the last pass, no queued transmits, no pending purges, and no stricter
+     * threshold left to apply. A component-scoped frame may skip the observe
+     * pass only then — a partial tree walk would under-count display order.
+     */
+    get quiescent(): boolean;
+    /** Transmit sequences to write before this frame's placements; clears the queue. */
+    takeTransmits(): readonly string[];
+    /**
+     * Drop transmit tracking so every still-live image re-enqueues its data
+     * (`a=t`) on the next render. Recovers when the terminal dropped the original
+     * transmit — e.g. Ghostty discarding graphics sent during its post-startup
+     * window — where a placement-only replay can never bind a Unicode placeholder.
+     * Pair with a component invalidate + forced repaint so the data and placement
+     * re-emit together; keeps no base64 in budget state (the transmit-once design).
+     */
+    forgetTransmitted(): void;
+}
+export declare class Image implements Component {
+    #private;
+    constructor(base64Data: string, mimeType: string, theme: ImageTheme, options?: ImageOptions, dimensions?: ImageDimensions);
+    invalidate(): void;
+    render(width: number): readonly string[];
+}

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

@@ -0,0 +1,25 @@
+import { type Component, type Focusable } from "../tui.js";
+/**
+ * Input component - single-line text input with horizontal scrolling
+ */
+export declare class Input implements Component, Focusable {
+    #private;
+    /** Rendered before the editable area; set to "" for chrome-less embedding. */
+    prompt: string;
+    /** Render the editable value as bullets while retaining the real value internally. */
+    mask: boolean;
+    onSubmit?: (value: string) => void;
+    onEscape?: () => void;
+    /** Focusable interface - set by TUI when focus changes */
+    focused: boolean;
+    getValue(): string;
+    setValue(value: string): void;
+    setUseTerminalCursor(useTerminalCursor: boolean): void;
+    getUseTerminalCursor(): boolean;
+    handleInput(data: string): void;
+    /** Apply terminal paste semantics to text from non-bracketed paste transports
+     *  (e.g. kitty's OSC 5522 enhanced clipboard read). Mirrors `Editor.pasteText`. */
+    pasteText(text: string): void;
+    invalidate(): void;
+    render(width: number): readonly string[];
+}

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

@@ -0,0 +1,25 @@
+import type { TUI } from "../tui.js";
+import { Text } from "./text.js";
+type ColorFn = (str: string) => string;
+/**
+ * Styles Loader message fragments without changing their visible text or width.
+ * Set `animated` for colorizers whose ANSI output changes over time.
+ */
+export type LoaderMessageColorFn = ColorFn & {
+    readonly animated?: true;
+};
+/** Animates a spinner and colorized message while asynchronous work is pending. */
+export declare class Loader extends Text {
+    #private;
+    private spinnerColorFn;
+    private messageColorFn;
+    private message;
+    constructor(ui: TUI, spinnerColorFn: ColorFn, messageColorFn: LoaderMessageColorFn, message?: string, spinnerFrames?: string[]);
+    render(width: number): readonly string[];
+    start(): void;
+    stop(): void;
+    /** Lifecycle teardown: stop the animation timer. Idempotent. */
+    dispose(): void;
+    setMessage(message: string): void;
+}
+export {};