react-x11 2.45.3 → 2.46.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.45.3",
+  "version": "2.46.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [
@@ -221,6 +221,10 @@
     "./cocoa-main": {
       "types": "./src/cocoa/main.d.ts",
       "default": "./src/cocoa/main.js"
+    },
+    "./frame/child": {
+      "types": "./src/frame/child.d.ts",
+      "default": "./src/frame/child.js"
     }
   },
   "types": "./src/index.d.ts"

package/src/cocoa/relaunch.js

@@ -143,6 +143,19 @@ export const WORKER_START = `(function (process, global) {
 // process for ever.
 const WORKER_END_MS = 5000;
 
+// Where Node starts an app (`startedRunning`): the script that loads the
+// `--require` preloads and then the entry, and the module that runs the
+// entry, an ES module's graph from an async function.
+const ENTRY_POINT = new Set([
+  'node:internal/main/run_main_module',
+  'node:internal/modules/run_main',
+]);
+
+// How a process is started under an ES module loader, as a flag of its own
+// or in NODE_OPTIONS: `--import tsx`, `--import=tsx`, `--loader
+// ts-node/esm`, `--experimental-loader ./hooks.mjs`.
+const LOADER_FLAG = /^--(?:import|loader|experimental-loader)(?:=|$)/;
+
 /**
  * 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
@@ -152,6 +165,8 @@ export function relaunchVeto({
   isMainThread: main,
   platform,
   env,
+  execArgv,
+  node,
   entry,
   compiled,
   late,
@@ -184,13 +199,33 @@ export function relaunchVeto({
   ) {
     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.
+  // Imported after the app started running: by an `import()` from a timer,
+  // say, or one the entry's body awaits. 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';
+  // Started under an ES module loader, before Node 24. The worker gets the
+  // loader's flags, and whether its hooks follow is the loader's to say:
+  // tsx, the one an app is likeliest to run under, keeps them to the main
+  // thread on Node 20 and 22 — before 22.22.3, by tsx 4.23's own check —
+  // and a worker without them stops on the entry's first .jsx or .ts module
+  // (measured, 20.20 and 22.16). No loader can be asked before the move, so
+  // any `--import` or `--loader` counts. From 24 an app under one moves,
+  // and tsx follows it there from 4.21.1 on 24.11.1 (an older one does not,
+  // docs/macos.md); `react-x11/cocoa-main` moves one on 20 or 22 whose
+  // loader follows.
+  if (node && node < 24 && startedUnderLoader(execArgv, env.NODE_OPTIONS)) {
+    return 'an ES module loader before Node 24';
+  }
   return null;
 }
 
+/** Whether node's flags, its own or NODE_OPTIONS', name an ES module loader. */
+function startedUnderLoader(execArgv = [], nodeOptions = '') {
+  return [...execArgv, ...nodeOptions.split(/\s+/)].some((flag) =>
+    LOADER_FLAG.test(flag),
+  );
+}
+
 /** What `relaunchVeto` reads, from this process. */
 export function describeProcess(moduleUrl) {
   const bun = globalThis.Bun;
@@ -199,6 +234,9 @@ export function describeProcess(moduleUrl) {
     isMainThread,
     platform: process.platform,
     env: process.env,
+    execArgv: process.execArgv,
+    // Node's major version; Bun answers with one of its own choosing
+    node: bun ? null : Number(process.versions.node.split('.')[0]),
     entry: typeof entry === 'string' && fs.existsSync(entry) ? entry : null,
     compiled: compiledExecutable(bun),
     late: startedRunning(bun, moduleUrl, entry),
@@ -216,15 +254,36 @@ function compiledExecutable(bun) {
 }
 
 /**
- * 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).
+ * Whether the entry's own code has started: whether this import is one the
+ * app made after its start, rather than part of it.
+ *
+ * Node tells by where the import is evaluated from. It starts an app from
+ * two modules of its own (`ENTRY_POINT`): a CommonJS entry, and every
+ * `require()` of its first run and of a `--require` preload, evaluate under
+ * them synchronously, and an ES module entry's graph — static imports, an
+ * `--import` preload's — from an async function there, which V8 keeps on
+ * the stack as an async frame. An `import()` is evaluated by a job of its
+ * own, whose stack ends in the module loader, or in the app's own code when
+ * that awaits it: an `await import()` in the entry's body, an async
+ * function of the app's. Measured on Node 20.20, 22.16, 23.2, 24.12, 25.4
+ * and 26.0, static imports nested and behind a module with a top-level
+ * await, and under tsx, `--experimental-loader`, source maps and a stack
+ * trace limit of 0. A Node that moved those modules would read every
+ * import as late, which keeps the app where it is rather than running it
+ * twice; test/cocoa-relaunch.test.js would say so on any OS.
+ *
+ * `performance.nodeTiming.loopStart`, -1 until the event loop turns, is the
+ * public signal and is wrong both ways: Node 20 and 22 turn the loop while
+ * they load an ES module entry, so no such entry moved there, and Node 24
+ * and later evaluate an `import()` the entry makes before the loop's first
+ * turn, so an app that made one moved and ran its entry twice.
+ *
+ * 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 (measured, Bun 1.4).
  */
 function startedRunning(bun, moduleUrl, entry) {
-  if (!bun) return performance.nodeTiming?.loopStart > 0;
+  if (!bun) return !evaluatedFromEntryPoint();
   try {
     return Boolean(createRequire(moduleUrl).cache?.[entry]?.loaded);
   } catch {
@@ -232,13 +291,40 @@ function startedRunning(bun, moduleUrl, entry) {
   }
 }
 
+/** Whether this stack, async frames and all, comes from `ENTRY_POINT`. */
+function evaluatedFromEntryPoint() {
+  const { prepareStackTrace, stackTraceLimit } = Error;
+  let sites;
+  try {
+    // Reflect.set: an Error the app has frozen is not a reason to throw
+    // from its import of react-x11
+    Reflect.set(Error, 'stackTraceLimit', Infinity);
+    Reflect.set(Error, 'prepareStackTrace', (_, callSites) => callSites);
+    const held = {};
+    Error.captureStackTrace(held);
+    sites = held.stack;
+  } finally {
+    Reflect.set(Error, 'prepareStackTrace', prepareStackTrace);
+    Reflect.set(Error, 'stackTraceLimit', stackTraceLimit);
+  }
+  if (!Array.isArray(sites)) return false;
+  for (const site of sites) {
+    const file = site.getFileName() ?? '';
+    if (ENTRY_POINT.has(file)) return true;
+    // the app's own code awaits this import, so it has run already
+    if (site.isAsync() && !file.startsWith('node:')) return false;
+  }
+  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));
+  const facts = describeProcess(moduleUrl);
+  const veto = relaunchVeto(facts);
   if (veto) return veto;
   let native;
   try {
@@ -248,7 +334,7 @@ export function relaunchOnImport(moduleUrl) {
     return 'no cocoa bridge';
   }
   if (typeof native.runMain !== 'function') return 'the bridge has no runMain';
-  return relaunch(describeProcess(moduleUrl).entry, native);
+  return relaunch(facts.entry, native);
 }
 
 /**

package/src/frame/child.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `react-x11/frame/child` — the entry a `<Frame>` forks: a pane process's
+ * whole bootstrap, over the IPC channel `fork()` sets up. **Resolved, not
+ * imported**: a `transport` that starts the pane its own way — under a
+ * sandbox, with a runtime of its own choosing — forks
+ * `fileURLToPath(import.meta.resolve('react-x11/frame/child'))`, and
+ * importing it anywhere else exits the process. No exports.
+ */
+export {};

package/src/frame/index.js

@@ -73,21 +73,22 @@ const childPath = () =>
 
 /** The default transport: fork this package's child entry. `execArgv` is
  * inherited, which is what carries a dev loader (tsx, the refresh loader)
- * into the pane; a bundled app forks plain JS and needs none. */
-function forkTransport({ src, display }) {
+ * into the pane; a bundled app forks plain JS and needs none. The pane's
+ * own flags and environment (`<Frame execArgv env>`) go on top. */
+function forkTransport({ src, display, execArgv = [], env = {} }) {
   const child = fork(childPath(), [], {
     serialization: 'advanced',
     // dev loaders (tsx, the refresh loader) follow into the pane; the test
     // runner's own flags must not — `--test` in execArgv would run the pane
-    // entry as a test file
-    execArgv: process.execArgv.filter(
-      (a) => a !== '--test' && !a.startsWith('--test-'),
-    ),
-    env: {
-      ...process.env,
-      REACT_X11_FRAME: '1',
-      ...(display ? { DISPLAY: display } : {}),
-    },
+    // entry as a test file. The pane's come after, so a flag it names is
+    // the one in force where the two disagree.
+    execArgv: [
+      ...process.execArgv.filter(
+        (a) => a !== '--test' && !a.startsWith('--test-'),
+      ),
+      ...execArgv,
+    ],
+    env: paneEnv(env, display),
   });
   void src; // resolved by the child from the hello, not from argv
   return {
@@ -121,6 +122,58 @@ function forkTransport({ src, display }) {
   };
 }
 
+/**
+ * The environment a pane process starts with: this one's, with what the
+ * `<Frame>` names over it — `undefined` takes a variable away — and then
+ * the two that are not the app's to set: `REACT_X11_FRAME`, which is how a
+ * pane knows it is one (`isFramed`), and `DISPLAY`, which `display` names.
+ */
+function paneEnv(env, display) {
+  const out = { ...process.env };
+  for (const [name, value] of Object.entries(env)) {
+    if (value === undefined) delete out[name];
+    else out[name] = value;
+  }
+  out.REACT_X11_FRAME = '1';
+  if (display) out.DISPLAY = display;
+  return out;
+}
+
+/**
+ * What a pane's process is started with, checked and as one string: the
+ * session's key, so that an `execArgv` array or an `env` object written in
+ * place — a new one each render — restarts nothing, and one that says
+ * something else restarts the pane. Throws on what a fork cannot take,
+ * which the session reports as a `spawn` failure.
+ */
+function launchOf(execArgv, env) {
+  if (
+    execArgv !== undefined &&
+    (!Array.isArray(execArgv) || execArgv.some((a) => typeof a !== 'string'))
+  ) {
+    throw new TypeError(
+      'react-x11: <Frame execArgv> is an array of strings — the flags the ' +
+        "pane's process is started with.",
+    );
+  }
+  if (
+    env !== undefined &&
+    (env === null ||
+      typeof env !== 'object' ||
+      Object.values(env).some((v) => v !== undefined && typeof v !== 'string'))
+  ) {
+    throw new TypeError(
+      "react-x11: <Frame env> maps a variable's name to a string, or to " +
+        'undefined to take it away.',
+    );
+  }
+  // `undefined` is kept apart from a variable left alone, which
+  // JSON.stringify would drop
+  return JSON.stringify([execArgv ?? [], env ?? {}], (_, v) =>
+    v === undefined ? { unset: true } : v,
+  );
+}
+
 function srcString(src) {
   if (src !== null && typeof src === 'object' && typeof src.href === 'string') {
     return src.href;
@@ -220,6 +273,8 @@ export function Frame({
   props = EMPTY_PROPS,
   style,
   display,
+  execArgv,
+  env: processEnv,
   bridge = true,
   fallback,
   focusable,
@@ -262,8 +317,20 @@ export function Frame({
   const source = srcString(src);
   const makeTransport = transport ?? forkTransport;
   const containerRef = useRef(null);
+  // the pane process's own flags and environment, by what they say
+  let launch;
+  let launchError = null;
+  try {
+    launch = launchOf(execArgv, processEnv);
+  } catch (err) {
+    launch = '';
+    launchError = err;
+  }
+  const paneProcess = useRef(null);
+  paneProcess.current = { execArgv: execArgv ?? [], env: processEnv ?? {} };
 
-  // The session: one child process per (src, display, transport, restart).
+  // The session: one child process per (src, display, the process's flags
+  // and environment, transport, restart).
   // Declared before the update effect so that on the mounting commit the
   // hello goes out first and the update pass sees itself already sent.
   useEffect(() => {
@@ -297,7 +364,13 @@ export function Frame({
 
     let t;
     try {
-      t = makeTransport({ src: source, display });
+      if (launchError) throw launchError;
+      t = makeTransport({
+        src: source,
+        display,
+        execArgv: paneProcess.current.execArgv,
+        env: paneProcess.current.env,
+      });
     } catch (err) {
       fail(Object.assign(err, { phase: 'spawn' }));
       return undefined;
@@ -439,7 +512,7 @@ export function Frame({
       // ask, and everything is unref'd so nothing holds the host open
       if (session.current === s) session.current = null;
     };
-  }, [source, display, generation, makeTransport, canShowPane]);
+  }, [source, display, launch, generation, makeTransport, canShowPane]);
 
   // One update per commit that changed the pane's inputs, props and env in
   // the same message — so a theme flip and the state change that caused it

package/src/types/frame.d.ts

@@ -45,6 +45,22 @@ export interface FrameComponentProps {
   style?: StyleProp;
   /** X display for the pane process; defaults to the inherited `$DISPLAY`. */
   display?: string;
+  /**
+   * Flags for the pane's process, after the ones it inherits from this one
+   * (a dev loader's): `['--max-old-space-size=256']` bounds the pane's heap,
+   * which nothing inside the pane can. They are handed to the runtime that
+   * forks it, so they are that runtime's flags. A change restarts the pane;
+   * the same flags in a new array do not.
+   */
+  execArgv?: readonly string[];
+  /**
+   * Environment variables for the pane's process, over this one's; a value
+   * of `undefined` takes a variable away. `DISPLAY` is `display`'s and
+   * `REACT_X11_FRAME` marks the pane (`isFramed`), so neither can be set
+   * here. A change restarts the pane; the same variables in a new object do
+   * not.
+   */
+  env?: Readonly<Record<string, string | undefined>>;
   /**
    * Which bridged contexts follow the app into this pane: `true` (default)
    * for every registered one — the theme included — `false` for none, or an
@@ -75,10 +91,23 @@ export interface FrameComponentProps {
    * (a loopback pair into `runFrameChild`), and the door to running a pane
    * somewhere other than a child process. Advanced; see docs/frame.md.
    */
-  transport?(options: { src: string; display?: string }): FrameTransport;
+  transport?(options: FrameTransportOptions): FrameTransport;
   ref?: Ref<FrameHandle>;
 }
 
+/** What a transport is asked to start: the pane module, and the display,
+ *  flags and environment `<Frame>` names for its process. The default
+ *  transport forks `react-x11/frame/child` with them. */
+export interface FrameTransportOptions {
+  src: string;
+  display?: string;
+  /** `<Frame execArgv>`, or none: added to what the pane inherits. */
+  execArgv: readonly string[];
+  /** `<Frame env>`, or none: over this process's environment, `undefined`
+   *  taking a variable away. */
+  env: Readonly<Record<string, string | undefined>>;
+}
+
 /** The parent's end of the wire to a pane. */
 export interface FrameTransport {
   /** May throw when the channel is gone or the message will not clone. */