vterm.js 0.6.1 → 0.7.1

package/README.md

@@ -35,6 +35,8 @@ Part of the [vterm](https://github.com/beorn/vterm) monorepo.
 
 ## Install
 
+> Install from npm; a git install resolves the TypeScript source and runs only under Bun.
+
 ```bash
 npm install vterm.js
 ```
@@ -435,6 +437,67 @@ The **reactive** counterpart is `signals.damage$` (see [Signals](#signals--the-r
 
 **Use vterm.js** when you need everything — 100% coverage of the [terminfo.dev](https://terminfo.dev) feature matrix.
 
+## vterm.js and xterm.js
+
+[xterm.js](https://www.npmjs.com/package/@xterm/xterm) is the standard for putting a terminal on a web page — DOM, canvas, and WebGL renderers, a large addon ecosystem, and the terminal inside VS Code. When the job is rendering a terminal to a human, reach for xterm.js. We do: [Termless](https://termless.dev)'s own `@termless/web-player`, which plays back recorded terminal sessions in the browser, is built directly on `@xterm/xterm`.
+
+vterm.js is for the opposite case: nothing ever gets painted. It's headless-first — the terminal as a **readable data structure**, not a rendered surface. Zero dependencies, pure TypeScript, full VT/ECMA-48/xterm standards coverage, a binary snapshot codec for exact state capture, a reactive read plane (`screen.signals`), absolute-row scrollback addressing, and semantic-zone detection (OSC 133 / OSC 633 prompt/command/output). That combination is aimed at testing, session recording, audit trails, and AI-agent infrastructure — consumers that need to know exactly what a terminal contains without ever drawing it.
+
+Because vterm.js makes no display claims, it's held to a stricter standard instead: engine conformance, graded publicly and continuously in [Termless](https://termless.dev)'s differential conformance corpus against xterm.js, Ghostty, and neovim's libvterm. Current per-engine results and every known gap live in the ratchet ledger (`known-gaps.json`) — it's two-way: an unlisted failure fails the build, and a listed gap that starts passing fails too. Full results are public at [termless.dev/advanced/conformance-corpus](https://termless.dev/advanced/conformance-corpus).
+
+## Deliberate divergences
+
+A handful of behaviours where vterm.js knowingly differs from neovim's
+libvterm, the reference implementation the conformance corpus is mined from.
+Each was ruled deliberately rather than left as a gap, so **100% conformance
+for vterm.js means 126/128 plus these documented divergences** — not 128.
+
+Each entry names the _override word_ that would reverse the ruling. If you need
+the other behaviour, open an issue with that word and the reason; it is the
+argument, not the preference, that would move it.
+
+### Cursor follows reflow when a resize shrinks below it
+
+Shrinking the terminal past the cursor's column carries the cursor with its
+line through the rewrap. libvterm, xterm.js and vt100.js instead clamp it to
+the last column of the row it was on.
+
+Following the line is what a reflowing terminal does — the cursor stays with
+the text a user was typing, rather than jumping to wherever that text used to
+end. Clamping is the pre-reflow behaviour the other three inherit from a
+shared ancestry, and three engines agreeing about their own history is not an
+argument about which is correct. Both ends of our own record/replay path read
+vterm.js, so there is no internal disagreement to resolve.
+
+**Override word: `clamp`.**
+
+### RIS clears the scrollback
+
+A full reset (`ESC c`) discards scrollback along with the screen. libvterm
+preserves it, so history banked before a reset can still be scrolled back to —
+and can even be popped back onto the screen by a later resize.
+
+Every other engine in the corpus — xterm.js, Ghostty and vt100.js — clears on
+RIS, as does xterm itself. A reset that leaves history behind surprises the
+common case, where `reset` is reached for precisely to get a clean terminal.
+
+**Override word: `match-ris`.**
+
+### Related: the deferred-wrap cursor
+
+Not an excluded case, but the same family and worth knowing if you read the
+cursor. When a glyph fills the last column with autowrap on, the terminal owes
+a wrap it has not performed. vterm.js represents that as the cursor sitting at
+`col == cols` — one past the last column — as xterm.js and vt100.js do.
+libvterm and Ghostty instead keep the cursor _on_ the last column and carry a
+separate pending-wrap flag. The corpus normalizes this rather than excluding
+it, so those cases pass; consumers reading `cursor.col` should simply expect
+the `col == cols` form.
+
+These entries mirror the corpus-side table in the suite's own README and the
+machine-readable reasons in `known-gaps.json`. A new ruling lands in all three
+at once.
+
 ## See also
 
 - [vt100.js](../vt100/) — VT100-era emulator (smaller, focused)

package/dist/index.d.mts

@@ -77,6 +77,8 @@ interface ScreenCell {
   hidden: boolean;
   blink: boolean;
   wide: boolean;
+  /** DECSCA: a selective erase (DECSED/DECSEL) leaves this cell alone. */
+  protected: boolean;
   url: string | null;
 }
 interface ScreenOptions {
@@ -118,6 +120,8 @@ interface ScreenAttrsSnapshot {
   inverse: boolean;
   hidden: boolean;
   blink: boolean;
+  /** DECSCA — cells written under it resist selective erase. */
+  protected: boolean;
   url: string | null;
 }
 interface ScreenColorStateSnapshot {
@@ -164,6 +168,26 @@ interface Snapshot {
    * `restore()` treats missing as all-false (hard-wrapped).
    */
   scrollbackSoftWrapped: boolean[];
+  /**
+   * DEC line attributes (DECDWL/DECDHL), SPARSE: only rows that are not normal
+   * appear, as `[rowIndex, attr]` pairs — 1 double-width, 2 double-height top,
+   * 3 double-height bottom.
+   *
+   * Sparse and header-resident on purpose. Double-width lines are a banner
+   * feature that almost no session emits, so a dense array per grid would be
+   * thousands of zeros; and the binary grid sections have no skippable framing,
+   * so a new array THERE would desynchronise an older reader rather than be
+   * ignored by it.
+   *
+   * Absent in snapshots taken before this field existed — `restore()` treats
+   * missing as all-normal. **Readers older than this field render DWL/DHL lines
+   * single-width**: a visual downgrade, never corruption.
+   */
+  lineAttrs?: {
+    main: [number, number][];
+    alt: [number, number][];
+    scrollback: [number, number][];
+  };
   cursor: {
     x: number;
     y: number;
@@ -180,6 +204,10 @@ interface Snapshot {
     originMode: boolean;
     autoWrap: boolean;
     charsetG0: boolean;
+    /** True when DEC Special Graphics is designated as G1. Absent in older snapshots: ASCII. */
+    charsetG1?: boolean;
+    /** True when SO has invoked G1 into GL. Absent in older snapshots: SI/G0. */
+    activeG1?: boolean;
   };
   attrs: ScreenAttrsSnapshot;
   modes: {
@@ -193,6 +221,8 @@ interface Snapshot {
     focusTracking: boolean;
     origin: boolean;
     insert: boolean;
+    /** LNM — LF also returns the carriage. Absent in older snapshots. */
+    newLine: boolean;
     reverseVideo: boolean;
     syncOutput: boolean;
     kittyKeyboardFlags: number;
@@ -242,6 +272,10 @@ interface Snapshot {
   };
   unicode: {
     charsetG0: boolean;
+    /** True when DEC Special Graphics is designated as G1. Absent in older snapshots: ASCII. */
+    charsetG1?: boolean;
+    /** True when SO has invoked G1 into GL. Absent in older snapshots: SI/G0. */
+    activeG1?: boolean;
     lastChar: string;
     pendingRegionalIndicator: string | null;
     afterZWJ: boolean;
@@ -402,6 +436,8 @@ interface TerminalModes {
   focusTracking: boolean;
   originMode: boolean;
   insertMode: boolean;
+  /** LNM — LF also returns the carriage (ECMA-48 mode 20). */
+  newLineMode: boolean;
   reverseVideo: boolean;
   syncOutput: boolean;
   leftRightMargin: boolean;