@linxiraos/pi-tui 1.0.0

package/dist/types/mouse.d.ts

@@ -0,0 +1,67 @@
+/**
+ * SGR mouse report parsing (`\x1b[<button;col;rowM` / `…m`).
+ *
+ * Mouse tracking is enabled only while a fullscreen overlay holds the
+ * alternate screen (see tui.ts MOUSE_TRACKING_ON), so consumers are
+ * fullscreen components hit-testing against their own rendered frame:
+ * the frame paints from screen row 0, hence `row`/`col` are exposed
+ * 0-based for direct indexing into rendered lines.
+ */
+/** A decoded SGR mouse report. */
+export interface SgrMouseEvent {
+    /** Raw button code (bit 32 = motion, bit 64 = wheel, low bits = button). */
+    button: number;
+    /** 0-based column of the event. */
+    col: number;
+    /** 0-based row of the event. */
+    row: number;
+    /** True for a release report (`m` suffix). */
+    release: boolean;
+    /** Wheel direction: -1 up, 1 down, null when not a wheel event. */
+    wheel: -1 | 1 | null;
+    /** True when the pointer moved (hover or drag) rather than clicked. */
+    motion: boolean;
+    /** True for a left-button press (not motion, not release, not wheel). */
+    leftClick: boolean;
+}
+/**
+ * Decode an SGR mouse report, or return null when `data` is not one.
+ * Callers on hot keypress paths should pre-check `data.startsWith("\x1b[<")`
+ * before paying for the regex.
+ */
+export declare function parseSgrMouse(data: string): SgrMouseEvent | null;
+/** Handler invoked with a decoded SGR event; returning `false` reports unhandled. */
+export type SgrMouseHandler = (event: SgrMouseEvent) => boolean | undefined;
+/**
+ * Decode an SGR mouse report and forward it to `handler`. Returns `false` when
+ * `data` is not an SGR mouse report (or fails to parse), so callers can fall
+ * through to other input handling. Centralizes the repeated
+ * `data.startsWith("\x1b[<")` + `parseSgrMouse()` pattern.
+ */
+export declare function routeSgrMouseInput(data: string, handler: SgrMouseHandler): boolean;
+/**
+ * Structural view of a SelectList-like target for mouse routing. Declared here
+ * (rather than importing the component) to keep this core module free of any
+ * component-to-core import cycle.
+ */
+export interface SelectListMouseTarget {
+    handleWheel(delta: -1 | 1): void;
+    hitTest(line: number): number | undefined;
+    setHoverIndex(index: number | null): void;
+    clickItem(index: number): void;
+}
+/**
+ * Route a decoded mouse event against a SelectList-like target at the given
+ * 0-based frame-local `line`. Centralizes the repeated wheel/hit-test/hover/
+ * click pattern. Returns `true` when the event was consumed.
+ */
+export declare function routeSelectListMouse(target: SelectListMouseTarget, event: SgrMouseEvent, line: number): boolean;
+/**
+ * Implemented by components that accept routed mouse events at frame-local
+ * coordinates. Hosts translate screen coordinates to the component's own
+ * rendered lines before forwarding.
+ */
+export interface MouseRoutable {
+    /** `line`/`col` are 0-based within the component's rendered output. */
+    routeMouse(event: SgrMouseEvent, line: number, col: number): void;
+}

package/dist/types/stdin-buffer.d.ts

@@ -0,0 +1,60 @@
+/**
+ * StdinBuffer buffers input and emits complete sequences.
+ *
+ * This is necessary because stdin data events can arrive in partial chunks,
+ * especially for escape sequences like mouse events. Without buffering,
+ * partial sequences can be misinterpreted as regular keypresses.
+ *
+ * For example, the mouse SGR sequence `\x1b[<35;20;5m` might arrive as:
+ * - Event 1: `\x1b`
+ * - Event 2: `[<35`
+ * - Event 3: `;20;5m`
+ *
+ * The buffer accumulates these until a complete sequence is detected.
+ * Call the `process()` method to feed input data.
+ *
+ * Based on code from OpenTUI (https://github.com/anomalyco/opentui)
+ * MIT License - Copyright (c) 2025 opentui
+ */
+import { EventEmitter } from "events";
+export type StdinBufferOptions = {
+    /**
+     * Maximum time to wait for sequence completion (default: 75ms).
+     * After this time, a genuinely incomplete escape is flushed.
+     */
+    timeout?: number;
+    /**
+     * Maximum extra time (default: 150ms) an unambiguous escape partial — an
+     * SGR mouse prefix, or any dangling escape while the kitty keyboard
+     * protocol is active — is held past `timeout` waiting for its tail.
+     */
+    partialHoldTimeout?: number;
+    /**
+     * Paste-mode inactivity watchdog (default: 1000ms). If no input arrives for
+     * this long while waiting for the bracketed-paste end marker, the paste is
+     * assumed truncated: accumulated bytes are delivered and input recovers.
+     */
+    pasteTimeout?: number;
+    /**
+     * Paste-mode byte cap (default: 64 MiB). Exceeding it aborts paste mode the
+     * same way, bounding memory when the end marker never arrives.
+     */
+    pasteByteLimit?: number;
+};
+export type StdinBufferEventMap = {
+    data: [string];
+    paste: [string];
+};
+/**
+ * Buffers stdin input and emits complete sequences via the 'data' event.
+ * Handles partial escape sequences that arrive across multiple chunks.
+ */
+export declare class StdinBuffer extends EventEmitter<StdinBufferEventMap> {
+    #private;
+    constructor(options?: StdinBufferOptions);
+    process(data: string | Buffer): void;
+    flush(): string[];
+    clear(): void;
+    getBuffer(): string;
+    destroy(): void;
+}

package/dist/types/symbols.d.ts

@@ -0,0 +1,25 @@
+export interface BoxSymbols {
+    topLeft: string;
+    topRight: string;
+    bottomLeft: string;
+    bottomRight: string;
+    horizontal: string;
+    vertical: string;
+    teeDown: string;
+    teeUp: string;
+    teeLeft: string;
+    teeRight: string;
+    cross: string;
+}
+export interface SymbolTheme {
+    cursor: string;
+    inputCursor: string;
+    boxRound: Omit<BoxSymbols, "teeDown" | "teeUp" | "teeLeft" | "teeRight" | "cross">;
+    boxSharp: BoxSymbols;
+    table: BoxSymbols;
+    quoteBorder: string;
+    hrChar: string;
+    /** Chip glyph drawn (painted with the referenced color) before inline hex colors. */
+    colorSwatch?: string;
+    spinnerFrames: string[];
+}

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

@@ -0,0 +1,285 @@
+import type { HangulCompatibilityJamoWidth } from "./utils.js";
+export { isInsideTmux, wrapTmuxPassthrough } from "./tmux.js";
+export declare enum ImageProtocol {
+    Kitty = "\u001B_G",
+    Iterm2 = "\u001B]1337;File=",
+    Sixel = "\u001BPq"
+}
+export declare enum NotifyProtocol {
+    Bell = "\u0007",
+    Osc99 = "\u001B]99;;",
+    Osc9 = "\u001B]9;"
+}
+export type TerminalId = "kitty" | "ghostty" | "wezterm" | "iterm2" | "vscode" | "alacritty" | "warp" | "base" | "trueColor";
+/** Terminal capability details used for rendering and protocol selection. */
+export declare class TerminalInfo {
+    readonly id: TerminalId;
+    readonly imageProtocol: ImageProtocol | null;
+    readonly trueColor: boolean;
+    readonly hyperlinks: boolean;
+    readonly notifyProtocol: NotifyProtocol;
+    readonly deccara: boolean;
+    readonly supportsScreenToScrollback: boolean;
+    /** Renders the Kitty OSC 66 text-sizing protocol (scaled spans). Kitty only. */
+    readonly textSizing: boolean;
+    /**
+     * Hangul Compatibility Jamo (U+3131..=U+318E) cell width. Ghostty follows
+     * UAX#11 (2 cells); Warp paints 1; "platform" keeps the OS default
+     * (macOS narrow, otherwise UAX#11).
+     */
+    readonly hangulJamoWidth: HangulCompatibilityJamoWidth;
+    constructor(id: TerminalId, imageProtocol: ImageProtocol | null, trueColor: boolean, hyperlinks: boolean, notifyProtocol?: NotifyProtocol, deccara?: boolean, supportsScreenToScrollback?: boolean, 
+    /** Renders the Kitty OSC 66 text-sizing protocol (scaled spans). Kitty only. */
+    textSizing?: boolean, 
+    /**
+     * Hangul Compatibility Jamo (U+3131..=U+318E) cell width. Ghostty follows
+     * UAX#11 (2 cells); Warp paints 1; "platform" keeps the OS default
+     * (macOS narrow, otherwise UAX#11).
+     */
+    hangulJamoWidth?: HangulCompatibilityJamoWidth);
+    /**
+     * Mutable clone for the {@link TERMINAL} singleton: copies every field and
+     * keeps the prototype methods, so the builder and runtime setters flip
+     * runtime-resolved {@link RuntimeTerminal} capabilities in place instead of
+     * reconstructing positional constructor args.
+     */
+    clone(): RuntimeTerminal;
+    isImageLine(line: string): boolean;
+    formatNotification(message: string | TerminalNotification): string;
+    sendNotification(message: string | TerminalNotification): void;
+}
+/** Detect terminal multiplexers where scrollback clearing and height-change redraws are hostile. */
+export declare function isInsideTerminalMultiplexer(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Whether the agent process is running inside a Zellij session. Read fresh on
+ * each call (like {@link isInsideTmux}) so a session attached/detached mid-run
+ * is observed and tests can toggle `Bun.env.ZELLIJ` per case.
+ */
+export declare function isInsideZellij(env?: NodeJS.ProcessEnv): boolean;
+export declare function isNotificationSuppressed(): boolean;
+/**
+ * Returns true when running in Windows Terminal with known SIXEL support.
+ *
+ * Windows Terminal introduced SIXEL support in preview 1.22.
+ */
+export declare function isWindowsTerminalPreviewSixelSupported(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/**
+ * Resolve an explicit user override for DEC 2026 synchronized output. Returns
+ * `false` for an opt-out, `true` for a force-on, or `null` when the user has
+ * expressed no preference. Shared by the static default and the runtime DECRQM
+ * probe so both honor the same precedence — an opt-out beats a force-on.
+ */
+export declare function synchronizedOutputUserOverride(env?: NodeJS.ProcessEnv): boolean | null;
+/**
+ * Whether DEC 2026 synchronized-output wrappers should be enabled by default.
+ *
+ * Policy (highest precedence first):
+ *   1. Explicit user override (`PI_NO_SYNC_OUTPUT`/`PI_TUI_SYNC_OUTPUT=0` off,
+ *      `PI_FORCE_SYNC_OUTPUT=1`/`PI_TUI_SYNC_OUTPUT=1` on).
+ *   2. Positive `TERM_FEATURES` advertisement (`Sy`) — survives SSH/mux wrapping.
+ *   3. Windows Terminal (1.24+) via `WT_SESSION`, on native win32 and the
+ *      WSL/SSH-fronted host alike.
+ *   4. Known direct terminals with confirmed support. SSH does *not* disable —
+ *      DEC 2026 passes through SSH when the outer terminal honors it.
+ *   5. Everything else starts off, including risky multiplexers; the runtime
+ *      DECRQM probe upgrades any of them when the terminal actually reports
+ *      `?2026` supported (current zellij, tmux master, foot, contour, mintty…).
+ */
+export declare function shouldEnableSynchronizedOutputByDefault(env?: NodeJS.ProcessEnv, terminalId?: TerminalId): 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;
+/**
+ * Resolve an explicit user override for OSC 8 hyperlinks. Returns `false` for
+ * an opt-out, `true` for a force-on, or `null` when the user has expressed no
+ * preference. Opt-out beats force-on so a kill switch is unambiguous, mirroring
+ * {@link synchronizedOutputUserOverride}.
+ */
+export declare function hyperlinksUserOverride(env?: NodeJS.ProcessEnv): boolean | null;
+/**
+ * Whether OSC 8 hyperlinks should be enabled by default.
+ *
+ * Policy (highest precedence first):
+ *   1. Explicit user override (`PI_NO_HYPERLINKS=1` off, `PI_FORCE_HYPERLINKS=1`
+ *      on). Opt-out wins ties.
+ *   2. Static terminal capability — terminals whose {@link TerminalInfo} marks
+ *      `hyperlinks: false` (e.g. `base`) stay off unless the user forced on.
+ *   3. GNU screen's explicit session marker (`STY`) always off, even if tmux is
+ *      also present: a screen layer anywhere in the path cannot forward OSC 8.
+ *   4. tmux session (`TMUX` set): enabled when tmux self-reports >= 3.4 via
+ *      `TERM_PROGRAM_VERSION` (tmux 3.4 stores OSC 8 as a cell attribute and
+ *      forwards it to outer terminals whose `terminal-features` include
+ *      `hyperlinks`). Older or unknown versions stay off; on outer terminals
+ *      without the feature configured, tmux silently drops the sequence —
+ *      identical to today. Checked before the screen-family TERM heuristic
+ *      because tmux's historical `default-terminal` is `screen-256color`, so
+ *      `TERM=screen*` inside a tmux session must NOT short-circuit to off.
+ *   5. screen-family TERM without `TMUX` always off: screen never gained OSC 8
+ *      support.
+ *   6. tmux-family TERM without `TMUX` env — unusual (e.g. inspection scripts);
+ *      no version available, so off.
+ *   7. Otherwise honor the static terminal capability.
+ */
+export declare function shouldEnableHyperlinksByDefault(env?: NodeJS.ProcessEnv, terminalId?: TerminalId): boolean;
+/**
+ * Warp implements the Kitty graphics protocol only on macOS/Linux; its Windows
+ * build (including Warp-hosted WSL shells) renders the same APC sequences as
+ * visible garbage. Keep platform/env injectable so the carve-out is testable
+ * without mutating `process.platform`.
+ */
+export declare function resolveWarpImageProtocol(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): ImageProtocol | null;
+/** Resolve terminal identity from environment markers used by common emulators. */
+export declare function detectTerminalId(env?: NodeJS.ProcessEnv): TerminalId;
+export declare const TERMINAL_ID: TerminalId;
+/**
+ * The process-wide {@link TERMINAL} singleton: a {@link TerminalInfo} whose
+ * post-construction capabilities — the image protocol and the probe-driven
+ * flags — are writable, so the runtime setters and tests mutate them directly
+ * instead of through an unsound cast. Every other field stays readonly.
+ */
+export interface RuntimeTerminal extends TerminalInfo {
+    imageProtocol: ImageProtocol | null;
+    hyperlinks: boolean;
+    deccara: boolean;
+    supportsScreenToScrollback: boolean;
+    textSizing: boolean;
+}
+export declare const TERMINAL: RuntimeTerminal;
+/**
+ * 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, platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): TerminalInfo;
+export interface CellDimensions {
+    widthPx: number;
+    heightPx: number;
+}
+export interface ImageDimensions {
+    widthPx: number;
+    heightPx: number;
+}
+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. `C=1` keeps
+ * the terminal cursor anchored at the placement origin so the renderer's
+ * explicit cursor movement remains the only row accounting. 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;
+    name?: string;
+    preserveAspectRatio?: boolean;
+    inline?: boolean;
+}): string;
+export declare function calculateImageRows(imageDimensions: ImageDimensions, targetWidthCells: number, cellDimensions?: CellDimensions): number;
+export declare function getPngDimensions(base64Data: string): ImageDimensions | null;
+export declare function getJpegDimensions(base64Data: string): ImageDimensions | null;
+export declare function getGifDimensions(base64Data: string): ImageDimensions | null;
+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;
+    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

@@ -0,0 +1,175 @@
+/**
+ * Split `data` into chunks whose encoded UTF-8 byte length is no greater than
+ * `maxChunkBytes`, preferring a line boundary (`\n`) as the cut point so
+ * escape sequences (which never contain `\n`) stay intact. The TUI's
+ * full-paint buffers are line-structured (`buffer += "\r\n"` between rows),
+ * so a newline almost always exists within the window. The fallback for a
+ * buffer with no newline in range is a hard cut at the last UTF-8 code-point
+ * boundary that still fits — the ConPTY viewport bug from a single oversized
+ * write is strictly worse than a one-frame escape-sequence glitch on a
+ * buffer the renderer effectively never produces.
+ *
+ * UTF-16 code units are walked manually rather than measuring with
+ * `Buffer.byteLength` per slice candidate: each code unit's UTF-8 width is
+ * known from its value (BMP `<0x80` → 1, `<0x800` → 2, surrogate pair → 4
+ * bytes across two units, other BMP → 3), and surrogate pairs are kept
+ * together so the chunker never splits a non-BMP character.
+ *
+ * Exported for unit testing of the chunking contract; `#safeWrite` is the
+ * sole production caller.
+ */
+export declare function chunkForConPTY(data: string, maxChunkBytes?: number): string[];
+/**
+ * Turns an unbounded, never-draining stdout writable buffer into a bounded
+ * disconnect signal.
+ *
+ * `process.stdout.write()` returns `false` once its buffer exceeds the stream
+ * high-water mark; the bytes stay queued and are only freed when the consumer
+ * drains (the `drain` event). While the consumer keeps up, writes are accepted
+ * and nothing accumulates. When it stalls, every subsequent write piles onto
+ * the buffer — a stalled-but-alive PTY reader never throws, so the write path
+ * has no other signal that output is going nowhere. This guard sums the bytes
+ * queued since backpressure began and reports when that backlog crosses the
+ * cap, at which point the caller treats the terminal as disconnected.
+ *
+ * Exported for unit testing; `ProcessTerminal` is the sole production user.
+ */
+export declare class OutputBacklogGuard {
+    #private;
+    private readonly capBytes;
+    constructor(capBytes?: number);
+    /** True once a refused write started a backlog that has not yet drained. */
+    get tracking(): boolean;
+    /**
+     * Record one `stdout.write()`: `accepted` is that call's return value and
+     * `bytes` its encoded size. Returns true when the pending backlog now
+     * exceeds the cap and the terminal should be treated as disconnected.
+     */
+    record(accepted: boolean, bytes: number): boolean;
+    /** Called on the stdout `drain` event: the buffer emptied, backlog cleared. */
+    reset(): void;
+}
+/** Record alternate-screen state (called by the TUI on `?1049h`/`?1049l` writes). */
+export declare function setAltScreenActive(active: boolean): void;
+/**
+ * Emergency terminal restore - call this from signal/crash handlers
+ * Resets terminal state without requiring access to the ProcessTerminal instance
+ */
+export declare function emergencyTerminalRestore(): void;
+/** Terminal-reported appearance (dark/light mode). */
+export type TerminalAppearance = "dark" | "light";
+/** Identity of an accepted explicit terminal appearance refresh request. */
+export type TerminalAppearanceRequestToken = number;
+export interface Terminal {
+    start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => void): void;
+    stop(): void;
+    /**
+     * Drain stdin before exiting to prevent Kitty key release events from
+     * leaking to the parent shell over slow SSH connections.
+     * @param maxMs - Maximum time to drain (default: 1000ms)
+     * @param idleMs - Exit early if no input arrives within this time (default: 50ms)
+     */
+    drainInput(maxMs?: number, idleMs?: number): Promise<void>;
+    write(data: string): void;
+    get columns(): number;
+    get rows(): number;
+    get kittyProtocolActive(): boolean;
+    get kittyEnableSequence(): string | null;
+    readonly keyboardEnhancementEnterSequence?: string | null;
+    readonly keyboardEnhancementExitSequence?: string | null;
+    moveBy(lines: number): void;
+    hideCursor(force?: boolean): void;
+    showCursor(force?: boolean): void;
+    clearLine(): void;
+    clearFromCursor(): void;
+    clearScreen(): void;
+    setTitle(title: string): void;
+    setProgress(active: boolean): void;
+    /**
+     * Register a callback for terminal appearance (dark/light) changes.
+     * Detection uses OSC 11 background color query with Mode 2031 as a change trigger.
+     * Fires when the detected appearance changes, including the initial detection.
+     * Subscribers registered after detection are invoked immediately with the
+     * already-detected appearance so late subscribers never miss it.
+     */
+    onAppearanceChange(callback: (appearance: TerminalAppearance, requestToken?: TerminalAppearanceRequestToken) => void): void;
+    /**
+     * Register a callback fired for every valid OSC 11 appearance report,
+     * including reports whose classification matches the current appearance.
+     * Unlike onAppearanceChange, this does not replay an earlier report.
+     * Optional so custom Terminals built against older pi-tui versions keep working.
+     */
+    onAppearanceReport?(callback: (appearance: TerminalAppearance, requestToken?: TerminalAppearanceRequestToken) => void): (() => void) | void;
+    /**
+     * Start a bounded OSC 11 background-color refresh cycle, driving appearance
+     * callbacks through the same parse/dedup pipeline used at startup and on Mode
+     * 2031 notifications. Direct terminals need one query; tmux needs a
+     * passthrough query to update its cache followed by one delayed direct cache
+     * read. Invoked on the user's explicit display-reset gesture so terminals
+     * without end-to-end Mode 2031 notifications pick up a light/dark switch
+     * without a restart. No periodic probes are armed.
+     *
+     * A caller-provided token must be propagated unchanged to callbacks and
+     * returned when the request is accepted. This lets callers establish ownership
+     * before implementations synchronously dispatch a cached response. Optional so
+     * custom Terminals built against older pi-tui versions keep working.
+     */
+    refreshAppearance?(requestToken?: TerminalAppearanceRequestToken): TerminalAppearanceRequestToken | 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. `confirmed` is false when the terminal answered the DA1
+     * sentinel without answering DECRQM, which proves only that querying support
+     * is unavailable — not that the private mode itself is unsupported.
+     */
+    onPrivateModeReport?(callback: (mode: number, supported: boolean, confirmed?: boolean) => void): void;
+}
+/**
+ * True when stdout flows through a ConPTY pseudo-console (native win32, or
+ * Linux running under WSL where stdout still crosses into ConPTY at the
+ * `wslhost` boundary). ConPTY hosts share the per-WriteFile viewport-tracking
+ * quirks documented above and on {@link MAX_CONPTY_WRITE_CHUNK_BYTES}, so both
+ * `#safeWrite` and the renderer's post-big-paint settle gate hang off this
+ * single predicate.
+ */
+export declare function isConPTYHosted(): boolean;
+/**
+ * Real terminal using process.stdin/stdout
+ */
+export declare class ProcessTerminal implements Terminal {
+    #private;
+    get kittyProtocolActive(): boolean;
+    get kittyEnableSequence(): string | null;
+    get keyboardEnhancementEnterSequence(): string | null;
+    get keyboardEnhancementExitSequence(): string | null;
+    get appearance(): TerminalAppearance | undefined;
+    onAppearanceChange(callback: (appearance: TerminalAppearance, requestToken?: TerminalAppearanceRequestToken) => void): void;
+    onAppearanceReport(callback: (appearance: TerminalAppearance, requestToken?: TerminalAppearanceRequestToken) => void): () => void;
+    /**
+     * Re-query the terminal background through the startup DA1-sentinel FIFO,
+     * pending/queued gating, parsing, dedup, and appearance callbacks. Inside
+     * tmux, only this explicit path first passes an OSC 11 query to the outer
+     * terminal, waits briefly for tmux to consume the response into its cache,
+     * then reads that cache with a direct query. The outer query deliberately has
+     * no DA1 sentinel: multiplexers can decode a fragmented DA1 response as a key
+     * sequence and leak the remaining bytes into the editor. Startup and Mode 2031
+     * probes remain direct. Suppressed while inactive, headless, or after teardown.
+     */
+    refreshAppearance(requestToken?: TerminalAppearanceRequestToken): TerminalAppearanceRequestToken | void;
+    onPrivateModeReport(callback: (mode: number, supported: boolean, confirmed?: boolean) => void): void;
+    start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => void): void;
+    drainInput(maxMs?: number, idleMs?: number): Promise<void>;
+    stop(): void;
+    write(data: string): void;
+    get columns(): number;
+    get rows(): number;
+    moveBy(lines: number): void;
+    hideCursor(force?: boolean): void;
+    showCursor(force?: boolean): void;
+    clearLine(): void;
+    clearFromCursor(): void;
+    clearScreen(): void;
+    setTitle(title: string): void;
+    setProgress(active: boolean): void;
+}

package/dist/types/tmux.d.ts

@@ -0,0 +1,6 @@
+/** Whether the process is running inside a tmux session. */
+export declare function isInsideTmux(env?: NodeJS.ProcessEnv): boolean;
+/** Wrap a control sequence in tmux's DCS passthrough envelope. */
+export declare function wrapTmuxPassthrough(payload: string): string;
+/** Pass a control sequence through tmux, leaving direct-terminal output unchanged. */
+export declare function wrapTmuxPassthroughIfNeeded(payload: string, env?: NodeJS.ProcessEnv): string;

package/dist/types/ttyid.d.ts

@@ -0,0 +1,9 @@
+/** Resolve the TTY device path for stdin (fd 0) via POSIX `ttyname(3)`. */
+export declare function getTtyPath(): string | null;
+/**
+ * Get a stable identifier for the current terminal.
+ * Uses the TTY device path (e.g., /dev/pts/3), falling back to environment
+ * variables for terminal multiplexers or terminal emulators.
+ * Returns null if no terminal can be identified (e.g., piped input).
+ */
+export declare function getTerminalId(): string | null;