@react-x11/components 0.3.0 → 0.5.0

package/src/terminal/vt/fonts.ts

@@ -11,17 +11,36 @@
 // 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.
+//
+// Not every backend's text engine has those seams. react-x11's Cocoa backend
+// up to 2.3.x answered `fonts.match()` with a face that has `metrics` and
+// `hasGlyph` and nothing else (it grew the rest in 2.4.0,
+// sidorares/react-x11#432), so everything here feature-detects
+// (`hasGlyphRuns`), and a `FontSet` over such an engine is a valid object
+// that builds no runs rather than a `TypeError` thrown from inside paint.
 
-/** 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;
+/** What every backend's face answers: metrics and coverage. */
+export interface EngineFont {
+  metrics(size: number): FontMetrics;
   hasGlyph(codepoint: number): boolean;
+}
+
+/**
+ * `metrics(size)` as the two engines report it. ntk gives `lineGap` and
+ * `lineHeight`; CoreText's name for the gap is `leading`, and it reports no
+ * line height at all — `lineHeightOf` reads whichever is there.
+ */
+export interface FontMetrics {
+  ascent: number;
+  descent: number;
+  lineGap?: number;
+  lineHeight?: number;
+  leading?: number;
+}
+
+/** ntk's `Font`: the glyph-run seams on top of the metrics (ntk#254). */
+export interface NtkFont extends EngineFont {
+  advanceOf(glyphId: number, size: number): number;
   /** ntk#254 — the lookup twin of `hasGlyph`, `null` when uncovered. */
   glyphIdFor(codepoint: number): number | null;
   shape(
@@ -31,17 +50,36 @@ export interface NtkFont {
   ): { glyphs: { id: number; ax: number; dx: number; dy: number }[] };
 }
 
-/** ntk's font manager, off `app.fonts`. */
+/**
+ * ntk's font manager, off `app.fonts` — or another engine's, which may
+ * answer plainer faces and have no `fallbackFor` at all.
+ */
 export interface NtkFonts {
   match(
     family: string,
     opts?: { weight?: number | string; style?: string },
-  ): NtkFont;
-  fallbackFor(
+  ): EngineFont;
+  fallbackFor?(
     codepoint: number,
     family?: string,
     opts?: { weight?: number | string; style?: string },
-  ): NtkFont | null;
+  ): EngineFont | null;
+}
+
+/**
+ * Whether a face can build glyph runs: `glyphIdFor` to find the glyph and
+ * `advanceOf` to measure it. A face without them still answers metrics and
+ * coverage, which is all react-x11's Cocoa backend offered before 2.4.0.
+ */
+export function hasGlyphRuns(
+  font: EngineFont | null | undefined,
+): font is NtkFont {
+  const f = font as Partial<NtkFont> | null | undefined;
+  return (
+    !!f &&
+    typeof f.glyphIdFor === 'function' &&
+    typeof f.advanceOf === 'function'
+  );
 }
 
 /** One glyph run, in the shape `ctx.drawGlyphs` documents. */
@@ -77,9 +115,20 @@ export class FontSet {
   readonly family: string;
   readonly size: number;
   readonly metrics: CellMetrics;
+  /**
+   * Whether this engine's faces can build glyph runs at all.
+   *
+   * `false` when `match()` answered a face with metrics and coverage but
+   * none of the glyph-run seams — react-x11's Cocoa backend before 2.4.0
+   * (sidorares/react-x11#432). `run()` is then always null, and the node
+   * paints nothing rather than half a terminal. A box with no fonts at all
+   * is a different state and stays `true`: the engine is ntk's, it just
+   * matched nothing, and backgrounds still draw.
+   */
+  readonly glyphRuns: boolean;
   private _fonts: NtkFonts;
-  private _faces = new Map<Variant, NtkFont | null>();
-  /** `variant \0 chars` → the run to stamp, or null for "nothing to draw". */
+  private _faces = new Map<Variant, EngineFont | null>();
+  /** `variant: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) {
@@ -88,17 +137,18 @@ export class FontSet {
     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;
+    this.glyphRuns = regular === null || hasGlyphRuns(regular);
+    const m = safeMetrics(regular, size);
+    const ascent = finite(m?.ascent, size * 0.8);
+    const descent = finite(m?.descent, size * 0.2);
+    const lineHeight = m ? lineHeightOf(m, ascent, descent) : 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;
+    if (hasGlyphRuns(regular)) {
+      const gid = safeGlyphId(regular, 0x30);
+      if (gid !== null) advance = safeAdvance(regular, gid, size) || advance;
     }
     const cellWidth = Math.max(1, Math.round(advance));
     const cellHeight = Math.max(1, Math.ceil(lineHeight));
@@ -123,18 +173,19 @@ export class FontSet {
    * 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 {
+  face(variant: Variant): EngineFont | null {
     const cached = this._faces.get(variant);
     if (cached !== undefined) return cached;
-    let font: NtkFont | null = null;
+    let font: EngineFont | null = null;
     try {
-      font = this._fonts.match(this.family, {
-        weight: variant === 'bold' || variant === 'boldItalic' ? 700 : 400,
-        style:
-          variant === 'italic' || variant === 'boldItalic'
-            ? 'italic'
-            : 'normal',
-      });
+      font =
+        this._fonts.match(this.family, {
+          weight: variant === 'bold' || variant === 'boldItalic' ? 700 : 400,
+          style:
+            variant === 'italic' || variant === 'boldItalic'
+              ? 'italic'
+              : 'normal',
+        }) ?? null;
     } catch {
       // no fontconfig, no fonts on the box: the caller draws backgrounds and
       // no glyphs rather than failing to paint at all
@@ -152,8 +203,10 @@ export class FontSet {
    * lookups rather than cmap searches.
    */
   run(chars: string, variant: Variant): GlyphRun | null {
-    if (!chars || chars === ' ') return null;
-    const key = `${variant}\u0000${chars}`;
+    if (!this.glyphRuns || !chars || chars === ' ') return null;
+    // The variant never contains a colon, so the key cannot be ambiguous
+    // whatever the cell holds.
+    const key = `${variant}:${chars}`;
     const hit = this._glyphs.get(key);
     if (hit !== undefined) return hit;
     const run = this._build(chars, variant);
@@ -163,7 +216,7 @@ export class FontSet {
 
   private _build(chars: string, variant: Variant): GlyphRun | null {
     const font = this.face(variant);
-    if (!font) return null;
+    if (!hasGlyphRuns(font)) return null;
     const first = chars.codePointAt(0);
     if (first === undefined) return null;
     const single = String.fromCodePoint(first).length === chars.length;
@@ -192,6 +245,7 @@ export class FontSet {
     // 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.
+    if (typeof (font as Partial<NtkFont>).shape !== 'function') return null;
     try {
       const shaped = font.shape(chars, this.size);
       if (!shaped.glyphs.length) return null;
@@ -202,14 +256,17 @@ export class FontSet {
   }
 
   private _fallback(codepoint: number, variant: Variant): NtkFont | null {
+    const fonts = this._fonts;
+    if (typeof fonts.fallbackFor !== 'function') return null;
     try {
-      return this._fonts.fallbackFor(codepoint, this.family, {
+      const face = fonts.fallbackFor(codepoint, this.family, {
         weight: variant === 'bold' || variant === 'boldItalic' ? 700 : 400,
         style:
           variant === 'italic' || variant === 'boldItalic'
             ? 'italic'
             : 'normal',
       });
+      return hasGlyphRuns(face) ? face : null;
     } catch {
       return null;
     }
@@ -218,12 +275,47 @@ export class FontSet {
 
 function safeGlyphId(font: NtkFont, codepoint: number): number | null {
   try {
-    return font.glyphIdFor(codepoint);
+    const gid = font.glyphIdFor(codepoint);
+    return typeof gid === 'number' && Number.isInteger(gid) ? gid : null;
+  } catch {
+    return null;
+  }
+}
+
+function safeAdvance(font: NtkFont, glyphId: number, size: number): number {
+  try {
+    return finite(font.advanceOf(glyphId, size), 0);
+  } catch {
+    return 0;
+  }
+}
+
+function safeMetrics(
+  font: EngineFont | null,
+  size: number,
+): FontMetrics | null {
+  if (!font || typeof font.metrics !== 'function') return null;
+  try {
+    const m = font.metrics(size);
+    return m && typeof m === 'object' ? m : null;
   } catch {
     return null;
   }
 }
 
+/**
+ * ntk's `lineHeight` when it is there; otherwise ascent + descent + gap, with
+ * the gap under either engine's name.
+ */
+function lineHeightOf(m: FontMetrics, ascent: number, descent: number): number {
+  const gap = finite(m.lineGap, finite(m.leading, 0));
+  return finite(m.lineHeight, ascent + descent + gap);
+}
+
+function finite(n: number | undefined, fallback: number): number {
+  return typeof n === 'number' && Number.isFinite(n) ? n : fallback;
+}
+
 /** `VARIANT_*` bits from `./colors.ts` to one of the four faces. */
 export function variantOf(bold: boolean, italic: boolean): Variant {
   if (bold && italic) return 'boldItalic';

package/src/terminal/vt/index.ts

@@ -33,7 +33,7 @@ import type { EmbedStatus, ExitInfo } from '../../embed/index.js';
 import type { TerminalColors } from '../backends.js';
 import { ELEMENT, VtTermNode } from './node.js';
 import type { VtTermProps } from './node.js';
-import { PtyUnavailableError, nodePtyHost } from './pty.js';
+import { PtyUnavailableError, defaultPtyHost } from './pty.js';
 import type { PtyHost, PtySession } from './pty.js';
 import { startTimeout, stopTimeout } from '../../embed/timers.js';
 import type { TimerId } from '../../embed/timers.js';
@@ -45,6 +45,8 @@ export type { VtTermProps };
 export {
   PTY_MODULES,
   PtyUnavailableError,
+  bunPtyHost,
+  defaultPtyHost,
   defaultShell,
   nodePtyHost,
   ptyLoadError,
@@ -203,7 +205,7 @@ export function VtTerminal(props: VtTerminalProps): ReactElement {
         );
         return;
       }
-      const host = handlers.current.pty ?? nodePtyHost();
+      const host = handlers.current.pty ?? defaultPtyHost();
       if (!(await host.available())) {
         // The message separates "nothing installed" from "installed but it
         // would not load" — a native module built for another Node ABI looks

package/src/terminal/vt/node.ts

@@ -68,6 +68,31 @@ const PREFERRED_COLS = 80;
 const PREFERRED_ROWS = 24;
 /** Wheel notches to lines, the way every terminal counts them. */
 const WHEEL_LINES = 3;
+
+/**
+ * Said once per process: the engine behind `app.fonts` has no glyph-run
+ * seams, so this element paints nothing. `process` and `console` come off
+ * `globalThis` because `src/` compiles with `types: []` — see `warnVtOnly`
+ * in `../index.ts`.
+ */
+let warnedNoGlyphRuns = false;
+function warnNoGlyphRuns(): void {
+  if (warnedNoGlyphRuns) return;
+  warnedNoGlyphRuns = true;
+  const g = globalThis as {
+    process?: { env?: Record<string, string | undefined> };
+    console?: { warn(message: string): void };
+  };
+  if (g.process?.env?.NODE_ENV === 'production') return;
+  g.console?.warn(
+    '@react-x11/components: <Terminal backend="vt"> — the text engine behind ' +
+      'app.fonts has no glyph-run seams (glyphIdFor/advanceOf on a face, ' +
+      'drawGlyphs on the context), so the terminal paints nothing. ' +
+      "react-x11's Cocoa backend before 2.4.0 was the known case " +
+      '(sidorares/react-x11#432); every backend of react-x11 2.5.0 and ' +
+      'later has them, so check which engine app.fonts is.',
+  );
+}
 /** OSC 52 payloads bigger than this are a program misbehaving, not a copy. */
 const MAX_OSC52 = 1_000_000;
 /** What counts as part of a word for double-click selection. */
@@ -283,6 +308,42 @@ export class VtTermNode extends Node {
 
   // --- metrics and layout --------------------------------------------------
 
+  /**
+   * Device pixels per logical pixel — the display scale (core's
+   * `docs/scale.md`).
+   *
+   * Everything this node computes with is device pixels: `contentBox()`,
+   * `this.style.fontSize` (core multiplies a style length before handing it
+   * over) and so the cell metrics shaped from it, the paint context and the
+   * renderer's surface. Two things are not, and each is converted once where
+   * it enters: a synthetic event's `x`/`y` (`_devicePoint`), and the
+   * constants below that never pass through a style — `DEFAULT_SIZE` and the
+   * cell guesses `measureContent` makes before there is a font.
+   */
+  private get _scale(): number {
+    return this.scale > 0 ? this.scale : 1;
+  }
+
+  /**
+   * A pointer event in the grid's own pixels.
+   *
+   * The native X event carries the device position the synthetic `x`/`y`
+   * were divided from, so it is the exact answer where there is one — core's
+   * own drawn elements read it the same way — and `x * scale` is the answer
+   * for an event synthesized without one.
+   */
+  private _devicePoint(ev: { x: number; y: number; nativeEvent?: unknown }): {
+    x: number;
+    y: number;
+  } {
+    const native = ev.nativeEvent as { x?: unknown; y?: unknown } | null;
+    const s = this._scale;
+    return {
+      x: typeof native?.x === 'number' ? native.x : ev.x * s,
+      y: typeof native?.y === 'number' ? native.y : ev.y * s,
+    };
+  }
+
   /**
    * The font, off the **style** rather than off a prop of its own.
    *
@@ -291,25 +352,47 @@ export class VtTermNode extends Node {
    * reason: a terminal inheriting the font from the tree above it is what
    * makes `<box style={{ fontSize: 15 }}>` mean what it says. `<Terminal>`'s
    * `fontFamily`/`fontSize` props are folded into this element's style.
+   *
+   * The size answered is in device pixels — the unit the glyphs are shaped
+   * at. A `fontSize` from the style arrives already multiplied; the default
+   * is a logical 13 and is multiplied here, so a bare `<Terminal>` on a 2x
+   * panel is the size it is on a 1x one, sharper rather than smaller.
    */
   private _fontStyle(): { family: string; size: number } {
     const style = this.style as { fontFamily?: string; fontSize?: number };
     return {
       family: style.fontFamily ?? DEFAULT_FAMILY,
-      size: Number(style.fontSize ?? DEFAULT_SIZE),
+      size: Number(style.fontSize ?? DEFAULT_SIZE * this._scale),
     };
   }
 
+  /**
+   * The faces for the current family and size, or null when there is no
+   * engine to build them from.
+   *
+   * Null is cached per font key when the engine answered but cannot build
+   * glyph runs — an `app.fonts` that is not ntk's and has not grown its
+   * seams, which react-x11's Cocoa backend was before 2.4.0
+   * (sidorares/react-x11#432) — so the probe runs once, not on every
+   * measure and paint. A box with no `app.fonts` at all (the mock
+   * backend) is not cached: it never had an engine to ask.
+   */
   private _fontSet(): FontSet | null {
     const { family, size } = this._fontStyle();
     const key = `${family}|${size}`;
-    if (this._fonts && key === this._fontKey) return this._fonts;
+    if (key === this._fontKey) return this._fonts;
     const fonts = (this.app as { fonts?: NtkFonts } | null | undefined)?.fonts;
     if (!fonts) return null;
+    const set = new FontSet(fonts, family, size);
     this._fontKey = key;
-    this._fonts = new FontSet(fonts, family, size);
     this._mirror.invalidate();
-    return this._fonts;
+    if (!set.glyphRuns) {
+      warnNoGlyphRuns();
+      this._fonts = null;
+      return null;
+    }
+    this._fonts = set;
+    return set;
   }
 
   /**
@@ -320,8 +403,11 @@ export class VtTermNode extends Node {
    */
   override measureContent({ width, height }: MeasureConstraints): MeasuredSize {
     const fonts = this._fontSet();
-    const cellWidth = fonts?.metrics.cellWidth ?? DEFAULT_SIZE * 0.6;
-    const cellHeight = fonts?.metrics.cellHeight ?? DEFAULT_SIZE * 1.2;
+    // The constraints and the answer are device pixels, like the metrics;
+    // the guesses made without a font (the mock backend) are scaled to match.
+    const s = this._scale;
+    const cellWidth = fonts?.metrics.cellWidth ?? DEFAULT_SIZE * 0.6 * s;
+    const cellHeight = fonts?.metrics.cellHeight ?? DEFAULT_SIZE * 1.2 * s;
     return {
       width: Math.min(PREFERRED_COLS * cellWidth, width),
       height: Math.min(PREFERRED_ROWS * cellHeight, height),
@@ -763,13 +849,18 @@ export class VtTermNode extends Node {
 
   // --- input: pointer ------------------------------------------------------
 
-  private _cellAt(ev: { x: number; y: number }): Grid {
+  /** The cell under a pointer event. `contentBox()` and the cell metrics are
+   *  device pixels, so the event is read in the same unit — a synthetic
+   *  `x`/`y` is logical, and comparing it directly put a 2x click on the
+   *  cell half as far from the corner as the pointer. */
+  private _cellAt(ev: { x: number; y: number; nativeEvent?: unknown }): Grid {
     const fonts = this._fontSet();
     const box = this.contentBox();
     const cellWidth = fonts?.metrics.cellWidth ?? 1;
     const cellHeight = fonts?.metrics.cellHeight ?? 1;
-    const col = Math.floor((ev.x - box.x) / cellWidth);
-    const row = Math.floor((ev.y - box.y) / cellHeight);
+    const p = this._devicePoint(ev);
+    const col = Math.floor((p.x - box.x) / cellWidth);
+    const row = Math.floor((p.y - box.y) / cellHeight);
     return {
       col: Math.max(0, Math.min(this._cols - 1, col)),
       row: Math.max(0, Math.min(this._rows - 1, row)),
@@ -875,10 +966,12 @@ export class VtTermNode extends Node {
       }
       return;
     }
-    // Dragging past an edge scrolls the scrollback under the pointer.
+    // Dragging past an edge scrolls the scrollback under the pointer. The
+    // box is device pixels; so is the point compared with it.
     const box = this.contentBox();
-    if (ev.y < box.y) term.scrollLines(-1);
-    else if (ev.y > box.y + box.height) term.scrollLines(1);
+    const { y } = this._devicePoint(ev);
+    if (y < box.y) term.scrollLines(-1);
+    else if (y > box.y + box.height) term.scrollLines(1);
     this._head = { line: this._absLine(row), col };
     this._updateSelection();
   }