@react-x11/components 0.8.0 → 0.10.0

package/src/embed/client.ts

@@ -12,8 +12,12 @@
 // `onReady` — because core's `<foreign>` already owns the protocol
 // (react-x11#269, ntk#246): the reparent, the save set, `_XEMBED_INFO`, the
 // synthetic ConfigureNotify, and handing the client back on unmount without
-// ever destroying it.
+// ever destroying it. The one thing asked of the connection directly is
+// whether it has that protocol at all (`canHostXEmbed`), because on a backend
+// that does not, `onReady` is no evidence either way: the Cocoa backend's
+// `<foreign>` still calls it, with `windowId: undefined`.
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useApp } from 'react-x11';
 
 import { nodeProcessHost } from './host.js';
 import type { ExitInfo, ProcessHost, SpawnedProcess } from './host.js';
@@ -25,7 +29,9 @@ import type { ExitInfo, ProcessHost, SpawnedProcess } from './host.js';
  * with no terminal emulator installed, or no mpv, is an ordinary machine.
  * Both components render their `fallback` on it, the way
  * `useDesktopCalendarEvents` reports "no bus, no ical.js" rather than
- * throwing.
+ * throwing. So is an app on a react-x11 backend that cannot embed another
+ * program's window at all — the native macOS one — and `error` says which of
+ * the two it is: a `BackendUnavailableError` or an `EmbedUnsupportedError`.
  */
 export type EmbedStatus =
   'idle' | 'starting' | 'running' | 'exited' | 'unavailable';
@@ -51,6 +57,65 @@ export class BackendUnavailableError extends Error {
   }
 }
 
+/**
+ * This app cannot host another program's window at all.
+ *
+ * Embedding is XEmbed, and XEmbed is X protocol — a reparent into a
+ * container, the save set, ClientMessages — which only react-x11's X11
+ * backend has. The native macOS backend has no cross-process window
+ * embedding (react-x11 `docs/macos.md`, "What this is, and is not"), so there
+ * is no window to hand a program and nothing to spawn.
+ *
+ * `useEmbeddedClient` reports it as `status: 'unavailable'`, the status a
+ * `BackendUnavailableError` gets, and for the same reason: it is an ordinary
+ * state of a healthy app, and the component renders its `fallback`. The class
+ * is what tells the two apart, because "install xterm" is the wrong advice
+ * here.
+ */
+export class EmbedUnsupportedError extends Error {
+  constructor() {
+    super(
+      '@react-x11/components: this react-x11 backend cannot embed another ' +
+        "program's window — XEmbed needs the X11 backend, and the native " +
+        'macOS one has no cross-process window embedding at all. Pass ' +
+        '`fallback` to render something else.',
+    );
+    this.name = 'EmbedUnsupportedError';
+  }
+}
+
+/** The slice of the app `canHostXEmbed` reads. `useApp()` is the escape
+ *  hatch, so the shape is written out rather than imported — the call
+ *  `../tray-host/manager.ts` makes for the slice it needs. */
+interface XEmbedHostApp {
+  X?: { SetSelectionOwner?: unknown; ReparentWindow?: unknown } | null;
+}
+
+/**
+ * Can this app host another program's window?
+ *
+ * Asked of the connection, because `<foreign>` cannot be the one to say: on
+ * react-x11's Cocoa backend it still calls `onReady`, with an undefined
+ * `windowId`, and on the headless mock mounting one throws from the commit.
+ * The test is `<TrayHost>`'s — its
+ * manager reports `'unavailable'` when `app.X` has no `SetSelectionOwner`,
+ * which is what core's Cocoa `X` lacks (react-x11 `src/cocoa/app.js`: a stub
+ * carrying only the few requests core makes there) and what the headless
+ * mock's `X` lacks too. `ReparentWindow` is asked as well, because it is the
+ * request an embed is actually made of.
+ *
+ * Takes the app rather than calling `useApp()`, so it can be asked off the
+ * render path — of `createRoot()`'s result, before there is a tree.
+ */
+export function canHostXEmbed(app: unknown): boolean {
+  const X = (app as XEmbedHostApp | null | undefined)?.X;
+  return (
+    !!X &&
+    typeof X.SetSelectionOwner === 'function' &&
+    typeof X.ReparentWindow === 'function'
+  );
+}
+
 /** What to run, and what to do with it once it is running. */
 export interface LaunchPlan {
   /** Absolute path or a name on `PATH`. */
@@ -101,13 +166,15 @@ export interface UseEmbeddedClientOptions {
   stopSignal?: string;
   onStart?: (info: { process: SpawnedProcess; backend?: string }) => void;
   onExit?: (info: ExitInfo) => void;
-  /** Spawn failures and missing backends alike. */
+  /** Spawn failures, missing backends, and an app that cannot host an
+   *  embedded window at all (`EmbedUnsupportedError`). */
   onError?: (err: Error) => void;
 }
 
 export interface EmbeddedClient {
   status: EmbedStatus;
-  /** The last failure, including a `BackendUnavailableError`. */
+  /** The last failure, including a `BackendUnavailableError` or an
+   *  `EmbedUnsupportedError`. */
   error: Error | null;
   pid: number | null;
   /** The container window, once `<foreign>` has one. */
@@ -134,12 +201,21 @@ export interface EmbeddedClient {
  * element's props — style, focus, the `onEmbedded`/`onClientGone` handlers a
  * component may want to compose with — belong to the component, not to the
  * lifecycle.
+ *
+ * **On an app that cannot host XEmbed** (`canHostXEmbed` is false — the
+ * native macOS backend), `status` is `'unavailable'` from the first render,
+ * `error` is an `EmbedUnsupportedError`, and nothing is probed or spawned.
+ * The caller should render no `<foreign>` there either: it has no socket to
+ * be.
  */
 export function useEmbeddedClient(
   options: UseEmbeddedClientOptions,
 ): EmbeddedClient {
   const { plan, enabled = true, stopSignal = 'SIGTERM' } = options;
   const host = useMemo(() => options.host ?? nodeProcessHost(), [options.host]);
+  // Asked every render: two property reads, and an app does not change
+  // backend under a mounted tree.
+  const embeddable = canHostXEmbed(useApp());
 
   const [windowId, setWindowId] = useState<number | null>(null);
   const [status, setStatus] = useState<EmbedStatus>('idle');
@@ -158,6 +234,24 @@ export function useEmbeddedClient(
   const handlers = useRef(options);
   handlers.current = options;
 
+  // No XEmbed on this connection means no window for a program to draw into,
+  // whatever `<foreign>` reports: the Cocoa backend's calls `onReady` with an
+  // undefined `windowId`, which slipped past a `windowId === null` guard and
+  // spawned `xterm -into undefined`. So the app decides, and the lifecycle
+  // below starts nothing without it. Decided while rendering rather than in
+  // an effect, so the first commit can already be the `fallback`, and
+  // reported from an effect keyed on the error itself, so `onError` hears it
+  // once rather than once per plan. `enabled` false still means "hold off": a
+  // pane nobody can see yet reports nothing.
+  const unsupported = enabled && !embeddable;
+  const unsupportedError = useMemo(
+    () => (unsupported ? new EmbedUnsupportedError() : null),
+    [unsupported],
+  );
+  useEffect(() => {
+    if (unsupportedError) handlers.current.onError?.(unsupportedError);
+  }, [unsupportedError]);
+
   const handleReady = useCallback((info: { windowId: number }) => {
     setWindowId(info.windowId);
   }, []);
@@ -170,7 +264,7 @@ export function useEmbeddedClient(
   }, []);
 
   useEffect(() => {
-    if (!enabled || windowId === null) {
+    if (!enabled || !embeddable || windowId === null) {
       setStatus('idle');
       return undefined;
     }
@@ -271,11 +365,11 @@ export function useEmbeddedClient(
       void planned?.dispose?.();
     };
     // `plan` is the restart signal — see the note on the option.
-  }, [enabled, windowId, plan, host, stopSignal, generation]);
+  }, [enabled, embeddable, windowId, plan, host, stopSignal, generation]);
 
   return {
-    status,
-    error,
+    status: unsupported ? 'unavailable' : status,
+    error: unsupportedError ?? error,
     pid,
     windowId,
     backend,

package/src/embed/index.ts

@@ -10,6 +10,8 @@
 // other `-into WID` program should not have to copy this file to exist.
 export {
   BackendUnavailableError,
+  EmbedUnsupportedError,
+  canHostXEmbed,
   resolveBackend,
   useEmbeddedClient,
 } from './client.js';

package/src/flow/draw.ts

@@ -38,6 +38,8 @@ interface CanvasLike {
   lineDashOffset?: number;
   save(): void;
   restore(): void;
+  translate(x: number, y: number): void;
+  scale(x: number, y: number): void;
   beginPath(): void;
   closePath(): void;
   moveTo(x: number, y: number): void;
@@ -56,6 +58,17 @@ interface LayoutLike {
   width: number;
   height: number;
   draw(ctx: unknown, x: number, y: number): void;
+  /** The engine's own coverage of the layout, one byte a device pixel, with
+   *  `pad` round its box — where the engine answers it (react-x11#673). */
+  coverage?(options?: { pad?: number }): TextCoverage | null;
+}
+
+/** A layout's coverage: `width` × `height` bytes, the layout's origin at
+ *  (pad, pad). */
+export interface TextCoverage {
+  width: number;
+  height: number;
+  data: Uint8Array;
 }
 
 /** One shaped string, kept between frames. `width` and `height` are
@@ -99,6 +112,14 @@ export interface PainterOptions {
    * no amount of batching on the wire would have fixed.
    */
   cache: Map<string, CachedText>;
+  /**
+   * While a zoom gesture moves: a label may be drawn from a layout shaped
+   * at another size, scaled to the one asked for, rather than shaped again
+   * at every step. The pane sets it only where the context scales text
+   * with its transform (`scalesText`), and paints the exact sizes once the
+   * gesture rests.
+   */
+  approximateText?: boolean;
 }
 
 function isCanvas(ctx: unknown): ctx is CanvasLike {
@@ -111,6 +132,13 @@ function isCanvas(ctx: unknown): ctx is CanvasLike {
 /** Bound, so a pathological graph cannot turn the width cache into a leak. */
 const CACHE_LIMIT = 4000;
 
+/** The sizes each string has been shaped at, per cache — what a label drawn
+ *  mid-zoom looks for instead of shaping itself again (`approximateText`). */
+const shapedSizes = new WeakMap<
+  Map<string, CachedText>,
+  Map<string, number[]>
+>();
+
 /**
  * A logical value on the device grid.
  *
@@ -126,6 +154,20 @@ export function toDevice(value: number, scale: number): number {
   return Math.abs(out - whole) < 1e-6 ? whole : out;
 }
 
+/**
+ * `Math.round` for a place on the device grid, deaf to floating-point noise
+ * at a half. A pan moves the graph by whole device pixels, and its blit
+ * takes a shift within a hair of whole as whole (`toDevice`: the viewport
+ * `-66.4` panned 27 down is `-39.400000000000006`). A place worked out from
+ * the new viewport can then sit a hair below the half the old one sat on,
+ * or above it, and round the other way — a node or a label a pixel from
+ * where the copy put it. Nudged past any such hair, a half rounds up on
+ * both sides of the blit.
+ */
+export function snapToGrid(value: number): number {
+  return Math.round(value + 1e-4);
+}
+
 function fontStyle(
   opts: PainterOptions,
   options: TextOptions | undefined,
@@ -146,8 +188,11 @@ function fontStyle(
  * repaint — a node with no explicit size is measured when the graph changes,
  * which is also when a hit test has to know how big it is — so measuring
  * cannot live behind the painter the way drawing does.
+ *
+ * Exported for the GL renderer's label atlas (`./gl/text.ts`), which draws
+ * the layout it measured onto a staging surface of its own.
  */
-function shape(
+export function shape(
   opts: PainterOptions,
   text: string,
   options: TextOptions | undefined,
@@ -159,11 +204,16 @@ function shape(
   // The colour is part of the key: it is baked into the layout, so two
   // labels that differ only in ink are two shaped runs. The scale is not:
   // it is constant for the life of the pane that owns the cache.
-  const key = `${family}|${size}|${options?.weight ?? 400}|${options?.color ?? opts.color}|${text}`;
+  const base = `${family}|${options?.weight ?? 400}|${options?.color ?? opts.color}|${text}`;
+  const key = `${size}|${base}`;
   const hit = cache.get(key);
   if (hit) return hit;
   const layout = fonts.layout(text, fontStyle(opts, options));
-  if (cache.size >= CACHE_LIMIT) cache.clear();
+  let sizes = shapedSizes.get(cache);
+  if (cache.size >= CACHE_LIMIT) {
+    cache.clear();
+    sizes?.clear();
+  }
   const s = opts.scale;
   const entry = {
     width: layout.width / s,
@@ -171,22 +221,86 @@ function shape(
     layout,
   };
   cache.set(key, entry);
+  if (!sizes) shapedSizes.set(cache, (sizes = new Map()));
+  const shaped = sizes.get(base);
+  if (shaped) shaped.push(size);
+  else sizes.set(base, [size]);
   return entry;
 }
 
+/**
+ * The layout a label is drawn from, and the scale it is drawn at: its own
+ * size where it has one, and mid-zoom (`approximateText`) the size nearest
+ * it that was shaped already — the one the gesture started from, for every
+ * label on screen. Shaping is most of what a zoom step costs in text, and
+ * a step that re-shapes every label at a size the next step moves off was
+ * paying it for nothing.
+ */
+function shapeNear(
+  opts: PainterOptions,
+  text: string,
+  options: TextOptions | undefined,
+): { entry: CachedText; scale: number } | null {
+  if (opts.approximateText) {
+    const size = options?.size ?? 13;
+    const family = options?.family ?? opts.family;
+    const base = `${family}|${options?.weight ?? 400}|${options?.color ?? opts.color}|${text}`;
+    const exact = opts.cache.get(`${size}|${base}`);
+    if (exact) return { entry: exact, scale: 1 };
+    const shaped = shapedSizes.get(opts.cache)?.get(base);
+    if (shaped && shaped.length > 0) {
+      let best = shaped[0];
+      for (const at of shaped) {
+        if (Math.abs(Math.log(at / size)) < Math.abs(Math.log(best / size))) {
+          best = at;
+        }
+      }
+      const entry = opts.cache.get(`${best}|${base}`);
+      if (entry) return { entry, scale: size / best };
+    }
+  }
+  const entry = shape(opts, text, options);
+  return entry ? { entry, scale: 1 } : null;
+}
+
 export function measureText(
   opts: PainterOptions,
   text: string,
   options?: TextOptions,
 ): { width: number; height: number } {
   const size = options?.size ?? 13;
-  const entry = shape(opts, text, options);
-  if (!entry) {
+  const near = shapeNear(opts, text, options);
+  if (!near) {
     // No font stack to ask. An estimate keeps layout plausible rather than
     // collapsing every node to its own padding.
     return { width: text.length * size * 0.55, height: size * 1.3 };
   }
-  return { width: entry.width, height: entry.height };
+  const { entry, scale } = near;
+  return { width: entry.width * scale, height: entry.height * scale };
+}
+
+/**
+ * Cut a string to fit `max` logical pixels, with an ellipsis. Linear from
+ * the end rather than a binary search: labels that need it are short, and
+ * the widths it walks through are the ones the cache already holds.
+ *
+ * Both renderers call this, so a label cut on one is cut the same on the
+ * other — the GL one sets whatever this returns as a raster.
+ */
+export function fitText(
+  opts: PainterOptions,
+  text: string,
+  options: TextOptions | undefined,
+  max: number,
+): string {
+  if (measureText(opts, text, options).width <= max) return text;
+  let cut = text.length;
+  while (cut > 1) {
+    cut--;
+    const candidate = `${text.slice(0, cut).trimEnd()}…`;
+    if (measureText(opts, candidate, options).width <= max) return candidate;
+  }
+  return '…';
 }
 
 class Painter implements FlowPainter {
@@ -230,6 +344,14 @@ class Painter implements FlowPainter {
     const { ctx } = this;
     ctx.strokeStyle = options.stroke ?? this.opts.color;
     ctx.lineWidth = this.d(options.lineWidth ?? 1);
+    // Every stroke says how it joins and ends; `polyline` and `strokeRuns`
+    // then round both. A context keeps whatever the last stroke set, so a
+    // pass that drew an edge before a handle stroked the handle with round
+    // joins and caps, and one that reached no edge — a node's own box,
+    // repainted by itself — stroked it mitred and butt-ended, and the same
+    // ring came out two ways depending on what else the pass drew.
+    ctx.lineJoin = 'miter';
+    ctx.lineCap = 'butt';
     if (typeof ctx.setLineDash === 'function') {
       ctx.setLineDash(options.dash ? options.dash.map((v) => this.d(v)) : []);
       if ('lineDashOffset' in ctx) {
@@ -321,6 +443,10 @@ class Painter implements FlowPainter {
     const { ctx } = this;
     ctx.beginPath();
     ctx.arc(this.d(x), this.d(y), this.d(r), 0, Math.PI * 2);
+    // Closed, so the ring is one loop with a join where it started: open,
+    // its two ends meet edge to edge, and a stroke with butt ends shows a
+    // hairline where they touch.
+    ctx.closePath();
     if (options.fill) {
       ctx.fillStyle = options.fill;
       ctx.fill();
@@ -367,6 +493,15 @@ class Painter implements FlowPainter {
     }
     if (!any) return;
     this.applyStroke(options);
+    // Set, not inherited: this was whatever the last `polyline` left, so a
+    // pass that stroked an edge alone before the zoom controls drew their
+    // glyphs with round ends, and one that reached only the controls drew
+    // them square — a panel repainted by itself, as a pan repaints its
+    // pinned furniture every frame, came out lighter than the panel it
+    // replaced. The same for batched edges, whose joins changed with what
+    // the pass had drawn first.
+    ctx.lineJoin = 'round';
+    ctx.lineCap = 'round';
     ctx.stroke();
     this.clearDash();
   }
@@ -431,46 +566,37 @@ class Painter implements FlowPainter {
     return measureText(this.opts, text, options);
   }
 
-  /** Cut a string to fit, with an ellipsis. Linear from the end rather than
-   * a binary search: labels that need it are short, and the widths it walks
-   * through are the ones the cache already holds. */
-  private fit(
-    text: string,
-    options: TextOptions | undefined,
-    max: number,
-  ): string {
-    if (this.measureText(text, options).width <= max) return text;
-    let cut = text.length;
-    while (cut > 1) {
-      cut--;
-      const candidate = `${text.slice(0, cut).trimEnd()}…`;
-      if (this.measureText(candidate, options).width <= max) return candidate;
-    }
-    return '…';
-  }
-
   text(text: string, x: number, y: number, options?: TextOptions): void {
     if (!text) return;
     const shown = options?.maxWidth
-      ? this.fit(text, options, options.maxWidth)
+      ? fitText(this.opts, text, options, options.maxWidth)
       : text;
-    const entry = shape(this.opts, shown, options);
-    if (!entry) return;
-    const layout = entry;
+    const near = shapeNear(this.opts, shown, options);
+    if (!near) return;
+    const { entry, scale } = near;
+    const width = entry.width * scale;
+    const height = entry.height * scale;
     const align = options?.align ?? 'left';
-    const dx =
-      align === 'center'
-        ? -layout.width / 2
-        : align === 'right'
-          ? -layout.width
-          : 0;
-    const dy = options?.baseline === 'middle' ? -layout.height / 2 : 0;
-    // Rounded on the device grid, where the glyphs land.
-    entry.layout.draw(
-      this.raw,
-      Math.round(this.d(x + dx)),
-      Math.round(this.d(y + dy)),
-    );
+    const dx = align === 'center' ? -width / 2 : align === 'right' ? -width : 0;
+    const dy = options?.baseline === 'middle' ? -height / 2 : 0;
+    if (scale === 1) {
+      // Rounded on the device grid, where the glyphs land.
+      entry.layout.draw(
+        this.raw,
+        snapToGrid(this.d(x + dx)),
+        snapToGrid(this.d(y + dy)),
+      );
+      return;
+    }
+    // Mid-zoom, a layout shaped at another size, scaled through the context
+    // — which draws it as outlines, glyphs and all (`scalesText`). Not on
+    // the grid: the whole label is moving, and it is set exactly at rest.
+    const ctx = this.ctx;
+    ctx.save();
+    ctx.translate(this.d(x + dx), this.d(y + dy));
+    ctx.scale(scale, scale);
+    entry.layout.draw(this.raw, 0, 0);
+    ctx.restore();
   }
 }
 

package/src/flow/gl/color.ts

@@ -0,0 +1,85 @@
+// CSS colours as the premultiplied floats a blend of ONE, ONE_MINUS_SRC_ALPHA
+// wants.
+//
+// Through ntk's own parser where it can be reached, because a graph's colours
+// come from three places and only one of them is ours: the palette (hex and
+// `rgba()`), `tint()` (`rgba()`), and an application's node and edge styles —
+// which are CSS, so `red` and `hsl(...)` are fair game and the 2D renderer
+// draws them. `cssColorStraight` is exported by ntk at runtime but not
+// declared by `react-x11/ntk`'s types, so it is probed rather than imported,
+// the way `src/flow/index.ts` probes the reconciler's escape hatch; the local
+// parser below is what a core that drops it degrades to.
+import * as ntk from 'react-x11/ntk';
+
+/** `[r, g, b, a]`, premultiplied, each in `0..1`. */
+export type Rgba = readonly [number, number, number, number];
+
+const CLEAR: Rgba = [0, 0, 0, 0];
+
+type Parser = (value: string) => readonly number[] | null;
+
+const ntkParser: Parser | null = (() => {
+  const candidate = (ntk as unknown as { cssColorStraight?: unknown })
+    .cssColorStraight;
+  return typeof candidate === 'function' ? (candidate as Parser) : null;
+})();
+
+/** Hex and `rgb()`/`rgba()` — every colour the default palette produces. */
+function localParse(value: string): readonly number[] | null {
+  const v = value.trim().toLowerCase();
+  if (v === 'transparent') return [0, 0, 0, 0];
+  if (v.startsWith('#')) {
+    const h = v.slice(1);
+    if (!/^[0-9a-f]+$/.test(h)) return null;
+    if (h.length === 3 || h.length === 4) {
+      const c = (i: number) => parseInt(h[i] + h[i], 16) / 255;
+      return [c(0), c(1), c(2), h.length === 4 ? c(3) : 1];
+    }
+    if (h.length === 6 || h.length === 8) {
+      const c = (i: number) => parseInt(h.slice(i * 2, i * 2 + 2), 16) / 255;
+      return [c(0), c(1), c(2), h.length === 8 ? c(3) : 1];
+    }
+    return null;
+  }
+  const m = /^rgba?\(([^)]*)\)$/.exec(v);
+  if (!m) return null;
+  const parts = m[1].split(/[\s,/]+/).filter(Boolean);
+  if (parts.length < 3) return null;
+  const channel = (p: string) =>
+    p.endsWith('%') ? parseFloat(p) / 100 : parseFloat(p) / 255;
+  const alpha =
+    parts[3] === undefined
+      ? 1
+      : parts[3].endsWith('%')
+        ? parseFloat(parts[3]) / 100
+        : parseFloat(parts[3]);
+  return [channel(parts[0]), channel(parts[1]), channel(parts[2]), alpha];
+}
+
+/**
+ * A colour cache. A frame asks for the same few colours thousands of times —
+ * every edge in one pen, every card in one fill — so parsing is once per
+ * distinct string, and the cache is bounded against an application that
+ * generates colours.
+ */
+export class ColorCache {
+  private readonly map = new Map<string, Rgba>();
+
+  get(value: string | undefined): Rgba {
+    if (!value) return CLEAR;
+    let rgba = this.map.get(value);
+    if (rgba) return rgba;
+    const parsed = (ntkParser ?? localParse)(value) ?? localParse(value);
+    // An unknown colour draws nothing rather than black: the same answer
+    // the 2D context gives a `fillStyle` it cannot read.
+    if (!parsed) {
+      rgba = CLEAR;
+    } else {
+      const a = parsed[3] ?? 1;
+      rgba = [parsed[0] * a, parsed[1] * a, parsed[2] * a, a];
+    }
+    if (this.map.size > 512) this.map.clear();
+    this.map.set(value, rgba);
+    return rgba;
+  }
+}