@linxiraos/pi-tui 1.1.0 → 1.1.2

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

@@ -0,0 +1,338 @@
+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" | "orca" | "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 supportsTextSizing: boolean;
+    /**
+     * Hangul Compatibility Jamo (U+3131..=U+318E) cell width. Ghostty and Orca follow
+     * 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. */
+    supportsTextSizing?: boolean, 
+    /**
+     * Hangul Compatibility Jamo (U+3131..=U+318E) cell width. Ghostty and Orca follow
+     * 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;
+/**
+ * Whether `PI_FORCE_IMAGE_PROTOCOL` pins the image protocol, including its
+ * `off`/`none` kill switch. A runtime capability probe must not override an
+ * explicit user choice: a forced protocol is already applied to {@link TERMINAL},
+ * and a forced "off" leaves `imageProtocol` null on purpose.
+ */
+export declare function isImageProtocolForced(): 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;
+    /** Whether OSC 66 text sizing is currently enabled. */
+    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 `supportsTextSizing`
+ * 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;
+export interface ParsedKittyPlacementLine {
+    imageId: number;
+    placementId: number | undefined;
+    columns: number;
+    rows: number;
+}
+/**
+ * Parse a frame line that consists solely of a Kitty direct placement (the
+ * last line of an {@link Image} block). Returns null for anything else —
+ * placeholder grids, tmux-wrapped placements, sixel/iTerm2 payloads — so
+ * callers fall back to writing the line verbatim.
+ */
+export declare function parseKittyDirectPlacementLine(line: string): ParsedKittyPlacementLine | null;
+/**
+ * Rebuild an {@link Image} direct-placement line for the viewport row it is
+ * written at. The component-rendered line encodes `CUU(rows-1)`, which clamps
+ * at the viewport top once the block's leading rows have scrolled out — the
+ * placement then re-anchors the full image shifted down over foreign rows.
+ * Anchor at the block's first *visible* row instead, clipping the source
+ * rectangle (`y=`/`h=`, image pixels) to the visible bottom slice.
+ */
+export declare function encodeKittyPlacementLine(options: {
+    imageId: number;
+    placementId: number;
+    columns: number;
+    /** Total cell rows of the image block. */
+    rows: number;
+    /** Viewport row the block's last line is being written at. */
+    screenRow: number;
+    /** Source image height in pixels, for the clipped source rectangle. */
+    imageHeightPx: 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;
+/**
+ * Delete every Kitty image and placement in the terminal. Used only by an
+ * explicit destructive display reset: text erases leave untracked placements
+ * painted, so per-image bookkeeping cannot guarantee a clean viewport.
+ */
+export declare function encodeKittyDeleteAllImages(): string;
+/**
+ * Delete a single placement of an image (`d=i`, lowercase): removes its cells
+ * and registry entry but keeps the transmitted data, so a later `a=p` under a
+ * fresh placement id needs no retransmit. Used to clear stale placement-epoch
+ * entries after a destructive history clear.
+ */
+export declare function encodeKittyDeletePlacement(imageId: number, placementId: 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,215 @@
+/**
+ * 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;
+/**
+ * Route an out-of-band escape sequence (e.g. an OSC title update) through the
+ * active terminal's output path. While a TUI owns stdout, frame paints go
+ * through the off-thread write pump and can split across multiple write(2)
+ * calls; a direct main-thread `process.stdout.write` can land between two of
+ * them — mid escape sequence — and the host terminal then prints the payload
+ * as literal text at the cursor position. Returns false when no terminal has
+ * started, in which case the caller owns stdout and may write directly.
+ */
+export declare function writeThroughActiveTerminal(data: string): boolean;
+/**
+ * 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";
+/** Options for {@link Terminal.start}. */
+export interface TerminalStartOptions {
+    /**
+     * Paint-only start: skip raw mode, stdin ownership, and every probe that
+     * elicits a response on stdin. The host tty keeps cooked-mode line editing
+     * (kernel echo lands at the hardware cursor), and typed bytes stay queued
+     * in the kernel until {@link Terminal.enableInput} takes ownership and
+     * replays them through `onInput`. Used for the startup prepaint so typing
+     * echoes even while module loading blocks the event loop.
+     */
+    deferInput?: boolean;
+}
+/** 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, options?: TerminalStartOptions): void;
+    /**
+     * Take ownership of stdin after a `deferInput` start: enable raw mode,
+     * attach input handlers, and run the capability probes start() skipped.
+     * Bytes the user typed in cooked mode meanwhile are replayed through
+     * `onInput`. No-op when input was never deferred. Optional so custom
+     * Terminals built against older pi-tui versions keep working.
+     */
+    enableInput?(): 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;
+    /**
+     * Output bytes accepted but not yet delivered to the terminal, when the
+     * implementation can report it. The renderer skips composing new frames
+     * while this backlog is deep, so a slow terminal receives only fresh
+     * frames instead of a queue of stale ones. Optional so custom Terminals
+     * built against older pi-tui versions keep working.
+     */
+    readonly pendingOutputBytes?: 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, options?: TerminalStartOptions): void;
+    enableInput(): void;
+    drainInput(maxMs?: number, idleMs?: number): Promise<void>;
+    stop(): void;
+    write(data: string): void;
+    get columns(): number;
+    get pendingOutputBytes(): 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;