react-x11 2.11.0 → 2.12.0

package/src/cocoa/bezels.js

@@ -18,11 +18,44 @@
 // frame padded back out by those insets and blitted from the ink region.
 // Scanned rather than hard-coded so a macOS release that redraws its
 // controls moves the answer instead of breaking it.
+//
+// ## On a worker
+//
+// In threaded mode (src/cocoa/main.js) the bridge makes the control on the
+// UI thread and answers a measure or a draw through a callback
+// (windowkit/appkit#54) — a cell made on the worker drew correct pixels
+// and then crashed the process at exit. So nothing here can ask and use
+// the answer in one call. The metrics layout reads synchronously, `natural`
+// and `shadow`, are fetched for every kind at startup (`prefetch`). A bezel
+// `get` has not drawn yet answers null and calls back once it has, and the
+// caller draws what it had meanwhile. A bezel drawn at rest brings its
+// pressed twin along, so the press — the input whose answer is the bezel —
+// never waits for one (AGENTS.md, "Answer the input").
+
+const KINDS = ['push', 'checkbox', 'radio', 'popup', 'slider', 'switch'];
+// the sizes the widget set lays its controls out at (components/native.js)
+const SIZES = ['regular', 'small'];
+// the fullest state, so the scan sees the whole footprint
+const SCAN_STATE = Object.freeze({
+  state: 1,
+  value: 0.5,
+  enabled: true,
+  appearance: 'light',
+});
+
 export class BezelStore {
-  constructor(native) {
+  /**
+   * `answersLater` says whether the bridge answers through a callback —
+   * asked at each call, since the app knows only once it has started.
+   */
+  constructor(native, { answersLater = () => false } = {}) {
     this._native = native;
+    this._answersLater = answersLater;
     this._canonical = new Map(); // kind|size|scale → { insets, natural }
+    this._scanning = new Map(); // kind|size|scale → the scan in flight
     this._cache = new Map(); // full param key → { surface, sx, sy, sw, sh }
+    this._drawing = new Map(); // full param key → callbacks awaiting it
+    this._gen = 0;
     this._MAX = 160;
   }
 
@@ -40,16 +73,21 @@ export class BezelStore {
   clear() {
     // the surfaces are freed by their External finalizer
     this._cache.clear();
+    // a draw still out is in the old accent: it goes to its callers, and
+    // not into the cache
+    this._gen++;
   }
 
   /**
    * The control's natural size in logical px — the size the bezel is
    * designed at, which layout adopts for the kinds that must not stretch
    * (checkbox, radio, switch). For the stretchable kinds only `height` is
-   * meaningful: a push button is as wide as its label needs.
+   * meaningful: a push button is as wide as its label needs. Null on a
+   * worker for a size `prefetch` did not cover, until its scan is in.
    */
   natural(kind, controlSize = 'regular') {
     const c = this._scan(kind, controlSize, 2);
+    if (!c) return null;
     return {
       width: Math.round(c.natural.width),
       height: Math.round(c.natural.height),
@@ -65,20 +103,38 @@ export class BezelStore {
    */
   shadow(kind, controlSize = 'regular') {
     const c = this._scan(kind, controlSize, 2);
+    if (!c) return { top: 0, bottom: 0 };
     return {
       top: Math.round(c.body.top),
       bottom: Math.round(c.body.bottom),
     };
   }
 
+  /**
+   * Scan every kind at the widget set's sizes, now: at scale 2 for the
+   * metrics (`natural` measures there) and at `scale` for the bezels the
+   * app will draw. Resolves once all are in. For a worker, where a scan is
+   * two answers from the UI thread; on the main thread it is not needed,
+   * each scan running the first time it is asked for.
+   */
+  prefetch(scale) {
+    const jobs = [];
+    for (const s of new Set([2, scale])) {
+      for (const kind of KINDS) {
+        for (const size of SIZES) jobs.push(this._scanLater(kind, size, s));
+      }
+    }
+    return Promise.all(jobs).then(() => undefined);
+  }
+
   /**
    * The bezel for one laid-out box: `w`/`h` in device px, blit-ready.
    * Returns `{ surface, sx, sy, sw, sh }` — draw with the 9-arg
-   * `ctx.drawImage` so the ink region lands exactly on the box.
+   * `ctx.drawImage` so the ink region lands exactly on the box. On a worker
+   * a bezel not drawn yet is null, and `onReady` is called once it is in.
    */
-  get(params, w, h, scale) {
+  get(params, w, h, scale, onReady = null) {
     const controlSize = params.controlSize ?? 'regular';
-    const c = this._scan(params.kind, controlSize, scale);
     const key = JSON.stringify([
       params.kind,
       controlSize,
@@ -92,7 +148,7 @@ export class BezelStore {
       h,
       scale,
     ]);
-    let entry = this._cache.get(key);
+    const entry = this._cache.get(key);
     if (entry) {
       // Map order is the recency order: re-inserting keeps the hot bezels
       // at the young end when the cache is over budget.
@@ -100,6 +156,23 @@ export class BezelStore {
       this._cache.set(key, entry);
       return entry;
     }
+    if (this._answersLater()) {
+      this._drawLater(key, { ...params, controlSize }, w, h, scale, onReady);
+      return null;
+    }
+    const c = this._scan(params.kind, controlSize, scale);
+    const frame = this._frame(c, w, h, scale);
+    this._native.drawControlIntoSurface(frame.surface, {
+      ...params,
+      controlSize,
+    });
+    this._store(key, frame.entry);
+    return frame.entry;
+  }
+
+  /** A surface padded out by the kind's insets, and the region of it a box
+   * `w` × `h` blits from. */
+  _frame(c, w, h, scale) {
     const fw = w / scale + c.insets.left + c.insets.right;
     const fh = h / scale + c.insets.top + c.insets.bottom;
     const surface = this._native.createSurface(
@@ -107,51 +180,123 @@ export class BezelStore {
       Math.max(1, Math.round(fh * scale)),
       scale,
     );
-    this._native.drawControlIntoSurface(surface, {
-      ...params,
-      controlSize,
-    });
-    entry = {
+    return {
       surface,
-      sx: Math.round(c.insets.left * scale),
-      sy: Math.round(c.insets.top * scale),
-      sw: w,
-      sh: h,
+      entry: {
+        surface,
+        sx: Math.round(c.insets.left * scale),
+        sy: Math.round(c.insets.top * scale),
+        sw: w,
+        sh: h,
+      },
     };
+  }
+
+  _store(key, entry) {
     this._cache.set(key, entry);
     if (this._cache.size > this._MAX) {
       // eldest first; the surface itself is freed by its External finalizer
       const oldest = this._cache.keys().next().value;
       this._cache.delete(oldest);
     }
-    return entry;
+  }
+
+  /** A worker's `get`: one draw per key however many ask, each asker called
+   * back when it lands. The surface is left alone until then — the bridge
+   * draws into its bitmap on the UI thread. */
+  _drawLater(key, params, w, h, scale, onReady) {
+    const waiting = this._drawing.get(key);
+    if (waiting) {
+      if (onReady) waiting.add(onReady);
+      return;
+    }
+    const callbacks = new Set(onReady ? [onReady] : []);
+    this._drawing.set(key, callbacks);
+    const gen = this._gen;
+    this._scanLater(params.kind, params.controlSize, scale).then((c) => {
+      const frame = this._frame(c, w, h, scale);
+      this._native.drawControlIntoSurface(frame.surface, params, () => {
+        this._drawing.delete(key);
+        if (gen === this._gen) this._store(key, frame.entry);
+        for (const fn of callbacks) fn();
+        // the twin a press will ask for, drawn before the press
+        if (!params.pressed && params.enabled !== false) {
+          this.get({ ...params, pressed: true }, w, h, scale);
+        }
+      });
+    });
   }
 
   /**
    * One render + alpha scan per (kind, size, scale): where does this cell
    * actually put ink inside the frame it is given? The frame is the natural
    * cellSize widened by 24pt so a stretchable bezel's side margins are
-   * visible as margins rather than crowding the ends.
+   * visible as margins rather than crowding the ends. Null on a worker when
+   * the scan is not in yet: it is asked for, and answers later.
    */
   _scan(kind, controlSize, scale) {
     const key = `${kind}|${controlSize}|${scale}`;
-    let c = this._canonical.get(key);
-    if (c) return c;
+    const done = this._canonical.get(key);
+    if (done) return done;
+    if (this._answersLater()) {
+      this._scanLater(kind, controlSize, scale);
+      return null;
+    }
     const m = this._native.measureControl({ kind, controlSize });
+    const frame = this._scanFrame(m, scale);
+    this._native.drawControlIntoSurface(frame.surface, {
+      kind,
+      controlSize,
+      ...SCAN_STATE,
+    });
+    return this._inkBox(key, frame, scale);
+  }
+
+  /** `_scan` through the bridge's callbacks: once per key, however many
+   * ask. */
+  _scanLater(kind, controlSize, scale) {
+    const key = `${kind}|${controlSize}|${scale}`;
+    const done = this._canonical.get(key);
+    if (done) return Promise.resolve(done);
+    let job = this._scanning.get(key);
+    if (job) return job;
+    const native = this._native;
+    job = new Promise((resolve) =>
+      native.measureControl({ kind, controlSize }, resolve),
+    )
+      .then((m) => {
+        const frame = this._scanFrame(m, scale);
+        return new Promise((resolve) =>
+          native.drawControlIntoSurface(
+            frame.surface,
+            { kind, controlSize, ...SCAN_STATE },
+            () => resolve(frame),
+          ),
+        );
+      })
+      .then((frame) => {
+        this._scanning.delete(key);
+        return this._inkBox(key, frame, scale);
+      });
+    this._scanning.set(key, job);
+    return job;
+  }
+
+  _scanFrame(m, scale) {
     const fw = m.width + 24;
     const fh = m.height;
     const pw = Math.max(1, Math.round(fw * scale));
     const ph = Math.max(1, Math.round(fh * scale));
-    const surface = this._native.createSurface(pw, ph, scale);
-    this._native.drawControlIntoSurface(surface, {
-      kind,
-      controlSize,
-      // the fullest state, so the scan sees the whole footprint
-      state: 1,
-      value: 0.5,
-      enabled: true,
-      appearance: 'light',
-    });
+    return {
+      surface: this._native.createSurface(pw, ph, scale),
+      fw,
+      fh,
+      pw,
+      ph,
+    };
+  }
+
+  _inkBox(key, { surface, fw, fh, pw, ph }, scale) {
     const buf = this._native.ctxGetImageData(surface, 0, 0, pw, ph);
     let x0 = pw;
     let y0 = ph;
@@ -189,7 +334,7 @@ export class BezelStore {
       by0 = y0;
       by1 = y1;
     }
-    c = {
+    const c = {
       insets: {
         left: x0 / scale,
         top: y0 / scale,

package/src/cocoa/dnd.js

@@ -149,28 +149,42 @@ export function requestedAction(operations) {
  * `DropSession.localDrop` hands the handler: `items` by type, the parsed
  * `files`, the best `text`, and a `getData` answering from the same read.
  */
-export function readPayload(native, types) {
+export function readPayload(native, types, carried = null) {
   const values = {};
   const urls = [];
-  const items = (() => {
-    try {
-      return native.dragItems?.() ?? [];
-    } catch {
-      return [];
-    }
-  })();
-  items.forEach((item, index) => {
+  // On a worker the drop carries its payload's text and URL forms itself
+  // (`items: [{ types, strings }]`, windowkit/appkit#51), since the drag
+  // pasteboard cannot be read back from there inside the callback; its
+  // other types are offered, and read as nothing.
+  const read = carried
+    ? {
+        items: carried,
+        string: (index, uti) => carried[index]?.strings?.[uti] ?? null,
+        data: () => null,
+      }
+    : {
+        items: (() => {
+          try {
+            return native.dragItems?.() ?? [];
+          } catch {
+            return [];
+          }
+        })(),
+        string: (index, uti) => native.dragItemString(index, uti),
+        data: (index, uti) => native.dragItemData(index, uti),
+      };
+  read.items.forEach((item, index) => {
     for (const uti of item?.types ?? []) {
       if (uti === 'public.file-url' || uti === 'public.url') {
-        const url = native.dragItemString(index, uti);
+        const url = read.string(index, uti);
         if (url) urls.push(url);
         continue;
       }
       const mime = mimeFromUti(uti, native);
       if (!mime || values[mime] !== undefined) continue;
       const value = isTextual(uti, mime)
-        ? native.dragItemString(index, uti)
-        : native.dragItemData(index, uti);
+        ? read.string(index, uti)
+        : read.data(index, uti);
       if (value == null) continue;
       values[mime] = value;
       if (
@@ -360,7 +374,7 @@ export class CocoaDropTransport {
     const offer = this._offer(ev);
     const extras = drag
       ? drag._dropExtras()
-      : readPayload(this.wnd._native, offer.types);
+      : readPayload(this.wnd._native, offer.types, ev.items ?? null);
     const outcome = this.session.localDrop(offer, extras, Date.now());
     if (drag && outcome.handled) drag.currentAction = outcome.action;
     const response = { accept: outcome.handled };

package/src/cocoa/fonts.js

@@ -17,7 +17,7 @@
 // fontShapeText / fontWithSize / ctxDrawGlyphs).
 //
 // Index spaces, because two meet here: `lines[].start/end` and
-// `runs[].start/end` are UTF-16 code units (what `rangeBands` in nodes.js
+// `runs[].start/end` are UTF-16 code units (what `rangeBands` in nodes/text.js
 // compares against), while `caretPosition()` takes and `indexAt()` returns
 // code points (what the selection and caret code speak). CoreText itself is
 // UTF-16 end to end; the code-point conversion happens at this boundary and
@@ -936,7 +936,7 @@ export class CocoaFontManager {
     }
     // A width offer of zero is a question, not a degenerate layout: yoga
     // asks it to find the node's min-content floor (`minWidth: 'auto'`,
-    // nodes.js). It used to fall into the `undefined` below and answer
+    // nodes/window/floors.js). It used to fall into the `undefined` below and answer
     // max-content — the whole paragraph on one line — so a `<text>` in a
     // flex item held its container open at its longest line and two equal
     // columns came out 823px and 34px wide. `brokenAtEveryOpportunity` is
@@ -944,7 +944,7 @@ export class CocoaFontManager {
     const minContent = Number.isFinite(maxWidth) && maxWidth <= 0;
     // Whether this paragraph is one that ends in a `…`. Both halves: ntk
     // elides off the line *count*, so an ellipsis with nothing to cap can
-    // never fire (nodes.js `_maxLines`), and neither can this.
+    // never fire (nodes/text.js `_maxLines`), and neither can this.
     const elides = overflow === 'ellipsis' && Number.isFinite(maxLines);
     // An eliding paragraph's floor is the mark, not its longest word, and
     // it is cut here because the native cannot cut without a width to cut

package/src/cocoa/glarea.js

@@ -161,7 +161,7 @@ export class CocoaGLArea {
     if (this.destroyed) return;
     this.rect = rect;
     const s = this.scale;
-    this._native.setLayerProps(this.layer, {
+    this._setLayerProps({
       frame: [rect.x / s, rect.y / s, rect.width / s, rect.height / s],
       // above both presenters' content: the surface presenter's contents
       // live on the root layer itself, the layers presenter's visuals top
@@ -193,8 +193,25 @@ export class CocoaGLArea {
   }
 
   map() {
-    if (!this.destroyed) {
-      this._native.setLayerProps(this.layer, { hidden: false });
+    if (!this.destroyed) this._setLayerProps({ hidden: false });
+  }
+
+  /**
+   * Everything this layer is handed goes out with Core Animation's implicit
+   * actions off. The layer is ours, not a presenter's, so no frame's
+   * transaction covers it, and a bare set animates each key for a quarter
+   * of a second from wherever the layer was: the surface grew into place
+   * at mount and trailed every step of a live resize. A present needs
+   * nothing here — `setLayerContentsIOSurface` opens its own transaction
+   * for the flip.
+   */
+  _setLayerProps(props) {
+    const native = this._native;
+    native.txBegin({ disableActions: true });
+    try {
+      native.setLayerProps(this.layer, props);
+    } finally {
+      native.txCommit();
     }
   }
 

package/src/cocoa/main.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `react-x11/cocoa-main` — the cocoa backend's threaded mode, a side-effect
+ * entry for `node --import` (`bun --preload`): the app's entry runs on a
+ * worker while AppKit keeps the main thread, so menus, drags, live resizes
+ * and modal panels no longer stop the app's JS. Does nothing off macOS.
+ * No exports.
+ */
+export {};

package/src/cocoa/main.js

@@ -0,0 +1,43 @@
+// react-x11/cocoa-main — threaded mode asked for by name, for `--import`:
+//
+//   node --import react-x11/cocoa-main app.jsx
+//   bun --preload react-x11/cocoa-main app.jsx
+//
+// Threaded mode is the default on macOS without it: the first import of
+// react-x11 moves the app onto a worker (src/cocoa/relaunch.js). This does
+// the same before the entry is even loaded, and skips the checks that keep
+// the automatic move from firing where it should not — so it is the way in
+// for an app the automatic move declines (react-x11 imported late, say),
+// and it spares the main thread from loading the entry's imports once for
+// nothing (docs/packaging.md).
+//
+// On the worker it starts, Node runs this `--import` again, before the
+// entry, and it sets the worker up there — earlier than the package's own
+// import would (Bun does not apply a `--preload` to a Worker, and gets the
+// import's). Anywhere else it does nothing, so one command line serves
+// every platform: on Linux the entry runs as it would without it, and so
+// does a Worker the app starts itself (it inherits this `--import`).
+import { isMainThread, workerData } from 'node:worker_threads';
+
+import { loadNative } from './native.js';
+import { bootstrapWorker, relaunch } from './relaunch.js';
+
+if (!isMainThread && workerData?.reactX11State) {
+  bootstrapWorker(workerData.reactX11State);
+} else if (isMainThread && process.platform === 'darwin') {
+  const entry = process.argv[1];
+  if (!entry) {
+    throw new Error(
+      'react-x11/cocoa-main: no entry script to run — start the app with ' +
+        '`node --import react-x11/cocoa-main app.js`.',
+    );
+  }
+  const native = loadNative();
+  if (typeof native.runMain !== 'function') {
+    throw new Error(
+      'react-x11/cocoa-main: the installed @windowkit/appkit has no ' +
+        'runMain() — threaded mode needs bridge 0.10 or later.',
+    );
+  }
+  relaunch(entry, native);
+}

package/src/cocoa/panehost.js

@@ -29,11 +29,21 @@ export class CocoaPaneHost {
       return;
     }
     this._rect = { ...rect };
-    this._native.setLayerProps(this.layer, {
-      frame: [rect.x / s, rect.y / s, rect.width / s, rect.height / s],
-      zPosition: 1e7,
-      hidden: false,
-    });
+    // Actions off: the layer is ours, not a presenter's, so no frame's
+    // transaction covers it, and a bare set tweens the pane into place at
+    // mount and after every resize — the trap CocoaGLArea._setLayerProps
+    // describes.
+    const native = this._native;
+    native.txBegin({ disableActions: true });
+    try {
+      native.setLayerProps(this.layer, {
+        frame: [rect.x / s, rect.y / s, rect.width / s, rect.height / s],
+        zPosition: 1e7,
+        hidden: false,
+      });
+    } finally {
+      native.txCommit();
+    }
   }
 
   /**

package/src/cocoa/presenter.js

@@ -26,12 +26,9 @@
 // knowing.
 import { cssColorStraight } from 'ntk';
 
-import {
-  Node,
-  addDamageRect,
-  damageToPaint,
-  intersectRects,
-} from '../nodes.js';
+import { Node } from '../nodes/node.js';
+import { addDamageRect, damageToPaint } from '../nodes/damage.js';
+import { intersectRects } from '../nodes/rects.js';
 import { EASING_CONTROL_POINTS, TRANSITION_CONTROL_POINTS } from '../styles.js';
 import { CocoaContext2D } from './context2d.js';
 
@@ -489,7 +486,7 @@ export function propBoxProps(node, app, scale, parentOrigin, order) {
 // --- animations the render server runs ---------------------------------------
 //
 // The node model keeps deciding what is animating and when it ends
-// (nodes.js `_retarget` / `_updateLoops`); what moves here is who
+// (nodes/animation.js `_retarget` / `_updateLoops`); what moves here is who
 // interpolates. Taken means the node's style goes to its target — the
 // layer's model value, sent by the next frame's property diff — and that
 // frame attaches an explicit animation carrying the pixels there; no frame
@@ -594,7 +591,12 @@ export class LayerAnimations {
         // transition reverses from where it got to" means here. A colour
         // cannot be additive, so the one before it is replaced.
         this._removeLive(node, prop);
-        const shown = this.native.presentationValue?.(layer, map.keyPath);
+        // On a worker the render server's value is an answer that comes
+        // later (windowkit/appkit#52), and the animation is added now: it
+        // runs from the declared value instead.
+        const shown = this.app._threaded
+          ? null
+          : this.native.presentationValue?.(layer, map.keyPath);
         opts.from = Array.isArray(shown) ? shown : this._value(map, entry.from);
         opts.to = this._value(map, entry.to);
         opts.timing = TRANSITION_CONTROL_POINTS;
@@ -806,7 +808,9 @@ export class CocoaLayerPresenter {
       }
       presented = true;
     } finally {
-      native.txCommit();
+      // the size this frame was laid out at, which a worker's live resize
+      // waits for (CocoaWindow._flip); the main thread's commit ignores it
+      native.txCommit(this.window._frameSize?.());
       this._claims = null;
       // a frame that threw half-way presents what it got to; the claims it
       // was answering are still owed, so the next frame answers them again

package/src/cocoa/promotion.js

@@ -32,12 +32,9 @@
 // clock. Overlays, toasts, drag ghosts, spinners and floating cards pass by
 // construction; a hover fade on a row in the middle of a list does not,
 // and stays on the clock. docs/macos.md §"Layer promotion" is the account.
-import {
-  BoxNode,
-  addDamageRect,
-  damageToPaint,
-  intersectRects,
-} from '../nodes.js';
+import { BoxNode } from '../nodes/box.js';
+import { addDamageRect, damageToPaint } from '../nodes/damage.js';
+import { intersectRects } from '../nodes/rects.js';
 import { resolveBorderWidths } from '../styles.js';
 import {
   LayerAnimations,
@@ -181,7 +178,7 @@ function scrollbarStrip(bar, scale) {
  * The surface window's promoted nodes: which ones have a layer, what each
  * layer shows, and the animations the render server runs on them.
  * `frame()` is the whole of the per-frame work, called by the window from
- * nodes.js's `prepareFrame` seam — after layout, before the damage is taken.
+ * the `prepareFrame` seam in nodes/window/flush.js — after layout, before the damage is taken.
  */
 export class CocoaPromotion {
   constructor(window) {