@gajae-code/tui 0.9.5 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-07-12
+### Fixed
+
+- Unified TUI wrapping, truncation, and visible-width measurements on the native grapheme-width engine, preventing Hangul tone marks from causing Korean/CJK layout width drift (#1979).
+
+- Preserved durable transcript semantic anchors at their screen rows when completion removes transient content, including CJK/emoji/ANSI reflow, prefix eviction, provider replacement, explicit exclusion of synthetic/IRC/pinned rows, and supported SSH, tmux, Termux, and Windows terminal paths (#1969).
+
+### Added
+
+- Added transparent Sixel and Kitty real-pixel encoders plus animated 16x16 frame art for the Gajae composer pet.
+- Added an opt-in IRC sidebar split (`alt+i`, remappable): a responsive 70:30 vertical right-hand split that renders Discord-style IRC message blocks through a shared inline/sidebar formatter, with unbounded session backfill and tail-aligned panes. Kitty terminals render inline images inside the split via a cursor-neutral graphics fallback; cursor-advancing protocols (iTerm2, raw Sixel) keep the textual placeholder (#2018).
+
 ## [0.9.4] - 2026-07-09
 
 ### Fixed

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

@@ -0,0 +1,127 @@
+/**
+ * ┌─ 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.
+ *
+ * GRID RULES
+ * - Exactly 16 rows × 16 columns. Only PALETTE keys below are valid chars.
+ * - `.` = transparent. Keep the outer columns transparent so the sprite sits
+ *   snug beside the input box (the widget reserves +1 column of slack).
+ *
+ * PALETTE (char → role) — see PALETTE for exact RGB:
+ *   .=transparent  K=dark outline  R=body red  r=red highlight
+ *   V=visor screen G=visor glow(green)  H=satgat straw  h=satgat brim
+ *   b=belly tan    A=antenna
+ *
+ * FRAME CATALOG (GajaePixelFrameName → PIXEL_GRIDS):
+ *   base    idle rest; also the dance "drop/settle" beat
+ *   gazeL   eyes glance left    ┐ idle loop (see gajae-pet-widget IDLE_LOOP)
+ *   gazeR   eyes glance right   │
+ *   flicker visor blink         ┘
+ *   flex    both claws up + `^^`; dance accent + random idle flex burst
+ *   danceL  left claw up + `><` + feet step left   ┐ work loop (PARA_PARA_STEPS)
+ *   danceR  right claw up + `^^` + feet step right  ┘
+ *
+ * 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.
+ *
+ * BEHAVIOR (timing, positioning, on/off) lives in
+ * packages/coding-agent/src/modes/components/gajae-pet-widget.ts.
+ *
+ * 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.
+ * └────────────────────────────────────────────────────────────────────────┘
+ */
+type Rgb = readonly [number, number, number];
+export type Palette = Record<string, Rgb | null>;
+export declare const PET_SKIN_IDS: readonly ["red", "blue"];
+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 type PetMode = (typeof PET_MODE_IDS)[number];
+/** Narrow an arbitrary string to a PetMode. */
+export declare function isPetMode(value: string): value is 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";
+/** 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]>;
+/**
+ * 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
+ * real animation (reuse PARA_PARA_STEPS for a work-in intro) rather than one held frame.
+ */
+export interface PetBurst {
+    /** Frames played once, in order, at the start of the burst. */
+    intro: ReadonlyArray<readonly [GajaePixelFrameName, number]>;
+    /** Frames cycled every `stepMs` for `ms` after the intro (a held or looping finish). */
+    tail?: {
+        frames: readonly GajaePixelFrameName[];
+        stepMs: number;
+        ms: number;
+    };
+}
+/** Everything that defines a pet skin: identity, UI copy, colors and behavior. */
+export interface PetSkin {
+    id: PetSkinId;
+    /** Selector/settings label, e.g. "RedGajae". */
+    label: string;
+    /** One-line selector/settings description. */
+    description: string;
+    palette: Palette;
+    /** Idle burst animation played between quiet idle loops. */
+    burst: 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;
+/** Test-only access to logical art; production rendering still uses encoded frames. */
+export declare const __gajaePetTestHooks: {
+    getPixelGrid(name: GajaePixelFrameName): 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 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>;
+    /** protocol the frames were encoded for */
+    protocol: "sixel" | "kitty";
+    widthPx: number;
+    heightPx: number;
+    columns: number;
+    rows: number;
+    /** terminal rows touched by the encoded raster, including pixel offset */
+    rasterRows: number;
+}
+/**
+ * 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.
+ */
+export declare function buildGajaePixelFrames(options: {
+    protocol: "sixel" | "kitty";
+    cellWidthPx: number;
+    cellHeightPx: number;
+    targetRows?: number;
+    /** Transparent pixel offset above sixel art for sub-cell vertical placement. */
+    sixelTopPaddingPx?: number;
+    /** Native sub-cell `Y=` pixel offset that drops the kitty sprite within its first cell. */
+    kittyCellYOffsetPx?: number;
+    kittyImageId?: number;
+    /** Color skin for the sprite palette (default "red"). */
+    skin?: PetSkinId;
+}): GajaePixelFrames;
+export {};

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

@@ -1,5 +1,6 @@
 import type { SymbolTheme } from "../symbols";
 import type { Component } from "../tui";
+import { type ViewportAnchorSpan } from "../utils";
 /** Test-only clock seam for streaming throttle tests. */
 export declare function __setMarkdownNowForTest(now: (() => number) | undefined): void;
 /** Test/diagnostic seam: number of synchronous highlight invocations since the last reset. */
@@ -70,6 +71,14 @@ export declare class Markdown implements Component {
     dispose(): void;
     invalidate(): void;
     render(width: number): string[];
+    renderWithViewportAnchorSource(width: number, source: {
+        id: string;
+    }): {
+        lines: string[];
+        anchors: Array<({
+            id: string;
+        } & ViewportAnchorSpan) | null>;
+    };
 }
 /**
  * Render inline markdown (bold, italic, code, links, strikethrough) to a styled string.

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

@@ -1,4 +1,5 @@
 import type { Component } from "../tui";
+import { type ViewportAnchorSpan } from "../utils";
 /**
  * Text component - displays multi-line text with word wrapping
  */
@@ -10,4 +11,12 @@ export declare class Text implements Component {
     setCustomBgFn(customBgFn?: (text: string) => string): void;
     invalidate(): void;
     render(width: number): string[];
+    renderWithViewportAnchorSource(width: number, source: {
+        id: string;
+    }): {
+        lines: string[];
+        anchors: Array<({
+            id: string;
+        } & ViewportAnchorSpan) | null>;
+    };
 }

package/dist/types/index.d.ts

@@ -3,6 +3,7 @@ export * from "./autocomplete";
 export * from "./components/box";
 export * from "./components/cancellable-loader";
 export * from "./components/editor";
+export * from "./components/gajae-pet";
 export * from "./components/image";
 export * from "./components/input";
 export * from "./components/loader";

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

@@ -22,6 +22,27 @@ export declare class TerminalInfo {
     sendNotification(message: string): void;
 }
 export declare function isNotificationSuppressed(): boolean;
+export interface TerminalGraphicsFallbackOptions {
+    /**
+     * Permit cursor-neutral image escapes (kitty `a=p,C=1` placements) to render
+     * inside this fallback scope. Cursor-advancing protocols (iTerm2/SIXEL)
+     * remain suppressed. A nested scope without this option revokes the
+     * permission for its own subtree.
+     */
+    allowCursorNeutralImages?: boolean;
+}
+/**
+ * Synchronously suppress terminal graphics while rendering a text-only surface.
+ * Nested scopes remain active until the outermost scope exits.
+ */
+export declare function withTerminalGraphicsFallback<T>(fn: () => T, options?: TerminalGraphicsFallbackOptions): T;
+/** Returns whether terminal graphics are currently suppressed by a render scope. */
+export declare function isTerminalGraphicsFallbackActive(): boolean;
+/**
+ * Returns whether cursor-neutral image escapes may render despite an active
+ * graphics-fallback scope. True only when every active fallback scope opted in.
+ */
+export declare function isCursorNeutralImagePermittedInFallback(): boolean;
 /**
  * Returns true when running in Windows Terminal with known SIXEL support.
  *

package/dist/types/tui.d.ts

@@ -57,6 +57,32 @@ export declare function isFocusable(component: Component | null): component is C
  */
 export declare const CURSOR_MARKER = "\u001B_pi:c\u0007";
 export { visibleWidth };
+/** Durable source identifier for a semantically anchored viewport row. */
+export type ViewportAnchorId = string;
+export interface ViewportAnchorRow {
+    id: ViewportAnchorId;
+    graphemeStart: number;
+    graphemeEnd: number;
+    cellStart: number;
+    cellEnd: number;
+}
+export interface ViewportAnchorRender {
+    lines: string[];
+    anchors: Array<ViewportAnchorRow | null>;
+}
+export interface ViewportAnchorProvider extends Component {
+    renderWithViewportAnchors(width: number): ViewportAnchorRender;
+}
+export interface ViewportAnchorSource {
+    id: ViewportAnchorId;
+}
+export interface ViewportAnchorSourceRenderer extends Component {
+    renderWithViewportAnchorSource(width: number, source: ViewportAnchorSource): ViewportAnchorRender;
+}
+export declare function isViewportAnchorProvider(component: Component): component is ViewportAnchorProvider;
+export declare function isViewportAnchorSourceRenderer(component: Component): component is ViewportAnchorSourceRenderer;
+export declare function renderComponentWithViewportAnchors(component: Component, width: number): ViewportAnchorRender;
+export declare function renderComponentWithViewportAnchorSource(component: Component, width: number, source: ViewportAnchorSource): ViewportAnchorRender;
 /**
  * Anchor position for overlays
  */
@@ -125,7 +151,7 @@ export interface OverlayHandle {
 /**
  * Container - a component that contains other components
  */
-export declare class Container implements Component {
+export declare class Container implements ViewportAnchorProvider {
     #private;
     children: Component[];
     addChild(component: Component): void;
@@ -135,9 +161,12 @@ export declare class Container implements Component {
     clear(): void;
     /** Remove all children without disposing them (for detach-then-readd reuse). */
     detachAll(): void;
+    /** Registers a direct child as eligible for semantic viewport anchoring. */
+    setViewportAnchorSource(component: Component, source: ViewportAnchorSource | null): void;
     dispose(): void;
     invalidate(): void;
     render(width: number): string[];
+    renderWithViewportAnchors(width: number): ViewportAnchorRender;
 }
 type TuiRenderCounterSnapshot = {
     debugRedrawEnvReads: number;
@@ -174,6 +203,12 @@ export declare class TUI extends Container {
     setClearOnShrink(enabled: boolean): void;
     setFocus(component: Component | null): void;
     setBottomPinnedComponent(component: Component | null): void;
+    /** Register the direct child whose rows are eligible for semantic viewport anchoring. */
+    setViewportAnchorComponent(component: Component | null): void;
+    /** Clear manual viewport ownership before replacing the transcript identity namespace. */
+    resetViewportAnchorIntent(): void;
+    /** Allow one semantic-neighbor reconciliation after a definitive same-transcript rebuild. */
+    prepareViewportAnchorForTranscriptRebuild(): void;
     scrollViewportPages(direction: -1 | 1): boolean;
     followLiveViewport(): boolean;
     /**
@@ -212,4 +247,11 @@ export declare class TUI extends Container {
         normalizationLimit: number;
         truncationLimit: number;
     };
+    /**
+     * Register an emitter whose escape payload is appended to every render
+     * write (inside its own synchronized-output block, cursor saved/restored).
+     * Used for absolute-positioned overlays such as pixel-image pets that live
+     * outside the line-based component model. Return null to emit nothing.
+     */
+    setPostRenderEmitter(emitter: (() => string | null) | undefined): void;
 }

package/dist/types/utils.d.ts

@@ -29,6 +29,29 @@ export declare function padding(n: number): string;
  * Get the shared grapheme segmenter instance.
  */
 export declare function getSegmenter(): Intl.Segmenter;
+export interface ViewportAnchorSpan {
+    graphemeStart: number;
+    graphemeEnd: number;
+    cellStart: number;
+    cellEnd: number;
+}
+export interface ViewportAnchorAnnotation {
+    text: string;
+    nextGrapheme: number;
+    nextCell: number;
+    token: string;
+}
+export declare const VIEWPORT_ANCHOR_PREFIX = "\u001B_AGJC_ANCHOR:";
+/**
+ * Tag every visible grapheme with an APC marker that survives ANSI-aware
+ * wrapping. The marker contains source grapheme and monotonic cell offsets.
+ */
+export declare function annotateViewportAnchorGraphemes(text: string, startGrapheme?: number, startCell?: number, token?: `${string}-${string}-${string}-${string}-${string}`): ViewportAnchorAnnotation;
+/** Remove viewport anchor markers and return the exact marked span for each row. */
+export declare function extractViewportAnchorRows(lines: readonly string[], token: string): {
+    lines: string[];
+    spans: Array<ViewportAnchorSpan | null>;
+};
 export declare function visibleWidthRaw(str: string): number;
 /**
  * Calculate the visible width of a string in terminal columns.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/tui",
-	"version": "0.9.5",
+	"version": "0.10.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",
@@ -27,7 +27,7 @@
 	"types": "./dist/types/index.d.ts",
 	"scripts": {
 		"check": "biome check . && bun run check:types",
-		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"check:types": "tsc -p tsconfig.json --noEmit",
 		"lint": "biome lint .",
 		"test": "bun test test/*.test.ts",
 		"test:perf": "PI_TUI_PERF_GATES=1 bun test test/perf-gates.test.ts",
@@ -35,8 +35,8 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.9.5",
-		"@gajae-code/utils": "0.9.5",
+		"@gajae-code/natives": "0.10.0",
+		"@gajae-code/utils": "0.10.0",
 		"lru-cache": "11.3.6",
 		"marked": "^18.0.3"
 	},