react-x11 2.45.1 → 2.45.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.45.1",
+  "version": "2.45.3",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [

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
@@ -157,12 +252,13 @@ export function relaunchOnImport(moduleUrl) {
 }
 
 /**
- * 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 +266,7 @@ export function bootstrapWorker(state) {
   const native = loadNative();
   installStdio();
   bindRelaunchState(state);
-  printUncaught();
   routeExit(native);
-  onWorkerEnd(signalEnded);
   openThreadedChannel(native).subscribe(forwardSignals());
 }
 
@@ -183,11 +277,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 +303,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/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';
 
@@ -407,6 +408,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({
@@ -525,6 +533,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 +634,7 @@ function PaneHostView({
         width: rect.width,
         height: rect.height,
         scale: rect.scale,
+        displayScale: rect.displayScale,
         live: liveNow(),
         ...(rect.screen && { screen: rect.screen }),
       });
@@ -609,6 +649,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 +673,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 +708,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 +809,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 +841,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/events.js

@@ -15,6 +15,7 @@
 // async and `fireEvent` is not.
 
 import { act } from './harness.js';
+import { describeNode } from './queries.js';
 import { keysymOf, MOD, XK_RETURN } from '../keysyms.js';
 
 /** The window node that owns a drawn node (a node, or a window itself). */
@@ -22,15 +23,23 @@ function rootWindow(node) {
   return node?.isWindow ? node : (node?.root ?? null);
 }
 
+const NOT_IN_A_WINDOW =
+  'react-x11/test: the target is not inside a realized window — did you ' +
+  'await renderX11(), or has it unmounted?';
+
 /** A node's centre in **screen** coordinates, which is what injection takes. */
 export function screenPointOf(node, { dx = 0, dy = 0 } = {}) {
   const win = rootWindow(node);
-  if (!win?.window) {
-    throw new Error(
-      'react-x11/test: the target is not inside a realized window — did you ' +
-        'await renderX11(), or has it unmounted?',
-    );
+  // Asked before the rect, which neither kind of node gives up: one that
+  // has unmounted, or that something hides, keeps the rect it was last laid
+  // out at, and what is at that spot now is whatever was behind it. The hit
+  // test passes over a hidden node, and an unmounted one is in no tree, so
+  // a pointer aimed there could only reach something else, and nothing
+  // would say so.
+  if (node?.destroyed || hiddenBy(node)) {
+    throw new Error(noRectMessage(node, win));
   }
+  if (!win?.window) throw new Error(NOT_IN_A_WINDOW);
   const origin = win.window._screenOrigin ?? {
     x: win.window.x ?? 0,
     y: win.window.y ?? 0,
@@ -44,10 +53,7 @@ export function screenPointOf(node, { dx = 0, dy = 0 } = {}) {
   }
   const abs = node.abs;
   if (!abs || (abs.width === 0 && abs.height === 0)) {
-    throw new Error(
-      `react-x11/test: <${node.kind}> has no laid-out rect yet. Layout runs ` +
-        'on the frame clock, so `await act()` before pointing at it.',
-    );
+    throw new Error(noRectMessage(node, win));
   }
   return {
     x: Math.round(origin.x + abs.x + abs.width / 2 + dx),
@@ -56,8 +62,101 @@ export function screenPointOf(node, { dx = 0, dy = 0 } = {}) {
   };
 }
 
+/**
+ * Why a node has no rect to aim at, worded as what to do about it. Only one
+ * answer is a matter of waiting, and its advice, `await act()`, is wrong for
+ * every other: no frame gives a size to a node that layout has already
+ * placed at 0×0. Asked in this order:
+ *
+ * - it has unmounted;
+ * - it is hidden: by its own `display: 'none'` or an ancestor's, by React,
+ *   or in a window kept unmapped by `hidden` or by React. That comes before
+ *   asking whether layout reached it, because a `<box>` with
+ *   `display: 'none'` never places its children at all.
+ *
+ *   These first two are asked whatever the node's rect: `screenPointOf`
+ *   comes here for them before it looks, since the rect such a node keeps
+ *   is where it was, not where anything is;
+ * - it has no box of its own: a span, an SVG shape;
+ * - layout has not placed it yet (`_placed`), or the window owes a pass
+ *   (`needsLayout`) that may still give it a size. A pending frame is no
+ *   witness: a paced window holds one with nothing scheduled;
+ * - layout placed it, at 0×0.
+ */
+function noRectMessage(node, win) {
+  const name = describeNode(node);
+  if (node.destroyed) {
+    return (
+      `react-x11/test: ${name} has unmounted, so it is nowhere on screen to ` +
+      'point at. If something replaced it, query for that instead.'
+    );
+  }
+  const hider = hiddenBy(node);
+  if (hider) {
+    const self = hider === node;
+    const has = self ? 'has' : 'which has';
+    const how =
+      hider.isWindow && hider.props.hidden
+        ? `${has} \`hidden\``
+        : hider.style?.display === 'none'
+          ? `${has} \`display: 'none'\``
+          : `${self ? 'is hidden by React' : 'which React has hidden'}, in ` +
+            'an `<Activity mode="hidden">` or a `<Suspense>` showing its ' +
+            'fallback';
+    return (
+      `react-x11/test: ${name} ` +
+      (self ? how : `is inside ${describeNode(hider)}, ${how}`) +
+      ', so there is nothing on screen to point at, and `await act()` will ' +
+      'not change that. ' +
+      (self
+        ? 'Show it before pointing at it.'
+        : 'Show that before pointing at anything inside it.')
+    );
+  }
+  if (!node.yoga) {
+    let owner = node.parent;
+    while (owner && !owner.yoga) owner = owner.parent;
+    return (
+      `react-x11/test: ${name} has no box of its own: it is laid out as part ` +
+      `of ${owner ? describeNode(owner) : 'its parent'}, so there is no ` +
+      'rect to point at. Point at that instead, with `{ dx, dy }` to reach ' +
+      'a spot inside it.'
+    );
+  }
+  if (!node._placed || win.needsLayout) {
+    return (
+      `react-x11/test: <${node.kind}> has no laid-out rect yet. Layout runs ` +
+      'on the frame clock, so `await act()` before pointing at it.'
+    );
+  }
+  return (
+    `react-x11/test: ${name} was laid out at 0×0, so there is nothing on ` +
+    'screen to point at. Layout has run since it last changed, so ' +
+    '`await act()` will not give it a size: give it one, with `width` and ' +
+    '`height`, `flexGrow` or content to size it, or point at an ancestor ' +
+    'or a child that has one. If its size comes from content still on its ' +
+    'way, such as an image that is loading, wait for that with `waitFor`.'
+  );
+}
+
+/** The node that takes `node` off the screen — itself or the nearest
+ * ancestor with `display: 'none'` or hidden by React, up to and including
+ * its window, which a `hidden` prop or React keeps unmapped — or null when
+ * nothing does. The same walk as the renderer's `_hiddenInTree`. */
+function hiddenBy(node) {
+  for (let n = node; n; n = n.parent) {
+    if (n.hidden || n.style?.display === 'none') return n;
+    if (n.isWindow) break;
+  }
+  return null;
+}
+
 function serverOf(node) {
-  const server = rootWindow(node)?.app?._reactX11TestServer;
+  // what a target that is no node at all — a `queryBy*` that found nothing —
+  // is told by `screenPointOf`, for the calls that never ask it
+  const win = rootWindow(node);
+  if (!win) throw new Error(NOT_IN_A_WINDOW);
+  const server = win.app?._reactX11TestServer;
   if (!server) {
     throw new Error(
       'react-x11/test: fireEvent needs the in-process X server, so it needs a ' +
@@ -142,10 +241,13 @@ export const fireEvent = {
     fireEvent.mouseMove(node, options);
   },
 
-  /** Move the pointer off the node, which is what produces a leave. */
-  mouseLeave(node, options = {}) {
-    const { server } = screenPointOf(node, options);
-    server.injectPointerMove(0, 0);
+  /**
+   * Move the pointer off the node, to the screen's origin, which is what
+   * produces a leave. Nothing is aimed at, so the node may since have been
+   * hidden or unmounted: it only names the connection.
+   */
+  mouseLeave(node) {
+    serverOf(node).injectPointerMove(0, 0);
   },
 
   mouseDown(node, options = {}) {
@@ -157,9 +259,13 @@ export const fireEvent = {
     for (const kc of modifiers.reverse()) server.injectKey(kc, false);
   },
 
+  /**
+   * Release the button wherever the pointer is — a `mouseMove` first puts
+   * it somewhere else. The node only names the connection, so it may be one
+   * the press hid or unmounted: the gesture can still end.
+   */
   mouseUp(node, options = {}) {
-    const { server } = screenPointOf(node, options);
-    server.injectButton(options.button ?? 1, false);
+    serverOf(node).injectButton(options.button ?? 1, false);
   },
 
   /** Press and release — the renderer synthesises the click from the pair. */

package/src/testing/harness.js

@@ -56,23 +56,84 @@ const DEFAULT_SCREEN = { width: 1280, height: 800 };
  * cheapest request with a reply, and its reply cannot arrive before every
  * request queued ahead of it has been processed — which is what makes it a
  * barrier rather than a sleep.
+ *
+ * **On a connection that is going, it resolves at once.** Nothing there will
+ * be answered, and a test that ends its connection still has `act()`,
+ * `waitFor` and `cleanup()` to get through — the last from an `afterEach`.
+ * node-x11 reports the two ways a connection goes very differently:
+ *
+ * - **The app closed it.** From the moment `close()` begins, every request
+ *   throws `client is in closing state` — synchronously, which inside the
+ *   promise below is a rejection.
+ * - **The server ended it** — it exited, or killed the client. All node-x11
+ *   says is an `end` event: it goes on taking requests and never answers
+ *   them, or anything that was in flight, so the round trip waits forever.
+ *   That is the route a test of `onDisconnect` has to take: over the
+ *   in-process stream pair, a client that closed its own connection never
+ *   hears it end.
  */
 export function settle(app, roundTrips = 2) {
   const X = app?.X;
   if (typeof X?.GetInputFocus !== 'function') return Promise.resolve();
+  // renderX11 settles as it mounts, so its connection is watched before a
+  // test can end it
+  const watch = watchEnd(X);
   let chain = Promise.resolve();
   for (let i = 0; i < roundTrips; i++) {
     chain = chain.then(
       () =>
         new Promise((resolve) => {
-          // resolve either way: a closing connection must not hang a test
-          X.GetInputFocus(() => resolve());
+          if (connectionGone(X)) return resolve();
+          const done = () => {
+            watch.waiting.delete(done);
+            resolve();
+          };
+          watch.waiting.add(done);
+          try {
+            X.GetInputFocus(done);
+          } catch {
+            // refused by a rule the check above does not know: whatever the
+            // reason, a request that never went out has nothing to drain
+            done();
+          }
         }),
     );
   }
   return chain;
 }
 
+// Each connection settle() has met: whether the server has ended it, and the
+// round trips waiting on it, which the end has to answer since no reply will.
+const watched = new WeakMap();
+
+function watchEnd(X) {
+  let watch = watched.get(X);
+  if (!watch) {
+    watch = { ended: false, waiting: new Set() };
+    watched.set(X, watch);
+    X.once?.('end', () => {
+      watch.ended = true;
+      for (const done of watch.waiting) done();
+    });
+  }
+  return watch;
+}
+
+/**
+ * Whether a request on this connection would go unanswered: the app began
+ * closing it, or its stream has ended — the test ntk makes before releasing
+ * anything (`connectionGone`, ntk's lib/cleanup.js) — or the server ended
+ * it, which only the `end` event says.
+ */
+function connectionGone(X) {
+  return Boolean(
+    X?._closing ||
+    X?.stream?.destroyed ||
+    X?.stream?.writableEnded ||
+    watched.get(X)?.ended,
+  );
+}
+
 async function createXServerApp({ screen, fonts }) {
   const [{ default: xserver }, ntk] = await Promise.all([
     optional('x11/lib/xserver/index.js', 'is the in-process X server'),
@@ -327,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 {
@@ -340,7 +404,44 @@ export async function act(fn, only = null) {
   for (const entry of entries) await settle(entry.app);
 }
 
-/** Run the frame the scheduler would have run, for every window in a root. */
+/**
+ * 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.
+ *
+ * Not skipped on a connection that has gone. The harm a frame can do there
+ * is to throw, which it would only once the app is closing, and the frame
+ * declines on such a connection before it sends a thing (`_flushFrame`); on
+ * one the server ended, its requests are taken and go nowhere. A check here
+ * would be a second copy of the frame's own.
+ */
 function flushFrames(entry) {
   for (const node of windowNodesOf(entry.windowNode)) {
     if (!node.window) continue;
@@ -359,12 +460,17 @@ async function unmountEntry(entry) {
   // before the unmount, so the teardown's own hook traffic is not recorded
   entry.at?.uninstall();
   try {
-    entry.root.unmount?.();
+    // awaited, or the catch is never reached: unmount is async
+    await entry.root.unmount?.();
   } catch {
     // a root whose connection already died: nothing left to unmount
   }
   await settle(entry.app);
-  if (entry.ownsApp) {
+  // A connection that is already going is not closed again. close() begins
+  // with a round trip, which one the test closed refuses by throwing, and
+  // which one whose stream has ended — the server's doing, or a dispose —
+  // never answers, hanging the teardown
+  if (entry.ownsApp && !connectionGone(entry.app.X)) {
     try {
       await entry.app.close?.();
     } catch {

package/src/testing/index.d.ts

@@ -343,7 +343,11 @@ export function cleanup(): Promise<void>;
  */
 export function setAppearance(values: PinnedAppearance): Promise<void>;
 
-/** Drain in-flight requests on a connection. */
+/**
+ * Drain in-flight requests on a connection. On one that has gone — closed by
+ * the app, or ended by the server — it resolves at once, since nothing there
+ * will be answered.
+ */
 export function settle(app: NtkApp, roundTrips?: number): Promise<void>;
 
 /**
@@ -461,8 +465,14 @@ export interface KeyOptions {
 export const fireEvent: {
   mouseMove(node: DrawnNode, options?: PointerOptions): void;
   mouseEnter(node: DrawnNode, options?: PointerOptions): void;
+  /** Move the pointer to the screen's origin, which is a leave. Aims at
+   *  nothing: `node` only names the connection, and may since have been
+   *  hidden or unmounted. */
   mouseLeave(node: DrawnNode, options?: PointerOptions): void;
   mouseDown(node: DrawnNode, options?: PointerOptions): void;
+  /** Release `button` wherever the pointer is — move it first to release
+   *  somewhere else. Aims at nothing: `node` only names the connection, and
+   *  may be one the press hid or unmounted. */
   mouseUp(node: DrawnNode, options?: PointerOptions): void;
   click(node: DrawnNode, options?: PointerOptions): void;
   doubleClick(node: DrawnNode, options?: PointerOptions): void;
@@ -491,6 +501,7 @@ export const userEvent: {
   click(node: DrawnNode, options?: PointerOptions): Promise<void>;
   doubleClick(node: DrawnNode, options?: PointerOptions): Promise<void>;
   hover(node: DrawnNode, options?: PointerOptions): Promise<void>;
+  /** `fireEvent.mouseLeave`, flushed: aims at nothing. */
   unhover(node: DrawnNode, options?: PointerOptions): Promise<void>;
   /** A scroll in notches; `smooth` takes fractions of one, as a touchpad
    *  measures them. */
@@ -517,7 +528,12 @@ export const userEvent: {
   }): Promise<void>;
 };
 
-/** A node's centre in screen coordinates. */
+/**
+ * A node's centre in screen coordinates. Throws, saying why, for a node
+ * with no rect: not laid out yet, laid out at 0×0, or laid out as part of
+ * another node — and for one that is hidden or has unmounted, whatever rect
+ * it kept, which is where it was and not where anything is.
+ */
 export function screenPointOf(
   node: DrawnNode,
   options?: { dx?: number; dy?: number },

package/src/testing/queries.js

@@ -66,11 +66,24 @@ export function roleOf(node) {
   return roleNameOf(node) ?? node.kind;
 }
 
-function describe(node) {
-  const text = textOf(node).trim();
+/** A node the way an error names it: its kind, its `data-testname` and the
+ * start of its text — what a test author can find it by. A `<popup>` is a
+ * window to the renderer, and is named as the element it was written as.
+ * The text is read whether or not the node is still mounted, unlike
+ * `textOf`'s: one that has unmounted presents nothing now, and is named by
+ * what it said. A mounted node holds no unmounted child, so for one of those
+ * the two read the same. */
+export function describeNode(node) {
+  let text = '';
+  (function read(n) {
+    if (typeof n.text === 'string') text += n.text;
+    for (const child of n.children ?? []) read(child);
+  })(node);
+  text = text.trim();
   const name = node.props?.['data-testname'];
+  const tag = node.isPopup ? 'popup' : node.kind;
   return (
-    `<${node.kind}${name ? ` data-testname="${name}"` : ''}>` +
+    `<${tag}${name ? ` data-testname="${name}"` : ''}>` +
     (text ? ` ${JSON.stringify(text.slice(0, 40))}` : '')
   );
 }
@@ -79,7 +92,7 @@ function inventory(root, limit = 12) {
   const lines = [];
   walk(root, (n) => {
     if (n.kind === 'textchunk' || n.kind === 'textspan') return;
-    if (lines.length < limit) lines.push(`  ${describe(n)}`);
+    if (lines.length < limit) lines.push(`  ${describeNode(n)}`);
   });
   return lines.join('\n');
 }
@@ -93,7 +106,7 @@ function one(root, found, what, printTree = inventory) {
   }
   throw new Error(
     `react-x11/test: found ${found.length} elements for ${what}, expected one:\n` +
-      found.map((n) => `  ${describe(n)}`).join('\n'),
+      found.map((n) => `  ${describeNode(n)}`).join('\n'),
   );
 }
 

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