react-x11 2.45.2 → 2.46.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.45.2",
+  "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/app.js

@@ -982,9 +982,12 @@ export class CocoaApp {
    * pane-present and pane-cursor go out. `players` is the
    * host's word that it plays the pane's `<video src>`s, which makes
    * `createPlayer` here — before the pane's first render, which asks.
+   * `displayScale` is the scale the host's window is drawn at, taken here
+   * for the same reason (`adoptPaneScale`).
    */
-  attachPaneChannel(channel, { players = false } = {}) {
+  attachPaneChannel(channel, { players = false, displayScale } = {}) {
     if (!this._paneMode) return;
+    this.adoptPaneScale(displayScale);
     this._paneSend = (msg) => {
       try {
         channel.send(msg);
@@ -1013,6 +1016,7 @@ export class CocoaApp {
         const wnd = msg.window != null ? this._windows.get(msg.window) : pane;
         wnd?._shown?.(msg.seq);
       } else if (msg?.type === 'pane-rect') {
+        this.adoptPaneScale(msg.displayScale);
         pane.setPaneSize(msg.width, msg.height, msg.scale, msg.screen);
         if (typeof msg.live === 'boolean') pane.setLive(msg.live);
         this._flushPaneOutbox();
@@ -1039,6 +1043,46 @@ export class CocoaApp {
     });
   }
 
+  /**
+   * The scale of the window a pane is shown in, as the host says it — in
+   * the hello and in every pane-rect — made this process's. Returns whether
+   * it moved.
+   *
+   * A pane process reads the screens when it starts, and the host read
+   * them when it did. Across a change of the desk between the two the
+   * answers differ: a browser's tabs drawn at 2x and a page forked for a
+   * new tab after the desk went to 1x — a mirror set for a projector — was
+   * laid out at 1x in a frame the host showed at 2x, every length in it
+   * half what it is beside the tabs, and every click it was sent landing
+   * at twice the distance. A pane has no window on a screen of its own;
+   * the host's window is its display, and its scale is the one everything
+   * here multiplies by: the layout, the fonts, the windows the pane opens,
+   * the screen layout their popups are placed against.
+   *
+   * From the hello that is all, before anything is laid out. A tree
+   * already laid out is restyled in the new unit, as a `scale` prop that
+   * moved restyles a subtree. The pane's own window keeps the scale its
+   * pane-rect gives it (`setPaneSize`): that one is the frame's, a
+   * `<box scale>` around the `<Frame>` included, and says how many device
+   * pixels the rect is.
+   */
+  adoptPaneScale(scale) {
+    if (!this._paneMode || !(scale > 0) || !Number.isFinite(scale)) {
+      return false;
+    }
+    if (scale === this.scale) return false;
+    this.scale = scale;
+    setScaleForTests(this, scale, 'frame');
+    setScreensForTests(this, screenLayout(this._screens, scale));
+    this.fonts?.setScale?.(scale);
+    for (const wnd of this._windows.values()) {
+      if (wnd.destroyed) continue;
+      if (wnd !== this._paneWindow) wnd.scale = scale;
+      wnd._reactX11Node?._rescaleSubtree();
+    }
+    return true;
+  }
+
   /**
    * A message about one of the pane's other windows (`CocoaPaneSubwindow`),
    * held until the host's first pane-rect. The host hears a pane's messages

package/src/cocoa/fonts.js

@@ -771,6 +771,31 @@ export class CocoaFontManager {
     this._typesetterUnits = 0;
   }
 
+  /**
+   * Make fonts at another scale from here on — a `<Frame>` pane taking the
+   * host's (`CocoaApp.adoptPaneScale`). Every handle made at the old one is
+   * let go: a size is in device pixels, so the same size at another scale
+   * is another point size, which is another optical size of San Francisco
+   * and another tracking. What the app loaded stays loaded.
+   */
+  setScale(scale) {
+    const next = scale > 0 && Number.isFinite(scale) ? scale : 1;
+    if (next === this._scale) return;
+    this._scale = next;
+    this._scaleArgs = next === 1 ? [] : [next];
+    this._fonts.clear();
+    this._faces.clear();
+    this._sized.clear();
+    this._layouts.clear();
+    // a face CoreText chose sizes itself by copying the handle it arrived
+    // as, and a copy keeps the scale it was made at
+    this._faceByPs.clear();
+    for (const faces of this._registered.values()) {
+      for (const reg of faces) reg.face = null;
+    }
+    this._forgetTypesetters();
+  }
+
   /**
    * A paragraph's typesetter, kept from a layout of the same text at any
    * width. Two thirds of a layout is the text becoming glyphs — the

package/src/cocoa/panewindow.js

@@ -188,6 +188,17 @@ export class CocoaPaneWindow {
     this._post({ type: 'pane-cursor', cursor: name ?? null });
   }
 
+  /**
+   * Tab off an end of the pane's order, handed to the host, which goes on
+   * from the `<Frame>`'s box as from any stop of its own
+   * (`EventManager._tabOut`). Answers whether anyone was there to take it.
+   */
+  tabOut(backwards) {
+    if (this.destroyed || !this.app._paneSend) return false;
+    this._post({ type: 'pane-tab-out', backwards });
+    return true;
+  }
+
   /** A message about this window, to the host. The pane's own names none:
    * the host knows it as the pane (`CocoaPaneSubwindow` names itself). */
   _post(msg) {
@@ -733,6 +744,12 @@ export class CocoaPaneSubwindow extends CocoaPaneWindow {
     this.app._postWindow({ ...msg, window: this.windowId });
   }
 
+  /** A window the pane makes besides its own is no stop in the host's
+   *  order: Tab goes round inside it, as in any window. */
+  tabOut() {
+    return false;
+  }
+
   _send(msg) {
     if (this.destroyed) return;
     this._post({ type: 'pane-window', ...msg });

package/src/cocoa/relaunch.js

@@ -29,18 +29,113 @@ 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');
+const BOOTED_KEY = 'react-x11.cocoa.workerBooted';
+const BOOTED = Symbol.for(BOOTED_KEY);
+
+// Printed above an error that ended the worker before its import of
+// react-x11 had run there: thrown by code the main thread had run without
+// a complaint a moment before, which is all the developer has to go on.
+const STOPPED_EARLY =
+  'react-x11: the app stopped on its worker thread before reaching its ' +
+  'import of react-x11 there. On macOS react-x11 runs the app on a worker ' +
+  'thread, starting the entry over on it, so what the entry imports ahead ' +
+  'of react-x11 runs twice: on the main thread, then on the worker, where ' +
+  'a call only a main thread may make — process.chdir(), say — throws. ' +
+  'Make such a call on the main thread only (isMainThread, from ' +
+  'node:worker_threads); what it changes holds for the whole process, the ' +
+  'worker included. Or keep the app on the main thread with ' +
+  'REACT_X11_THREADED=0. See docs/macos.md, "What changes for an app".';
+
+/**
+ * What a worker `relaunch` starts runs before the app's entry, as the source
+ * of a function of `(process, global)`: what the worker needs from its first
+ * line, since the main thread is parked and hears nothing else from it.
+ *
+ * Its end, written into the shared state after the app's last exit
+ * listener. The main thread ends the process on it, so 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.
+ *
+ * Its uncaught error, printed by itself. Node hands a worker's uncaught
+ * error to its parent as an event, and the parent here 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. Straight to fd 2,
+ * because the worker's own stderr forwards through the parked thread too
+ * until `bootstrapWorker` replaces it; a pipe the main thread made
+ * non-blocking answers EAGAIN when full, and the write waits it out.
+ *
+ * Both used to be set up by `bootstrapWorker`, when the entry reached its
+ * import of react-x11. A worker that died before then — a module imported
+ * ahead of react-x11 calling `process.chdir()`, which only a main thread
+ * may — wrote nothing into the shared state and printed nothing, and the
+ * process waited in `Atomics.wait` for ever.
+ *
+ * A string, not a function's `toString()`: a build step rewrites a function
+ * — a bundler's name helper, a coverage counter — into references the
+ * worker cannot resolve, and a throw here hangs the process the way this
+ * exists to prevent.
+ */
+export const WORKER_START = `(function (process, global) {
+  'use strict';
+  const { workerData } = process.getBuiltinModule('node:worker_threads');
+  const { writeSync } = process.getBuiltinModule('node:fs');
+  const { inspect } = process.getBuiltinModule('node:util');
+  const state = new Int32Array(workerData.reactX11State);
+
+  const write = (text) => {
+    const bytes = Buffer.from(text);
+    for (let off = 0; off < bytes.length; ) {
+      try {
+        off += writeSync(2, bytes, off);
+      } catch (err) {
+        if (err.code !== 'EAGAIN') return;
+      }
+    }
+  };
+  process.on('uncaughtExceptionMonitor', (err) => {
+    if (process.listenerCount('uncaughtException') > 0) return;
+    const why = global[Symbol.for(${JSON.stringify(BOOTED_KEY)})]
+      ? ''
+      : ${JSON.stringify(`${STOPPED_EARLY}\n`)};
+    write(why + inspect(err) + '\\n');
+  });
+
+  const add = process.on;
+  const end = (code) => {
+    const n = Number.parseInt(code ?? process.exitCode ?? 0, 10) || 0;
+    Atomics.store(state, 1, n);
+    Atomics.store(state, 0, ${RELAUNCH.ENDED});
+    Atomics.notify(state, 0);
+  };
+  add.call(process, 'exit', end);
+  for (const name of [
+    'on',
+    'addListener',
+    'once',
+    'prependListener',
+    'prependOnceListener',
+  ]) {
+    const method = process[name];
+    process[name] = function (event, listener) {
+      const out = method.call(this, event, listener);
+      if (event === 'exit' && listener !== end) {
+        process.removeListener('exit', end);
+        add.call(process, 'exit', end);
+      }
+      return out;
+    };
+  }
+})`;
 
 // 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
@@ -48,6 +143,19 @@ const BOOTED = Symbol.for('react-x11.cocoa.workerBooted');
 // 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
@@ -57,6 +165,8 @@ export function relaunchVeto({
   isMainThread: main,
   platform,
   env,
+  execArgv,
+  node,
   entry,
   compiled,
   late,
@@ -89,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;
@@ -104,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),
@@ -121,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 {
@@ -137,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 {
@@ -153,16 +334,17 @@ 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);
 }
 
 /**
- * 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.
+ * The worker's side, set up the moment it imports react-x11, on top of
+ * `WORKER_START`, which has said how the worker ends and printed what
+ * crashed it since its first line: after it the app cannot tell it is on a
+ * worker, short of asking — its logs reach the terminal, `process.exit`
+ * ends the process, 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;
@@ -170,9 +352,7 @@ export function bootstrapWorker(state) {
   const native = loadNative();
   installStdio();
   bindRelaunchState(state);
-  printUncaught();
   routeExit(native);
-  onWorkerEnd(signalEnded);
   openThreadedChannel(native).subscribe(forwardSignals());
 }
 
@@ -183,11 +363,24 @@ export function bootstrapWorker(state) {
  */
 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 —
+  // The worker runs the app's own entry, 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.
+  // src/bootstrap.js), recognising the shared state in its workerData, and
+  // runs `WORKER_START` before anything else, so that it can end the
+  // process even if it never gets that far.
+  //
+  // Node starts the worker on those lines, as `eval` code that then runs
+  // the entry the way Node runs a worker's file: `process.argv[1]` set to
+  // it, and `Module.runMain`, which runs the `--import` loaders first and
+  // makes the entry the main module, `require.main` and `import.meta.main`
+  // as before. An `import()` of the entry does neither, and an eval worker
+  // runs no `--import` of its own (measured, Node 20–26). Bun's eval worker
+  // loses both a failure of the entry and `require.main` (measured, Bun
+  // 1.4), so there the entry stays the worker's own and the lines go in as
+  // its preload, base64-encoded: percent-encoded, Bun skipped them without
+  // an error.
   //
   // 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
@@ -196,11 +389,25 @@ export function relaunch(entry, native) {
   // `--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, {
+  const options = {
     argv: process.argv.slice(2),
     env: SHARE_ENV,
     workerData: { reactX11State: state.buffer },
-  });
+  };
+  const start = `${WORKER_START}(process, globalThis);\n`;
+  if (globalThis.Bun) {
+    const source = Buffer.from(start).toString('base64');
+    new Worker(entry, {
+      ...options,
+      preload: [`data:text/javascript;base64,${source}`],
+    });
+  } else {
+    new Worker(
+      `${start}process.argv[1] = ${JSON.stringify(entry)};\n` +
+        "process.getBuiltinModule('node:module').runMain(process.argv[1]);\n",
+      { ...options, eval: true },
+    );
+  }
   for (;;) {
     Atomics.wait(state, 0, RELAUNCH.WAITING);
     const now = Atomics.load(state, 0);

package/src/cocoa/threaded.js

@@ -13,13 +13,13 @@ 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.
+// it needs — AppKit, or nothing more because it is done, which the worker
+// says from the first line it runs (`WORKER_START`).
 export const RELAUNCH = Object.freeze({ WAITING: 0, APPKIT: 1, ENDED: 2 });
 let relaunchState = null;
 
@@ -44,63 +44,6 @@ export async function requestAppKit(native, state = relaunchState) {
   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;

package/src/events.js

@@ -622,6 +622,9 @@ export class EventManager {
     // window gets keys, and the focused node's caret/ring has to follow
     onDiscrete('focus', (ev) => this._onWindowFocus(true, ev));
     onDiscrete('blur', (ev) => this._onWindowFocus(false, ev));
+    // Tab arriving from outside the window: a `<Frame>`'s host moving its
+    // focus into the pane this window is (`_tabEnter`)
+    onDiscrete('tabenter', (ev) => this._tabEnter(Boolean(ev?.backwards)));
   }
 
   /**
@@ -2071,8 +2074,9 @@ export class EventManager {
     const manager = this.focusManager;
     if (manager !== this) return manager._cycleFocus(backwards);
     const list = this._tabbables();
-    if (list.length === 0) return;
     const index = list.indexOf(this.focused);
+    if (this._tabOut(list, index, backwards)) return;
+    if (list.length === 0) return;
     if (index === -1) {
       // nothing focused, or focus sits outside the current scope: Tab enters
       this.focus(backwards ? list[list.length - 1] : list[0], 'key', {
@@ -2089,6 +2093,47 @@ export class EventManager {
     );
   }
 
+  /**
+   * Tab off an end of a window that is itself a stop in another window's
+   * order — a `<Frame>`'s pane, whose host goes on from the box the pane is
+   * shown in. The order does not wrap there: the window hands Tab back
+   * (`tabOut` on the backend window, which says whether anyone took it),
+   * and lets go of its focus, as an XEmbed client does when it sends
+   * FOCUS_NEXT, so the stop it was at shows no ring while the host's next
+   * one does. Coming back, Tab lands at an end again (`_tabEnter`).
+   *
+   * Not inside a focus scope: a modal's order wraps in a pane as it does
+   * in a window, and the dialog keeps the keyboard until it closes.
+   */
+  _tabOut(list, index, backwards) {
+    const wnd = this.node.window;
+    if (typeof wnd?.tabOut !== 'function') return false;
+    if (this._scopeRoot() !== this.node) return false;
+    // nothing focused is not an end: Tab enters at one
+    if (list.length && index !== (backwards ? 0 : list.length - 1)) {
+      return false;
+    }
+    if (!wnd.tabOut(backwards)) return false;
+    this.focus(null);
+    return true;
+  }
+
+  /**
+   * Tab arriving at this window from the one it is shown in: the first stop
+   * in its order, or the last for a back-Tab, as a Tab into a window with
+   * nothing focused lands. A window with no stop keeps the keys where they
+   * are, and the next Tab hands them straight back (`_tabOut`).
+   */
+  _tabEnter(backwards) {
+    const manager = this.focusManager;
+    if (manager !== this) return manager._tabEnter(backwards);
+    const list = this._tabbables();
+    if (list.length === 0) return;
+    this.focus(backwards ? list[list.length - 1] : list[0], 'key', {
+      backwards,
+    });
+  }
+
   /**
    * A subtree just stopped being visible: `<Suspense>` showing its fallback,
    * `<Activity mode="hidden">`, or a style that turned `display: 'none'`.

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/childmain.js

@@ -230,8 +230,13 @@ export async function runFrameChild(transport, options = {}) {
       send: (msg) => transport.send(msg),
       onMessage: (cb) => transport.onMessage(cb),
     },
-    // what the host does for the pane that a pane cannot do itself
-    { players: Boolean(hello.players) },
+    {
+      // what the host does for the pane that a pane cannot do itself
+      players: Boolean(hello.players),
+      // and the scale it is drawn at, before anything here is laid out at
+      // the one this process read for itself
+      displayScale: hello.rect?.displayScale,
+    },
   );
 
   let closing = false;

package/src/frame/index.js

@@ -46,6 +46,7 @@ import React, {
 import { useAppOrNull } from '../appcontext.js';
 import { canEmbed } from '../embedding.js';
 import { WHEEL_NOTCH_PX } from '../events.js';
+import { XK_TAB } from '../keysyms.js';
 import { FrameEnv } from './env.js';
 import { CallbackTable, PROTOCOL } from './protocol.js';
 
@@ -72,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 {
@@ -120,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;
@@ -219,6 +273,8 @@ export function Frame({
   props = EMPTY_PROPS,
   style,
   display,
+  execArgv,
+  env: processEnv,
   bridge = true,
   fallback,
   focusable,
@@ -261,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(() => {
@@ -296,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;
@@ -407,6 +481,13 @@ export function Frame({
     const rect = {
       width: Math.round((node?.abs?.width || 0) / sc) || 400,
       height: Math.round((node?.abs?.height || 0) / sc) || 300,
+      // The display scale the host is drawn at. A pane process reads the
+      // screens when it starts, which is not when the host did: a page
+      // forked after the desk went to 1x — a mirror set for a projector —
+      // was laid out at 1x in a frame the host showed at 2x. A pane that
+      // has no window of its own takes this one instead of its own
+      // (`CocoaApp.adoptPaneScale`).
+      ...(node?.root?.scale > 0 && { displayScale: node.root.scale }),
     };
     s.sent = { props: p, env: e, bridge: b };
     trySend({
@@ -431,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
@@ -525,6 +606,37 @@ function PaneHostView({
   const embedErrorRef = useRef(onEmbedError);
   embedErrorRef.current = onEmbedError;
 
+  const forward = (name, data) => (ev) => {
+    const s = session.current;
+    const node = containerRef.current;
+    if (!s || !node) return;
+    const sc = node.scale ?? 1;
+    const payload = {
+      x: Math.max(0, Math.round(ev.x * sc - node.abs.x)),
+      y: Math.max(0, Math.round(ev.y * sc - node.abs.y)),
+      rootx: Math.round(ev.x * sc),
+      rooty: Math.round(ev.y * sc),
+      // The modifier mask, which a synthetic event carries on its native
+      // event alone. Read off the synthetic one, every key and press
+      // reached the pane with none: Shift+Tab went forwards there, and a
+      // Ctrl+C or a Shift+click was a C and a click.
+      buttons: ev.nativeEvent?.buttons ?? 0,
+      time: Date.now(),
+      ...data(ev),
+    };
+    try {
+      s.trySend?.({ type: 'pane-event', name, ev: payload });
+    } catch {
+      // the exit path owns the failure story
+    }
+  };
+  const key = (ev) => ({
+    keysym: ev.keysym,
+    baseKeysym: ev.baseKeysym ?? ev.keysym,
+    codepoint: ev.codepoint,
+    keycode: ev.keycode ?? 0,
+  });
+
   useEffect(() => {
     const s = session.current;
     const node = containerRef.current;
@@ -595,6 +707,7 @@ function PaneHostView({
         width: rect.width,
         height: rect.height,
         scale: rect.scale,
+        displayScale: rect.displayScale,
         live: liveNow(),
         ...(rect.screen && { screen: rect.screen }),
       });
@@ -609,6 +722,7 @@ function PaneHostView({
       a.width === b.width &&
       a.height === b.height &&
       a.scale === b.scale &&
+      a.displayScale === b.displayScale &&
       a.screen?.x === b.screen?.x &&
       a.screen?.y === b.screen?.y;
     const sized = () => {
@@ -632,7 +746,11 @@ function PaneHostView({
             y: Math.round(origin.y + node.abs.y),
           }
         : null;
-      const rect = { width, height, scale: sc, screen };
+      // `scale` is the frame's, a `<box scale>` around it included, and
+      // says how many device pixels the pane's rect is; `displayScale` is
+      // the window's, the one the pane lays out at (see the hello)
+      const displayScale = node.root?.scale ?? sc;
+      const rect = { width, height, scale: sc, displayScale, screen };
       if (sameRect(rect, pending ?? sent)) return;
       if (inFlight) pending = rect;
       else transmit(rect);
@@ -663,8 +781,67 @@ function PaneHostView({
       }),
     );
 
+    // Tab, which goes through the pane as it goes through any subtree. The
+    // box is a stop in this window's order, and the pane's own order hangs
+    // off it — the chain XEmbed makes for a `<foreign>` with FOCUS_FIRST,
+    // FOCUS_LAST and FOCUS_NEXT/PREV (src/foreignnodes.js). Tab arriving
+    // at the box goes on into the pane, at its first stop or, for a
+    // back-Tab, its last (`tabenter`). Tab while the box has the focus is
+    // the pane's, sent on and not cycled here. And the pane running off an
+    // end of its order hands Tab back (`pane-tab-out`), which goes on from
+    // the box. Without the three, the box took a Tab and the pane the next,
+    // which moved the pane's focus a stop and this window's out of the
+    // pane, so Tab went between one of the pane's stops and the window's.
+    //
+    // Keys go over as the box's default action, after the whole tree has
+    // had them, so a chord the application answered above the box never
+    // reaches the pane: sent from the box's handler, Ctrl+Tab switched the
+    // application's tab and moved the focus in the pane. And the pane
+    // composes what it is sent, as an embedded client does, rather than
+    // this window composing it first.
+    const tabInto = (backwards) =>
+      s.trySend?.({
+        type: 'pane-event',
+        name: 'tabenter',
+        ev: { backwards, buttons: 0, time: Date.now() },
+      });
+    const own = {
+      defaultFocus: Object.hasOwn(node, 'defaultFocus'),
+      defaultKeyDown: Object.hasOwn(node, 'defaultKeyDown'),
+      defaultKeyUp: Object.hasOwn(node, 'defaultKeyUp'),
+      composes: Object.hasOwn(node, 'composes'),
+    };
+    const was = {
+      defaultFocus: node.defaultFocus,
+      defaultKeyDown: node.defaultKeyDown,
+      defaultKeyUp: node.defaultKeyUp,
+      composes: node.composes,
+    };
+    const sendKeyDown = forward('keydown', key);
+    const sendKeyUp = forward('keyup', key);
+    node.defaultFocus = (info) => {
+      if (info?.reason === 'key') tabInto(Boolean(info.backwards));
+    };
+    node.defaultKeyDown = (ev) => {
+      sendKeyDown(ev);
+      // the pane's order answers it, and hands it back at an end
+      if (ev.keysym === XK_TAB) ev.preventDefault();
+    };
+    node.defaultKeyUp = sendKeyUp;
+    node.composes = false;
+
     const off = s.transport.onMessage((msg) => {
-      if (msg?.type === 'pane-window') {
+      if (msg?.type === 'pane-tab-out') {
+        // Only from focus the box holds: a pane that hands back a Tab it
+        // was not given is news that came too late.
+        const manager = node.root?.events?.focusManager;
+        if (!manager || manager.focused !== node) return;
+        const backwards = msg.backwards === true;
+        manager._cycleFocus(backwards);
+        // the window's only stop: round into the pane again, at the end
+        // that Tab comes to next
+        if (manager.focused === node) tabInto(backwards);
+      } else if (msg?.type === 'pane-window') {
         host.paneWindow?.(msg);
       } else if (msg?.type === 'pane-menu') {
         host.popUpMenu?.(msg);
@@ -705,32 +882,15 @@ function PaneHostView({
       node.root?.events?.refreshCursor();
       node.absolutize = origAbsolutize;
       if (origShift) node._shiftAbs = origShift;
+      for (const name of Object.keys(own)) {
+        if (own[name]) node[name] = was[name];
+        else delete node[name];
+      }
       if (s.paneHost === host) s.paneHost = null;
       host.destroy();
     };
   }, [app, session, containerRef]);
 
-  const forward = (name, data) => (ev) => {
-    const s = session.current;
-    const node = containerRef.current;
-    if (!s || !node) return;
-    const sc = node.scale ?? 1;
-    const payload = {
-      x: Math.max(0, Math.round(ev.x * sc - node.abs.x)),
-      y: Math.max(0, Math.round(ev.y * sc - node.abs.y)),
-      rootx: Math.round(ev.x * sc),
-      rooty: Math.round(ev.y * sc),
-      buttons: ev.buttons ?? 0,
-      time: Date.now(),
-      ...data(ev),
-    };
-    try {
-      s.trySend?.({ type: 'pane-event', name, ev: payload });
-    } catch {
-      // the exit path owns the failure story
-    }
-  };
-
   return h('box', {
     ref: containerRef,
     style,
@@ -754,17 +914,5 @@ function PaneHostView({
       smooth: Boolean(ev.smooth),
       source: 'forwarded',
     })),
-    onKeyDown: forward('keydown', (ev) => ({
-      keysym: ev.keysym,
-      baseKeysym: ev.baseKeysym ?? ev.keysym,
-      codepoint: ev.codepoint,
-      keycode: ev.keycode ?? 0,
-    })),
-    onKeyUp: forward('keyup', (ev) => ({
-      keysym: ev.keysym,
-      baseKeysym: ev.baseKeysym ?? ev.keysym,
-      codepoint: ev.codepoint,
-      keycode: ev.keycode ?? 0,
-    })),
   });
 }

package/src/nodes/window/listeners.js

@@ -4,6 +4,7 @@
 import { discrete } from '../../events.js';
 import { createClientMessages } from '../../clientmessage.js';
 import { callHandler } from '../../errors.js';
+import { ntkRoot } from '../../ntkroot.js';
 import { runWithPriority, DiscreteEventPriority } from '../../priority.js';
 import { DEV } from '../util.js';
 
@@ -178,9 +179,48 @@ export class WindowListeners {
         }),
       );
     }
+    if (this.props.embeddable && !parentWindow) this._initXEmbedTab(wnd);
     this.events.attach();
   }
 
+  /**
+   * Tab through a window another client embeds — a `<Frame>`'s pane on X11
+   * — as XEmbed's client. The embedder is a `<foreign>`
+   * (src/foreignnodes.js): Tab arriving at it sends XEMBED_FOCUS_IN with
+   * FOCUS_FIRST or FOCUS_LAST, which is this window's `tabenter`, and
+   * XEMBED_FOCUS_NEXT or _PREV, which its `tabOut` sends, moves the
+   * embedder's focus on from it (`EventManager._tabEnter`, `_tabOut`). The
+   * Cocoa and Windows panes say the same two things over their channel.
+   * Without it, Tab went round the pane's own stops for good: nothing
+   * handed it back.
+   *
+   * ntk's `XEmbedPlug` speaks it, and publishes `_XEMBED_INFO` with
+   * XEMBED_MAPPED set — an embedder maps such a window as it takes it, as it
+   * maps one that publishes none, so the pane still never maps itself.
+   */
+  _initXEmbedTab(wnd) {
+    const ntk = ntkRoot();
+    if (!ntk?.XEmbedPlug || typeof wnd.sendClientMessage !== 'function') {
+      return;
+    }
+    if (typeof wnd.tabOut === 'function') return;
+    const { XEMBED } = ntk;
+    const plug = new ntk.XEmbedPlug(this.app, { window: wnd });
+    plug.ready.catch(() => {});
+    plug.on('focusIn', (detail) => {
+      if (detail !== XEMBED.FOCUS_FIRST && detail !== XEMBED.FOCUS_LAST) {
+        return;
+      }
+      wnd.emit('tabenter', { backwards: detail === XEMBED.FOCUS_LAST });
+    });
+    wnd.tabOut = (backwards) => {
+      if (!plug.embedder) return false;
+      if (backwards) plug.focusPrev();
+      else plug.focusNext();
+      return true;
+    };
+  }
+
   /**
    * A close request nobody handled — `onCloseRequest` is the override, this
    * is what happens without one.

package/src/testing/harness.js

@@ -388,10 +388,13 @@ export async function act(fn, only = null) {
     // block — commit and settle. One round leaves that update in flight, and
     // React says so out loud ("An update to Button inside a test was not
     // wrapped in act(...)"), which is how this was found.
+    // A pointer move off the wire is still not in the tree: its window holds
+    // it for the next frame, so each round also hands over what is held.
     for (let round = 0; round < 2; round++) {
       await React.act(async () => {
         await new Promise((resolve) => setImmediate(resolve));
         for (const entry of entries) await settle(entry.app);
+        for (const entry of entries) deliverHeldEvents(entry);
       });
     }
   } finally {
@@ -401,6 +404,35 @@ export async function act(fn, only = null) {
   for (const entry of entries) await settle(entry.app);
 }
 
+/**
+ * Dispatch the events each window in a root is holding for its next frame.
+ *
+ * ntk delivers its noisy events — pointer motion, a resize, an expose —
+ * merged, once a frame, and starts frames at least a frame interval apart.
+ * A move that lands within an interval of the last frame waits out the rest
+ * of it, and the rest ends after `act()` has returned: the second of two
+ * hovers in a row is such a move, the first one's frame having started the
+ * interval, and the assertion right after it saw the pointer where it had
+ * been. A press or a key never waits, since ntk delivers what it holds ahead
+ * of any discrete event, but a pure move has nothing behind it.
+ *
+ * Delivered as the frame would deliver them, only now, and inside
+ * `React.act`, so what the handlers set commits in the same round.
+ * `flushCoalescedEvents()` is ntk's public way to ask for that; an ntk
+ * without it has only the method its frame calls, and that branch goes once
+ * the floor is an ntk with it.
+ */
+function deliverHeldEvents(entry) {
+  for (const node of windowNodesOf(entry.windowNode)) {
+    const win = node.window;
+    if (typeof win?.flushCoalescedEvents === 'function') {
+      win.flushCoalescedEvents();
+    } else {
+      win?._flushCoalesced?.();
+    }
+  }
+}
+
 /**
  * Run the frame the scheduler would have run, for every window in a root.
  *

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. */

package/src/win32/app.js

@@ -418,9 +418,12 @@ export class Win32App {
    * The pane process's end of the frame channel: geometry and input in,
    * presents and the cursor out. Feature-detected by the pane bootstrap
    * (src/frame/childmain.js), and a no-op in a process that is not a pane.
+   * `displayScale` is the scale the host's window is drawn at, taken before
+   * the pane's first render (`adoptPaneScale`).
    */
-  attachPaneChannel(channel) {
+  attachPaneChannel(channel, { displayScale } = {}) {
     if (!this._paneMode) return;
+    this.adoptPaneScale(displayScale);
     this._paneSend = (msg) => {
       try {
         channel.send(msg);
@@ -429,6 +432,8 @@ export class Win32App {
       }
     };
     channel.onMessage((msg) => {
+      // the app's, so heard with no window to size yet as well
+      if (msg?.type === 'pane-rect') this.adoptPaneScale(msg.displayScale);
       const wnd = [...this._windows.values()][0];
       if (!wnd) return;
       if (msg?.type === 'pane-rect') {
@@ -439,6 +444,36 @@ export class Win32App {
     });
   }
 
+  /**
+   * The scale of the window a pane is shown in, as the host says it — in
+   * the hello and in every pane-rect — made this process's. Returns whether
+   * it moved.
+   *
+   * A pane process reads the screens when it starts, and the host read
+   * them when it did. Across a change of the desk between the two — a
+   * display's scaling changed, a laptop docked — the answers differ, and a
+   * pane forked after it was laid out at its own scale in a buffer the host
+   * sized at the host's: every length in it off by the ratio of the two,
+   * and every click it was sent landing that far off too. The host's window
+   * is a pane's display, and its scale is the one the tree multiplies by.
+   * The pane's buffer keeps the scale its pane-rect gives it
+   * (`Win32PaneWindow.setPaneSize`): that one is the frame's, a
+   * `<box scale>` around the `<Frame>` included. A tree already laid out
+   * is restyled in the new unit.
+   */
+  adoptPaneScale(scale) {
+    if (!this._paneMode || !(scale > 0) || !Number.isFinite(scale)) {
+      return false;
+    }
+    if (scale === this.scale) return false;
+    this.scale = scale;
+    setScaleForTests(this, scale, 'frame');
+    for (const wnd of this._windows.values()) {
+      if (!wnd.destroyed) wnd._reactX11Node?._rescaleSubtree();
+    }
+    return true;
+  }
+
   close() {
     if (this._closed) return Promise.resolve();
     this._closed = true;

package/src/win32/panewindow.js

@@ -224,6 +224,14 @@ export class Win32PaneWindow {
     this.title = title;
   }
 
+  /** Tab off an end of the pane's order, handed to the host, which goes on
+   *  from the `<Frame>`'s box (the Cocoa pane's `tabOut`). */
+  tabOut(backwards) {
+    if (this.destroyed || !this.app._paneSend) return false;
+    this.app._paneSend({ type: 'pane-tab-out', backwards });
+    return true;
+  }
+
   /** The cursor this pane's tree names, sent to the host, which shows it:
    *  the pointer is over the host's window, not this one (the Cocoa pane's
    *  `setCursor`). */