@gajae-code/tui 0.13.2 → 0.13.3

package/CHANGELOG.md

@@ -2,16 +2,24 @@
 
 ## [Unreleased]
 
+## [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
 
-- 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.
+- 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
 

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,28 @@
  * 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 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 +65,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,28 +81,38 @@ 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[];
 };
 /** 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 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";
     widthPx: number;
     heightPx: number;
     columns: number;
@@ -108,11 +122,11 @@ 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.
  */
 export declare function buildGajaePixelFrames(options: {
-    protocol: "sixel" | "kitty";
+    protocol: "sixel" | "kitty" | "iterm2";
     cellWidthPx: number;
     cellHeightPx: number;
     targetRows?: number;
@@ -121,6 +135,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;
+    /** Transparent iTerm2-only top padding for half-cell vertical alignment. */
+    iterm2TopPaddingPx?: number;
+    /** Transparent iTerm2-only bottom padding inside the two-row 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/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.13.2",
+	"version": "0.13.3",
 	"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.13.3",
+		"@gajae-code/utils": "0.13.3",
 		"lru-cache": "11.3.6",
 		"marked": "18.0.6"
 	},