vterm.js 0.4.0 → 0.5.1

package/dist/index.d.mts

@@ -33,11 +33,36 @@
  * @see https://terminfo.dev for the feature matrix
  * @see https://github.com/beorn/vterm for the monorepo
  */
-interface CellColor {
+/**
+ * An RGB color, identity-preserving. `r`/`g`/`b` are always present (painters read
+ * them unconditionally); `index` is optional palette provenance. Named `Color` per the
+ * §9 naming ruling (rule 5: flat progressive shape over a discriminated union — a type
+ * named `RGB` that carries `.index` would lie). {@link CellColor} is the deprecated alias.
+ */
+interface Color {
   r: number;
   g: number;
   b: number;
+  /**
+   * The palette index (0-255) this RGB was resolved from, when the color came
+   * from an INDEXED SGR (`31`, `91`, `38;5;N`, `48;5;N`, `58;5;N`, …). Absent
+   * for true 24-bit RGB (`38;2;R;G;B`) and for OSC-sourced colors (OSC 4/10/11),
+   * which are genuine RGB with no themeable index.
+   *
+   * Why it exists: vterm resolves every indexed SGR to `palette256[idx]` at parse
+   * time. Without keeping the origin index, {@link serializeSnapshot} can only
+   * re-emit `38;2;R;G;B`, which bakes vterm's built-in ANSI values and defeats the
+   * outer terminal's theme on reattach. Preserving `index` lets the serializer
+   * re-emit the faithful indexed form so a themeable receiver themes it again.
+   *
+   * It rides {@link Snapshot} as plain optional data (like
+   * `scrollbackSoftWrapped`) and is stripped at the {@link VtermScreen.getCell} /
+   * {@link VtermScreen.getRow} read boundary, whose contract is the resolved RGB.
+   */
+  index?: number;
 }
+/** @deprecated Renamed to {@link Color} (§9 naming ruling). This alias rides the migration window. */
+type CellColor = Color;
 type UnderlineStyle = "none" | "single" | "double" | "curly" | "dotted" | "dashed";
 interface ScreenCell {
   char: string;
@@ -73,16 +98,397 @@ interface SixelImage {
   row: number;
   col: number;
 }
+interface ScreenAttrsSnapshot {
+  fg: CellColor | null;
+  bg: CellColor | null;
+  bold: boolean;
+  faint: boolean;
+  italic: boolean;
+  underline: UnderlineStyle;
+  underlineColor: CellColor | null;
+  overline: boolean;
+  strikethrough: boolean;
+  inverse: boolean;
+  hidden: boolean;
+  blink: boolean;
+  url: string | null;
+}
+interface ScreenColorStateSnapshot {
+  palette256: CellColor[];
+  defaultFgColor: CellColor | null;
+  defaultBgColor: CellColor | null;
+  cursorColor: CellColor | null;
+  specialColors: [number, CellColor][];
+  pointerFgColor: CellColor | null;
+  pointerBgColor: CellColor | null;
+  highlightBgColor: CellColor | null;
+  highlightFgColor: CellColor | null;
+}
+type ScreenParserState = "ground" | "escape" | "escape_charset" | "escape_hash" | "csi" | "osc" | "dcs" | "dcs_passthrough" | "osc_st" | "dcs_st" | "apc" | "apc_st";
+interface ScreenBufferSnapshot {
+  grid: ScreenCell[][];
+  softWrapped: boolean[];
+}
+/**
+ * The whole-world persist/restore value — grids, ranges, modes, cursor, colors,
+ * parser transients, wrap bits. JSON-safe plain data; the persist boundary, not the
+ * incremental read path. Named `Snapshot` per §9 (the namespace supplies the context);
+ * {@link ScreenSnapshot} is the deprecated alias.
+ *
+ * Note: `cursor`/`savedState` still carry `x`/`y` (not `col`/`row`) — the §9
+ * `Cursor{col,row}` field rename is DEFERRED here because these fields are the wire
+ * shape read by the binary codec (`encodeScreenSnapshotBinary`); renaming them silently
+ * changes the persisted format. The {@link Cursor} read type + `getCursor()` accessor
+ * carry the col/row vocabulary at the read boundary instead.
+ */
+interface Snapshot {
+  version: 1;
+  cols: number;
+  rows: number;
+  scrollbackLimit: number;
+  activeBuffer: "main" | "alt";
+  main: ScreenBufferSnapshot;
+  alt: ScreenBufferSnapshot;
+  scrollback: ScreenCell[][];
+  /**
+   * Per-scrollback-row soft-wrap bit: true when the row soft-wraps INTO the
+   * following row (autowrap continued the same logical line below it) — the
+   * same semantics as `ScreenBufferSnapshot.softWrapped`. Parallel to
+   * `scrollback`. Absent in snapshots taken before this field existed —
+   * `restore()` treats missing as all-false (hard-wrapped).
+   */
+  scrollbackSoftWrapped: boolean[];
+  cursor: {
+    x: number;
+    y: number;
+    visible: boolean;
+    shape: "block" | "underline" | "bar";
+    blinking: boolean;
+    savedX: number;
+    savedY: number;
+  };
+  savedState: {
+    x: number;
+    y: number;
+    attrs: ScreenAttrsSnapshot;
+    originMode: boolean;
+    autoWrap: boolean;
+    charsetG0: boolean;
+  };
+  attrs: ScreenAttrsSnapshot;
+  modes: {
+    bracketedPaste: boolean;
+    applicationCursor: boolean;
+    applicationKeypad: boolean;
+    autoWrap: boolean;
+    mouseTracking: boolean;
+    mouseTrackingMode: number;
+    sgrMouse: boolean;
+    focusTracking: boolean;
+    origin: boolean;
+    insert: boolean;
+    reverseVideo: boolean;
+    syncOutput: boolean;
+    kittyKeyboardFlags: number;
+    kittyKeyboardStack: number[];
+    kittyGraphics: boolean;
+    colorSchemeReporting: boolean;
+    decColumn: boolean;
+    altScroll: boolean;
+    utf8Mouse: boolean;
+  };
+  margins: {
+    scrollTop: number;
+    scrollBottom: number;
+    leftRight: boolean;
+    left: number;
+    right: number;
+  };
+  colors: {
+    current: ScreenColorStateSnapshot;
+    stack: ScreenColorStateSnapshot[];
+  };
+  tabStops: number[];
+  title: string;
+  clipboard: string;
+  cwd: string;
+  notifications: string[];
+  viewportOffset: number;
+  parser: {
+    state: ScreenParserState;
+    esc: string;
+    osc: string;
+    dcs: string;
+    dcsStart: {
+      row: number;
+      col: number;
+    };
+    apc: string;
+    utf8PendingBytes: number[];
+  };
+  unicode: {
+    charsetG0: boolean;
+    lastChar: string;
+    pendingRegionalIndicator: string | null;
+    afterZWJ: boolean;
+  };
+}
+/** @deprecated Renamed to {@link Snapshot} (§9 naming ruling). This alias rides the migration window. */
+type ScreenSnapshot = Snapshot;
+/**
+ * The cursor position at the read boundary, in the grid's own `col`/`row` vocabulary
+ * (§9 naming ruling: `x`/`y` contradicted the row/col naming used everywhere else, and
+ * the `State` suffix was redundant). Returned by {@link VtermScreen.getCursor}; the legacy
+ * {@link VtermScreen.getCursorPosition} still returns the `{ x, y }` shape (deprecated).
+ */
+interface Cursor {
+  col: number;
+  row: number;
+}
+/**
+ * A terminal write as serializable data — the coarse WRITE vocabulary, symmetric with the
+ * Hab session journal and termless `Recording`. Bytes remain the CANONICAL encoding of an
+ * `output` op (they are what the journal persists and what {@link Screen.tapOps} delivers);
+ * a `string` is a convenience input to {@link Screen.apply} that is UTF-8-encoded before it
+ * is applied. This is deliberately NOT a per-VT-action reification — fine-grained parsed
+ * actions are surfaced by {@link ParserEvent} through {@link Screen.tapParser}.
+ */
+type TerminalOp = {
+  type: "output";
+  data: Uint8Array | string;
+} | {
+  type: "resize";
+  cols: number;
+  rows: number;
+};
+/**
+ * A single parsed VT action, emitted by {@link Screen.tapParser} AFTER the engine applies it,
+ * in stream order. A minimal, stable union over what the parser dispatches:
+ *
+ * - `print`   — a run of consecutive printable graphemes, coalesced within one {@link
+ *               Screen.process}/{@link Screen.apply} flood and flushed before the next control
+ *               event (and at end-of-flood).
+ * - `execute` — a recognized C0 control byte (BEL, BS, HT, LF, VT, FF, CR); `code` is the byte.
+ * - `csi`     — a complete CSI sequence; `final` is the dispatching byte, `params` are the
+ *               `;`-separated numeric parameters (empty → `0`, matching the engine's own parse),
+ *               `prefix` is the private marker (`?`/`>`/`<`/`=`) when present, `intermediates`
+ *               are the `0x20`–`0x2f` bytes when present. (Colon sub-parameters collapse to
+ *               their leading integer — the top-level view the non-SGR dispatchers also use.)
+ * - `osc`     — a complete OSC with a numeric `code`; `data` is everything after the first `;`.
+ * - `esc`     — a complete non-CSI/OSC escape (`ESC c`/`D`/`M`/`7`/`8`/`E`/`H`/`=`/`>` and the
+ *               charset/`#` designators); `final` is the dispatching byte, `intermediates`
+ *               carries the `(`/`)`/`#` designator byte when present.
+ *
+ * DCS and APC string sequences are not (yet) surfaced. A listener MUST NOT throw — taps are
+ * fail-loud: an exception propagates out of the write call (the engine state stays consistent).
+ */
+type ParserEvent = {
+  kind: "print";
+  text: string;
+} | {
+  kind: "execute";
+  code: number;
+} | {
+  kind: "csi";
+  final: string;
+  params: number[];
+  prefix?: string;
+  intermediates?: string;
+} | {
+  kind: "osc";
+  code: number;
+  data: string;
+} | {
+  kind: "esc";
+  final: string;
+  intermediates?: string;
+};
+/**
+ * Accumulated per-row damage since the previous {@link Screen.takeDirty} call — the PULL-plane
+ * observation surface for renderers that read on their own schedule (distinct from the push-plane
+ * {@link Screen.tapOps}/{@link Screen.tapParser}). Absolute-row indexed, consistent with
+ * {@link Screen.getRowAbsolute}.
+ *
+ * - `rows` — the changed rows as retained-relative ABSOLUTE indices (row 0 = oldest retained
+ *   scrollback line), OR the literal `"all"` when the whole visible buffer changed structurally
+ *   (resize, full clear, alt-screen switch, reset, restore). The `Set` is freshly OWNED by the
+ *   caller — the engine keeps a separate empty accumulator after the take.
+ * - `cursor` — `true` when the cursor position/visibility/shape/blink changed since the last take.
+ * - `scrolled` — number of lines that entered scrollback since the last take (a renderer shifts
+ *   its viewport by this and repaints only the rows in `rows`).
+ *
+ * Contract note on trimming: a retention trim shifts every absolute index down by the trimmed
+ * count; `rows` are valid against the buffer AT take time. Pair with {@link Screen.firstRetainedRow}
+ * (which bumps by the trimmed count) to rebase indices cached across a take that spanned a trim.
+ */
+interface DirtyRegion {
+  rows: Set<number> | "all";
+  cursor: boolean;
+  scrolled: number;
+}
+/**
+ * A minimal read-signal — the atom of the REACTIVE read plane (§4). Defined IN vterm.js, which
+ * stays dependency-free (§9 rule 7: compatible SHAPES over shared imports). A consumer wraps it in
+ * `alien-signals`, a zustand store, or React's `useSyncExternalStore` trivially, because the shape
+ * is exactly `{ get, subscribe }` — nothing here imports a reactive library.
+ *
+ * - `get()` returns the CURRENT value, computed live from engine state. It is pull-safe and
+ *   independent of subscription: calling it never schedules, consumes, or resets a delivery.
+ * - `subscribe(listener)` registers for change delivery and returns an unsubscribe function. The
+ *   listener fires at most once per flush boundary (see {@link ScreenSignals}), and only when the
+ *   value actually changed since the last delivery (equality-gated). Subscribing does NOT fire
+ *   immediately — the baseline is the value at subscribe time, so only later changes deliver.
+ *   Fail-loud: a throwing listener propagates out of the write call.
+ */
+interface ReadSignal<T> {
+  get(): T;
+  subscribe(listener: (value: T) => void): () => void;
+}
+/** The terminal's screen size (its column/row dimensions). Emitted by {@link ScreenSignals.size$}. */
+interface Size {
+  cols: number;
+  rows: number;
+}
+/**
+ * The closed DEC/xterm private-mode set at the OBSERVATION boundary — everything a guest previously
+ * discovered by regex-scanning the DECSET byte stream. Emitted by {@link ScreenSignals.modes$}
+ * (equality-gated: one emission per flush that actually flips a mode). Mirrors the string keys of
+ * {@link Screen.getMode}, plus the numeric mouse-tracking protocol level.
+ */
+interface TerminalModes {
+  altScreen: boolean;
+  cursorVisible: boolean;
+  bracketedPaste: boolean;
+  applicationCursor: boolean;
+  applicationKeypad: boolean;
+  autoWrap: boolean;
+  mouseTracking: boolean;
+  /** The active mouse-tracking protocol: `0` = off; `1000`/`1002`/`1003` = X10/button/any-event. */
+  mouseTrackingMode: number;
+  sgrMouse: boolean;
+  utf8Mouse: boolean;
+  focusTracking: boolean;
+  originMode: boolean;
+  insertMode: boolean;
+  reverseVideo: boolean;
+  syncOutput: boolean;
+  leftRightMargin: boolean;
+  colorSchemeReporting: boolean;
+  kittyKeyboard: boolean;
+  kittyGraphics: boolean;
+  sixel: boolean;
+}
+/**
+ * The REACTIVE read plane (§4): five equality-gated signals over the SAME state the pull plane
+ * ({@link Screen.getRowAbsolute}/{@link Screen.takeDirty}) and the push plane ({@link Screen.tapOps})
+ * expose. It replaces consumers' title-polling and DECSET regex scanning.
+ *
+ * Zero overhead when unused: `.signals` is lazily created (the getter allocates nothing until first
+ * read), and each signal is lazily created on first access (per-signal laziness). The write core does
+ * NO signal bookkeeping until `.signals` is read, and NO per-write damage accumulation until
+ * `damage$` actually has a subscriber.
+ *
+ * Flush boundary: every signal coalesces to AT MOST ONE emission per public state-mutating call
+ * (`process`/`apply`/`resize`/`reset`/`restore`; `apply` inherits it via `process`/`resize`) — the
+ * natural batch. `title$`/`modes$`/`cursor$`/`size$` fire only when their value actually changed
+ * across the call; `damage$` publishes the BATCHED dirty-set accumulated during the call.
+ *
+ * Two-plane coexistence: `damage$` runs on an accumulator INDEPENDENT of {@link Screen.takeDirty}.
+ * Subscribing never steals or resets the pull-plane epoch, so a `damage$` renderer and a
+ * `takeDirty()` differ observe the same damage without draining each other.
+ */
+interface ScreenSignals {
+  /** The window title (OSC 0/2). Replaces title-diff polling. */
+  title$: ReadSignal<string>;
+  /** The closed DEC/xterm mode set. Replaces the guest's DECSET regex scanner. */
+  modes$: ReadSignal<TerminalModes>;
+  /** The cursor position in grid `col`/`row` (§9). Visibility rides {@link modes$}`.cursorVisible`. */
+  cursor$: ReadSignal<Cursor>;
+  /** The screen size. */
+  size$: ReadSignal<Size>;
+  /**
+   * The per-flush BATCHED dirty region — the union of rows changed during the call (or `"all"` on a
+   * structural change), with the cursor/scroll deltas. Same shape as {@link Screen.takeDirty}, but
+   * drained on its OWN epoch (see the interface note); this is precisely what a future canvas/DOM
+   * renderer subscribes to. The emitted region (including its `rows` `Set`) is SHARED across all
+   * `damage$` subscribers for that flush — treat it as read-only.
+   */
+  damage$: ReadSignal<DirtyRegion>;
+}
 interface Screen {
   readonly cols: number;
   readonly rows: number;
+  /** The reactive read plane (§4). Lazily created; zero write-path overhead until used. */
+  readonly signals: ScreenSignals;
   process(data: Uint8Array): void;
   resize(cols: number, rows: number): void;
+  /**
+   * Apply one {@link TerminalOp} — the single public write entry, symmetric with the journal.
+   * `output` routes to {@link process} (a `string` payload is UTF-8-encoded first); `resize`
+   * routes to {@link resize}. Additive over `process`/`resize`, which remain public.
+   */
+  apply(op: TerminalOp): void;
+  /**
+   * Observe applied ops (opt-in). The listener fires exactly once per applied op — one per
+   * `process`/`apply`/`resize` call — with the CANONICAL payload (an `output` op always carries
+   * a `Uint8Array`). Returns an unsubscribe function. Zero overhead when no listener is
+   * registered. Enables symmetric journaling of the write stream.
+   */
+  tapOps(listener: (op: TerminalOp) => void): () => void;
+  /**
+   * Observe parsed VT actions (opt-in), delivered AFTER each is applied, in stream order.
+   * Returns an unsubscribe function. Zero overhead when no listener is registered — no {@link
+   * ParserEvent} is allocated on the byte-flood path unless a listener exists.
+   */
+  tapParser(listener: (event: ParserEvent) => void): () => void;
   reset(): void;
+  snapshot(): Snapshot;
+  restore(snapshot: Snapshot): void;
+  /** Serialize the current state to minimal ANSI — `serializeSnapshot(this.snapshot(), options)`. */
+  serialize(options?: SerializeOptions): string;
   getCell(row: number, col: number): ScreenCell;
+  /**
+   * The cells of a screen-relative row (§9: **row = cells, line = text**). Colors are
+   * stripped of palette-origin index at the read boundary.
+   */
+  getRow(row: number): ScreenCell[];
+  /** @deprecated Renamed to {@link getRow} (§9: row = cells, line = text). */
   getLine(row: number): ScreenCell[];
   getText(): string;
+  /** Scrollback rows above the visible grid, oldest first, rendered like getText(). */
+  getScrollbackText(): string;
   getTextRange(startRow: number, startCol: number, endRow: number, endCol: number): string;
+  /** Total rows in the buffer: retained scrollback + screen. */
+  totalRows(): number;
+  /** Number of visible screen rows (the terminal's row dimension). */
+  screenRows(): number;
+  /**
+   * Absolute row where the viewport's top line sits. At the bottom (no scroll):
+   * `totalRows() - screenRows()`. Scrolled fully up: `0`.
+   */
+  viewportTop(): number;
+  /**
+   * The row at ABSOLUTE index `row` (row 0 = oldest retained scrollback line; the screen occupies
+   * the last `screenRows()` rows). Colors are stripped of palette-origin index like {@link getLine}.
+   * Out-of-range indices return a blank row (matching the {@link getLine} read-boundary contract).
+   */
+  getRowAbsolute(row: number): ScreenCell[];
+  /**
+   * The GLOBAL index of retained absolute row 0 — i.e. the number of scrollback lines permanently
+   * evicted by retention trimming since creation (0 initially). Increases only when trimming drops
+   * lines; resets on {@link reset}/{@link restore}. A stable global row id is
+   * `firstRetainedRow() + <absolute row>`; an increase since a prior read signals a trim.
+   */
+  firstRetainedRow(): number;
+  /**
+   * Take and reset the accumulated per-row damage since the previous call — the pull-plane damage
+   * surface for renderers. See {@link DirtyRegion}. Always-on (independent of {@link tapOps}); the
+   * write path costs at most one Set membership update per row-run.
+   */
+  takeDirty(): DirtyRegion;
+  /** Cursor position in the grid's `col`/`row` vocabulary (§9). See {@link Cursor}. */
+  getCursor(): Cursor;
+  /** @deprecated Use {@link getCursor} — returns `{ col, row }` per the §9 naming ruling. */
   getCursorPosition(): {
     x: number;
     y: number;
@@ -102,5 +508,45 @@ interface Screen {
   getSixelImages(): SixelImage[];
 }
 declare function createScreen(options?: ScreenOptions): Screen;
+interface SerializeOptions {
+  /** Emit scrollback history rows before the screen paint. Default: true. */
+  includeScrollback?: boolean;
+  /** Emit the window title (OSC 0) when non-empty. Default: false. */
+  includeTitle?: boolean;
+  /** Emit OSC 8 hyperlinks for cell and pending-pen urls. Default: true. */
+  hyperlinks?: boolean;
+  /**
+   * Snapshot mode keys to skip during emission (e.g. `"bracketedPaste"`,
+   * `"mouseTracking"`, `"kittyKeyboardFlags"`, `"origin"`, `"insert"`).
+   * The receiver keeps its fresh default for excluded keys — an explicit,
+   * caller-requested divergence from the snapshot. DECAWM paint discipline
+   * is correctness, not configuration, and cannot be excluded.
+   */
+  excludeModes?: readonly string[];
+}
+/**
+ * Serialize a snapshot to minimal ANSI a FRESH same-size terminal can replay.
+ * Phase order + the hard exclusion set are documented on the section header
+ * above; every ordering constraint is pinned by the mode round-trip matrix.
+ *
+ * Intended divergences (documented, not silent): syncOutput/decColumn are
+ * never emitted; the inactive buffer, SCP saved cursor, DECSC saved state,
+ * color stack, and parser/pending-wrap/mid-parse state are unserializable to
+ * a VT byte stream by design — the binary snapshot carries them.
+ */
+declare function serializeSnapshot(snapshot: ScreenSnapshot, options?: SerializeOptions): string;
+//#endregion
+//#region src/snapshot-codec.d.ts
+/**
+ * Encode a {@link ScreenSnapshot} to a compact binary buffer. Output is
+ * deterministic for identical input and decodes back to a deep-equal snapshot.
+ */
+declare function encodeScreenSnapshotBinary(snapshot: ScreenSnapshot): Uint8Array;
+/**
+ * Decode a buffer produced by {@link encodeScreenSnapshotBinary} back into a
+ * {@link ScreenSnapshot}. Throws loudly on an unknown version byte, truncated
+ * input, or any internal inconsistency — never returns a partial/normalized result.
+ */
+declare function decodeScreenSnapshotBinary(bytes: Uint8Array): ScreenSnapshot;
 //#endregion
-export { type CellColor, type ScreenCell, type SemanticZone, type SixelImage, type UnderlineStyle, type Screen as VtermScreen, type ScreenOptions as VtermScreenOptions, createScreen as createVtermScreen };
+export { type CellColor, type Color, type Cursor, type DirtyRegion, type ParserEvent, type ReadSignal, type ScreenCell, type ScreenSignals, type ScreenSnapshot, type ScreenSnapshot as VtermScreenSnapshot, type SemanticZone, type SerializeOptions, type SixelImage, type Size, type Snapshot, type TerminalModes, type TerminalOp, type UnderlineStyle, type Screen as VtermScreen, type ScreenAttrsSnapshot as VtermScreenAttrsSnapshot, type ScreenBufferSnapshot as VtermScreenBufferSnapshot, type ScreenColorStateSnapshot as VtermScreenColorStateSnapshot, type ScreenOptions as VtermScreenOptions, type ScreenParserState as VtermScreenParserState, createScreen as createVtermScreen, decodeScreenSnapshotBinary, encodeScreenSnapshotBinary, serializeSnapshot };