@prometheus-ai/tui 0.5.4 → 0.5.8

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

@@ -1,13 +1,26 @@
+/**
+ * Kitty graphics: Unicode placeholder placement (`U=1` + U+10EEEE), with
+ * runtime feature state and env overrides.
+ *
+ * Unicode placeholders let a transmitted image be displayed by writing ordinary
+ * text cells — the placeholder char U+10EEEE plus row/column combining
+ * diacritics — instead of a cursor-positioned `a=p` direct placement. The image
+ * then participates in the normal text grid, so it survives horizontal slicing,
+ * reflow and overlapping draws (each cell names its own row+column, so a sliced
+ * row still maps to the correct sub-region). See kitty
+ * `docs/graphics-protocol.rst` "Unicode placeholders for relative placements".
+ *
+ * This module is intentionally free of `./terminal-capabilities` imports so the
+ * dependency stays one-way (capabilities → kitty-graphics) and no import cycle
+ * forms. Protocol gating (`imageProtocol === Kitty`) lives in the caller.
+ */
 /** 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;
 }
 /**
  * Whether the detected terminal renders Kitty Unicode placeholders (`U=1` +
@@ -29,16 +42,8 @@ export interface KittyGraphicsFeatures {
 export declare function detectKittyUnicodePlaceholdersSupport(terminalId: string, env?: NodeJS.ProcessEnv): boolean;
 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
@@ -72,23 +77,3 @@ export declare function renderKittyPlaceholderLines(opts: {
     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/loop-watchdog.d.ts

@@ -0,0 +1,39 @@
+export interface LoopWatchdogOptions {
+    /** How far ahead each probe tick is scheduled, in ms. Default 250. */
+    intervalMs?: number;
+    /** A tick later than this past its deadline counts as a block. Default 250. */
+    thresholdMs?: number;
+    /** Monotonic clock source; injectable for tests. Default `performance.now`. */
+    now?: () => number;
+    /** Timer source; injectable for tests. Default `setTimeout`. */
+    schedule?: (cb: () => void, ms: number) => LoopWatchdogTimer;
+}
+/**
+ * Timer handle the watchdog arms. `cancel`, when present, is invoked on stop()
+ * so a stopped watchdog leaves no armed timer to wake the loop even once.
+ */
+interface LoopWatchdogTimer {
+    unref?(): void;
+    cancel?(): void;
+}
+/**
+ * Always-on event-loop lag probe. Each tick is scheduled `intervalMs` ahead of
+ * a recorded deadline; a tick that fires `thresholdMs` past its deadline means
+ * the loop was blocked that long. The overshoot is logged once on the rising
+ * edge (one block ⇒ one line, deduped via `#wasBlocked`), tagged with the phase
+ * active during the elapsed interval via {@link takeRecentLoopPhase} — which
+ * survives the synchronous push/pop the instrumented hot paths do before this
+ * delayed tick can run — so the stall names its cause instead of "unknown".
+ *
+ * The handle is `unref`'d so the probe never keeps the process alive, and stop()
+ * cancels the armed timer when the handle exposes `cancel` (the default
+ * `setTimeout` handle does, via `clearTimeout`). The `#generation` guard remains
+ * as a fallback for injected handles that cannot cancel.
+ */
+export declare class LoopWatchdog {
+    #private;
+    constructor(options?: LoopWatchdogOptions);
+    start(): void;
+    stop(): void;
+}
+export {};

package/dist/types/mouse.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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;
+/**
+ * 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

@@ -23,6 +23,23 @@ export type StdinBufferOptions = {
      * 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];

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

@@ -16,14 +16,20 @@ export declare class TerminalInfo {
     readonly trueColor: boolean;
     readonly hyperlinks: boolean;
     readonly notifyProtocol: NotifyProtocol;
-    readonly 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, 
+    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);
+    /**
+     * 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;
@@ -36,23 +42,28 @@ export declare function isNotificationSuppressed(): boolean;
  */
 export declare function isWindowsTerminalPreviewSixelSupported(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
 /**
- * Whether live-frame native scrollback rebuilds are unsafe when the terminal
- * viewport position is unobservable.
- *
- * A TUI history rebuild emits xterm ED3 (`CSI 3 J`, erase saved lines). Many
- * terminals either clamp a scrolled reader back to the active tail or erase host
- * scrollback when ED3 lands. The important property is not the brand name — it
- * is that an unknown viewport position cannot be proven safe. Environment
- * markers are therefore only used to prove *risk* or a strongly-known profile;
- * unknown POSIX/remote/multiplexer shapes default to risky for passive renders.
+ * 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.
  *
- * Native win32 is excluded here because the renderer has dedicated ConPTY
- * deferral paths; a `WT_SESSION` sighting on POSIX means Windows Terminal is the
- * outer host fronting WSL, where the same ED3 yank applies. See #1610/#1682/#1799.
+ * Policy (highest precedence first):
+ *   1. Explicit user override (`PROMETHEUS_NO_SYNC_OUTPUT`/`PROMETHEUS_TUI_SYNC_OUTPUT=0` off,
+ *      `PROMETHEUS_FORCE_SYNC_OUTPUT=1`/`PROMETHEUS_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 detectTerminalEagerEraseScrollbackRisk(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
-/** Whether DEC 2026 synchronized-output wrappers should be enabled by default. */
-export declare function shouldEnableSynchronizedOutputByDefault(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, terminalId?: TerminalId): boolean;
+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
@@ -74,8 +85,53 @@ export declare function shouldEnableSynchronizedOutputByDefault(env?: NodeJS.Pro
  * `PROMETHEUS_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 (`PROMETHEUS_NO_HYPERLINKS=1` off, `PROMETHEUS_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;
 export declare const TERMINAL_ID: TerminalId;
-export declare const TERMINAL: TerminalInfo;
+/**
+ * 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.
  */

package/dist/types/terminal.d.ts

@@ -1,3 +1,26 @@
+/**
+ * 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[];
+/** 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
@@ -19,6 +42,7 @@ export interface Terminal {
     get columns(): number;
     get rows(): number;
     get kittyProtocolActive(): boolean;
+    get kittyEnableSequence(): string | null;
     moveBy(lines: number): void;
     hideCursor(): void;
     showCursor(): void;
@@ -27,42 +51,6 @@ export interface Terminal {
     clearScreen(): void;
     setTitle(title: string): void;
     setProgress(active: boolean): void;
-    /**
-     * Returns whether the native terminal viewport is at the scrollback tail when
-     * the host exposes that state. `undefined` means the terminal cannot report it.
-     *
-     * `ProcessTerminal` deliberately does not implement this — no real terminal
-     * can answer it truthfully:
-     *
-     * - POSIX terminals expose no scrollback-position API at all.
-     * - Every modern Windows terminal host (Windows Terminal, VS Code, Tabby,
-     *   Hyper, Alacritty, WezTerm, JetBrains, …) fronts console apps through
-     *   ConPTY, where kernel32's `GetConsoleScreenBufferInfo` describes the
-     *   pseudo-console buffer. That buffer is pinned to the visible grid —
-     *   scrollback lives in the host UI, invisible to console APIs
-     *   (microsoft/terminal#10191) — so a probe reads "at bottom" no matter
-     *   where the user scrolled. Trusting it let streaming-time rebuilds emit
-     *   `\x1b[3J` and yank scrolled readers: #1635 (Windows Terminal), #1746
-     *   (Tabby and other ConPTY hosts). No env var distinguishes these hosts
-     *   (Tabby sets none), so trust cannot be conditional on the environment.
-     * - Legacy conhost (the only non-ConPTY host) keeps a real scrollback
-     *   buffer, but its window follows the output cursor: a probe comparing
-     *   `srWindow.Bottom` against `dwSize.Y - 1` reads "scrolled up" for a user
-     *   following live output until all ~9001 buffer rows fill, permanently
-     *   blocking checkpoint scrollback reconciliation.
-     *
-     * The renderer treats a missing implementation / `undefined` as "unknown":
-     * live mutations defer destructive rebuilds and reconcile native scrollback
-     * at explicit checkpoints (prompt submit), where the user's keystroke has
-     * already pinned the host viewport to the bottom. Only test terminals
-     * (xterm.js-backed) implement this with a real answer.
-     */
-    isNativeViewportAtBottom?(): boolean | undefined;
-    /**
-     * Override the global terminal-profile ED3 risk decision for custom/test
-     * terminals. `undefined` falls back to the resolved `TERMINAL` profile.
-     */
-    hasEagerEraseScrollbackRisk?(): boolean | undefined;
     /**
      * Register a callback for terminal appearance (dark/light) changes.
      * Detection uses OSC 11 background color query with Mode 2031 as a change trigger.
@@ -77,12 +65,22 @@ export interface Terminal {
      */
     onPrivateModeReport?(callback: (mode: number, supported: 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 appearance(): TerminalAppearance | undefined;
     onAppearanceChange(callback: (appearance: TerminalAppearance) => void): void;
     onPrivateModeReport(callback: (mode: number, supported: boolean) => void): void;