react-x11 2.11.0 → 2.13.0

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,
@@ -145,6 +142,18 @@ function paintsSomething(node) {
   return Boolean(node.isScroller?.());
 }
 
+/**
+ * Inside a `<glarea>`: drawn on a pane above the surface (src/gloverlay.js).
+ * A layer of its own would sit on the root layer *under* the GL layer, so a
+ * promoted node there would vanish behind the surface it is drawn over.
+ */
+function insideGlArea(node) {
+  for (let n = node.parent; n && !n.isWindow; n = n.parent) {
+    if (n.isGlArea) return true;
+  }
+  return false;
+}
+
 /**
  * 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
@@ -153,6 +162,7 @@ function paintsSomething(node) {
  */
 function promotableNode(node) {
   if (node.destroyed || !plainBox(node)) return false;
+  if (insideGlArea(node)) return false;
   if (!stylePaintsPlain(node, node._targetStyle ?? node.style)) return false;
   if (node.isScroller?.()) return false;
   return !paintsOutline(node);
@@ -181,7 +191,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) {

package/src/cocoa/relaunch.js

@@ -0,0 +1,207 @@
+// Threaded mode by default (docs/macos.md §"JS on a worker"). On macOS the
+// process main thread is AppKit's — the only thread it lets own a window —
+// and while the app's JS runs there, every menu, drag, live resize and
+// modal panel stops it. So the first import of react-x11 on the main thread
+// moves the app onto a `worker_threads` Worker before the app's own code has
+// run, and parks the main thread for AppKit.
+//
+// It can be that early because of how modules evaluate: an entry's imports
+// finish before its own body starts, so when react-x11 is being evaluated
+// the entry has not run a line. The worker is started on that entry, and
+// the main thread never returns to it — `process.exit` is the only way out.
+// Nothing here is a top-level await, which would cost the CommonJS builds
+// (docs/packaging.md, tier 3) and `require()` of the package.
+//
+// The main thread waits without AppKit, on shared memory, until the worker
+// says what it needs: the first cocoa `createRoot` asks for it
+// (`requestAppKit`, src/cocoa/threaded.js), and an app that never makes one
+// — an X11 app on XQuartz, a script — never launches AppKit and never gets
+// a Dock tile.
+//
+// `react-x11/cocoa-main` (src/cocoa/main.js) is the same move, asked for by
+// name: it runs before the entry is even loaded, and skips the checks.
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { isMainThread, SHARE_ENV, Worker } from 'node:worker_threads';
+
+import { loadNative } from './native.js';
+import {
+  bindRelaunchState,
+  forwardSignals,
+  installStdio,
+  onWorkerEnd,
+  openThreadedChannel,
+  printUncaught,
+  RELAUNCH,
+  routeExit,
+  signalEnded,
+} from './threaded.js';
+
+// Set once the worker is set up, process-wide: the explicit launcher and
+// the package's own import can both reach `bootstrapWorker`, and from two
+// copies of the package the bridge would refuse the second `connect`.
+const BOOTED = Symbol.for('react-x11.cocoa.workerBooted');
+
+// How long the main thread waits, once AppKit's run is over, for the
+// worker's own exit handlers to finish — they run to the end in a process
+// of their own, and should here; a handler that hangs must not hang the
+// process for ever.
+const WORKER_END_MS = 5000;
+
+/**
+ * Why this import should not move the app onto a worker, or null when it
+ * should. A pure answer over what the process says about itself, so that
+ * each rule is testable on any OS.
+ */
+export function relaunchVeto({
+  isMainThread: main,
+  platform,
+  env,
+  entry,
+  compiled,
+  late,
+}) {
+  if (!main) return 'not the main thread';
+  if (platform !== 'darwin') return 'not macOS';
+  if (env.REACT_X11_THREADED === '0') return 'REACT_X11_THREADED=0';
+  if (env.REACT_X11_BACKEND && env.REACT_X11_BACKEND !== 'cocoa') {
+    return `REACT_X11_BACKEND=${env.REACT_X11_BACKEND}`;
+  }
+  // a REPL, `node -e`, or an entry that is not a file a worker can load
+  if (!entry) return 'no entry script';
+  // a single executable carries its entry inside the binary, where a worker
+  // cannot load it from (docs/packaging.md)
+  if (compiled) return 'a single executable';
+  // a test runner's file is a test, not an app: node --test, bun test,
+  // vitest, jest
+  if (
+    env.NODE_TEST_CONTEXT ||
+    env.VITEST ||
+    env.JEST_WORKER_ID ||
+    env.NODE_ENV === 'test'
+  ) {
+    return 'a test runner';
+  }
+  // Imported after the app started running — a dynamic import from a
+  // timer, say. Relaunching would run again, on the worker, everything the
+  // entry has already done on this thread.
+  if (late) return 'imported after the app started running';
+  return null;
+}
+
+/** What `relaunchVeto` reads, from this process. */
+export function describeProcess(moduleUrl) {
+  const bun = globalThis.Bun;
+  const entry = bun ? bun.main : process.argv[1];
+  return {
+    isMainThread,
+    platform: process.platform,
+    env: process.env,
+    entry: typeof entry === 'string' && fs.existsSync(entry) ? entry : null,
+    compiled: compiledExecutable(bun),
+    late: startedRunning(bun, moduleUrl, entry),
+  };
+}
+
+function compiledExecutable(bun) {
+  // `bun build --compile` serves its modules from a virtual filesystem
+  if (bun) return /^\/\$bunfs\/|~BUN/.test(String(bun.main));
+  try {
+    return createRequire(process.execPath)('node:sea').isSea();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether the entry's own code has started. Node's event loop has not
+ * turned while the entry's static imports evaluate —
+ * `performance.nodeTiming.loopStart` is -1 until it does. Bun reports 1
+ * there from the first line; what tells in Bun is the entry's record in the
+ * module cache, which is there once the entry has been evaluated and
+ * absent while its imports are (both measured, Node 26 and Bun 1.4).
+ */
+function startedRunning(bun, moduleUrl, entry) {
+  if (!bun) return performance.nodeTiming?.loopStart > 0;
+  try {
+    return Boolean(createRequire(moduleUrl).cache?.[entry]?.loaded);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The import-time move (src/bootstrap.js): relaunch when nothing vetoes it
+ * and a bridge that can run AppKit's loop is installed. Returns why it did
+ * not, for anyone asking; when it does, it does not return.
+ */
+export function relaunchOnImport(moduleUrl) {
+  const veto = relaunchVeto(describeProcess(moduleUrl));
+  if (veto) return veto;
+  let native;
+  try {
+    native = loadNative();
+  } catch {
+    // no bridge: `createRoot` falls back to X11 the way it always has
+    return 'no cocoa bridge';
+  }
+  if (typeof native.runMain !== 'function') return 'the bridge has no runMain';
+  return relaunch(describeProcess(moduleUrl).entry, native);
+}
+
+/**
+ * The worker's side, set up the moment it imports react-x11: after it the
+ * app cannot tell it is on a worker, short of asking — its logs reach the
+ * terminal, `process.exit` ends the process, a crash is printed, and a
+ * Ctrl-C reaches its `process.on('SIGINT')` (src/cocoa/threaded.js). What
+ * the app imports before react-x11 runs before this, so a module that logs
+ * as it loads should come after it.
+ */
+export function bootstrapWorker(state) {
+  if (globalThis[BOOTED]) return;
+  globalThis[BOOTED] = true;
+  const native = loadNative();
+  installStdio();
+  bindRelaunchState(state);
+  printUncaught();
+  routeExit(native);
+  onWorkerEnd(signalEnded);
+  openThreadedChannel(native).subscribe(forwardSignals());
+}
+
+/**
+ * Start the app's entry on a worker and park this thread — waiting, then
+ * in AppKit's run once the worker asks for it — until the app is done.
+ * Never returns.
+ */
+export function relaunch(entry, native) {
+  const state = new Int32Array(new SharedArrayBuffer(8));
+  // The worker's entry is the app's own, so nothing has to ship beside it —
+  // a bundle (docs/packaging.md, tier 2) is one file, and a worker entry of
+  // 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.
+  new Worker(entry, {
+    argv: process.argv.slice(2),
+    execArgv: process.execArgv,
+    env: SHARE_ENV,
+    workerData: { reactX11State: state.buffer },
+  });
+  for (;;) {
+    Atomics.wait(state, 0, RELAUNCH.WAITING);
+    const now = Atomics.load(state, 0);
+    if (now === RELAUNCH.APPKIT) break;
+    if (now === RELAUNCH.ENDED) process.exit(Atomics.load(state, 1));
+  }
+  native.initApp();
+  const code = native.runMain();
+  // Back from AppKit: the app asked to exit — its `process.exit`, a crash,
+  // a signal nobody listened for — and `code` is what it asked for, or the
+  // worker ended without asking. Its exit handlers may still be running;
+  // the worker says when they are done.
+  Atomics.wait(state, 0, RELAUNCH.APPKIT, WORKER_END_MS);
+  const ended = Atomics.load(state, 0) === RELAUNCH.ENDED;
+  process.exit(code ?? (ended ? Atomics.load(state, 1) : 0));
+}

package/src/cocoa/threaded.js

@@ -0,0 +1,246 @@
+// Threaded mode's worker half (docs/macos.md §"JS on a worker: a UI thread
+// of the bridge's own"): with the launcher (src/cocoa/main.js) holding the
+// process main thread in the bridge's `runMain()`, the app's JS runs on a
+// `worker_threads` Worker, and this module is what that worker needs to
+// talk to the parked thread — the one event channel the bridge allows, and
+// the three things a Worker does differently when its main thread never
+// returns to its event loop.
+//
+// The channel's existence is the switch: `createCocoaApp` asks
+// `threadedChannel()`, and null is pump mode.
+import { Console } from 'node:console';
+import fs from 'node:fs';
+import { constants } from 'node:os';
+import { Writable } from 'node:stream';
+import tty from 'node:tty';
+import { inspect } from 'node:util';
+
+let channel = null;
+
+// The relaunch's shared state (src/cocoa/relaunch.js), [state, exit code]:
+// the main thread waits on it, without AppKit, until the worker says what
+// it needs — AppKit, or nothing more because it is done.
+export const RELAUNCH = Object.freeze({ WAITING: 0, APPKIT: 1, ENDED: 2 });
+let relaunchState = null;
+
+/** The worker's end of the relaunch's shared state. */
+export function bindRelaunchState(buffer) {
+  relaunchState = buffer ? new Int32Array(buffer) : null;
+}
+
+/**
+ * Ask the main thread for AppKit, and wait until its run has started. The
+ * main thread waits without it, so an app that never makes a cocoa root
+ * never launches it; the first cocoa `createRoot` does. Until `runMain`
+ * runs the bridge has published nothing — an app that asked `listScreens()`
+ * then got `[]` and took scale 1 on a 2x panel (measured) — so the wait is
+ * not optional.
+ */
+export async function requestAppKit(native, state = relaunchState) {
+  if (state && Atomics.load(state, 0) === RELAUNCH.WAITING) {
+    Atomics.store(state, 0, RELAUNCH.APPKIT);
+    Atomics.notify(state, 0);
+  }
+  while (!native.threaded()) await new Promise((r) => setTimeout(r, 1));
+}
+
+/** The worker is done, with `code`: the main thread ends the process. */
+export function signalEnded(code, state = relaunchState) {
+  if (!state) return;
+  Atomics.store(state, 1, Number.parseInt(code, 10) || 0);
+  Atomics.store(state, 0, RELAUNCH.ENDED);
+  Atomics.notify(state, 0);
+}
+
+/**
+ * Call `fn(code)` when the worker exits, after every exit listener the app
+ * has — its last word. The main thread ends the process on it, and an app's
+ * `process.on('exit')` handler must have finished by then, as it has in a
+ * process of its own. Kept last by re-adding it whenever the app adds one:
+ * Node runs a worker's exit listeners through `process.emit` and Bun calls
+ * them directly (measured), so wrapping the emit would cover only Node.
+ */
+export function onWorkerEnd(fn, proc = process) {
+  const add = proc.on;
+  const last = (code) => fn(code ?? proc.exitCode ?? 0);
+  add.call(proc, 'exit', last);
+  for (const name of [
+    'on',
+    'addListener',
+    'once',
+    'prependListener',
+    'prependOnceListener',
+  ]) {
+    const method = proc[name];
+    proc[name] = function (event, listener) {
+      const out = method.call(this, event, listener);
+      if (event === 'exit' && listener !== last) {
+        proc.removeListener('exit', last);
+        add.call(proc, 'exit', last);
+      }
+      return out;
+    };
+  }
+}
+
+/**
+ * Print an uncaught error the way Node prints one, from the worker itself.
+ * Node hands a worker's uncaught error to its parent as an event, and the
+ * parent here is parked for good — it ends the process on the worker's
+ * word and never runs its event loop again to hear it. Only when nothing
+ * handles the error: an app's own `uncaughtException` handler means it is
+ * not uncaught.
+ */
+export function printUncaught(
+  proc = process,
+  write = (s) => proc.stderr.write(s),
+) {
+  proc.on('uncaughtExceptionMonitor', (err) => {
+    if (proc.listenerCount('uncaughtException') > 0) return;
+    write(`${inspect(err)}\n`);
+  });
+}
+
+/** The open channel, or null outside threaded mode. */
+export function threadedChannel() {
+  return channel;
+}
+
+/**
+ * `connect` once, and fan each batch out to whoever subscribed: the
+ * bootstrap for signals, `CocoaApp` for everything else. The bridge takes
+ * one connection per environment, and the bootstrap needs it before the
+ * app's entry has run — a Ctrl-C during startup is already an event.
+ *
+ * What a subscriber throws leaves the delivery once every subscriber has
+ * had the batch, and the bridge makes it the worker's uncaught exception
+ * (windowkit/appkit#65): the launcher prints it and the process exits 1, as
+ * a throw from a click handler ends an X11 app.
+ */
+export function openThreadedChannel(native) {
+  if (channel) return channel;
+  const listeners = new Set();
+  native.connect((batch) => {
+    let failed = false;
+    let failure;
+    for (const fn of [...listeners]) {
+      try {
+        fn(batch);
+      } catch (err) {
+        if (!failed) failure = err;
+        failed = true;
+      }
+    }
+    if (failed) throw failure;
+  });
+  channel = {
+    native,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+  };
+  return channel;
+}
+
+/** Forget the channel — the tests' way to run pump and threaded apps in one
+ * process. */
+export function resetThreadedChannelForTests() {
+  channel = null;
+}
+
+/**
+ * A stream that writes straight to `fd`, synchronously. A Worker's own
+ * `process.stdout` forwards every write through its parent's event loop,
+ * and the parent here is parked in `[NSApp run]`: without this, everything
+ * the app logs is lost (measured). Synchronous, so a line written just
+ * before an exit is not lost either; a pipe the main thread opened
+ * non-blocking answers EAGAIN when full, and the write waits it out.
+ */
+export function fdStream(fd, write = fs.writeSync) {
+  const stream = new Writable({
+    write(chunk, encoding, done) {
+      try {
+        for (let off = 0; off < chunk.length;) {
+          try {
+            off += write(fd, chunk, off);
+          } catch (err) {
+            if (err.code !== 'EAGAIN') throw err;
+          }
+        }
+      } catch (err) {
+        done(err);
+        return;
+      }
+      done();
+    },
+  });
+  stream.fd = fd;
+  stream.isTTY = tty.isatty(fd);
+  // what a colouring library asks a TTY stream, answered as a TTY's would be
+  if (stream.isTTY) {
+    stream.getColorDepth = tty.WriteStream.prototype.getColorDepth;
+    stream.hasColors = tty.WriteStream.prototype.hasColors;
+  }
+  return stream;
+}
+
+/**
+ * Stdout and stderr on fds 1 and 2, and a console over them — the console
+ * too, because Bun's writes past `process.stdout` altogether.
+ */
+export function installStdio(proc = process, global = globalThis) {
+  const stdout = fdStream(1);
+  const stderr = fdStream(2);
+  Object.defineProperty(proc, 'stdout', {
+    configurable: true,
+    get: () => stdout,
+  });
+  Object.defineProperty(proc, 'stderr', {
+    configurable: true,
+    get: () => stderr,
+  });
+  Object.defineProperty(global, 'console', {
+    configurable: true,
+    writable: true,
+    value: new Console({ stdout, stderr }),
+  });
+}
+
+/**
+ * `process.exit` inside a Worker ends the worker and nothing else: the main
+ * thread stays in `[NSApp run]` with nothing left to end it, a Dock tile
+ * for an app that is gone (measured). So an exit asks the main thread
+ * first — `requestExit` makes `runMain` return the code, and the launcher
+ * ends the process with it — and then ends the worker as before, so the
+ * code after an exit still never runs. Node's own handling of an uncaught
+ * error calls `process.exit()` too, which is how a crash reaches the
+ * launcher with its code.
+ */
+export function routeExit(native, proc = process) {
+  const exitWorker = proc.exit.bind(proc);
+  proc.exit = (code) => {
+    const n = Number.parseInt(code ?? proc.exitCode ?? 0, 10);
+    native.requestExit(Number.isFinite(n) ? n : 0);
+    return exitWorker(code);
+  };
+}
+
+/**
+ * A handler for the channel that gives the worker its signals back. Node
+ * delivers SIGINT, SIGTERM and SIGHUP to the main thread only, which is
+ * parked, so the bridge reads them there and sends each as an event; this
+ * re-emits it on the worker's `process`, where the app's
+ * `process.on('SIGINT')` is. A signal nobody listens for ends the process
+ * the way the signal would have: 128 + its number.
+ */
+export function forwardSignals(proc = process) {
+  return (batch) => {
+    for (const ev of batch) {
+      if (ev.type !== 'signal') continue;
+      const name = ev.signal;
+      if (proc.listenerCount(name) > 0) proc.emit(name, name);
+      else proc.exit(128 + (constants.signals[name] ?? 0));
+    }
+  };
+}