@gajae-code/tui 0.13.2 → 0.14.0

package/CHANGELOG.md

@@ -2,9 +2,14 @@
 
 ## [Unreleased]
 
-## [0.13.2] - 2026-08-13
+## [0.14.0] - 2026-08-17
 
 ### Fixed
+- iTerm2 pet capability probes now wait for pending input without disabling Kitty keyboard mode, disabling `modifyOtherKeys`, or detaching the live input handler.
+- iTerm2 Gajae Pet frames now carry a dedicated filename, so dragging one retains iTerm's native drag behavior while the coding agent can discard only the temporary pet pathname pasted back into its composer.
+- iTerm2 Gajae Pet now uses one animated GIF upload per meaningful state change and a raster lease that excludes its cell rectangle from generic TUI redraw erases, eliminating animation flicker while preserving geometry-derived art placement and leaving Kitty and Sixel encoding unchanged.
+
+- Layout-only animation and selector frames can now reuse an unchanged revisioned transcript subtree instead of rebuilding every off-screen transcript component, anchor row, and Kitty placement on each tick. Ordinary render requests remain conservative, and transcript revision, width, identity, and global invalidation changes still force a full subtree render.
 
 - A fast double-Esc (or triple-Esc) whose ESC bytes coalesce into one stdin chunk — which tmux always produces within its escape-time window, and SSH batching produces routinely — is now emitted as individual Escape key presses instead of a single `"\x1b\x1b"` sequence that parsed as the unbound `alt+escape` and silently swallowed both presses. This restores the double-Esc draft-clear and double-Esc selector gestures under tmux/SSH. Option-as-Meta sequences with a real continuation (e.g. Option+Up as `ESC ESC [ A`) remain atomic, and an ESC-cancelled incomplete sequence is still emitted whole.
 - An ambiguous trailing run of Escape bytes now stays buffered until a continuation or the flush timeout resolves it, so `ESC ESC ESC` followed by `[A` in the next chunk still decodes as Escape then `alt+up` instead of two Escapes plus a plain Up that fired the destructive double-Escape gesture.
@@ -13,6 +18,25 @@
 - A long run of Escape bytes followed by another key now decodes in linear time instead of rescanning the remaining input on every step, which blocked the event loop for over a second on a 50,000-byte run.
 - Apple Terminal.app now retains its default keyboard mode when it does not support the Kitty keyboard protocol, avoiding the modifyOtherKeys fallback that breaks Korean/Hangul IME composition.
 
+## [0.13.3] - 2026-08-15
+
+### Added
+- Added the Ouroboros pet component with frame data, selector integration, and animation lifecycle shared with the existing Gajae Pet (#4468).
+
+### Fixed
+- Non-finite overlay geometry can no longer turn frame padding into an infinite allocating loop on the main thread; margins, positions, offsets, and minimum widths now fall back to bounded terminal-relative values (#4481).
+- Kitty inline images are no longer deleted when live output moves their anchor above the viewport, so terminal-native scrollback keeps previously rendered images visible (#4424).
+
+## [0.13.2] - 2026-08-13
+
+### Fixed
+
+- Fast double-Esc and triple-Esc sequences coalesced into one stdin chunk by tmux or SSH are now emitted as individual Escape presses, restoring draft-clear and selector gestures while preserving atomic Option-as-Meta sequences (#4312 by @Yeachan-Heo).
+- Ambiguous trailing Escape bytes now remain buffered until a continuation or flush timeout resolves them, preventing a split `ESC ESC ESC [A` sequence from firing the destructive double-Escape gesture (#4312 by @Yeachan-Heo).
+- Escape presses immediately followed by bracketed paste are now emitted individually instead of being swallowed as an unbound `alt+escape` sequence (#4312 by @Yeachan-Heo).
+- Long runs of Escape bytes now decode in linear time without repeatedly rescanning accumulated input; 50,000 byte-by-byte reads now complete in milliseconds instead of seconds (#4312 by @Yeachan-Heo).
+- Apple Terminal.app now retains its default keyboard mode when it does not support the Kitty keyboard protocol, avoiding the modifyOtherKeys fallback that broke Korean/Hangul IME composition (#4297 by @Yeachan-Heo).
+
 ## [0.13.1] - 2026-08-11
 
 ### Added

package/dist/types/components/gajae-pet.d.ts

@@ -1,11 +1,12 @@
+import { type OuroborosFrameName } from "./ouroboros-pet";
 /**
  * ┌─ GAJAE PET SPRITE SPEC ────────────────────────────────────────────────┐
- * The pet is a 16×16 pixel sprite drawn beside the composer. Everything here is
- * data: no PNGs, no assets — each frame is 16 strings of 16 chars, encoded to a
- * sixel or kitty escape at runtime. Author a new frame by drawing a grid.
+ * Pets are square pixel sprites drawn beside the composer. Everything here is
+ * data: no PNGs or binary assets. Current pet frames are 16×16 and render into
+ * the same terminal footprint.
  *
  * GRID RULES
- * - Exactly 16 rows × 16 columns. Only PALETTE keys below are valid chars.
+ * - Every frame within a skin has the same square dimensions.
  * - `.` = transparent. Keep the outer columns transparent so the sprite sits
  *   snug beside the input box (the widget reserves +1 column of slack).
  *
@@ -26,7 +27,8 @@
  * RENDERING: buildGajaePixelFrames({ protocol, cellWidthPx, cellHeightPx,
  * targetRows: 2 }) scales the art to 2 terminal rows and encodes each frame
  * once. Kitty uses a native `Y=` sub-cell drop (set by the widget) to sit on the
- * composer border; sixel uses transparent top padding.
+ * composer border; sixel uses transparent top padding; iTerm2 uses an inline PNG
+ * sized to the reserved cell block.
  *
  * BEHAVIOR (timing, positioning, on/off) lives in
  * packages/coding-agent/src/modes/components/gajae-pet-widget.ts.
@@ -34,26 +36,29 @@
  * ADD A FRAME: draw the grid → add its name to GajaePixelFrameName → register it in
  * PIXEL_GRIDS → reference it from an idle/work loop or a skin burst.
  *
- * ADD A PET (skin): append one entry to PET_SKINS below — { id, label, description,
- * palette, burst }. The id flows into PetSkinId/PetMode automatically, the settings
- * enum, `/pet` command and both selectors derive their options from PET_SKINS, and the
- * widget reads `burst` to animate — no other file needs editing. Recolor with a palette
- * spread (see BLUE_PALETTE); add frames only for poses the catalog lacks.
+ * ADD A PET (skin): append one PET_SKINS entry with its palette, frame registry,
+ * base/idle/work animations and burst. The id flows into PetSkinId/PetMode
+ * automatically; settings, `/pet`, and both selectors derive from PET_SKINS.
  * └────────────────────────────────────────────────────────────────────────┘
  */
 type Rgb = readonly [number, number, number];
 export type Palette = Record<string, Rgb | null>;
-export declare const PET_SKIN_IDS: readonly ["red", "blue"];
+export declare const PET_SKIN_IDS: readonly ["red", "blue", "ouroboros"];
 export type PetSkinId = (typeof PET_SKIN_IDS)[number];
 /** Every pet mode: "off" plus each skin id, in menu order. */
-export declare const PET_MODE_IDS: readonly ["off", "red", "blue"];
+export declare const PET_MODE_IDS: readonly ["off", "red", "blue", "ouroboros"];
 export type PetMode = (typeof PET_MODE_IDS)[number];
 /** Narrow an arbitrary string to a PetMode. */
 export declare function isPetMode(value: string): value is PetMode;
+/** Resolve a persisted mode after a skin has been removed. Explicit "off" remains off. */
+export declare function resolvePetMode(value: string): PetMode;
 /** Logical pixel-pet frame names shared by the overlay state machine. */
 export type GajaePixelFrameName = "base" | "gazeL" | "gazeR" | "flicker" | "flex" | "danceL" | "danceR" | "cry1" | "cry2" | "cry3";
+export type PetFrameName = GajaePixelFrameName | OuroborosFrameName;
 /** Para-para work dance beats: the working loop and each skin's burst "work-in" intro. */
-export declare const PARA_PARA_STEPS: ReadonlyArray<readonly [GajaePixelFrameName, number]>;
+export type GajaeGifFrameTuple = readonly [GajaePixelFrameName, number];
+export declare const PARA_PARA_STEPS: readonly GajaeGifFrameTuple[];
+export declare const GAJAE_IDLE_STEPS: ReadonlyArray<readonly [GajaePixelFrameName, number]>;
 /**
  * A skin's idle burst: a short intro sequence, then an optional looping tail. It drives
  * BOTH the random live show-off AND the selector's preview demo, so give every skin a
@@ -61,10 +66,10 @@ export declare const PARA_PARA_STEPS: ReadonlyArray<readonly [GajaePixelFrameNam
  */
 export interface PetBurst {
     /** Frames played once, in order, at the start of the burst. */
-    intro: ReadonlyArray<readonly [GajaePixelFrameName, number]>;
+    intro: ReadonlyArray<readonly [PetFrameName, number]>;
     /** Frames cycled every `stepMs` for `ms` after the intro (a held or looping finish). */
     tail?: {
-        frames: readonly GajaePixelFrameName[];
+        frames: readonly PetFrameName[];
         stepMs: number;
         ms: number;
     };
@@ -77,29 +82,108 @@ export interface PetSkin {
     /** One-line selector/settings description. */
     description: string;
     palette: Palette;
+    frames: Readonly<Record<string, string[]>>;
+    baseFrame: PetFrameName;
+    idle: ReadonlyArray<readonly [PetFrameName, number]>;
+    workEnter?: ReadonlyArray<readonly [PetFrameName, number]>;
+    work: ReadonlyArray<readonly [PetFrameName, number]>;
+    workExit?: ReadonlyArray<readonly [PetFrameName, number]>;
     /** Idle burst animation played between quiet idle loops. */
     burst: PetBurst;
+    /** Optional variants that interrupt and then resume the work loop. */
+    workBursts?: readonly PetBurst[];
 }
 /** Skin registry — the single source for palettes, behavior and selector/command copy. */
 export declare const PET_SKINS: Record<PetSkinId, PetSkin>;
 /** Total burst duration (intro beats plus the looping tail). */
 export declare function petBurstDurationMs(burst: PetBurst): number;
 /** The frame to show `elapsed` ms into a burst (`now` cycles the looping tail). */
-export declare function petBurstFrame(burst: PetBurst, elapsed: number, now: number): GajaePixelFrameName;
+export declare function petBurstFrame(burst: PetBurst, elapsed: number, now: number): PetFrameName;
 /** Test-only access to logical art; production rendering still uses encoded frames. */
 export declare const __gajaePetTestHooks: {
-    getPixelGrid(name: GajaePixelFrameName): string[];
+    getPixelGrid(name: PetFrameName, skin?: PetSkinId): string[];
 };
+export interface GajaeGifFrame {
+    readonly name: PetFrameName;
+    readonly delayMs: number;
+}
+export type GajaeGifTimeline = readonly GajaeGifFrame[];
+export interface GajaeGifRectangle {
+    readonly width?: number;
+    readonly height?: number;
+}
+export interface GajaeGifDisplaySize {
+    /** iTerm2 display width: bare numbers are terminal cells; strings may use px or auto. */
+    readonly width: number | string;
+    /** iTerm2 display height: bare numbers are terminal cells; strings may use px or auto. */
+    readonly height: number | string;
+}
+export interface GajaeGifContentInset {
+    /** Transparent top padding in source pixels. */
+    readonly topPx?: number;
+    /** Transparent bottom padding in source pixels. */
+    readonly bottomPx?: number;
+}
+export interface GajaePetGifArtifact {
+    readonly bytes: Uint8Array;
+    readonly base64: string;
+    readonly width: number;
+    readonly height: number;
+    readonly frames: readonly GajaeGifFrame[];
+    readonly skin: PetSkinId;
+    readonly multipart: readonly string[];
+    readonly tmuxDcs: readonly string[];
+}
+export interface GajaePetGifOptions {
+    readonly skin?: PetSkinId;
+    readonly timeline?: GajaeGifTimeline;
+    readonly cellWidthPx?: number;
+    readonly cellHeightPx?: number;
+    readonly targetRows?: number;
+    readonly rectangle?: GajaeGifRectangle;
+    readonly displaySize?: GajaeGifDisplaySize;
+    readonly contentInset?: GajaeGifContentInset;
+}
+export declare const idleTimeline: () => GajaeGifTimeline;
+export declare const workingTimeline: () => GajaeGifTimeline;
+export declare const burstTimeline: (skin?: PetSkinId) => GajaeGifTimeline;
+export declare const previewTimeline: (skin?: PetSkinId) => GajaeGifTimeline;
+export declare function encodeGajaePetGif(input?: GajaePetGifOptions | GajaeGifTimeline): GajaePetGifArtifact;
+export declare function getGajaePetGifCached(input?: GajaePetGifOptions | GajaeGifTimeline): GajaePetGifArtifact;
+export declare function getGajaePetGifCacheStats(): {
+    size: number;
+    bytes: number;
+    gifBytes: number;
+    base64Bytes: number;
+    multipartBytes: number;
+    tmuxDcsBytes: number;
+    evictions: number;
+};
+export declare function resetGajaePetGifCache(): void;
+export declare const clearGajaePetGifCache: typeof resetGajaePetGifCache;
 /** Encode a grid as a transparent SIXEL image, optionally bottom-aligned by top padding. */
 export declare function encodeGridSixel(grid: string[], scale: number, topPaddingPx?: number, palette?: Palette): string;
+/**
+ * Encode a grid as an iTerm2 inline PNG spanning a terminal cell block.
+ *
+ * The escape's `width`/`height` are the reserved cell-block footprint in
+ * character cells (unitless numbers per the iTerm2 inline-images protocol).
+ * iTerm2 resolves cells against its own live font metrics, so the sprite
+ * scales with the real terminal geometry — including Retina, where iTerm2
+ * divides `Npx` values by the backing-scale factor and would render a fixed
+ * pixel box at half size.
+ */
+export declare function encodeGridIterm2(grid: string[], scale: number, columns: number, rows: number, topPaddingPx?: number, bottomPaddingPx?: number, leftPaddingPx?: number, rightPaddingPx?: number, palette?: Palette): string;
 /** Encode a bottom-aligned grid as kitty raw RGBA at `scale`. */
 export declare function encodeGridKitty(grid: string[], scale: number, imageId: number, cols: number, rows: number, topPaddingPx?: number, cellYOffsetPx?: number, leftPaddingPx?: number, rightPaddingPx?: number, palette?: Palette): string;
 export interface GajaePixelFrames {
     /** escape payload per logical frame (drawn at the current cursor cell) */
-    frames: Record<GajaePixelFrameName, string>;
+    frames: Record<string, string>;
     /** protocol the frames were encoded for */
-    protocol: "sixel" | "kitty";
+    protocol: "sixel" | "kitty" | "iterm2";
+    /** Scaled sprite width before transparent cell-block padding. */
     widthPx: number;
+    /** Encoded raster height, including protocol-specific transparent padding. */
     heightPx: number;
     columns: number;
     rows: number;
@@ -108,11 +192,22 @@ export interface GajaePixelFrames {
 }
 /**
  * Build overlay pixel frames exactly `targetRows` terminal rows tall when the
- * terminal cells permit it. Nearest-neighbor sampling preserves the 16x16 art
- * while allowing fractional scale factors such as 36px / 16px.
+ * terminal cells permit it. Each skin owns its source resolution so future
+ * additions can opt into denser art without changing the terminal footprint.
+ *
+ * Geometry contract:
+ * - `scale = max(1, targetRows * cellHeightPx / gridHeight)`
+ * - `columns = ceil(scaledSpriteWidthPx / cellWidthPx)`
+ * - `rows = ceil(scaledSpriteHeightPx / cellHeightPx)`
+ * - the square sprite is centered in a `columns * cellWidthPx` PNG canvas
+ *
+ * iTerm2 receives unitless `width=columns;height=rasterRows`, so it resolves the
+ * padded block with its live cell metrics. The PNG has that block's pixel aspect
+ * ratio, allowing `preserveAspectRatio=0` without stretching the authored square
+ * sprite. Kitty and Sixel retain their protocol-specific paths.
  */
 export declare function buildGajaePixelFrames(options: {
-    protocol: "sixel" | "kitty";
+    protocol: "sixel" | "kitty" | "iterm2";
     cellWidthPx: number;
     cellHeightPx: number;
     targetRows?: number;
@@ -121,6 +216,10 @@ export declare function buildGajaePixelFrames(options: {
     /** Native sub-cell `Y=` pixel offset that drops the kitty sprite within its first cell. */
     kittyCellYOffsetPx?: number;
     kittyImageId?: number;
+    /** Additional transparent iTerm2-only top padding for sub-cell vertical alignment. */
+    iterm2TopPaddingPx?: number;
+    /** Transparent iTerm2-only bottom padding inside the canvas. */
+    iterm2BottomPaddingPx?: number;
     /** Color skin for the sprite palette (default "red"). */
     skin?: PetSkinId;
 }): GajaePixelFrames;

package/dist/types/components/ouroboros-pet.d.ts

@@ -0,0 +1,23 @@
+export declare const OUROBOROS_FRAME_NAMES: readonly ["idle", "tongue-1", "tongue-2", "blink", "cry-1", "cry-2", "cry-3", "heart-turn-0", "heart-turn-1", "heart-turn-3", "heart-turn-4", "heart-turn-5", "heart-turn-6", "heart-turn-10", "heart-turn-11", "heart", "heart-accent", "enter-1", "enter-2", "spin-1", "spin-2", "spin-3", "spin-4", "spin-5", "spin-6", "spin-7", "spin-8"];
+export type OuroborosFrameName = (typeof OUROBOROS_FRAME_NAMES)[number];
+export declare const OUROBOROS_PIXEL_GRIDS: Record<OuroborosFrameName, string[]>;
+/** Quiet loop with frequent tongue flicks and an occasional three-drop sob. */
+export declare const OUROBOROS_IDLE_STEPS: ReadonlyArray<readonly [OuroborosFrameName, number]>;
+/** One sob builds into three distinct tear drops: 1-2-3-2-3-2-3. */
+export declare const OUROBOROS_CRY_STEPS: ReadonlyArray<readonly [OuroborosFrameName, number]>;
+/**
+ * Signature flex: the eye opens before the body rolls counterclockwise through
+ * 45°, 90°, 120°, and the final overlap with the heart pose. The return reuses
+ * the authored frames in reverse.
+ */
+export declare const OUROBOROS_HEART_STEPS: ReadonlyArray<readonly [OuroborosFrameName, number]>;
+/** Head leads left while the resting coil resolves into the infinity loop. */
+export declare const OUROBOROS_WORK_ENTER_STEPS: ReadonlyArray<readonly [OuroborosFrameName, number]>;
+/** The exact inverse of work entry, so stopping visibly unwinds into idle. */
+export declare const OUROBOROS_WORK_EXIT_STEPS: ReadonlyArray<readonly [OuroborosFrameName, number]>;
+/** Retouched eight-frame infinity loop with the full body following the head. */
+export declare const OUROBOROS_WORK_STEPS: ReadonlyArray<readonly [OuroborosFrameName, number]>;
+/** Leave the infinity loop, perform the heart flourish, then resolve back into it. */
+export declare const OUROBOROS_WORK_HEART_STEPS: ReadonlyArray<readonly [OuroborosFrameName, number]>;
+/** Leave the infinity loop for a three-drop sob, then resume at full size. */
+export declare const OUROBOROS_WORK_CRY_STEPS: ReadonlyArray<readonly [OuroborosFrameName, number]>;

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

@@ -21,6 +21,7 @@ export interface SelectListTheme {
     noMatch: (text: string) => string;
     symbols: SymbolTheme;
 }
+export type SelectListThemeSource = SelectListTheme | (() => SelectListTheme);
 export interface SelectListTruncatePrimaryContext {
     text: string;
     maxWidth: number;
@@ -37,12 +38,12 @@ export declare class SelectList implements Component {
     #private;
     private readonly items;
     private readonly maxVisible;
-    private readonly theme;
+    private readonly themeSource;
     private readonly layout;
     onSelect?: (item: SelectItem) => void;
     onCancel?: () => void;
     onSelectionChange?: (item: SelectItem) => void;
-    constructor(items: ReadonlyArray<SelectItem>, maxVisible: number, theme: SelectListTheme, layout?: SelectListLayoutOptions);
+    constructor(items: ReadonlyArray<SelectItem>, maxVisible: number, themeSource: SelectListThemeSource, layout?: SelectListLayoutOptions);
     setFilter(filter: string): void;
     setSelectedIndex(index: number): void;
     handleNavigation(action: "tui.select.up" | "tui.select.down" | "tui.select.pageUp" | "tui.select.pageDown"): void;

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

@@ -195,4 +195,26 @@ export interface RenderedImage {
 }
 export declare function renderImage(base64Data: string, imageDimensions: ImageDimensions, options?: ImageRenderOptions): RenderedImage | null;
 export declare function imageFallback(mimeType: string, dimensions?: ImageDimensions, filename?: string): string;
+export type Iterm2Capability = {
+    readonly key: string;
+    readonly value: string;
+};
+export type Iterm2CapabilityReply = "complete-f" | "missing-f" | "invalid-f" | undefined;
+/**
+ * Classifies complete iTerm2 capability replies. An absent result means the
+ * input does not yet contain a complete capability frame.
+ */
+export declare function parseITerm2CapabilityReply(input: Uint8Array | string): Iterm2CapabilityReply;
+export declare function encodeITerm2Multipart(base64Data: string, options?: {
+    width?: number | string;
+    height?: number | string;
+}): string[];
+export declare function wrapITerm2RecordForTmux(record: string): string;
+export declare function wrapITerm2RecordsForTmux(records: readonly string[]): string[];
+export declare function parseITerm2Capabilities(input: string): Iterm2Capability[];
+export declare class Iterm2CapabilitiesParser {
+    #private;
+    push(input: Uint8Array | string): Iterm2Capability[];
+    reset(): void;
+}
 export {};

package/dist/types/terminal.d.ts

@@ -45,6 +45,14 @@ export interface Terminal {
      * @param idleMs - Exit early if no input arrives within this time (default: 50ms)
      */
     drainInput(maxMs?: number, idleMs?: number): Promise<void>;
+    /**
+     * Wait for pending stdin to go quiet without changing terminal protocols or
+     * the active input handler. Capability probes use this non-destructive drain;
+     * shutdown paths must continue using drainInput().
+     * @param maxMs - Maximum time to wait (default: 1000ms)
+     * @param idleMs - Exit early if no input arrives within this time (default: 50ms)
+     */
+    drainPendingInput?(maxMs?: number, idleMs?: number): Promise<void>;
     write(data: string): void;
     get available(): boolean;
     readonly isProcessTerminal?: boolean;
@@ -90,6 +98,7 @@ export declare class ProcessTerminal implements Terminal {
     onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
     setMouseEnabled(enabled: boolean): void;
     start(onInput: (data: string) => void, onResize: () => void): void;
+    drainPendingInput(maxMs?: number, idleMs?: number): Promise<void>;
     drainInput(maxMs?: number, idleMs?: number): Promise<void>;
     stop(): void;
     write(data: string): void;

package/dist/types/tui.d.ts

@@ -1,5 +1,82 @@
 import type { Terminal } from "./terminal";
 import { visibleWidth } from "./utils";
+export type CellRect = Readonly<{
+    column: number;
+    row: number;
+    width: number;
+    height: number;
+}>;
+export type RasterLeaseToken = Readonly<{
+    ownerId: string;
+    generation: number;
+    rect: CellRect;
+}>;
+export type RasterLeaseInvalidatedNotification = Readonly<{
+    type: "raster-lease-invalidated";
+    queueId: number;
+    token: RasterLeaseToken;
+    cause: "intersecting-generic-output" | "full-redraw" | "resize" | "terminal-loss" | "capability-loss" | "mode-off" | "dispose" | "explicit" | "manual-viewport";
+    eraseAck: TerminalOutputAck;
+}>;
+export type RasterLeaseRequest = Readonly<{
+    ownerId: string;
+    rect: CellRect;
+    erase: Readonly<{
+        type: "raster-erase";
+        bytes: Uint8Array;
+    }>;
+    onInvalidated?: (notice: RasterLeaseInvalidatedNotification) => void;
+}>;
+export type TerminalOutputOperation = Readonly<{
+    type: "generic-render";
+    rect: CellRect;
+    bytes: Uint8Array;
+}> | Readonly<{
+    type: "generic-full-redraw";
+    rect: CellRect;
+    bytes: Uint8Array;
+}> | Readonly<{
+    type: "raster-multipart-batch";
+    records: readonly Uint8Array[];
+    prefix?: Uint8Array;
+    afterPrefix?: () => Promise<boolean>;
+    /** Synchronous freshness gate evaluated immediately before terminal output. */
+    shouldWrite?: () => boolean;
+    replayPrefix?: Uint8Array;
+    suffix?: Uint8Array;
+    abortSuffix?: Uint8Array;
+    restoreCursorVisibility?: boolean;
+}> | Readonly<{
+    type: "raster-erase";
+    bytes: Uint8Array;
+}> | Readonly<{
+    type: "raster-probe";
+    bytes: Uint8Array;
+}> | Readonly<{
+    type: "queued-output";
+    bytes: Uint8Array;
+    shouldWrite?: () => boolean;
+    /** Runs synchronously at the terminal write boundary after a successful write. */
+    onWritten?: () => void;
+}>;
+export type TerminalOutputAck = Readonly<{
+    queueId: number;
+    operation: TerminalOutputOperation["type"];
+    status: "written" | "stale-token" | "revoked" | "failed";
+    token?: RasterLeaseToken;
+}>;
+export type LifecycleCleanupAck = Readonly<{
+    attempted: number;
+    written: number;
+    stillPending: number;
+}>;
+export type RasterLeaseAcquireResult = Readonly<{
+    status: "acquired";
+    token: RasterLeaseToken;
+}> | Readonly<{
+    status: "rejected";
+    reason: "invalid-geometry" | "terminal-unavailable" | "owner-conflict" | "manual-viewport";
+}>;
 /** Discrete mouse-wheel notch size in terminal rows (xterm/less-style). */
 export declare const DEFAULT_WHEEL_LINES = 3;
 type InputListenerResult = {
@@ -7,6 +84,10 @@ type InputListenerResult = {
     data?: string;
 } | undefined;
 type InputListener = (data: string) => InputListenerResult;
+type PostRenderEmission = {
+    payload: string;
+    onWritten?: () => void;
+};
 /**
  * Component interface - all components must implement this
  */
@@ -53,6 +134,12 @@ export interface Component {
      * Default is false - release events are filtered out.
      */
     wantsKeyRelease?: boolean;
+    /**
+     * Optional monotonic revision for renderer-level subtree reuse. Components that
+     * expose this MUST advance it whenever render output can change without a
+     * width change. Unversioned components are always rendered normally.
+     */
+    getRenderRevision?(): bigint;
     /**
      * Invalidate any cached rendering state.
      * Called when theme changes or when component needs to re-render from scratch.
@@ -238,6 +325,7 @@ export interface OverlayHandle {
 export declare class Container implements ViewportAnchorProvider {
     #private;
     children: Component[];
+    getRenderRevision(): bigint;
     addChild(component: Component): void;
     removeChild(component: Component): void;
     /** Remove a child without disposing it (for detach-then-readd reuse). */
@@ -254,6 +342,8 @@ export declare class Container implements ViewportAnchorProvider {
     clear(): void;
     /** Remove all children without disposing them (for detach-then-readd reuse). */
     detachAll(): void;
+    /** Replace direct children without disposing reusable components. */
+    replaceChildren(children: Component[]): void;
     /** Registers a direct child as eligible for semantic viewport anchoring. */
     setViewportAnchorSource(component: Component, source: ViewportAnchorSource | null): void;
     dispose(): void;
@@ -344,6 +434,20 @@ export declare class TUI extends Container {
     /** Check if there are any visible overlays */
     hasOverlay(): boolean;
     invalidate(): void;
+    acquireRasterLease(request: RasterLeaseRequest): Promise<RasterLeaseAcquireResult>;
+    submitTerminalOutput(request: Readonly<{
+        operation: TerminalOutputOperation;
+        token?: RasterLeaseToken;
+    }>): Promise<TerminalOutputAck>;
+    invalidateRasterLease(request: Readonly<{
+        token: RasterLeaseToken;
+        cause: RasterLeaseInvalidatedNotification["cause"];
+    }>): Promise<TerminalOutputAck>;
+    notifyTerminalLifecycle(event: {
+        kind: "availability-restored" | "explicit-cleanup";
+        source: "tui" | "interactive-mode" | "transport";
+        terminalGeneration: number;
+    }): Promise<LifecycleCleanupAck>;
     start(): void;
     /**
      * Wait for a specific render request generation to be written successfully.
@@ -355,8 +459,15 @@ export declare class TUI extends Container {
      */
     waitForRenderCommit(generation: number, timeoutMs?: number): Promise<boolean>;
     get terminalAvailable(): boolean;
+    get isRunning(): boolean;
+    get terminalGeneration(): number;
+    get manualViewportActive(): boolean;
     addInputListener(listener: InputListener): () => void;
+    drainInput(maxMs: number, quiescenceMs: number): Promise<void>;
+    drainPetProbeInput(maxMs: number, quiescenceMs: number): Promise<void>;
     removeInputListener(listener: InputListener): void;
+    /** Refresh terminal cell metrics for a verified external image transport. */
+    refreshImageCellSize(): void;
     stop(): void;
     /**
      * Viewport-repaint-aware resize render request.
@@ -372,6 +483,8 @@ export declare class TUI extends Container {
      */
     requestResizeRender(): void;
     requestRender(force?: boolean, source?: string): void;
+    /** Request a frame whose mutation is known to be outside the viewport-anchor subtree. */
+    requestLayoutRender(source?: string): void;
     requestRenderWithGeneration(force?: boolean, source?: string): number;
     getLineRenderCacheStats(): {
         normalizationSize: number;
@@ -380,13 +493,18 @@ export declare class TUI extends Container {
         truncationLimit: number;
     };
     /** Retain terminal cleanup until a write succeeds, even after its component is disposed. */
-    queueTerminalCleanup(payload: string, onDelivered?: () => void): void;
-    /** Retry queued terminal cleanup after terminal recovery or before shutdown. */
-    flushTerminalCleanup(): void;
+    queueTerminalCleanup(payload: string, onDelivered?: () => void): Promise<void>;
+    /** Queue protocol-neutral output behind the same terminal ordering as renders. */
+    queueTerminalOutput(payload: string, options?: {
+        shouldWrite?: () => boolean;
+        onWritten?: () => void;
+    }): Promise<TerminalOutputAck>;
+    /** Retry retained cleanup after recovery or before shutdown. */
+    flushTerminalCleanup(restoreTerminalAvailability?: boolean): void;
     /**
      * Register an emitter whose payload is delivered after each shared render
      * transaction. The emitter is an exempt physical overlay: its bytes are
      * deliberately kept out of the shared transcript write.
      */
-    setPostRenderEmitter(emitter: (() => string | null) | undefined): void;
+    setPostRenderEmitter(emitter: (() => string | PostRenderEmission | null) | undefined): void;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.13.2",
+	"version": "0.14.0",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -36,8 +36,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.13.2",
-		"@gajae-code/utils": "0.13.2",
+		"@gajae-code/natives": "0.14.0",
+		"@gajae-code/utils": "0.14.0",
 		"lru-cache": "11.3.6",
 		"marked": "18.0.6"
 	},