@gajae-code/tui 0.13.3 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [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.
+- Escape presses immediately followed by a bracketed paste in the same read are now emitted as individual Escape presses instead of one coalesced sequence that parsed as the unbound `alt+escape` and swallowed every press.
+- A long run of Escape bytes arriving as many small reads no longer rescans the accumulated buffer on every read; only the two-byte ambiguous tail stays buffered, so 50,000 byte-by-byte Escape reads cost 50ms instead of 2.4s.
+- 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

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

@@ -56,7 +56,8 @@ export declare function resolvePetMode(value: string): PetMode;
 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
@@ -102,10 +103,77 @@ export declare function petBurstFrame(burst: PetBurst, elapsed: number, now: num
 export declare const __gajaePetTestHooks: {
     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. */
-export declare function encodeGridIterm2(grid: string[], scale: number, topPaddingPx?: number, bottomPaddingPx?: 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 {
@@ -113,7 +181,9 @@ export interface GajaePixelFrames {
     frames: Record<string, string>;
     /** protocol the frames were encoded for */
     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;
@@ -124,6 +194,17 @@ export interface GajaePixelFrames {
  * Build overlay pixel frames exactly `targetRows` terminal rows tall when the
  * 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" | "iterm2";
@@ -135,9 +216,9 @@ export declare function buildGajaePixelFrames(options: {
     /** Native sub-cell `Y=` pixel offset that drops the kitty sprite within its first cell. */
     kittyCellYOffsetPx?: number;
     kittyImageId?: number;
-    /** Transparent iTerm2-only top padding for half-cell vertical alignment. */
+    /** Additional transparent iTerm2-only top padding for sub-cell vertical alignment. */
     iterm2TopPaddingPx?: number;
-    /** Transparent iTerm2-only bottom padding inside the two-row canvas. */
+    /** Transparent iTerm2-only bottom padding inside the canvas. */
     iterm2BottomPaddingPx?: number;
     /** Color skin for the sprite palette (default "red"). */
     skin?: PetSkinId;

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.3",
+	"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.3",
-		"@gajae-code/utils": "0.13.3",
+		"@gajae-code/natives": "0.14.0",
+		"@gajae-code/utils": "0.14.0",
 		"lru-cache": "11.3.6",
 		"marked": "18.0.6"
 	},