@oh-my-pi/pi-tui 15.8.3 → 15.9.0

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## [Unreleased]
 
+## [15.9.0] - 2026-06-04
+
+### Added
+
+- Added Kitty `CSI 22 J` screen-to-scrollback clears for non-destructive full paints, while keeping ED3 for destructive history/session rebuilds.
+- Added Kitty OSC 99 rich notification formatting and startup capability probing.
+- Added Kitty OSC 66 text-sized Markdown H1 headings (2x scale) plus native text-width support for OSC 66 spans. Off by default and gated to Kitty (the only terminal implementing OSC 66) via the `TERMINAL.textSizing` capability; hosts enable it through `setTextSizing`.
+- Added Kitty Unicode placeholder image rendering (`U=1` + U+10EEEE with explicit row/column diacritics): inline images are drawn as real text cells that carry the image id in their foreground color, so they survive horizontal slicing, reflow, and overlapping draws instead of relying on cursor-positioned `a=p` placements. Enabled by default on Kitty-family terminals; opt out with `PI_NO_KITTY_PLACEHOLDERS=1`, and falls back to direct placement when a grid exceeds the diacritic table's addressable range.
+- Added Kitty temp-file image transmission (`t=t`): on local sessions, decoded PNG bytes are written to a `tty-graphics-protocol` temp file and the path is sent instead of in-band base64, gated behind a startup `a=q,t=t` support probe. Controlled by `PI_KITTY_IMAGE_TRANSMISSION=direct|temp-file|auto`; disabled over SSH unless explicitly forced.
+- Added DECRQM capability detection for DEC private modes 2026 (synchronized output) and 2048 (in-band resize). Synchronized-output paint wrappers are dropped when the terminal reports 2026 unsupported (preserving the `PI_NO_SYNC_OUTPUT` override), and DEC 2048 in-band resize is enabled when supported — reported geometry and cell pixel size are updated from `CSI 48 ; rows ; cols ; yPx ; xPx t` reports, with SIGWINCH and `CSI 16 t` kept as fallbacks.
+- Added an injectable render scheduler for TUI tests, allowing deterministic render drains without patching global clocks or event-loop timing.
+- Added `ImageBudget`, an inline-image cap that keeps only the most recent N images as live terminal graphics and demotes older ones to their text fallback. Once a new image pushes the count past the cap, the renderer hides the oldest via a full redraw plus an explicit Kitty graphics purge (`a=d,d=I`) — text-clear escapes (`CSI 2 J`/`CSI 3 J`) do not remove Kitty images. Configure the cap via `TUI#setMaxInlineImages` (`0` disables it).
+- Changed Kitty inline images to a transmit-once + placement scheme: the base64 data is sent a single time (`a=t`) keyed by a stable image id, then every repaint emits only the tiny placement (`a=p,i=…,p=…`). Repaints — including full redraws — no longer re-send image data or stack duplicate placements, and the diff/line buffers and render caches hold short placement strings instead of multi-KB base64. The `ImageBudget` doubles as the transmit store (it tracks which ids are loaded and re-transmits after a purge frees the data). iTerm2/Sixel, which have no addressable image store, keep sending inline data as before.
+- Added a renderer-level DECCARA rectangular-SGR optimizer that paints solid background panels/rows (Box/Text/Markdown fills, status bars, any full-width `theme.bg` row) as a single coalesced rectangle escape (`CSI 2*x` / `CSI Pt;Pl;Pb;Pr;<sgr>$r` / `CSI *x`) instead of emitting a full-width run of background-styled spaces on every visible row. It operates at emit time on the final ANSI strings — components are unchanged — and strips only trailing padding it can prove sits under a single non-default background span, coalescing vertically adjacent identical fills into one rectangle and falling back to the original bytes whenever the rectangle would not save bytes. Enabled only on Kitty, which implements the SGR-background extension (`docs/deccara.rst`); **Ghostty is intentionally excluded** because its `CSI $r` is unimplemented (ghostty-org/ghostty#632) and would drop the background entirely. Scrollback-bound rows and the append/scroll paths always keep the padded representation so native history preserves colored cells, and the `PI_NO_DECCARA` kill switch (plus tmux/screen/zellij detection) forces the fallback.
+- Added `CMUX_SURFACE_ID` environment variable support to `getTerminalId()`, so cmux terminal surfaces get a stable identifier alongside kitty, tmux, macOS Terminal.app, and Windows Terminal — enabling per-surface session breadcrumbs for `omp -c` in cmux.
+
+### Changed
+
+- Changed TUI tests to use Ghostty's VT engine (`ghostty-web`) instead of `@xterm/headless`.
+- Changed the default inline-image live graphics budget from 3 to 8 images.
+
+### Fixed
+
+- Fixed the DECCARA background-fill optimizer rejecting or repainting the wrong cells when a trailing fill crossed from default-background spaces into colored spaces.
+- Fixed DEC private-mode reports with DECRPM status 3/4 being treated as unsupported, so permanent 2026/2048 reports stay recognized.
+- Fixed OSC 66 text-sizing width and slicing edge cases, including ZWJ emoji payloads and partial slices through scaled spans.
+
+- Fixed focused `Input` components following `TUI#setShowHardwareCursor`, so single-line prompts render either the terminal cursor or software cursor consistently with the editor.
+- Fixed the DECCARA background-fill optimizer painting fills on the wrong rows ("split into unaligned halves") in the differential repaint path. When a diff grew the transcript past the viewport, writing the rewritten rows scrolled the terminal, but the absolute DECCARA rectangle coordinates were derived from the pre-scroll viewport top, so every fill landed `scrollAmount` rows too low while the relatively-positioned text settled correctly; rows scrolled into history were also shortened, dropping their background padding from native scrollback. Rectangles now target the post-scroll rows and only rows remaining in the final viewport are optimized.
+- Fixed native scrollback desynchronization after terminal width or height changes reflowed overflowing content while the viewport was not at the bottom
+- Fixed a notification chip (or any injected block) rendering on top of an actively streaming tool render on ED3-risk terminals (Ghostty/kitty/Alacritty/iTerm2). While a foreground tool streams, its header's elapsed-time counter ticks every frame; once output scrolls the header above the viewport top, each tick is an offscreen edit that — because the eager scrollback-rebuild opt-in is gated off on these terminals — repaints the viewport in place and advances the rendered line count without committing the new overflow to native history. `#scrollbackHighWater` then lagged the logical viewport top, so a later content shrink whose changes landed in the visible region slipped past the shrink-across-boundary guard and reached the differential emitter, which is anchored to `#maxLinesRendered - height`: it rewrote only the suffix, dropped the newly exposed top row, and left a blank at the bottom, drifting every row below the edit one line up so it painted over the rows above. Such shrinks now re-anchor the bottom of the viewport with a non-destructive repaint, and the foreground-streaming shrink-across-boundary case repaints the live tail instead of padding and pinning the pre-shrink viewport.
+- Fixed a terminal resize during foreground-tool streaming on an unknown-viewport / ED3-risk host (Ghostty/kitty/Alacritty/iTerm2/WSL) leaving native scrollback permanently out of sync, so scrolling back after the turn showed missing rows. A pure geometry resize (no content change) takes the in-place viewport-repaint path, which — unlike a content-bearing resize that rebuilds via the geometry branch — never flagged native history. Because the prompt-submit checkpoint (`refreshNativeScrollbackIfDirty`) only rebuilds when scrollback is marked dirty on these hosts, the discrepancy was never reconciled. Overflowing geometry repaints whose viewport is not known to be at the bottom now mark scrollback dirty so the next checkpoint rebuilds an exact copy of the transcript.
+
 ## [15.8.2] - 2026-06-03
 
 ### Added

package/README.md

@@ -538,7 +538,7 @@ interface Terminal {
 **Built-in implementations:**
 
 - `ProcessTerminal` - Uses `process.stdin/stdout`
-- `VirtualTerminal` - For testing (uses `@xterm/headless`)
+- `VirtualTerminal` - For testing (uses ghostty-web)
 
 ## Utilities
 

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

@@ -7,6 +7,72 @@ 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. */
+    beginPass(): 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.
+     */
+    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[];
+    /** Whether `imageId`'s data still needs to be transmitted to the terminal. */
+    shouldTransmit(imageId: number): boolean;
+    /**
+     * 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;
+    /** Transmit sequences to write before this frame's placements; clears the queue. */
+    takeTransmits(): readonly string[];
 }
 export declare class Image implements Component {
     #private;

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

@@ -10,6 +10,8 @@ export declare class Input implements Component, Focusable {
     focused: boolean;
     getValue(): string;
     setValue(value: string): void;
+    setUseTerminalCursor(useTerminalCursor: boolean): void;
+    getUseTerminalCursor(): boolean;
     handleInput(data: string): void;
     invalidate(): void;
     render(width: number): string[];

package/dist/types/deccara.d.ts

@@ -0,0 +1,49 @@
+/** DECSACE — select the rectangle change extent so DECCARA fills a rectangle. */
+export declare const DECSACE_RECT = "\u001B[2*x";
+/** DECSACE — restore the default (stream) change extent. */
+export declare const DECSACE_DEFAULT = "\u001B[*x";
+/**
+ * Encode a single DECCARA rectangle. `top`/`bottom` are 1-based inclusive screen
+ * rows, `left`/`right` 1-based inclusive columns, `sgr` the raw SGR parameter
+ * list to apply (e.g. `48;2;10;20;30`, `48;5;4`, `41`).
+ */
+export declare function encodeDeccara(top: number, left: number, bottom: number, right: number, sgr: string): string;
+/** Where to cut a fillable line and the background to paint over the remainder. */
+export interface BgFillAnalysis {
+    /** Byte index where droppable trailing background padding begins (0 = whole line). */
+    cut: number;
+    /** 0-based column where the trailing padding begins (DECCARA left = leftCol + 1). */
+    leftCol: number;
+    /** SGR parameter list of the background covering the trailing region. */
+    bg: string;
+}
+/**
+ * Decide whether `line` (a final, width-fit, reset-terminated ANSI string) is a
+ * full-width background fill whose trailing padding can be replaced by a DECCARA
+ * rectangle. Returns `null` unless it can *prove* the dropped bytes are literal
+ * trailing spaces under a single, constant, non-default background span (or the
+ * entire row is background-styled spaces).
+ *
+ * Conservative by construction: any OSC sequence (hyperlinks/images), any
+ * non-SGR CSI, a partial row, an inconsistent or default trailing background, or
+ * a malformed escape all yield `null` so the caller keeps the exact original.
+ */
+export declare function analyzeBgFillLine(line: string, width: number): BgFillAnalysis | null;
+/** Per-frame plan: the (possibly shortened) row strings and the DECCARA batch. */
+export interface DeccaraPlan {
+    /** Row strings to write, parallel to the input. Optimized rows are shortened. */
+    texts: string[];
+    /** DECSACE-wrapped rectangle batch to emit after the rows, or `""` if none. */
+    sequence: string;
+}
+/**
+ * Plan DECCARA rectangles for a contiguous block of visible rows.
+ *
+ * `lines[k]` is the final ANSI string for screen row `firstScreenRow + k`
+ * (0-based). For each fillable row the trailing background padding is removed
+ * (the row's cells are cleared/erased by the caller, then repainted by the
+ * rectangle), and vertically adjacent rows with an identical left/right/bg span
+ * coalesce into one rectangle. Rectangles are emitted only when they save more
+ * bytes than they cost, so the result never exceeds the original byte count.
+ */
+export declare function planDeccaraFills(lines: string[], width: number, firstScreenRow?: number): DeccaraPlan;

package/dist/types/index.d.ts

@@ -12,10 +12,12 @@ export * from "./components/spacer";
 export * from "./components/tab-bar";
 export * from "./components/text";
 export * from "./components/truncated-text";
+export * from "./deccara";
 export type * from "./editor-component";
 export * from "./fuzzy";
 export * from "./keybindings";
 export * from "./keys";
+export * from "./kitty-graphics";
 export * from "./stdin-buffer";
 export type * from "./symbols";
 export * from "./terminal";

package/dist/types/kitty-graphics.d.ts

@@ -0,0 +1,76 @@
+/** Kitty Unicode placeholder base character (U+10EEEE, Plane 16 PUA). */
+export declare const KITTY_PLACEHOLDER = "\uDBFB\uDEEE";
+/** Largest row/column index expressible with the diacritic table (one cell each). */
+export declare const KITTY_PLACEHOLDER_MAX_CELLS: number;
+export type KittyTransmissionMedium = "direct" | "temp-file";
+export interface KittyGraphicsFeatures {
+    /** Display images via Unicode placeholders instead of direct `a=p` placement. */
+    unicodePlaceholders: boolean;
+    /** How image data reaches the terminal: in-band base64 or a temp file. */
+    transmissionMedium: KittyTransmissionMedium;
+}
+export declare function getKittyGraphics(): Readonly<KittyGraphicsFeatures>;
+export declare function setKittyGraphics(partial: Partial<KittyGraphicsFeatures>): void;
+/**
+ * Whether temp-file transmission may be promoted at runtime: forced via env,
+ * disabled via env, otherwise auto (local sessions only — a temp file written
+ * locally is not readable by a terminal on the far side of an SSH link).
+ */
+export declare function kittyTempFileAllowed(): boolean;
+/** Whether a `columns`×`rows` placeholder grid fits within the diacritic table. */
+export declare function kittyPlaceholdersFit(columns: number, rows: number): boolean;
+/** True when the base64 payload is a PNG (kitty `f=100` / temp-file path only). */
+export declare function isPngBase64(base64Data: string): boolean;
+/**
+ * Virtual placement APC (`a=p,U=1`): tells the terminal that placeholder cells
+ * carrying image id `i` should display the transmitted image, scaled to fit the
+ * `c`×`r` cell box. Re-emitting with a stable `placementId` replaces in place.
+ */
+export declare function encodeKittyVirtualPlacement(opts: {
+    imageId: number;
+    placementId?: number;
+    columns: number;
+    rows: number;
+}): string;
+/**
+ * Build the placeholder cell grid as one string per row. The image id is carried
+ * in each row's foreground color and the placement id (if any) in its underline
+ * color; every cell names its explicit row+column diacritic (robust to slicing,
+ * unlike left-inheritance). Returns exactly `rows` strings.
+ */
+export declare function encodeKittyPlaceholderGrid(opts: {
+    imageId: number;
+    placementId?: number;
+    columns: number;
+    rows: number;
+}): string[];
+/**
+ * Full placeholder render: the virtual-placement APC prefixes line 0, and every
+ * line carries placeholder cells. Returns exactly `rows` lines (no cursor moves).
+ */
+export declare function renderKittyPlaceholderLines(opts: {
+    imageId: number;
+    placementId?: number;
+    columns: number;
+    rows: number;
+}): string[];
+/**
+ * Transmit a PNG via a temp file (`t=t`): decode the base64 to bytes once, write
+ * them to a temp file, and send the base64-encoded file path as payload. Returns
+ * the APC string, or `null` on any failure (caller falls back to direct base64).
+ *
+ * Synchronous filesystem writes are mandated by the synchronous render pipeline
+ * (`Image.render` → `renderImage` are sync); there is no async seam here.
+ */
+export declare function encodeKittyTempFileTransmit(base64Png: string, imageId: number): string | null;
+/**
+ * Encode a temp-file support probe: write a tiny PNG to a temp file and ask the
+ * terminal to query it (`a=q,t=t`). A conforming terminal replies
+ * `ESC _ G i=<probeId>;OK ESC \`. Returns the query APC plus a `cleanup` that
+ * removes the probe file (best-effort; kitty self-deletes the magic-named file).
+ * Returns `null` if the temp file cannot be written.
+ */
+export declare function encodeKittyTempFileProbe(probeId: number): {
+    sequence: string;
+    cleanup: () => void;
+} | null;

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

@@ -17,10 +17,16 @@ export declare class TerminalInfo {
     readonly hyperlinks: boolean;
     readonly notifyProtocol: NotifyProtocol;
     readonly eagerEraseScrollbackRisk: boolean;
-    constructor(id: TerminalId, imageProtocol: ImageProtocol | null, trueColor: boolean, hyperlinks: boolean, notifyProtocol?: NotifyProtocol, eagerEraseScrollbackRisk?: boolean);
+    readonly deccara: boolean;
+    readonly supportsScreenToScrollback: boolean;
+    /** Renders the Kitty OSC 66 text-sizing protocol (scaled spans). Kitty only. */
+    readonly textSizing: boolean;
+    constructor(id: TerminalId, imageProtocol: ImageProtocol | null, trueColor: boolean, hyperlinks: boolean, notifyProtocol?: NotifyProtocol, eagerEraseScrollbackRisk?: boolean, deccara?: boolean, supportsScreenToScrollback?: boolean, 
+    /** Renders the Kitty OSC 66 text-sizing protocol (scaled spans). Kitty only. */
+    textSizing?: boolean);
     isImageLine(line: string): boolean;
-    formatNotification(message: string): string;
-    sendNotification(message: string): void;
+    formatNotification(message: string | TerminalNotification): string;
+    sendNotification(message: string | TerminalNotification): void;
 }
 export declare function isNotificationSuppressed(): boolean;
 /**
@@ -52,12 +58,47 @@ export declare function isWindowsTerminalPreviewSixelSupported(env?: NodeJS.Proc
  * Pure helper for tests and `TERMINAL` trait construction. See #1682 and #1719.
  */
 export declare function detectTerminalEagerEraseScrollbackRisk(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/**
+ * Whether the terminal applies Kitty-style DECCARA rectangular SGR changes
+ * (`CSI Pt ; Pl ; Pb ; Pr ; <sgr> $ r`) extended to background color, so large
+ * filled regions can be painted as rectangles instead of background-padded
+ * strings on every row.
+ *
+ * Verified against terminal sources rather than terminfo, because a bare
+ * `Cara`/DECCARA terminfo capability does not imply the Kitty SGR-background
+ * extension:
+ * - Kitty implements it for *all* SGR attributes including background (see
+ *   kitty `docs/deccara.rst` and the `test_deccara` parser test).
+ * - Ghostty does NOT: its `CSI $ r` dispatch falls through to an "unknown CSI"
+ *   warning and DECCARA/DECSACE are tracked as unsupported
+ *   (ghostty-org/ghostty#632). Enabling it there would silently drop panel
+ *   backgrounds, so ghostty stays on the padded-string fallback.
+ *
+ * Disabled under tmux/screen/zellij multiplexers — screen-coordinate rectangle
+ * protocols are not safe to assume through a multiplexer — and via the
+ * `PI_NO_DECCARA` kill switch. Pure helper for tests and `TERMINAL` construction.
+ */
+export declare function detectRectangularSgrSupport(terminalId: TerminalId, env?: NodeJS.ProcessEnv): boolean;
 export declare const TERMINAL_ID: TerminalId;
 export declare const TERMINAL: TerminalInfo;
 /**
  * Override terminal image protocol at runtime after capability probes complete.
  */
 export declare function setTerminalImageProtocol(imageProtocol: ImageProtocol | null): void;
+/**
+ * Override DECCARA rectangular-SGR capability at runtime. Used by tests to
+ * exercise the optimizer and fallback paths deterministically — the default is
+ * resolved once at import and force-disabled under the test runtime.
+ */
+export declare function setTerminalDeccara(enabled: boolean): void;
+/** Override screen-to-scrollback clear support for targeted renderer tests. */
+export declare function setTerminalScreenToScrollback(enabled: boolean): void;
+/**
+ * Enable/disable OSC 66 text-sizing at runtime. The coding-agent calls this from
+ * the `tui.textSizing` setting (gated on the terminal's static `textSizing`
+ * capability); tests flip it directly to exercise the scaled-heading path.
+ */
+export declare function setTerminalTextSizing(enabled: boolean): void;
 export declare function getTerminalInfo(terminalId: TerminalId): TerminalInfo;
 export interface CellDimensions {
     widthPx: number;
@@ -71,14 +112,53 @@ export interface ImageRenderOptions {
     maxWidthCells?: number;
     maxHeightCells?: number;
     preserveAspectRatio?: boolean;
+    /**
+     * Stable Kitty image id (`i=`). When set, the image is displayed via a
+     * transmit-once + placement scheme keyed off this id instead of re-sending the
+     * base64 each frame.
+     */
+    imageId?: number;
+    /** Stable Kitty placement id (`p=`); defaults to {@link imageId}. */
+    placementId?: number;
+    /** When true (Kitty + {@link imageId}), also return the one-time transmit sequence. */
+    includeTransmit?: boolean;
 }
 export declare function getCellDimensions(): CellDimensions;
 export declare function setCellDimensions(dims: CellDimensions): void;
+/** Transmit-and-display (`a=T`) — the self-contained form used when no stable id is available. */
 export declare function encodeKitty(base64Data: string, options?: {
     columns?: number;
     rows?: number;
     imageId?: number;
 }): string;
+/**
+ * Transmit image data only (`a=t`), keyed by `imageId`, without displaying it.
+ * Sent once per image; the data then persists in the terminal's store (it
+ * survives scroll-off and text clears for images with a non-zero id), so
+ * subsequent frames display it with the tiny {@link encodeKittyPlacement}
+ * sequence instead of re-sending the base64.
+ */
+export declare function encodeKittyTransmit(base64Data: string, imageId: number): string;
+/**
+ * Display a previously transmitted image (`a=p`) at the cursor. Carrying a
+ * stable `placementId` (`p=`) means re-emitting the sequence on a repaint
+ * *replaces* the existing placement (moving/resizing it without flicker) rather
+ * than stacking a duplicate.
+ */
+export declare function encodeKittyPlacement(options: {
+    imageId: number;
+    placementId?: number;
+    columns?: number;
+    rows?: number;
+}): string;
+/**
+ * Kitty graphics delete command for a single image id. Uses `d=I` (capital)
+ * which removes the image and every one of its placements — on screen *and* in
+ * scrollback — and frees the backing data. `q=2` suppresses the terminal reply.
+ * Text-clearing escapes (`CSI 2 J` / `CSI 3 J`) do not remove Kitty graphics, so
+ * this is the only way to actually purge a placed image.
+ */
+export declare function encodeKittyDeleteImage(imageId: number): string;
 export declare function encodeITerm2(base64Data: string, options?: {
     width?: number | string;
     height?: number | string;
@@ -93,7 +173,29 @@ export declare function getGifDimensions(base64Data: string): ImageDimensions |
 export declare function getWebpDimensions(base64Data: string): ImageDimensions | null;
 export declare function getImageDimensions(base64Data: string, mimeType: string): ImageDimensions | null;
 export declare function renderImage(base64Data: string, imageDimensions: ImageDimensions, options?: ImageRenderOptions): {
-    sequence: string;
+    sequence?: string;
+    lines?: string[];
     rows: number;
+    transmit?: string;
 } | null;
 export declare function imageFallback(mimeType: string, dimensions?: ImageDimensions, filename?: string): string;
+/**
+ * Structured terminal notification. Rich fields are honored only by OSC 99
+ * (Kitty) once support is confirmed; other protocols and the unconfirmed Kitty
+ * path collapse to a single `title: body` line.
+ */
+export interface TerminalNotification {
+    title?: string;
+    body?: string;
+    id?: string;
+    type?: string | string[];
+    urgency?: "low" | "normal" | "critical";
+    iconName?: string;
+    sound?: "silent" | "system" | "info" | "warning" | "error" | "question";
+    actions?: "focus" | "report" | "focus-report" | "none";
+    expiresMs?: number;
+}
+/** Record the OSC 99 capability-probe result (called by ProcessTerminal). */
+export declare function setOsc99Supported(supported: boolean): void;
+/** True when OSC 99 structured notifications have been confirmed available. */
+export declare function isOsc99Supported(): boolean;

package/dist/types/terminal.d.ts

@@ -66,6 +66,11 @@ export interface Terminal {
     onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
     /** The last detected terminal appearance, or undefined if not yet known. */
     get appearance(): TerminalAppearance | undefined;
+    /**
+     * Register a callback fired once per DEC private mode when its DECRQM support
+     * status resolves. Optional: only real terminals implement capability probing.
+     */
+    onPrivateModeReport?(callback: (mode: number, supported: boolean) => void): void;
 }
 /**
  * Real terminal using process.stdin/stdout
@@ -75,6 +80,7 @@ export declare class ProcessTerminal implements Terminal {
     get kittyProtocolActive(): boolean;
     get appearance(): TerminalAppearance | undefined;
     onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
+    onPrivateModeReport(callback: (mode: number, supported: boolean) => void): void;
     start(onInput: (data: string) => void, onResize: () => void): void;
     drainInput(maxMs?: number, idleMs?: number): Promise<void>;
     stop(): void;

package/dist/types/tui.d.ts

@@ -1,3 +1,4 @@
+import { ImageBudget } from "./components/image";
 import type { Terminal } from "./terminal";
 import { visibleWidth } from "./utils";
 type InputListenerResult = {
@@ -5,6 +6,17 @@ type InputListenerResult = {
     data?: string;
 } | undefined;
 type InputListener = (data: string) => InputListenerResult;
+export interface RenderTimer {
+    cancel(): void;
+}
+export interface RenderScheduler {
+    now(): number;
+    scheduleImmediate(callback: () => void): void;
+    scheduleRender(callback: () => void, delayMs: number): RenderTimer;
+}
+export interface TUIOptions {
+    renderScheduler?: RenderScheduler;
+}
 /**
  * Component interface - all components must implement this
  */
@@ -31,14 +43,21 @@ export interface Component {
     invalidate(): void;
 }
 /**
- * Interface for components that can receive focus and display a hardware cursor.
+ * Interface for components that can receive focus and display a cursor.
  * When focused, the component should emit CURSOR_MARKER at the cursor position
  * in its render output. TUI will find this marker and position the hardware
  * cursor there for proper IME candidate window positioning.
+ *
+ * Components that can switch between terminal-cursor and software-cursor
+ * rendering expose `setUseTerminalCursor`; TUI keeps that mode in sync with
+ * its resolved hardware-cursor preference whenever focus or the preference
+ * changes.
  */
 export interface Focusable {
     /** Set by TUI when focus changes. Component should emit CURSOR_MARKER when true. */
     focused: boolean;
+    /** Set by TUI when hardware cursor rendering is enabled or disabled. */
+    setUseTerminalCursor?(useTerminalCursor: boolean): void;
 }
 /** Options for scheduling a TUI render. */
 export interface RenderRequestOptions {
@@ -153,8 +172,16 @@ export declare class TUI extends Container {
         preFocus: Component | null;
         hidden: boolean;
     }[];
-    constructor(terminal: Terminal, showHardwareCursor?: boolean);
+    constructor(terminal: Terminal, showHardwareCursor?: boolean, options?: TUIOptions);
     get fullRedraws(): number;
+    /** Shared budget that caps how many inline images render as live graphics. */
+    get imageBudget(): ImageBudget;
+    /**
+     * Set how many inline images stay live graphics before older ones fall back
+     * to text (`0` disables the cap). Older images are hidden via a graphics purge
+     * plus a full redraw on the frame after a new image exceeds the cap.
+     */
+    setMaxInlineImages(cap: number): void;
     getShowHardwareCursor(): boolean;
     setShowHardwareCursor(enabled: boolean): void;
     getClearOnShrink(): boolean;
@@ -164,6 +191,12 @@ export declare class TUI extends Container {
      * When false, empty rows remain (reduces redraws on slower terminals).
      */
     setClearOnShrink(enabled: boolean): void;
+    /**
+     * Whether DEC 2026 synchronized-output wrappers are currently emitted around
+     * paints. Starts from `PI_NO_SYNC_OUTPUT` and is force-disabled at runtime if
+     * the terminal reports mode 2026 unsupported via DECRQM.
+     */
+    get synchronizedOutput(): boolean;
     /**
      * When enabled, live render frames rebuild native scrollback on offscreen and
      * structural changes even when the viewport position is unobservable (POSIX,

package/dist/types/utils.d.ts

@@ -1,6 +1,21 @@
 import { Ellipsis, type ExtractSegmentsResult, type SliceResult } from "@oh-my-pi/pi-natives";
 export { Ellipsis } from "@oh-my-pi/pi-natives";
 export { getDefaultTabWidth, getIndentation } from "@oh-my-pi/pi-utils";
+export type TextSizingScale = 1 | 2 | 3;
+export type TextSizingVerticalAlign = "top" | "bottom" | "center";
+export type TextSizingHorizontalAlign = "left" | "right" | "center";
+export interface TextSizingOptions {
+    scale?: TextSizingScale;
+    widthCells?: number;
+    verticalAlign?: TextSizingVerticalAlign;
+    horizontalAlign?: TextSizingHorizontalAlign;
+}
+/**
+ * Encode a plain-text span using Kitty's OSC 66 text-sizing protocol. The TUI
+ * emits only safe UTF-8 payloads and ST terminators so its ANSI parser and the
+ * terminal agree on span boundaries.
+ */
+export declare function encodeTextSized(text: string, options?: TextSizingOptions): string;
 export declare function sliceWithWidth(line: string, startCol: number, length: number, strict?: boolean | null): SliceResult;
 export declare function truncateToWidth(text: string, maxWidth: number, ellipsisKind?: Ellipsis | null, pad?: boolean | null): string;
 export declare function wrapTextWithAnsi(text: string, width: number): string[];

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "15.8.3",
+	"version": "15.9.0",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -37,14 +37,14 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "15.8.3",
-		"@oh-my-pi/pi-utils": "15.8.3",
+		"@oh-my-pi/pi-natives": "15.9.0",
+		"@oh-my-pi/pi-utils": "15.9.0",
 		"lru-cache": "11.5.1",
 		"marked": "^18.0.4"
 	},
 	"devDependencies": {
 		"chalk": "^5.6.2",
-		"@xterm/headless": "^6.0.0"
+		"ghostty-web": "^0.4.0"
 	},
 	"engines": {
 		"bun": ">=1.3.14"