@linxiraos/pi-tui 1.0.0

package/dist/types/keybindings.d.ts

@@ -0,0 +1,197 @@
+import { type KeyId } from "./keys.js";
+/**
+ * Global keybinding registry.
+ * Downstream packages can add keybindings via declaration merging.
+ */
+export interface Keybindings {
+    "tui.editor.cursorUp": true;
+    "tui.editor.cursorDown": true;
+    "tui.editor.cursorLeft": true;
+    "tui.editor.cursorRight": true;
+    "tui.editor.cursorWordLeft": true;
+    "tui.editor.cursorWordRight": true;
+    "tui.editor.cursorLineStart": true;
+    "tui.editor.cursorLineEnd": true;
+    "tui.editor.jumpForward": true;
+    "tui.editor.jumpBackward": true;
+    "tui.editor.pageUp": true;
+    "tui.editor.pageDown": true;
+    "tui.editor.deleteCharBackward": true;
+    "tui.editor.deleteCharForward": true;
+    "tui.editor.deleteWordBackward": true;
+    "tui.editor.deleteWordForward": true;
+    "tui.editor.deleteToLineStart": true;
+    "tui.editor.deleteToLineEnd": true;
+    "tui.editor.yank": true;
+    "tui.editor.yankPop": true;
+    "tui.editor.undo": true;
+    "tui.input.newLine": true;
+    "tui.input.submit": true;
+    "tui.input.tab": true;
+    "tui.input.copy": true;
+    "tui.select.up": true;
+    "tui.select.down": true;
+    "tui.select.pageUp": true;
+    "tui.select.pageDown": true;
+    "tui.select.confirm": true;
+    "tui.select.cancel": true;
+}
+export type Keybinding = keyof Keybindings;
+export type { KeyId };
+export interface KeybindingDefinition {
+    defaultKeys: KeyId | KeyId[];
+    description?: string;
+}
+export type KeybindingDefinitions = Record<string, KeybindingDefinition>;
+export type KeybindingsConfig = Record<string, KeyId | KeyId[] | undefined>;
+export declare const TUI_KEYBINDINGS: {
+    readonly "tui.editor.cursorUp": {
+        readonly defaultKeys: "up";
+        readonly description: "Move cursor up";
+    };
+    readonly "tui.editor.cursorDown": {
+        readonly defaultKeys: "down";
+        readonly description: "Move cursor down";
+    };
+    readonly "tui.editor.cursorLeft": {
+        readonly defaultKeys: ["left", "ctrl+b"];
+        readonly description: "Move cursor left";
+    };
+    readonly "tui.editor.cursorRight": {
+        readonly defaultKeys: ["right", "ctrl+f"];
+        readonly description: "Move cursor right";
+    };
+    readonly "tui.editor.cursorWordLeft": {
+        readonly defaultKeys: ["alt+left", "ctrl+left", "alt+b"];
+        readonly description: "Move cursor word left";
+    };
+    readonly "tui.editor.cursorWordRight": {
+        readonly defaultKeys: ["alt+right", "ctrl+right", "alt+f"];
+        readonly description: "Move cursor word right";
+    };
+    readonly "tui.editor.cursorLineStart": {
+        readonly defaultKeys: ["home", "ctrl+a"];
+        readonly description: "Move to line start";
+    };
+    readonly "tui.editor.cursorLineEnd": {
+        readonly defaultKeys: ["end", "ctrl+e"];
+        readonly description: "Move to line end";
+    };
+    readonly "tui.editor.jumpForward": {
+        readonly defaultKeys: "ctrl+]";
+        readonly description: "Jump forward to character";
+    };
+    readonly "tui.editor.jumpBackward": {
+        readonly defaultKeys: "ctrl+alt+]";
+        readonly description: "Jump backward to character";
+    };
+    readonly "tui.editor.pageUp": {
+        readonly defaultKeys: "pageUp";
+        readonly description: "Page up";
+    };
+    readonly "tui.editor.pageDown": {
+        readonly defaultKeys: "pageDown";
+        readonly description: "Page down";
+    };
+    readonly "tui.editor.deleteCharBackward": {
+        readonly defaultKeys: "backspace";
+        readonly description: "Delete character backward";
+    };
+    readonly "tui.editor.deleteCharForward": {
+        readonly defaultKeys: ["delete", "ctrl+d"];
+        readonly description: "Delete character forward";
+    };
+    readonly "tui.editor.deleteWordBackward": {
+        readonly defaultKeys: ["ctrl+w", "alt+backspace", "ctrl+backspace", "super+alt+backspace"];
+        readonly description: "Delete word backward";
+    };
+    readonly "tui.editor.deleteWordForward": {
+        readonly defaultKeys: ["alt+delete", "alt+d", "super+alt+delete", "super+alt+d"];
+        readonly description: "Delete word forward";
+    };
+    readonly "tui.editor.deleteToLineStart": {
+        readonly defaultKeys: "ctrl+u";
+        readonly description: "Delete to line start";
+    };
+    readonly "tui.editor.deleteToLineEnd": {
+        readonly defaultKeys: "ctrl+k";
+        readonly description: "Delete to line end";
+    };
+    readonly "tui.editor.yank": {
+        readonly defaultKeys: "ctrl+y";
+        readonly description: "Yank";
+    };
+    readonly "tui.editor.yankPop": {
+        readonly defaultKeys: "alt+y";
+        readonly description: "Yank pop";
+    };
+    readonly "tui.editor.undo": {
+        readonly defaultKeys: ["ctrl+-", "ctrl+_"];
+        readonly description: "Undo";
+    };
+    readonly "tui.input.newLine": {
+        readonly defaultKeys: ["shift+enter", "ctrl+j"];
+        readonly description: "Insert newline";
+    };
+    readonly "tui.input.submit": {
+        readonly defaultKeys: "enter";
+        readonly description: "Submit input";
+    };
+    readonly "tui.input.tab": {
+        readonly defaultKeys: "tab";
+        readonly description: "Tab / autocomplete";
+    };
+    readonly "tui.input.copy": {
+        readonly defaultKeys: "ctrl+c";
+        readonly description: "Copy selection";
+    };
+    readonly "tui.select.up": {
+        readonly defaultKeys: "up";
+        readonly description: "Move selection up";
+    };
+    readonly "tui.select.down": {
+        readonly defaultKeys: "down";
+        readonly description: "Move selection down";
+    };
+    readonly "tui.select.pageUp": {
+        readonly defaultKeys: "pageUp";
+        readonly description: "Selection page up";
+    };
+    readonly "tui.select.pageDown": {
+        readonly defaultKeys: "pageDown";
+        readonly description: "Selection page down";
+    };
+    readonly "tui.select.confirm": {
+        readonly defaultKeys: "enter";
+        readonly description: "Confirm selection";
+    };
+    readonly "tui.select.cancel": {
+        readonly defaultKeys: ["escape", "ctrl+c"];
+        readonly description: "Cancel selection";
+    };
+};
+export interface KeybindingConflict {
+    key: KeyId;
+    keybindings: string[];
+}
+export declare function canonicalKeyId(key: string): string;
+export declare function addKeyAliases(keys: Set<string>, key: KeyId): void;
+export declare class KeybindingsManager {
+    #private;
+    constructor(definitions: KeybindingDefinitions, userBindings?: KeybindingsConfig);
+    matches(data: string, keybinding: Keybinding): boolean;
+    /**
+     * Set-lookup variant of {@link matches} for hot input paths: the caller
+     * parses `data` once (`parseKey` + `canonicalKeyId`) and probes many
+     * bindings without re-parsing the raw sequence per probe.
+     */
+    matchesCanonical(canonical: string | undefined, keybinding: Keybinding): boolean;
+    getKeys(keybinding: Keybinding): KeyId[];
+    getDefinition(keybinding: Keybinding): KeybindingDefinition;
+    getConflicts(): KeybindingConflict[];
+    setUserBindings(userBindings: KeybindingsConfig): void;
+    getUserBindings(): KeybindingsConfig;
+    getResolvedBindings(): KeybindingsConfig;
+}
+export declare function setKeybindings(keybindings: KeybindingsManager): void;
+export declare function getKeybindings(): KeybindingsManager;

package/dist/types/keys.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Keyboard input handling for terminal applications.
+ *
+ * Supports both legacy terminal sequences and Kitty keyboard protocol.
+ * See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/
+ * Reference: https://github.com/sst/opentui/blob/7da92b4088aebfe27b9f691c04163a48821e49fd/packages/core/src/lib/parse.keypress.ts
+ *
+ * Symbol keys are also supported, however some ctrl+symbol combos
+ * overlap with ASCII codes, e.g. ctrl+[ = ESC.
+ * See: https://sw.kovidgoyal.net/kitty/keyboard-protocol/#legacy-ctrl-mapping-of-ascii-keys
+ * Those can still be * used for ctrl+shift combos
+ *
+ * API:
+ * - matchesKey(data, keyId) - Check if input matches a key identifier
+ * - parseKey(data) - Parse input and return the key identifier
+ * - Key - Helper object for creating typed key identifiers
+ * - setKittyProtocolActive(active) - Set global Kitty protocol state
+ * - isKittyProtocolActive() - Query global Kitty protocol state
+ */
+import type { KeyEventType } from "@linxiraos/pi-natives";
+/** Whether the local process is running directly under Windows Terminal. */
+export declare function isWindowsTerminalSession(): boolean;
+/**
+ * Match ambiguous legacy Backspace bytes against an expected modifier mask.
+ *
+ * Windows Terminal encodes Ctrl+Backspace as raw `0x08` (BS) and plain
+ * Backspace as `0x7f` (DEL). Remote/container sessions lose terminal identity,
+ * and multiplexers (tmux/screen/Zellij) inherit `WT_SESSION` while emitting
+ * raw `0x08` for plain Backspace themselves, so the automatic heuristic is
+ * limited to direct Windows Terminal sessions. `PI_TUI_RAW_BACKSPACE_IS_CTRL=1`
+ * explicitly opts into the mapping everywhere.
+ */
+export declare function matchesRawBackspace(data: string, expectedModifier: number): boolean;
+/**
+ * Set the global Kitty keyboard protocol state.
+ * Called by ProcessTerminal after detecting protocol support.
+ */
+export declare function setKittyProtocolActive(active: boolean): void;
+/**
+ * Query whether Kitty keyboard protocol is currently active.
+ */
+export declare function isKittyProtocolActive(): boolean;
+type Letter = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z";
+type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+type SymbolKey = "`" | "-" | "=" | "[" | "]" | "\\" | ";" | "'" | "," | "." | "/" | "!" | "@" | "#" | "$" | "%" | "^" | "&" | "*" | "(" | ")" | "_" | "+" | "|" | "~" | "{" | "}" | ":" | "<" | ">" | "?";
+type SpecialKey = "escape" | "esc" | "enter" | "return" | "tab" | "space" | "backspace" | "delete" | "insert" | "clear" | "home" | "end" | "pageUp" | "pageDown" | "up" | "down" | "left" | "right" | "f1" | "f2" | "f3" | "f4" | "f5" | "f6" | "f7" | "f8" | "f9" | "f10" | "f11" | "f12";
+type BaseKey = Letter | Digit | SymbolKey | SpecialKey;
+type ModifierName = "ctrl" | "shift" | "alt" | "super";
+type ModifiedKeyId<Key extends string, RemainingModifiers extends ModifierName = ModifierName> = {
+    [M in RemainingModifiers]: `${M}+${Key}` | `${M}+${ModifiedKeyId<Key, Exclude<RemainingModifiers, M>>}`;
+}[RemainingModifiers];
+/**
+ * Union type of all valid key identifiers.
+ * Provides autocomplete and catches typos at compile time.
+ */
+export type KeyId = BaseKey | ModifiedKeyId<BaseKey>;
+/**
+ * Typed helper for constructing key identifiers with autocomplete.
+ *
+ * The runtime values are just the canonical key-name strings (so `Key.enter`
+ * is literally `"enter"`); the value of `Key` over a bag of magic strings is
+ * that each property is typed to the exact `KeyId` literal it produces and the
+ * modifier methods return precisely-typed concatenations (e.g. `Key.ctrl("c")`
+ * is `"ctrl+c"`, not just `string`). This mirrors the upstream
+ * `@mariozechner/pi-tui` `Key` export verbatim so plugins built against any
+ * scope alias (`@mariozechner`, `@earendil-works`, `@oh-my-pi`) keep working
+ * once the specifier shim remaps them to this package.
+ */
+export declare const Key: {
+    readonly escape: "escape";
+    readonly esc: "esc";
+    readonly enter: "enter";
+    readonly return: "return";
+    readonly tab: "tab";
+    readonly space: "space";
+    readonly backspace: "backspace";
+    readonly delete: "delete";
+    readonly insert: "insert";
+    readonly clear: "clear";
+    readonly home: "home";
+    readonly end: "end";
+    readonly pageUp: "pageUp";
+    readonly pageDown: "pageDown";
+    readonly up: "up";
+    readonly down: "down";
+    readonly left: "left";
+    readonly right: "right";
+    readonly f1: "f1";
+    readonly f2: "f2";
+    readonly f3: "f3";
+    readonly f4: "f4";
+    readonly f5: "f5";
+    readonly f6: "f6";
+    readonly f7: "f7";
+    readonly f8: "f8";
+    readonly f9: "f9";
+    readonly f10: "f10";
+    readonly f11: "f11";
+    readonly f12: "f12";
+    readonly backtick: "`";
+    readonly hyphen: "-";
+    readonly equals: "=";
+    readonly leftbracket: "[";
+    readonly rightbracket: "]";
+    readonly backslash: "\\";
+    readonly semicolon: ";";
+    readonly quote: "'";
+    readonly comma: ",";
+    readonly period: ".";
+    readonly slash: "/";
+    readonly exclamation: "!";
+    readonly at: "@";
+    readonly hash: "#";
+    readonly dollar: "$";
+    readonly percent: "%";
+    readonly caret: "^";
+    readonly ampersand: "&";
+    readonly asterisk: "*";
+    readonly leftparen: "(";
+    readonly rightparen: ")";
+    readonly underscore: "_";
+    readonly plus: "+";
+    readonly pipe: "|";
+    readonly tilde: "~";
+    readonly leftbrace: "{";
+    readonly rightbrace: "}";
+    readonly colon: ":";
+    readonly lessthan: "<";
+    readonly greaterthan: ">";
+    readonly question: "?";
+    readonly ctrl: <K extends BaseKey>(key: K) => `ctrl+${K}`;
+    readonly shift: <K extends BaseKey>(key: K) => `shift+${K}`;
+    readonly alt: <K extends BaseKey>(key: K) => `alt+${K}`;
+    readonly super: <K extends BaseKey>(key: K) => `super+${K}`;
+    readonly ctrlShift: <K extends BaseKey>(key: K) => `ctrl+shift+${K}`;
+    readonly shiftCtrl: <K extends BaseKey>(key: K) => `shift+ctrl+${K}`;
+    readonly ctrlAlt: <K extends BaseKey>(key: K) => `ctrl+alt+${K}`;
+    readonly altCtrl: <K extends BaseKey>(key: K) => `alt+ctrl+${K}`;
+    readonly shiftAlt: <K extends BaseKey>(key: K) => `shift+alt+${K}`;
+    readonly altShift: <K extends BaseKey>(key: K) => `alt+shift+${K}`;
+    readonly ctrlSuper: <K extends BaseKey>(key: K) => `ctrl+super+${K}`;
+    readonly superCtrl: <K extends BaseKey>(key: K) => `super+ctrl+${K}`;
+    readonly shiftSuper: <K extends BaseKey>(key: K) => `shift+super+${K}`;
+    readonly superShift: <K extends BaseKey>(key: K) => `super+shift+${K}`;
+    readonly altSuper: <K extends BaseKey>(key: K) => `alt+super+${K}`;
+    readonly superAlt: <K extends BaseKey>(key: K) => `super+alt+${K}`;
+    readonly ctrlShiftAlt: <K extends BaseKey>(key: K) => `ctrl+shift+alt+${K}`;
+    readonly ctrlShiftSuper: <K extends BaseKey>(key: K) => `ctrl+shift+super+${K}`;
+};
+interface ParsedKittySequence {
+    codepoint: number;
+    shiftedKey?: number;
+    baseLayoutKey?: number;
+    modifier: number;
+    eventType?: KeyEventType;
+}
+/**
+ * Check if the input is a key release event.
+ * Only meaningful when Kitty keyboard protocol with flag 2 is active.
+ * Returns false if Kitty protocol is not active.
+ */
+export declare function isKeyRelease(data: string): boolean;
+/**
+ * Check if the input is a key repeat event.
+ * Only meaningful when Kitty keyboard protocol with flag 2 is active.
+ * Returns false if Kitty protocol is not active.
+ */
+export declare function isKeyRepeat(data: string): boolean;
+export declare function parseKittySequence(data: string): ParsedKittySequence | null;
+/**
+ * Extract printable text from raw terminal input.
+ *
+ * Handles Kitty CSI-u text-producing keys so text-entry components can treat
+ * keypad digits, keypad operators, and shifted symbols the same as direct character input.
+ */
+export declare function extractPrintableText(data: string): string | undefined;
+/**
+ * Decode terminal input into the printable character it represents.
+ *
+ * Tries Kitty CSI-u first, then falls back to xterm modifyOtherKeys. Returns
+ * undefined for control sequences and modifier-only events.
+ */
+export declare function decodePrintableKey(data: string): string | undefined;
+/**
+ * Match input data against a key identifier string.
+ *
+ * Supported key identifiers:
+ * - Single keys: "escape", "tab", "enter", "backspace", "delete", "home", "end", "space"
+ * - Arrow keys: "up", "down", "left", "right"
+ * - Ctrl combinations: "ctrl+c", "ctrl+z", etc.
+ * - Shift combinations: "shift+tab", "shift+enter"
+ * - Alt combinations: "alt+enter", "alt+backspace"
+ * - Combined modifiers: "shift+ctrl+p", "ctrl+alt+x"
+ *
+ * Use the Key helper for autocomplete: Key.ctrl("c"), Key.escape, Key.ctrlShift("p")
+ *
+ * @param data - Raw input data from terminal
+ * @param keyId - Key identifier (e.g., "ctrl+c", "escape", Key.ctrl("c"))
+ */
+export declare function matchesKey(data: string, keyId: KeyId): boolean;
+/**
+ * Parse terminal input and return a normalized key identifier.
+ *
+ * Returns key names like "escape", "ctrl+c", "shift+tab", "alt+enter".
+ * Returns undefined if the input is not a recognized key sequence.
+ *
+ * @param data - Raw input data from terminal
+ */
+export declare function parseKey(data: string): string | undefined;
+export {};

package/dist/types/kill-ring.d.ts

@@ -0,0 +1,20 @@
+export declare class KillRing {
+    #private;
+    /**
+     * Add text to the kill ring.
+     *
+     * @param text - The killed text to add
+     * @param opts - Push options
+     * @param opts.prepend - If accumulating, prepend (backward deletion) or append (forward deletion)
+     * @param opts.accumulate - Merge with the most recent entry instead of creating a new one
+     */
+    push(text: string, opts: {
+        prepend: boolean;
+        accumulate?: boolean;
+    }): void;
+    /** Get most recent entry without modifying the ring. */
+    peek(): string | undefined;
+    /** Move last entry to front (for yank-pop cycling). */
+    rotate(): void;
+    get length(): number;
+}

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

@@ -0,0 +1,76 @@
+/**
+ * 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 interface KittyGraphicsFeatures {
+    /** Display images via Unicode placeholders instead of direct `a=p` placement. */
+    unicodePlaceholders: boolean;
+}
+/**
+ * Whether the detected terminal renders Kitty Unicode placeholders (`U=1` +
+ * U+10EEEE with row/column diacritics).
+ *
+ * Kitty and Ghostty advertise placeholder support directly. A tmux session
+ * cannot use cursor-positioned placements because the outer terminal does not
+ * know pane scroll/reflow state, so an explicit `PI_FORCE_IMAGE_PROTOCOL=kitty`
+ * also opts into placeholders there — matching `timg -pk`. Automatic tmux
+ * fallback stays off because the unknown outer terminal may render U+10EEEE as
+ * literal PUA boxes (#1877).
+ *
+ * `PI_NO_KITTY_PLACEHOLDERS=1` and `PI_KITTY_PLACEHOLDERS=0` remain hard
+ * opt-outs; `PI_KITTY_PLACEHOLDERS=1` explicitly opts in anywhere else.
+ */
+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 a `columns`×`rows` placeholder grid fits within the diacritic table. */
+export declare function kittyPlaceholdersFit(columns: number, rows: number): 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[];

package/dist/types/latex-block.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Render a display LaTeX math fragment to lines with full 2-D layout: stacked
+ * fractions, stretchy delimiters, matrix grids, operator limits, drawn
+ * radicals. Top-level source newlines and `\\` become vertical rows (so a
+ * `lhs =` line stays above its block). Inline math should use `latexToUnicode`
+ * instead — fractions there stay single-line.
+ */
+export declare function latexToBlock(src: string): string[];

package/dist/types/latex-to-unicode.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Math font command names (`\mathbf`, `\mathbb`, …) whose single brace argument
+ * restyles glyphs. Exported for the display block engine (`latex-block`), which
+ * re-wraps inline runs inside these commands when their argument contains 2-D
+ * layout (fractions, matrices) so styling survives box boundaries.
+ */
+export declare const MATH_FONT_COMMANDS: ReadonlySet<string>;
+/**
+ * Painter for a LaTeX color scope (optional model + spec, e.g. `rgb`/`1,0,0` or
+ * `red`): returns a function that paints already-rendered text with the scope's
+ * foreground, re-asserting it after embedded foreground resets so nested color
+ * runs restore to the scope color; null when the color cannot be resolved. Used
+ * by the display block engine (`latex-block`) to paint structural glyphs
+ * (fraction bars, stretched delimiters, matrix brackets) inside
+ * `\color`/`\textcolor` scopes.
+ */
+export declare function latexColorScope(model: string | null, spec: string): ((text: string) => string) | null;
+/**
+ * Convert a bare LaTeX math fragment (no surrounding `$`/`\(` delimiters) to its
+ * best-effort Unicode rendering. Unknown commands degrade to their bare name;
+ * `\\` becomes a newline. Always returns a string (never throws).
+ */
+export declare function latexToUnicode(src: string): string;
+/**
+ * True when `env` is a math environment safe to auto-render without `$`/`\[`
+ * delimiters. The trailing `*` of starred variants (`align*`, `equation*`) is
+ * ignored; text-mode environments (`tabular`, `itemize`, …) return false.
+ */
+export declare function isBareMathEnvironment(env: string): boolean;
+/**
+ * Scan prose for math spans — `$$…$$`, `\[…\]` (display) and `$…$`, `\(…\)`
+ * (inline) — and replace each with its Unicode rendering, leaving everything
+ * else verbatim. Newlines inside a span collapse to spaces so the result stays
+ * single-line-safe.
+ *
+ * Inline `$…$` uses pandoc's anti-currency heuristics: the opener must not be
+ * followed by whitespace, the closer must not be preceded by whitespace nor
+ * followed by a digit, and `\$` is treated as a literal dollar — so "$5 and
+ * $10" is left untouched.
+ */
+export declare function renderMathInText(text: string): string;
+/**
+ * Index of the `$` that closes an inline math span opened at `open` (the index
+ * of the opening `$`), or -1 when the run is not inline math. Applies pandoc's
+ * anti-currency heuristics: the opener must not be followed by whitespace, the
+ * closer must not be preceded by whitespace nor followed by a digit, `\$` is a
+ * literal dollar, and the span may not span a newline. Shared by
+ * `renderMathInText` and the markdown math tokenizer so the rule has one home.
+ */
+export declare function inlineMathSpanEnd(text: string, open: number): number;

package/dist/types/loop-watchdog.d.ts

@@ -0,0 +1,44 @@
+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;
+    /** Overshoot beyond this likely includes system sleep, so it is suppressed. Default 60_000. */
+    sleepMs?: 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. An overshoot beyond
+ * `sleepMs` is treated as system sleep rather than a synchronous stall: the
+ * process could not have run JS during the missed interval, and one resume
+ * should not produce a multi-minute `ui.loop-blocked` record.
+ */
+export declare class LoopWatchdog {
+    #private;
+    constructor(options?: LoopWatchdogOptions);
+    start(): void;
+    stop(): void;
+}
+export {};