@react-x11/components 0.1.0 → 0.2.0

package/src/terminal/vt/diff.ts

@@ -0,0 +1,467 @@
+// What changed on screen, derived by diffing the emulator's buffer against a
+// mirror of what the surface currently shows.
+//
+// The renderer deliberately never asks "what did that escape sequence touch?".
+// Escape-level damage is fragile — one CSI can move the whole screen, and a
+// palette change or a selection drag touches cells no sequence named — while
+// a signature compare over the viewport is a few thousand integer compares
+// (microseconds for a normal grid) and catches *everything*. It also makes
+// "eventually correct" structural rather than a discipline: skip as many
+// frames as you like, the next diff repairs the screen, because the mirror
+// describes pixels rather than intentions.
+//
+// Pure: structural emulator types in, plain arrays out. No X, no node, no
+// `@xterm/headless` import — so the whole model is asserted against synthetic
+// grids in `test/terminal-vt.test.ts`.
+import { resolveCell } from './colors.js';
+import type { CellState, Palette, ResolvedCell } from './colors.js';
+import type { XtermCell, XtermTerminal } from './xterm.js';
+
+/** A run of cells to redraw, in grid coordinates. */
+export interface DirtySpan {
+  row: number;
+  col: number;
+  count: number;
+}
+
+/** The band the scroll fast path moves, in rows. */
+export interface RowCopy {
+  srcRow: number;
+  dstRow: number;
+  count: number;
+}
+
+export interface DiffResult {
+  /** Issued before anything is drawn, or null when nothing survived. */
+  copy: RowCopy | null;
+  spans: DirtySpan[];
+  /** Geometry or buffer changed under us: everything was marked dirty. */
+  full: boolean;
+}
+
+/**
+ * One frame's worth of resolved cells.
+ *
+ * Parallel typed arrays rather than objects: a 240×67 grid is 16k cells, and
+ * the whole point of the diff is that touching all of them costs less than a
+ * millisecond. `chars` is the one string array, and it is read only for cells
+ * the diff already decided are dirty.
+ */
+export interface GridSnapshot {
+  cols: number;
+  rows: number;
+  chars: string[];
+  /** 1 normally, 2 for a wide glyph, 0 for the cell it covers. */
+  width: Uint8Array;
+  fg: Int32Array;
+  bg: Int32Array;
+  /** `DECO_*` and `VARIANT_*` from `./colors.ts`. */
+  flags: Uint16Array;
+  sig: Uint32Array;
+  rowSig: Uint32Array;
+  /** Buffer-absolute index of the row at the top of the viewport. */
+  absTop: number;
+  alt: boolean;
+}
+
+export function createSnapshot(cols: number, rows: number): GridSnapshot {
+  const n = Math.max(1, cols * rows);
+  return {
+    cols,
+    rows,
+    chars: new Array<string>(n).fill(' '),
+    width: new Uint8Array(n).fill(1),
+    fg: new Int32Array(n),
+    bg: new Int32Array(n),
+    flags: new Uint16Array(n),
+    sig: new Uint32Array(n),
+    rowSig: new Uint32Array(Math.max(1, rows)),
+    absTop: 0,
+    alt: false,
+  };
+}
+
+/** A selection, in buffer-absolute lines so scrollback keeps it. */
+export interface SelectionRange {
+  startLine: number;
+  startCol: number;
+  endLine: number;
+  endCol: number;
+}
+
+/** Where the cursor is and what it looks like this frame. */
+export interface CursorState {
+  col: number;
+  /** Viewport row, or -1 when the cursor is scrolled out of view. */
+  row: number;
+  shape: 'block' | 'underline' | 'bar' | 'hollow' | 'none';
+}
+
+export interface ReadOptions {
+  palette: Palette;
+  selection: SelectionRange | null;
+  cursor: CursorState;
+  brightBold: boolean;
+}
+
+/** Whether an absolute line/column is inside the selection. */
+export function inSelection(
+  selection: SelectionRange | null,
+  line: number,
+  col: number,
+): boolean {
+  if (!selection) return false;
+  const { startLine, startCol, endLine, endCol } = selection;
+  if (line < startLine || line > endLine) return false;
+  if (line === startLine && col < startCol) return false;
+  if (line === endLine && col >= endCol) return false;
+  return true;
+}
+
+/** Selection endpoints, ordered — a drag runs in either direction. */
+export function orderSelection(
+  anchorLine: number,
+  anchorCol: number,
+  headLine: number,
+  headCol: number,
+): SelectionRange {
+  const backwards =
+    headLine < anchorLine || (headLine === anchorLine && headCol < anchorCol);
+  return backwards
+    ? {
+        startLine: headLine,
+        startCol: headCol,
+        endLine: anchorLine,
+        endCol: anchorCol,
+      }
+    : {
+        startLine: anchorLine,
+        startCol: anchorCol,
+        endLine: headLine,
+        endCol: headCol,
+      };
+}
+
+/** FNV-1a, 32 bits. Fast, well-mixed, and the arithmetic stays in int32. */
+function mixIn(hash: number, value: number): number {
+  let h = (hash ^ (value & 0xffff)) >>> 0;
+  h = Math.imul(h, 0x01000193) >>> 0;
+  h = (h ^ ((value >>> 16) & 0xffff)) >>> 0;
+  return Math.imul(h, 0x01000193) >>> 0;
+}
+
+const FNV_OFFSET = 0x811c9dc5;
+
+/** Distinct numbers rather than the shape names: two of them start with the
+ *  same letter, and a signature that cannot tell a bar from a block is a
+ *  cursor that does not repaint when the style prop changes. */
+const CURSOR_SHAPE_ID: Record<CursorState['shape'], number> = {
+  none: 0,
+  block: 1,
+  underline: 2,
+  bar: 3,
+  hollow: 4,
+};
+
+const scratch: ResolvedCell = { fg: 0, bg: 0, flags: 0 };
+const cellState: CellState = {
+  selected: false,
+  cursor: 'none',
+  brightBold: true,
+};
+
+/**
+ * Read the viewport into `out`, resolving every cell to its two paint colours
+ * and its signature.
+ *
+ * The signature is where selection, cursor position, cursor phase and the
+ * palette generation enter the model: they are inputs to the hash, so a
+ * selection drag or a theme flip repaints exactly the cells whose *pixels*
+ * differ, through the same one mechanism as a program writing text. There is
+ * no second damage path anywhere in this component.
+ */
+export function readViewport(
+  term: XtermTerminal,
+  out: GridSnapshot,
+  options: ReadOptions,
+  work?: XtermCell,
+): GridSnapshot {
+  const buffer = term.buffer.active;
+  const { cols, rows } = out;
+  const cell = work ?? buffer.getNullCell();
+  const { palette, selection, cursor } = options;
+  cellState.brightBold = options.brightBold;
+
+  out.absTop = buffer.viewportY;
+  out.alt = buffer.type === 'alternate';
+
+  for (let row = 0; row < rows; row++) {
+    const line = buffer.getLine(buffer.viewportY + row);
+    const absLine = buffer.viewportY + row;
+    // The row hash mixes only its cells. Nothing extra — an input that is
+    // *not* visible in a cell (a palette counter, a frame number) would make
+    // every row differ every frame, and the scroll detector below reads these
+    // signatures to find the band that survived a shift.
+    let rowHash = FNV_OFFSET;
+    const base = row * cols;
+    for (let col = 0; col < cols; col++) {
+      const index = base + col;
+      const got = line?.getCell(col, cell);
+      let chars = ' ';
+      let width = 1;
+      if (got) {
+        chars = got.getChars() || ' ';
+        width = got.getWidth();
+      }
+      cellState.selected = inSelection(selection, absLine, col);
+      cellState.cursor =
+        cursor.row === row && cursor.col === col ? cursor.shape : 'none';
+      if (got) {
+        resolveCell(got, palette, cellState, scratch);
+      } else {
+        // Past the end of a short line, or a line the buffer has trimmed:
+        // blank in the default colours, which is what the screen shows.
+        scratch.fg = palette.foreground;
+        scratch.bg = palette.background;
+        scratch.flags = 0;
+        if (cellState.selected) {
+          scratch.bg = palette.selectionBackground;
+          scratch.fg = palette.selectionForeground;
+        }
+        if (cellState.cursor === 'block') {
+          scratch.bg = palette.cursor;
+          scratch.fg = palette.cursorText;
+        }
+      }
+
+      out.chars[index] = chars;
+      out.width[index] = width;
+      out.fg[index] = scratch.fg;
+      out.bg[index] = scratch.bg;
+      out.flags[index] = scratch.flags;
+
+      let hash = mixIn(FNV_OFFSET, scratch.fg);
+      hash = mixIn(hash, scratch.bg);
+      hash = mixIn(hash, scratch.flags | (width << 8));
+      for (let i = 0; i < chars.length; i++) {
+        hash = mixIn(hash, chars.charCodeAt(i));
+      }
+      // The cursor shape is not a colour, so it has to enter the signature on
+      // its own — a bar becoming an underline changes pixels and nothing else.
+      if (cellState.cursor !== 'none') {
+        hash = mixIn(hash, CURSOR_SHAPE_ID[cellState.cursor] << 24);
+      }
+      out.sig[index] = hash;
+      rowHash = mixIn(rowHash, hash);
+    }
+    out.rowSig[row] = rowHash;
+  }
+  return out;
+}
+
+/**
+ * What the surface currently shows, as signatures.
+ *
+ * Only hashes: the mirror never holds text or colours, because the only
+ * question it answers is "does this cell still look like what I drew".
+ */
+export class Mirror {
+  cols = 0;
+  rows = 0;
+  absTop = 0;
+  alt = false;
+  /** No frame has been drawn yet, so nothing on the surface is trustworthy. */
+  private _valid = false;
+  private _sig = new Uint32Array(0);
+  private _rowSig = new Uint32Array(0);
+  private _force = new Uint8Array(0);
+
+  /** Forget everything: a resize, a font change, a renderer swap. */
+  invalidate(): void {
+    this._valid = false;
+  }
+
+  resize(cols: number, rows: number): void {
+    if (cols === this.cols && rows === this.rows) return;
+    this.cols = cols;
+    this.rows = rows;
+    this._sig = new Uint32Array(Math.max(1, cols * rows));
+    this._rowSig = new Uint32Array(Math.max(1, rows));
+    this._force = new Uint8Array(Math.max(1, rows));
+    this._valid = false;
+  }
+
+  /**
+   * Diff a snapshot against the mirror and adopt it.
+   *
+   * The mirror is updated to describe what the caller is *about* to draw, so
+   * a caller that does not draw the result has to `invalidate()`.
+   */
+  diff(snapshot: GridSnapshot): DiffResult {
+    const { cols, rows } = snapshot;
+    if (cols !== this.cols || rows !== this.rows) this.resize(cols, rows);
+
+    const spans: DirtySpan[] = [];
+    const full =
+      !this._valid || snapshot.alt !== this.alt || cols === 0 || rows === 0;
+
+    let copy: RowCopy | null = null;
+    this._force.fill(full ? 1 : 0);
+
+    if (!full) {
+      const shift = detectShift(this, snapshot);
+      if (shift !== 0) {
+        copy = shiftMirror(this, shift, cols, rows);
+      }
+    }
+
+    for (let row = 0; row < rows; row++) {
+      const base = row * cols;
+      if (!this._force[row] && this._rowSig[row] === snapshot.rowSig[row]) {
+        continue;
+      }
+      this._rowSig[row] = snapshot.rowSig[row];
+      if (this._force[row]) {
+        // Nothing is known about this row's pixels — a fresh mirror, or the
+        // strip a scroll exposed. One span, no per-cell comparison.
+        for (let col = 0; col < cols; col++) {
+          this._sig[base + col] = snapshot.sig[base + col];
+        }
+        if (cols > 0) spans.push({ row, col: 0, count: cols });
+        continue;
+      }
+      // Collect runs of changed cells, bridging gaps of up to two unchanged
+      // cells: three draw calls for `a_b_c` cost more than one for `a_b_c`.
+      let start = -1;
+      let clean = 0;
+      for (let col = 0; col < cols; col++) {
+        const index = base + col;
+        const changed = this._sig[index] !== snapshot.sig[index];
+        if (changed) {
+          this._sig[index] = snapshot.sig[index];
+          if (start < 0) start = col;
+          clean = 0;
+        } else if (start >= 0) {
+          clean++;
+          if (clean > 2) {
+            spans.push({ row, col: start, count: col - clean - start + 1 });
+            start = -1;
+            clean = 0;
+          }
+        }
+      }
+      if (start >= 0)
+        spans.push({ row, col: start, count: cols - clean - start });
+    }
+
+    this.absTop = snapshot.absTop;
+    this.alt = snapshot.alt;
+    this._valid = true;
+    return { copy, spans, full };
+  }
+
+  /** For the shift search and the row shuffle — not part of the contract. */
+  rowSignature(row: number): number {
+    return this._rowSig[row];
+  }
+
+  /** @internal */
+  _internals(): {
+    sig: Uint32Array;
+    rowSig: Uint32Array;
+    force: Uint8Array;
+  } {
+    return { sig: this._sig, rowSig: this._rowSig, force: this._force };
+  }
+}
+
+/**
+ * How far the screen moved, in rows. Positive means content moved *up* — the
+ * shell scrolled, or the user paged down.
+ *
+ * The buffer's own `viewportY` is the first guess and is exact while the
+ * scrollback is still filling. Once it saturates, lines are trimmed off the
+ * top and `viewportY` stops moving although the screen very much does — so
+ * the fallback is a search over the mirror's row signatures.
+ *
+ * A wrong guess cannot corrupt anything. The mirror is shifted by exactly the
+ * amount the pixels were, so any row that does not then match its snapshot
+ * signature is repainted; a bad guess costs one CopyArea and some redraw, and
+ * that is the whole exposure.
+ */
+function detectShift(mirror: Mirror, snapshot: GridSnapshot): number {
+  const { rows, cols } = snapshot;
+  if (rows < 2 || cols === 0) return 0;
+
+  let differing = 0;
+  for (let row = 0; row < rows; row++) {
+    if (mirror.rowSignature(row) !== snapshot.rowSig[row]) differing++;
+    if (differing > 2) break;
+  }
+  // Typing, a spinner, a cursor blink: nothing moved, and the search is the
+  // most expensive thing that would happen this frame if we let it run.
+  if (differing <= 2) return 0;
+
+  const hint = snapshot.absTop - mirror.absTop;
+  if (
+    hint !== 0 &&
+    Math.abs(hint) < rows &&
+    verifyShift(mirror, snapshot, hint)
+  ) {
+    return hint;
+  }
+  for (let shift = 1; shift < rows; shift++) {
+    if (mirror.rowSignature(shift) === snapshot.rowSig[0]) {
+      if (verifyShift(mirror, snapshot, shift)) return shift;
+    }
+    if (mirror.rowSignature(0) === snapshot.rowSig[shift]) {
+      if (verifyShift(mirror, snapshot, -shift)) return -shift;
+    }
+  }
+  return 0;
+}
+
+/** Does most of the band that would survive this shift actually match? */
+function verifyShift(
+  mirror: Mirror,
+  snapshot: GridSnapshot,
+  shift: number,
+): boolean {
+  const { rows } = snapshot;
+  const survivors = rows - Math.abs(shift);
+  if (survivors < 2) return false;
+  let matched = 0;
+  for (let i = 0; i < survivors; i++) {
+    const from = shift > 0 ? i + shift : i;
+    const to = shift > 0 ? i : i - shift;
+    if (mirror.rowSignature(from) === snapshot.rowSig[to]) matched++;
+  }
+  // Three quarters: a partial scroll region (vim inserting a line inside a
+  // window) still moves most of the band, and the rows it does not move are
+  // repainted by the ordinary diff below.
+  return matched >= Math.max(2, Math.ceil(survivors * 0.75));
+}
+
+/** Move the mirror's rows the way the pixels are about to move. */
+function shiftMirror(
+  mirror: Mirror,
+  shift: number,
+  cols: number,
+  rows: number,
+): RowCopy {
+  const { sig, rowSig, force } = mirror._internals();
+  const count = rows - Math.abs(shift);
+  if (shift > 0) {
+    sig.copyWithin(0, shift * cols, rows * cols);
+    rowSig.copyWithin(0, shift, rows);
+    for (let row = count; row < rows; row++) force[row] = 1;
+  } else {
+    const up = -shift;
+    sig.copyWithin(up * cols, 0, count * cols);
+    rowSig.copyWithin(up, 0, count);
+    for (let row = 0; row < up; row++) force[row] = 1;
+  }
+  return shift > 0
+    ? { srcRow: shift, dstRow: 0, count }
+    : { srcRow: 0, dstRow: -shift, count };
+}

package/src/terminal/vt/fonts.ts

@@ -0,0 +1,233 @@
+// Cell metrics and glyphs.
+//
+// A terminal bypasses text shaping by construction: the grid decides where
+// every glyph goes, so there are no ligatures, no kerning and no cluster
+// positioning to compute — which is exactly what makes the fast path fast.
+// ntk's public seam for that is `Font.glyphIdFor(cp)` plus the documented
+// `drawGlyphs` run contract (ntk#254): a cmap lookup and a hand-built run,
+// no shaping anywhere.
+//
+// The one case that does need shaping is a cluster — a base letter with
+// combining marks, a text-presentation emoji with a variation selector — and
+// `Font.shape()` handles those one cluster at a time, cached, on a path a
+// normal screen never touches.
+
+/** ntk's `Font`, as this module uses it. */
+export interface NtkFont {
+  metrics(size: number): {
+    ascent: number;
+    descent: number;
+    lineGap: number;
+    lineHeight: number;
+  };
+  advanceOf(glyphId: number, size: number): number;
+  hasGlyph(codepoint: number): boolean;
+  /** ntk#254 — the lookup twin of `hasGlyph`, `null` when uncovered. */
+  glyphIdFor(codepoint: number): number | null;
+  shape(
+    text: string,
+    size: number,
+    opts?: Record<string, unknown>,
+  ): { glyphs: { id: number; ax: number; dx: number; dy: number }[] };
+}
+
+/** ntk's font manager, off `app.fonts`. */
+export interface NtkFonts {
+  match(
+    family: string,
+    opts?: { weight?: number | string; style?: string },
+  ): NtkFont;
+  fallbackFor(
+    codepoint: number,
+    family?: string,
+    opts?: { weight?: number | string; style?: string },
+  ): NtkFont | null;
+}
+
+/** One glyph run, in the shape `ctx.drawGlyphs` documents. */
+export interface GlyphRun {
+  font: NtkFont;
+  size: number;
+  glyphs: { id: number; ax: number; dx: number; dy: number }[];
+}
+
+export const VARIANTS = ['regular', 'bold', 'italic', 'boldItalic'] as const;
+export type Variant = (typeof VARIANTS)[number];
+
+export interface CellMetrics {
+  /** Integers, because the grid, the copy band and the fill rects are. */
+  cellWidth: number;
+  cellHeight: number;
+  /** Baseline offset from the top of the cell. */
+  baseline: number;
+  /** Where a single underline sits, from the top of the cell. */
+  underline: number;
+  /** Thickness of underline/strike/overline rules. */
+  ruleHeight: number;
+}
+
+/**
+ * The four faces, the cell box, and the glyph cache — everything that depends
+ * on the font and nothing that depends on the frame.
+ *
+ * Rebuilt when the family or the size changes; the node drops its mirror at
+ * the same time, because every cell's pixels moved.
+ */
+export class FontSet {
+  readonly family: string;
+  readonly size: number;
+  readonly metrics: CellMetrics;
+  private _fonts: NtkFonts;
+  private _faces = new Map<Variant, NtkFont | null>();
+  /** `variant \0 chars` → the run to stamp, or null for "nothing to draw". */
+  private _glyphs = new Map<string, GlyphRun | null>();
+
+  constructor(fonts: NtkFonts, family: string, size: number) {
+    this._fonts = fonts;
+    this.family = family;
+    this.size = size;
+
+    const regular = this.face('regular');
+    const m = regular?.metrics(size);
+    const ascent = m ? m.ascent : size * 0.8;
+    const descent = m ? m.descent : size * 0.2;
+    const lineHeight = m ? m.lineHeight : size * 1.2;
+    // The advance of a digit is the cell width: in a monospace face every
+    // glyph agrees, and in a face that is not monospace the digit is still
+    // the least surprising answer.
+    let advance = size * 0.6;
+    if (regular) {
+      const gid = regular.glyphIdFor(0x30);
+      if (gid !== null) advance = regular.advanceOf(gid, size) || advance;
+    }
+    const cellWidth = Math.max(1, Math.round(advance));
+    const cellHeight = Math.max(1, Math.ceil(lineHeight));
+    const baseline = Math.min(
+      cellHeight - 1,
+      Math.round(ascent + (cellHeight - ascent - descent) / 2),
+    );
+    this.metrics = {
+      cellWidth,
+      cellHeight,
+      baseline,
+      underline: Math.min(
+        cellHeight - 1,
+        baseline + Math.max(1, Math.round(size / 10)),
+      ),
+      ruleHeight: Math.max(1, Math.round(size / 14)),
+    };
+  }
+
+  /**
+   * One of the four faces. A family with no bold or no italic resolves to the
+   * regular one — ntk does not synthesise either, and a fake oblique is worse
+   * than an honest upright (overstrike emulation is a later, separate call).
+   */
+  face(variant: Variant): NtkFont | null {
+    const cached = this._faces.get(variant);
+    if (cached !== undefined) return cached;
+    let font: NtkFont | null = null;
+    try {
+      font = this._fonts.match(this.family, {
+        weight: variant === 'bold' || variant === 'boldItalic' ? 700 : 400,
+        style:
+          variant === 'italic' || variant === 'boldItalic'
+            ? 'italic'
+            : 'normal',
+      });
+    } catch {
+      // no fontconfig, no fonts on the box: the caller draws backgrounds and
+      // no glyphs rather than failing to paint at all
+      font = null;
+    }
+    this._faces.set(variant, font);
+    return font;
+  }
+
+  /**
+   * The run for one cell's characters, or null when there is nothing to draw.
+   *
+   * Cached per (variant, chars) — a screen of text is a few hundred distinct
+   * entries, and the cache is what keeps a full-screen redraw a matter of
+   * lookups rather than cmap searches.
+   */
+  run(chars: string, variant: Variant): GlyphRun | null {
+    if (!chars || chars === ' ') return null;
+    const key = `${variant}\u0000${chars}`;
+    const hit = this._glyphs.get(key);
+    if (hit !== undefined) return hit;
+    const run = this._build(chars, variant);
+    this._glyphs.set(key, run);
+    return run;
+  }
+
+  private _build(chars: string, variant: Variant): GlyphRun | null {
+    const font = this.face(variant);
+    if (!font) return null;
+    const first = chars.codePointAt(0);
+    if (first === undefined) return null;
+    const single = String.fromCodePoint(first).length === chars.length;
+
+    if (single) {
+      let face = font;
+      let gid = safeGlyphId(face, first);
+      if (gid === null) {
+        // Nothing in the terminal's own face covers it — a box-drawing
+        // character in a font that has none, a CJK glyph, an emoji. The
+        // fallback face is a different glyphset, so it becomes its own run;
+        // it still goes out in the same request as everything else.
+        const fallback = this._fallback(first, variant);
+        if (!fallback) return null;
+        face = fallback;
+        gid = safeGlyphId(face, first);
+        if (gid === null) return null;
+      }
+      return {
+        font: face,
+        size: this.size,
+        glyphs: [{ id: gid, ax: this.metrics.cellWidth, dx: 0, dy: 0 }],
+      };
+    }
+
+    // A cluster: shape it once and keep the result. Rare enough that the
+    // shaping cost never reaches a frame budget, and correct where a
+    // codepoint-at-a-time walk would stack the marks on top of each other.
+    try {
+      const shaped = font.shape(chars, this.size);
+      if (!shaped.glyphs.length) return null;
+      return { font, size: this.size, glyphs: shaped.glyphs };
+    } catch {
+      return null;
+    }
+  }
+
+  private _fallback(codepoint: number, variant: Variant): NtkFont | null {
+    try {
+      return this._fonts.fallbackFor(codepoint, this.family, {
+        weight: variant === 'bold' || variant === 'boldItalic' ? 700 : 400,
+        style:
+          variant === 'italic' || variant === 'boldItalic'
+            ? 'italic'
+            : 'normal',
+      });
+    } catch {
+      return null;
+    }
+  }
+}
+
+function safeGlyphId(font: NtkFont, codepoint: number): number | null {
+  try {
+    return font.glyphIdFor(codepoint);
+  } catch {
+    return null;
+  }
+}
+
+/** `VARIANT_*` bits from `./colors.ts` to one of the four faces. */
+export function variantOf(bold: boolean, italic: boolean): Variant {
+  if (bold && italic) return 'boldItalic';
+  if (bold) return 'bold';
+  if (italic) return 'italic';
+  return 'regular';
+}