react-x11 2.15.3 → 2.16.1

package/src/cocoa/app.js

@@ -22,7 +22,7 @@ import { deliverActivate, deliverOpen } from '../application.js';
 import { flushPendingFrames } from '../frames.js';
 import { flushSyncWork } from '../priority.js';
 import { setCompositingForTests } from '../compositing.js';
-import { setScreensForTests } from '../screens.js';
+import { setScreenPolling, setScreensForTests } from '../screens.js';
 import { setScaleForTests } from '../scale.js';
 import { BezelStore } from './bezels.js';
 import { CocoaGLArea, cocoaGLConfig, resolveCocoaGLRuntime } from './glarea.js';
@@ -40,6 +40,7 @@ import { CocoaFilePanels } from './filepanels.js';
 import { CocoaFontManager } from './fonts.js';
 import { releaseImageUpload } from './context2d.js';
 import { CocoaSurface } from './surface.js';
+import { CocoaSymbols } from './symbols.js';
 import { CocoaWindow } from './window.js';
 import { decodeKey, modifierMask } from './keymap.js';
 import { loadNative } from './native.js';
@@ -69,6 +70,23 @@ const FRAME_SLACK_MS = 1;
 // to 100, docs/windows.md §"Resize"). `createRoot({ cocoa: { resizeWait } })`
 // sets it; 0 is no handshake at all.
 const RESIZE_WAIT_MS = 50;
+// How often the screen layout is re-read while something is watching it, in
+// ms. There is no event to wait for — the bridge keeps its `NSScreen` copy
+// current on macOS's notification and emits nothing (#617) — so
+// `useScreens()`'s promise to re-render when a monitor is plugged in is
+// kept by asking. 500 is half a second behind a replug, which is under the
+// time it takes to look at the screen, against one `listScreens()` read a
+// second (a lock and a few doubles on a worker, an `NSScreen.screens` walk
+// on the main thread). Only while a component is subscribed:
+// `createRoot({ cocoa: { screenPoll } })` sets it, 0 turns it off, and
+// nothing polls in an app that never calls `useScreens()`.
+const SCREEN_POLL_MS = 500;
+// The floor under a re-read driven by something that is *not* a clock: a
+// window reporting where it is, which a drag reports every frame and a
+// display change reports once. A second is far too long to matter to a
+// person and short enough that a rearrangement is noticed by the time they
+// have finished moving the window (`_recheckScreens`).
+const SCREEN_RECHECK_MS = 1000;
 
 export class CocoaApp {
   constructor(native, options = {}) {
@@ -156,6 +174,26 @@ export class CocoaApp {
     const screens = native.listScreens();
     this.scale = screens[0]?.scale ?? 1;
     this._screens = screens;
+    // …and how the layout stays current, because nothing pushes it: the
+    // bridge republishes its copy on macOS's own notification but emits no
+    // event, so this side asks — before a placement reads the layout, when
+    // a window reports a move, and on a clock while `useScreens()` has a
+    // subscriber (`refreshScreens`, #617). `_screensAt` is when the last
+    // read happened, which is what throttles the ones that are not clocks.
+    this._screensAt = performance.now();
+    this._screenTimer = null;
+    const screenPoll = options.cocoa?.screenPoll ?? SCREEN_POLL_MS;
+    if (!(screenPoll >= 0) || !Number.isFinite(screenPoll)) {
+      throw new TypeError(
+        'react-x11: cocoa.screenPoll is a number of milliseconds, 0 for ' +
+          `none — got ${screenPoll}.`,
+      );
+    }
+    this._screenPoll = screenPoll;
+    setScreenPolling(this, {
+      revalidate: () => this.refreshScreens(),
+      watched: (on) => this._pollScreens(on),
+    });
 
     // The name the Dock, ⌘-Tab and the menu bar print. An unbundled
     // process is registered with LaunchServices under its executable —
@@ -200,6 +238,8 @@ export class CocoaApp {
     // real bridge on the machine — the manager's default loads it only when
     // it is built standalone
     this.fonts = new CocoaFontManager(native);
+    // `<image src={{ symbol }}>`'s names are SF Symbols here (src/symbols.js)
+    this.symbols = new CocoaSymbols(native);
 
     // Native open/save panels (src/cocoa/filepanels.js). Present exactly
     // when the bridge has them (>= 0.5), and its presence is what puts the
@@ -501,6 +541,102 @@ export class CocoaApp {
     this._windows.set(wnd._key, wnd);
   }
 
+  /**
+   * Re-read the screen layout and publish it if the desk has changed — the
+   * answer to a monitor plugged in, unplugged, rearranged, woken or made
+   * primary (#617). Returns whether anything moved.
+   *
+   * **`listScreens()` is always current; this side's copy was not.** The
+   * bridge republishes its `NSScreen` snapshot on
+   * `NSApplicationDidChangeScreenParametersNotification` and answers a
+   * pump-mode call from AppKit live — what was read once and kept forever
+   * is `_screens`, taken in the constructor. So the whole fix is to ask
+   * again, and the read is cheap enough to ask on demand: before a
+   * placement clamps a popup to a monitor (`availableArea` through
+   * `setScreenPolling`), when a window reports a move (`_recheckScreens`),
+   * and on a clock while `useScreens()` is mounted (`_pollScreens`).
+   *
+   * Public, and the seam for an app that knows before any of those do —
+   * `app.refreshScreens()` publishes whatever the OS says right now.
+   *
+   * **The app's scale is not re-derived.** Every rect this backend speaks
+   * in is points × `app.scale`, fixed at startup, and a window's origin,
+   * an event's coordinates and a surface's pixels all already exist in
+   * that space; moving it under them is a different and much larger change
+   * than re-reading a layout. The layout is converted at the scale the rest
+   * of the app uses, which is what keeps `monitorAt()` answering with the
+   * head a window is actually on (see `screenLayout`).
+   */
+  refreshScreens() {
+    if (this._closed) return false;
+    this._screensAt = performance.now();
+    let screens = null;
+    try {
+      screens = this._native.listScreens?.();
+    } catch {
+      // a bridge going away, or a fake with nothing to say
+      return false;
+    }
+    // An empty answer is "could not tell", never "no displays": a Mac with
+    // the lid shut and no panel attached still has the desk it had, and
+    // publishing nothing would take every monitor out from under
+    // `availableArea` and size the next window against the void.
+    if (!screens?.length) return false;
+    if (sameScreens(screens, this._screens)) return false;
+    this._screens = screens;
+    setScreensForTests(this, screenLayout(screens, this.scale));
+    // A monitor's refresh rate can change under a window that never moved —
+    // a mode switch, a panel woken at 60Hz — and a window's clock is read
+    // from this list rather than kept by the display (`frameIntervalFor`).
+    for (const wnd of this._windows.values()) {
+      if (!wnd.destroyed) wnd._refreshFrameInterval?.();
+    }
+    return true;
+  }
+
+  /**
+   * The layout, re-read at most once every `SCREEN_RECHECK_MS`.
+   *
+   * For the signals that mean "something about the desk may have moved"
+   * rather than "it did": a window reporting its position, which a drag
+   * reports every frame and a display change reports once. Plugging a
+   * monitor in moves the windows that were on it, so this is the one place
+   * the OS does tell us something — it just does not say what.
+   */
+  _recheckScreens() {
+    if (performance.now() - this._screensAt < SCREEN_RECHECK_MS) return false;
+    return this.refreshScreens();
+  }
+
+  /**
+   * The layout on a clock, while something is subscribed to it.
+   *
+   * `useScreens()` says it re-renders when a monitor is plugged in or
+   * unplugged and when the arrangement changes. On X11 that is a RandR
+   * event; here there is nothing to wait for, so while a component is
+   * watching, this asks every `cocoa.screenPoll` ms — on an unref'd timer,
+   * which never holds the process open and never wakes an app that is
+   * waiting on nothing else. An app that never calls `useScreens()` pays
+   * nothing at all: the paths where a stale layout is visible ask for
+   * themselves.
+   *
+   * Started and stopped by the session as the first subscriber arrives and
+   * the last one leaves (`setScreenPolling`), so a hook that unmounts takes
+   * the clock with it.
+   */
+  _pollScreens(on) {
+    if (this._screenTimer) {
+      clearInterval(this._screenTimer);
+      this._screenTimer = null;
+    }
+    if (!on || this._closed || !(this._screenPoll > 0)) return;
+    this._screenTimer = setInterval(
+      () => this.refreshScreens(),
+      this._screenPoll,
+    );
+    this._screenTimer.unref?.();
+  }
+
   /**
    * How often `wnd` may paint, in ms: the explicit `frameInterval` when the
    * root was given one, else the period of the screen under the window's
@@ -641,6 +777,8 @@ export class CocoaApp {
   _unregisterWindow(wnd) {
     this._windows.delete(wnd._key);
     if (this._grabWindow === wnd) this._grabWindow = null;
+    // a popup that took the keyboard and closed is not where keys go next
+    if (this._lastKeyWindow === wnd) this._lastKeyWindow = null;
   }
 
   // --- the pump ------------------------------------------------------------
@@ -802,8 +940,8 @@ export class CocoaApp {
     this._rafQueue = [];
     let soonest = Infinity;
     for (const entry of queue) {
-      // A window whose last flip has not given its back buffer back yet
-      // (threaded mode's fence, `CocoaWindow.frameInFlight`) waits before
+      // A window whose last flip has not reached its layer yet (threaded
+      // mode's fence, `CocoaWindow.frameInFlight`) waits before
       // its clock is asked, or the clock would count a frame that did not
       // run. The release is an event, and the batch it arrives in ticks
       // again.
@@ -874,7 +1012,7 @@ export class CocoaApp {
    * paid once, when the batch is done: ten moves and a click that crossed
    * while this thread was busy are one frame, not eleven. Then what a pump
    * tick does: the frames that are due, and the ones a window's visibility
-   * or its back buffer was holding, which an occlusion change or a
+   * or its last flip was holding, which an occlusion change or a
    * `surface-released` in this very batch may just have freed.
    */
   _routeBatch(batch) {
@@ -1090,9 +1228,9 @@ export class CocoaApp {
     // the notch and the scroll, most of a refresh period of nothing.
     //
     // Mostly: a trackpad's momentum lands two in one tick often, and a
-    // second flip inside the refresh draws into the buffer the first one
-    // just took off glass (`CocoaWindow._flippedRecently` says why that
-    // shows). So the rest of a burst lands React's half and leaves the
+    // second flip inside the refresh is a frame the display never shows
+    // (`CocoaWindow._flippedRecently` says what it cost). So the rest of a
+    // burst lands React's half and leaves the
     // paint to the paced frame the scroll already asked for — the model
     // has scrolled, and the next refresh shows all of it.
     if (wnd._flippedRecently()) {
@@ -1135,6 +1273,10 @@ export class CocoaApp {
   _routeGeometry(ev) {
     const wnd = this._window(ev);
     if (!wnd || wnd.destroyed) return;
+    // Before the window re-paces itself against the screen list below: a
+    // display plugged in or removed moves the windows that were on it, and
+    // this is the only thing the bridge says about it (`_recheckScreens`).
+    this._recheckScreens();
     wnd._nativeResized(ev);
     wnd.emit('resize', {
       width: wnd.width,
@@ -1201,9 +1343,10 @@ export class CocoaApp {
   /**
    * `surface-released`: a worker's frame took an IOSurface off a layer and
    * the frame that replaced it has committed (windowkit/appkit#52). The
-   * window whose back buffer that was stops waiting on it
-   * (`CocoaWindow._surfaceReleased`), and the tick at the end of this
-   * batch runs the frame it was holding.
+   * window whose buffer that was stops waiting on it, and may draw into it
+   * again once the WindowServer lets go of it too
+   * (`CocoaWindow._surfaceReleased`); the tick at the end of this batch
+   * runs the frame it was holding.
    */
   _routeSurfaceReleased(ev) {
     for (const wnd of this._windows.values()) {
@@ -1369,6 +1512,7 @@ export class CocoaApp {
     this._pump = null;
     if (this._frameTimer) clearTimeout(this._frameTimer);
     this._frameTimer = null;
+    this._pollScreens(false);
     this._cocoaGL?.destroy();
     this._cocoaGL = null;
     this._unsubscribe?.();
@@ -1407,6 +1551,12 @@ export class CocoaApp {
  * *width* as a bound to every other head: a second display wider than the
  * built-in had its right edge pulled in by the difference, and every
  * anchored popup that reached past it was clamped back (issue #453).
+ *
+ * **Everything the bridge says about a screen comes through**, not only its
+ * rects. `primary` and the panel's refresh rate were dropped here, so
+ * `useScreens().primary` read null on macOS — every entry `primary: false`
+ * — and `refreshRate` null beside a `frameIntervalFor` that was pacing
+ * windows on that very number (#617).
  */
 export function screenLayout(screens, scale) {
   const rect = (r) => ({
@@ -1417,9 +1567,17 @@ export function screenLayout(screens, scale) {
   });
   const primary = screens?.[0];
   return {
-    monitors: (screens ?? []).map((screen) => ({
+    monitors: (screens ?? []).map((screen, i) => ({
       ...rect(screen),
       ...(screen.visible ? { visible: rect(screen.visible) } : null),
+      // `NSScreen.screens[0]` **is** the primary — the screen with the menu
+      // bar, which is where macOS puts a window that names no position —
+      // and the bridge flags it as well; the index is the same fact for a
+      // bridge that does not.
+      primary: screen.primary ?? i === 0,
+      // `NSScreen.maximumFramesPerSecond`, as `fps`. 0 is the OS declining
+      // to say (before macOS 12), which is `useScreens()`'s null.
+      refreshRate: screen.fps > 0 ? screen.fps : null,
     })),
     // Still published for `useScreens().workArea`, which is one rect for
     // the desktop by definition; the primary's is the closest macOS has.
@@ -1427,6 +1585,48 @@ export function screenLayout(screens, scale) {
   };
 }
 
+/**
+ * Whether two `listScreens()` answers describe the same desk.
+ *
+ * Every field the layout is built from, in the order they arrived — which
+ * is `NSScreen.screens`, so the order is the arrangement and the primary,
+ * and a change in it is a change. `fps` counts because a window's frame
+ * clock is read from it, and `scale` because a screen that switched mode
+ * is not the screen it was even at the same size.
+ *
+ * Pure, and exported for that reason: it decides whether a re-read
+ * re-renders every `useScreens()` subscriber, and a poll that publishes an
+ * unchanged layout twice a second is a render loop rather than a fix.
+ */
+export function sameScreens(a, b) {
+  if (!a || !b || a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i];
+    const y = b[i];
+    if (
+      x.x !== y.x ||
+      x.y !== y.y ||
+      x.width !== y.width ||
+      x.height !== y.height ||
+      x.scale !== y.scale ||
+      x.fps !== y.fps ||
+      x.primary !== y.primary ||
+      !sameRect(x.visible, y.visible)
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** Two `visible` rects, either of which a bridge may not have reported. */
+function sameRect(a, b) {
+  if (!a || !b) return !a === !b;
+  return (
+    a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height
+  );
+}
+
 /**
  * Build the app and seed the platform stores the way the mock seeds them —
  * `beginScale`/`beginScreens`/`beginCompositing` find a session already

package/src/cocoa/context2d.js

@@ -1046,6 +1046,29 @@ export class CocoaContext2D {
     this._dirty();
   }
 
+  /**
+   * An SF Symbol by name, fitted into the rect and centred, in the fill
+   * colour — `ctxDrawSymbol`, `@windowkit/appkit` 0.12.0. Answers false,
+   * drawing nothing, for a name the system does not know and on a bridge
+   * without the verb. `options` are the bridge's: `pointSize`, `weight`,
+   * `scale`, `variableValue`.
+   */
+  drawSymbol(name, x, y, width, height, options) {
+    if (typeof this._native.ctxDrawSymbol !== 'function') return false;
+    this._applyFill();
+    const drawn = this._native.ctxDrawSymbol(
+      this._s(),
+      name,
+      x,
+      y,
+      width,
+      height,
+      options,
+    );
+    if (drawn) this._dirty();
+    return drawn === true;
+  }
+
   drawImage(image, ...args) {
     const src = this._sourceHandle(image);
     if (!src) return;

package/src/cocoa/fonts.js

@@ -462,11 +462,31 @@ export class CocoaFace {
   }
 }
 
+/**
+ * The features a letter-spaced span is set with: CSS's rule, and ntk's, that
+ * the optional ligatures come off where letters are spaced — an `fi` drawn as
+ * one glyph cannot open in its middle — unless the style names them.
+ */
+const OPTIONAL_LIGATURES_OFF = Object.freeze({
+  liga: 0,
+  clig: 0,
+  dlig: 0,
+  hlig: 0,
+});
+function spacedFeatures(features, spacing) {
+  if (!spacing) return features;
+  return features
+    ? { ...OPTIONAL_LIGATURES_OFF, ...features }
+    : OPTIONAL_LIGATURES_OFF;
+}
+
 export class CocoaFontManager {
   /** @param native the @windowkit/appkit module; the tests hand in a fake */
   constructor(native = loadNative()) {
     this._native = native;
     this._fonts = new Map(); // family|weight|italic|size -> handle
+    // handle -> features key -> the handle with those features set
+    this._featured = new WeakMap();
     this._faces = new Map(); // family|weight|italic -> face wrapper
     this._registered = new Map(); // lowercase family -> [{cg, weight, italic}]
     this._byKey = new Map(); // ntk Font key -> { cg } | { ps }
@@ -585,6 +605,52 @@ export class CocoaFontManager {
     return handle;
   }
 
+  /**
+   * `handle` with OpenType features set — `fontApplyFeatures`, which
+   * `@windowkit/appkit` has from 0.11.0 — for the resolved `features` a
+   * style hands the engines, tag → value. Kept per handle, so a paragraph
+   * laid out every repaint asks the bridge for a featured font once. A
+   * bridge without the verb gets the handle back as it was
+   * (`_textAdjustments`).
+   */
+  _withFeatures(handle, features) {
+    if (!handle || !features || !this._textAdjustments()) return handle;
+    let perHandle = this._featured.get(handle);
+    if (!perHandle) this._featured.set(handle, (perHandle = new Map()));
+    const key = JSON.stringify(features);
+    let featured = perHandle.get(key);
+    if (!featured) {
+      featured = this._native.fontApplyFeatures(handle, features);
+      perHandle.set(key, featured);
+    }
+    return featured;
+  }
+
+  /**
+   * Whether the bridge sets features and letter spacing at all. Both arrived
+   * in one `@windowkit/appkit` release, `fontApplyFeatures` with the span's
+   * `letterSpacing`; an older bridge takes the span option and ignores it,
+   * so the verb is what answers for both.
+   *
+   * Without them the text draws as the face has it — digits proportional,
+   * letters unspaced — and nothing else goes wrong. But a style that asked
+   * for either and got nothing is a question with no thread to pull, so
+   * development says so, once.
+   */
+  _textAdjustments() {
+    if (typeof this._native.fontApplyFeatures === 'function') return true;
+    if (process.env.NODE_ENV !== 'production' && !this._warnedAdjustments) {
+      this._warnedAdjustments = true;
+      console.warn(
+        'react-x11: this @windowkit/appkit has no fontApplyFeatures, so ' +
+          'letterSpacing, fontVariantNumeric and fontFeatureSettings do ' +
+          'nothing on the Cocoa backend. Update @windowkit/appkit to the ' +
+          'version react-x11 lists in its optionalDependencies.',
+      );
+    }
+    return false;
+  }
+
   _withVariations(handle, variations) {
     if (
       variations &&
@@ -882,6 +948,8 @@ export class CocoaFontManager {
         sp.color ?? base.color ?? null,
         sp.variations ?? base.variations ?? null,
         (sp.font ?? base.font)?.key ?? null,
+        sp.features ?? base.features ?? null,
+        sp.letterSpacing ?? base.letterSpacing ?? 0,
       ]),
       options.maxWidth,
       options.align,
@@ -926,12 +994,22 @@ export class CocoaFontManager {
         ),
         variations,
       );
+      // Letter spacing is the typesetter's kerning attribute, and it turns
+      // the optional ligatures off the way ntk does, so the two engines
+      // agree on what a spaced word is made of (#588).
+      let spacing = span.letterSpacing ?? base.letterSpacing ?? 0;
+      if (spacing && !this._textAdjustments()) spacing = 0;
+      handle = this._withFeatures(
+        handle,
+        spacedFeatures(span.features ?? base.features, spacing),
+      );
       const color = span.color ?? base.color;
       if (color == null) contextInk = true;
       nativeSpans.push({
         text: t,
         font: handle,
         ...(color == null ? {} : { color: parseColor(color) }),
+        ...(spacing ? { letterSpacing: spacing } : {}),
       });
     }
     // A width offer of zero is a question, not a degenerate layout: yoga

package/src/cocoa/presenter.js

@@ -480,9 +480,21 @@ export function propBoxProps(node, app, scale, parentOrigin, order) {
     backgroundColor: colour(style.backgroundColor),
     borderWidth: border / scale,
     borderColor: colour(style.borderColor),
+    opacity: layerOpacity(style),
   };
 }
 
+/**
+ * `opacity` as a layer's own. On the layer presenter a node's children are
+ * its sublayers, so this fades the subtree with it; the bitmap paths draw
+ * the group themselves and never promote a faded box.
+ */
+export function layerOpacity(style) {
+  const value = style?.opacity;
+  if (typeof value !== 'number' || Number.isNaN(value)) return 1;
+  return Math.min(1, Math.max(0, value));
+}
+
 // --- animations the render server runs ---------------------------------------
 //
 // The node model keeps deciding what is animating and when it ends
@@ -586,6 +598,10 @@ export class LayerAnimations {
         opts.timing = EASING_CONTROL_POINTS[entry.easing];
         opts.repeat = Infinity;
         opts.autoreverse = entry.alternate;
+        // CA's two halves of one CSS delay: a begin time the layer waits
+        // for showing `from`, or a time offset that starts it that far in
+        if (entry.delay > 0) opts.delay = entry.delay / 1000;
+        else if (entry.delay < 0) opts.timeOffset = -entry.delay / 1000;
       } else if (map.colour) {
         // From where the pixels are — which is what "an interrupted
         // transition reverses from where it got to" means here. A colour
@@ -1112,6 +1128,7 @@ export class CocoaLayerPresenter {
       ],
       zPosition: order,
       hidden: Boolean(node.hidden),
+      opacity: layerOpacity(node.style),
       // the layer covers the ink bounds; clipping (if any) belongs to the
       // CONTENT box, which a raster self cannot express — scrolling
       // containers that also raster keep clipping via a child guard below

package/src/cocoa/promotion.js

@@ -154,6 +154,25 @@ function insideGlArea(node) {
   return false;
 }
 
+const faded = (style) => style?.opacity !== undefined && !(style.opacity >= 1);
+
+/**
+ * A box whose `opacity` is below 1, now or on its way there, is a group the
+ * bitmap composites (`NodePaint._paintGroup`) — the box and everything in it
+ * drawn once and faded as one. On a layer of its own the box and its content
+ * would be separate layers under the one opacity, fading one over the other,
+ * and an opacity the frame clock is still animating would never reach the
+ * layer at all.
+ */
+function fadesAsGroup(node) {
+  return (
+    faded(node.style) ||
+    faded(node._targetStyle) ||
+    Boolean(node._anim?.has('opacity')) ||
+    Boolean(node._loops?.some((loop) => loop.prop === 'opacity'))
+  );
+}
+
 /**
  * Can this node be a property box on a layer at all — the static half of
  * the answer, the same whatever the scene around it does: a plain box by
@@ -163,6 +182,7 @@ function insideGlArea(node) {
 function promotableNode(node) {
   if (node.destroyed || !plainBox(node)) return false;
   if (insideGlArea(node)) return false;
+  if (fadesAsGroup(node)) return false;
   if (!stylePaintsPlain(node, node._targetStyle ?? node.style)) return false;
   if (node.isScroller?.()) return false;
   return !paintsOutline(node);

package/src/cocoa/relaunch.js

@@ -181,11 +181,16 @@ export function relaunch(entry, native) {
   // the package's own would be a second one the bundler never emits. The
   // worker sets itself up when it imports react-x11 (`bootstrapWorker`,
   // src/bootstrap.js), recognising the shared state in its workerData.
-  // execArgv carries a loader like `--import tsx`, which is what lets the
-  // worker load a .jsx entry at all.
+  //
+  // No `execArgv`: a Worker given none inherits the node flags the process
+  // started with, and among them a loader like `--import tsx`, which is what
+  // lets the worker load a .jsx entry at all. Handed `process.execArgv`
+  // instead, it refuses the whole list over one V8 or process-wide flag —
+  // `--expose-gc`, `--max-old-space-size`, `--title` — which the worker
+  // would have had anyway, since those hold for every thread: it gets `gc`
+  // either way (measured, Node 20–26; Bun treats the two the same).
   new Worker(entry, {
     argv: process.argv.slice(2),
-    execArgv: process.execArgv,
     env: SHARE_ENV,
     workerData: { reactX11State: state.buffer },
   });

package/src/cocoa/symbols.js

@@ -0,0 +1,64 @@
+// SF Symbols for the Cocoa backend (#591): `app.symbols`, the provider
+// `<image src={{ symbol }}>` asks (src/symbols.js), over `@windowkit/appkit`'s
+// `symbolSize` and `ctxDrawSymbol` (0.12.0).
+//
+// A symbol is a template — its shape, in whatever colour it is drawn with —
+// so it is drawn the way a glyph run is: in the context's fill colour, through
+// its transform and clip. Sizes are points, which on this backend are logical
+// pixels.
+
+import { warnOnce } from '../symbols.js';
+
+export class CocoaSymbols {
+  constructor(native) {
+    this.native = native;
+    this.sizes = new Map(); // name and options -> { width, height } | null
+  }
+
+  /** Whether the bridge draws symbols at all. Without the verbs nothing is
+   *  shown and nothing else goes wrong, so development says so, once. */
+  _available() {
+    if (typeof this.native?.ctxDrawSymbol === 'function') return true;
+    warnOnce(
+      'react-x11: this @windowkit/appkit has no ctxDrawSymbol, so <image ' +
+        'src={{ symbol }}> shows nothing on the Cocoa backend. Update ' +
+        '@windowkit/appkit to the version react-x11 lists in its ' +
+        'optionalDependencies.',
+    );
+    return false;
+  }
+
+  size(name, options) {
+    if (!this._available()) return null;
+    const bridge = bridgeOptions(options);
+    const key = JSON.stringify([name, bridge]);
+    if (!this.sizes.has(key)) {
+      if (this.sizes.size > 512) this.sizes.clear();
+      this.sizes.set(key, this.native.symbolSize(name, bridge));
+    }
+    return this.sizes.get(key);
+  }
+
+  draw(ctx, name, rect, options) {
+    if (typeof ctx.drawSymbol !== 'function' || !this._available()) {
+      return false;
+    }
+    ctx.fillStyle = options.color;
+    return ctx.drawSymbol(
+      name,
+      rect.x,
+      rect.y,
+      rect.width,
+      rect.height,
+      bridgeOptions(options),
+    );
+  }
+}
+
+/** What the bridge is handed: the options it knows, and only those set. */
+const bridgeOptions = ({ pointSize, weight, scale, variableValue }) => ({
+  pointSize,
+  weight,
+  ...(scale === undefined ? {} : { scale }),
+  ...(variableValue === undefined ? {} : { variableValue }),
+});