react-x11 2.1.4 → 2.2.1

package/package.json

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

package/src/Reconciler.js

@@ -34,7 +34,11 @@ import {
 } from './nodes.js';
 import { hasDropProps } from './dnd.js';
 import { AppProvider } from './appcontext.js';
-import { defaultRootHandlers, setErrorHandler } from './errors.js';
+import {
+  defaultRootHandlers,
+  setErrorHandler,
+  STRICT_TOKENS,
+} from './errors.js';
 import {
   registerApp,
   unregisterApp,
@@ -53,6 +57,7 @@ import { endIdle } from './idle.js';
 import { endKeyboardState } from './keyboardstate.js';
 import { endXSettings } from './xsettings.js';
 import { watchAppearance } from './appearance.js';
+import { setDesktopIntegration } from './desktopintegration.js';
 import { ForeignNode } from './foreignnodes.js';
 import { GlAreaNode } from './glnodes.js';
 import { createRegisteredNode, registeredElements } from './registry.js';
@@ -302,15 +307,29 @@ const HostConfig = {
     // and trapFocus need commitMount too — the node has to be in the tree
     // first, so it can find the EventManager that owns focus. Drop targets
     // likewise: registration needs the root, which insertion assigns.
+    //
+    // Under REACT_X11_STRICT_TOKENS every token-styled node asks for one as
+    // well, since a bad token is only *found* once the node is attached —
+    // which is after this ran — and commitMount is the first moment React
+    // holds that node's own fiber (nodes.js `_tokenProblem`). Gated on the
+    // flag so the default mount pays nothing for a debugging mode.
     return (
       type === 'popup' ||
       Boolean(props.autoFocus) ||
       Boolean(props.trapFocus) ||
-      hasDropProps(props)
+      hasDropProps(props) ||
+      (STRICT_TOKENS && instance._usesTokens)
     );
   },
 
   commitMount(instance, type, props) {
+    // first, and before any of the work below: the tree is on its way out.
+    // `false` afterwards marks this instance's one commitMount spent, so a
+    // later re-attach throws at once rather than deferring to a call that
+    // will never come (nodes.js `_tokenProblem`).
+    const tokenError = instance._tokenError;
+    instance._tokenError = false;
+    if (tokenError) throw tokenError;
     if (type === 'popup') {
       instance.realize(null);
     }
@@ -605,6 +624,12 @@ function watchConnection(app, onDisconnect, deliberate) {
  *
  * `display`, `fontSource`, `glxVisual` and `onXError` go straight to ntk.
  * Anything else ntk understands, build the client yourself and pass `app`.
+ *
+ * `desktop: false` turns off the three things this turns on for you that talk
+ * to the session bus — the appearance ladder, the accessibility bridge and
+ * the global menu — for an embedder that owns them, or a process that must
+ * not fork. `desktop: { appearance: false }` names one. See
+ * src/desktopintegration.js and docs/desktop.md.
  */
 export async function createRoot(options = {}) {
   // Before anything builds a node: every drawn node creates a yoga node in
@@ -627,6 +652,11 @@ export async function createRoot(options = {}) {
   }
   const { app: borrowed, onDisconnect, ...rest } = options;
   const owned = borrowed === undefined;
+  // Before anything starts, for two reasons: a bad `desktop` shape must throw
+  // with nothing in flight, like the check above it — and `startA11y()` below
+  // reads this policy, so it has to be settled before the first await, not
+  // after (src/desktopintegration.js).
+  setDesktopIntegration(rest.desktop);
   // The connection is started first, and the order is the point rather than a
   // detail. `loadLayout()` is only nominally asynchronous: instantiating the
   // engine blocks the event loop for 15-50 ms before it returns its promise

package/src/a11y.js

@@ -40,6 +40,10 @@
 //     from gi.repository import Atspi; \
 //     print({k: int(getattr(Atspi.Role, k)) for k in dir(Atspi.Role) if not k.startswith('_')})"
 
+// The one import, and it keeps this file's promise: a `Set` and two functions
+// over it, with no D-Bus, no node builtins and nothing at module scope.
+import { desktopIntegrationEnabled } from './desktopintegration.js';
+
 /** AT-SPI role numbers (AtspiRole). */
 export const ATSPI_ROLE = Object.freeze({
   INVALID: 0,
@@ -1245,6 +1249,10 @@ let startPromise = null;
  * tests are exactly this case.
  */
 function a11yEnabled() {
+  // `createRoot({ desktop: false })` outranks every environment variable,
+  // including the one that forces the climb: it is the embedder saying this
+  // process does not talk to the desktop (src/desktopintegration.js, #417).
+  if (!desktopIntegrationEnabled('a11y')) return false;
   const own = process.env.REACT_X11_A11Y;
   if (own === '0') return false;
   if (own) return true;

package/src/appearance.js

@@ -57,6 +57,7 @@ import os from 'node:os';
 import path from 'node:path';
 
 import { sessionBus } from './bus.js';
+import { desktopIntegrationEnabled } from './desktopintegration.js';
 import { PORTAL_NAME, PORTAL_PATH } from './portal.js';
 import { beginXSettings, watchXSettings, xsettings } from './xsettings.js';
 
@@ -238,6 +239,12 @@ function sanitize(saved) {
 function load() {
   if (cacheChecked) return;
   cacheChecked = true;
+  // `createRoot({ desktop: false })` means this process does not follow the
+  // desktop, and that has to include the remembered answer: seeding from the
+  // cache would leave an app that opted out drawing in whatever colours this
+  // machine happened to be in last time, which is the opposite of the
+  // determinism the switch is asked for (#417).
+  if (!desktopIntegrationEnabled('appearance')) return;
   const file = cacheFile();
   if (!file) return;
   try {
@@ -702,6 +709,10 @@ async function runLadder(app) {
  */
 export function systemAppearance(options = {}) {
   if (owner) return Promise.resolve(snapshot);
+  // Turned off, so there is nothing to climb and nothing to remember: the
+  // defaults, which is a real answer — `'no-preference'` means *use your own*
+  // (src/desktopintegration.js).
+  if (!desktopIntegrationEnabled('appearance')) return Promise.resolve(NOTHING);
   load();
   if (!probe) {
     // **Failure is not cached**, for the same reason `bus.js` does not cache

package/src/atspi.js

@@ -32,7 +32,7 @@
 // resurrected: the slots are cleared and the app simply stops being
 // accessible until restarted, the same contract bus.js documents.
 
-import { addressFor, loadTransport } from './bus.js';
+import { loadTransport, resolveAddress } from './bus.js';
 import {
   hooks,
   ATSPI_ROLE,
@@ -1818,8 +1818,11 @@ async function connected(bus) {
  */
 async function accessibilityBusAddress(dbus) {
   if (process.env.AT_SPI_BUS_ADDRESS) return process.env.AT_SPI_BUS_ADDRESS;
-  const busAddress = addressFor('session');
-  if (!busAddress && process.platform !== 'darwin') return null;
+  // Resolved, not read: on macOS this is where the session bus address comes
+  // from, and letting `dbus-native` find it for itself would be a blocking
+  // `spawnSync` on the way to the first frame (#417).
+  const busAddress = await resolveAddress('session');
+  if (!busAddress) return null;
   let sbus = null;
   try {
     sbus = dbus.createClient({ busAddress });

package/src/bus.js

@@ -135,9 +135,8 @@ export async function loadTransport() {
  * address is incoherent under sharing. Two callers, two addresses, one
  * socket — which would win? Tests use this same seam.
  *
- * Not public, but exported for atspi.js, whose one-shot discovery probe
- * dials its own short-lived connection rather than the shared one — see
- * the note in `accessibilityBusAddress`.
+ * Synchronous, and so it cannot answer on macOS — see `resolveAddress`,
+ * which is what every dial goes through.
  */
 export function addressFor(kind) {
   if (kind === 'system') {
@@ -149,21 +148,102 @@ export function addressFor(kind) {
   if (process.env.DBUS_SESSION_BUS_ADDRESS) {
     return process.env.DBUS_SESSION_BUS_ADDRESS;
   }
-  // macOS advertises the session bus through launchd, which dbus-native
-  // already falls back to on its own. Leave it undefined and let it.
+  // macOS advertises the session bus through launchd rather than through the
+  // environment, and asking launchd is a subprocess — see `launchdAddress`.
   if (process.platform === 'darwin') return undefined;
   const runtimeDir = process.env.XDG_RUNTIME_DIR;
   return runtimeDir ? `unix:path=${runtimeDir}/bus` : undefined;
 }
 
+/**
+ * The in-flight or settled lookup, shared by every dial in the process.
+ *
+ * **Failure is cached here**, which is the one place in this module where it
+ * is — and the exception is deliberate. A session bus can genuinely appear
+ * under `$XDG_RUNTIME_DIR` mid-run, so that answer is never remembered; what
+ * launchd exports is a *login session* fact, set when the bus is installed
+ * and started, which does not happen under a running app. Re-asking would be
+ * a fork per feature probe to learn the same "no".
+ */
+let launchd = null;
+
+/**
+ * Ask launchd where the session bus is, **without blocking the event loop**.
+ *
+ * This is the whole reason `resolveAddress` exists (#417). `dbus-native` will
+ * do this lookup itself, from `createStream`, with `spawnSync` — it has to,
+ * because its own entry point is synchronous — and a fork+exec of `launchctl`
+ * on a cold page cache costs 120–150 ms of *blocked loop*, measured. Landing
+ * that inside `createRoot()` stalls the X handshake, the yoga instantiate and
+ * the first paint behind a question about the colour scheme.
+ *
+ * Every caller here is already asynchronous, so the same lookup done with
+ * `execFile` costs the same wall clock and none of the loop: the handshake
+ * and the layout engine run through it. Handing `dbus-native` the resolved
+ * `unix:path=…` is then what keeps it off its own synchronous path.
+ *
+ * The variable name is D-Bus's, and the fallback to our own environment is
+ * `launchdSocketPath`'s: a process launched from a shell that has it already
+ * knows the answer.
+ */
+function launchdAddress() {
+  if (launchd) return launchd;
+  launchd = (async () => {
+    const VAR = 'DBUS_LAUNCHD_SESSION_BUS_SOCKET';
+    let fromLaunchd = '';
+    try {
+      const { execFile } = await import('node:child_process');
+      fromLaunchd = await new Promise((resolve) => {
+        execFile(
+          'launchctl',
+          ['getenv', VAR],
+          { encoding: 'utf8' },
+          (err, stdout) => resolve(err ? '' : String(stdout).trim()),
+        );
+      });
+    } catch {
+      // no `launchctl` on $PATH, or no child processes to be had at all
+    }
+    const socket = fromLaunchd || process.env[VAR] || '';
+    return socket ? `unix:path=${socket}` : undefined;
+  })();
+  return launchd;
+}
+
+/**
+ * Where to dial, resolved — the synchronous sources first, and launchd only
+ * where they have nothing to say.
+ *
+ * Not public, but exported for atspi.js, whose one-shot discovery probe
+ * dials its own short-lived connection rather than the shared one — see the
+ * note in `accessibilityBusAddress`. It matters that it goes through here
+ * too: two dials that each let `dbus-native` ask launchd are two blocking
+ * forks, and the answer is the same both times.
+ *
+ * @param {BusKind} kind
+ * @returns {Promise<string | undefined>}
+ */
+export async function resolveAddress(kind) {
+  const direct = addressFor(kind);
+  if (direct !== undefined) return direct;
+  if (kind !== 'session' || process.platform !== 'darwin') return undefined;
+  return await launchdAddress();
+}
+
 function noAddressError(kind) {
+  if (kind !== 'session') {
+    return new Error(
+      'react-x11: no system bus address. $DBUS_SYSTEM_BUS_ADDRESS is unset ' +
+        'and there is no default.',
+    );
+  }
   return new Error(
-    `react-x11: no ${kind} bus address. ` +
-      (kind === 'session'
-        ? '$DBUS_SESSION_BUS_ADDRESS is unset and $XDG_RUNTIME_DIR is not ' +
-          'set either, which is normal over ssh, under a bare startx and in ' +
-          'most containers.'
-        : '$DBUS_SYSTEM_BUS_ADDRESS is unset and there is no default.'),
+    'react-x11: no session bus address. $DBUS_SESSION_BUS_ADDRESS is unset ' +
+      (process.platform === 'darwin'
+        ? 'and launchd has no $DBUS_LAUNCHD_SESSION_BUS_SOCKET either, which ' +
+          'is normal on a Mac with no D-Bus installed.'
+        : 'and $XDG_RUNTIME_DIR is not set either, which is normal over ssh, ' +
+          'under a bare startx and in most containers.'),
   );
 }
 
@@ -216,8 +296,11 @@ async function connect(kind, generation) {
     return fail(noTransportError(cause));
   }
 
-  const busAddress = addressFor(kind);
-  if (!busAddress && process.platform !== 'darwin') {
+  // Resolved rather than read, so `dbus-native` never reaches its own
+  // `spawnSync` fallback on macOS (#417) — and so "this Mac has no D-Bus"
+  // fails here, before a socket is dialled, instead of inside a constructor.
+  const busAddress = await resolveAddress(kind);
+  if (!busAddress) {
     return fail(noAddressError(kind));
   }
 
@@ -538,6 +621,10 @@ export function busRefs(kind) {
  * exported object survives into the next test.
  */
 export function _resetBusState() {
+  // Including what launchd said: a suite that pins `process.platform` would
+  // otherwise inherit the answer — or the absence of one — from a case that
+  // ran under a different one.
+  launchd = null;
   for (const kind of KINDS) {
     state[kind] = newState(kind, state[kind].generation + 1);
     notify(kind);

package/src/desktopintegration.js

@@ -0,0 +1,98 @@
+// Whether this process talks to the desktop at all — the `desktop` option on
+// `createRoot()`, and the one place that decides what it covers.
+//
+// ## What is in the group and why
+//
+// Three things react-x11 turns on for you without being asked, and all three
+// reach the session bus:
+//
+//   `appearance`  the light/dark, accent, contrast and reduced-motion ladder
+//                 (src/appearance.js) — the settings portal, then macOS, then
+//                 XSETTINGS
+//   `a11y`        the AT-SPI bridge, started from `createRoot()`
+//                 (src/a11y.js, docs/accessibility.md)
+//   `globalMenu`  a `MenuBar` handing its menu to the panel instead of drawing
+//                 it (src/globalmenu.js, docs/globalmenu.md)
+//
+// Each already had an off switch and each of those was an **environment
+// variable** — `REACT_X11_A11Y=0`, `NO_AT_BRIDGE=1`,
+// `REACT_X11_NO_GLOBAL_MENU=1`, or unsetting `DBUS_SESSION_BUS_ADDRESS` for
+// the appearance ladder. That is a seam an app cannot reach for itself: the
+// environment is inherited, so a process that sets one before `createRoot()`
+// has also set it for every child it spawns, and the D-Bus one turns off the
+// portals and the app's own services along with the follower. AGENTS.md asks
+// for the off switch to be somewhere the embedder can actually stand.
+//
+// ## Why the policy is process-wide when the option is per-root
+//
+// Because so is the thing it describes. There is one desktop, one D-Bus
+// identity, and one AT-SPI bridge per process — `startA11y()` says so in its
+// name, and appearance.js says so in its header. A per-root flag over
+// process-wide state would be a seam that reads as finer than it is.
+//
+// So **off wins, and off latches.** A root that says `desktop: false` is a
+// root with a constraint — an embedder that owns the toplevel, a test, a
+// daemon that must not fork — and a second root quietly turning the feature
+// back on for it would be the bug. Turning something back *on* is a thing
+// this module deliberately cannot do.
+//
+// The one honest limit: a feature already started stays started. `startA11y()`
+// is memoised per process, so a second root's `desktop: false` stops the next
+// climb and not the bridge that is already up. Pass it on the first root.
+
+/** @typedef {'appearance'|'a11y'|'globalMenu'} DesktopFeature */
+
+/** @type {DesktopFeature[]} */
+const FEATURES = ['appearance', 'a11y', 'globalMenu'];
+
+/** What has been turned off, for the life of the process. */
+const off = new Set();
+
+/**
+ * Apply a root's `desktop` option. Not public — `createRoot({ desktop })` is
+ * the public shape.
+ *
+ * `undefined` is the default and means every feature stays on; `false` turns
+ * all of them off; an object names them one at a time, and a key left out is
+ * left alone.
+ *
+ * @param {boolean | Partial<Record<DesktopFeature, boolean>> | undefined} desktop
+ */
+export function setDesktopIntegration(desktop) {
+  if (desktop === undefined || desktop === true) return;
+  if (desktop === false) {
+    for (const feature of FEATURES) off.add(feature);
+    return;
+  }
+  if (typeof desktop !== 'object') {
+    throw new TypeError(
+      'react-x11: createRoot({ desktop }) takes false or an object of ' +
+        `${FEATURES.map((f) => `${f}: false`).join(', ')} — got ` +
+        `${JSON.stringify(desktop)}.`,
+    );
+  }
+  for (const [feature, on] of Object.entries(desktop)) {
+    if (!FEATURES.includes(/** @type {DesktopFeature} */ (feature))) {
+      throw new TypeError(
+        `react-x11: createRoot({ desktop: { ${feature} } }) — no such ` +
+          `desktop integration. Expected ${FEATURES.join(', ')}.`,
+      );
+    }
+    if (on === false) off.add(feature);
+  }
+}
+
+/**
+ * Whether a feature may run. Every one of the three asks this first, ahead of
+ * its own environment variable, so `desktop: false` is the outermost answer.
+ *
+ * @param {DesktopFeature} feature
+ */
+export function desktopIntegrationEnabled(feature) {
+  return !off.has(feature);
+}
+
+/** Test seam, not public: forget the latch. */
+export function _resetDesktopIntegration() {
+  off.clear();
+}

package/src/errors.js

@@ -59,6 +59,48 @@ export function reportHandlerError(node, handler, error) {
   markFailed();
 }
 
+/**
+ * `REACT_X11_STRICT_TOKENS=1` makes a `$token` the theme does not define
+ * fatal again, for a build that would rather stop than paint something
+ * wrong. The default reports and carries on — see `reportStyleError`.
+ *
+ * Guarded rather than a bare `process.env` because the playground bundle
+ * runs in a browser, where there is no `process` at all.
+ */
+export const STRICT_TOKENS =
+  (typeof process === 'undefined'
+    ? undefined
+    : process.env?.REACT_X11_STRICT_TOKENS) === '1';
+
+/** Messages already printed, so a shared misspelled style reports once per
+ *  (node, message) rather than once per restyle — a theme swap re-resolves
+ *  the whole subtree and would otherwise print the same line every time. */
+const reportedStyleErrors = new WeakMap();
+
+/**
+ * A style the node cannot resolve — today only an unknown `$token`.
+ *
+ * Not a throw, and deliberately: the mistake is one property in one style,
+ * and the tree it would take down is the whole GUI. The property is dropped
+ * (so the widget paints without it, visibly wrong), the message names the
+ * token and whose element wore it, and `process.exitCode` is set so a test
+ * run or a supervisor still counts this as a failure. `REACT_X11_STRICT_TOKENS=1`
+ * restores the throw.
+ */
+export function reportStyleError(node, message) {
+  const seen = reportedStyleErrors.get(node);
+  if (seen?.has(message)) return;
+  if (seen) seen.add(message);
+  else reportedStyleErrors.set(node, new Set([message]));
+  const owner = ownerName(node);
+  console.error(
+    `${message}${owner ? ` — in ${owner}` : ''}. ` +
+      'The property is dropped and the app carries on; set ' +
+      'REACT_X11_STRICT_TOKENS=1 to make this throw instead.',
+  );
+  markFailed();
+}
+
 /** Wrap a call to user code so a throw is reported instead of escaping. */
 export function callHandler(node, handler, fn, ev) {
   try {

package/src/globalmenu.js

@@ -57,6 +57,7 @@
 import { useEffect, useRef, useState } from 'react';
 
 import { loadTransport, sessionBus } from './bus.js';
+import { desktopIntegrationEnabled } from './desktopintegration.js';
 import {
   DBUSMENU_IFACE,
   PROPERTY_TYPES,
@@ -126,6 +127,10 @@ const menuPathFor = (xid) => `/com/react_x11/menus/${xid}`;
  * it is the one that works without touching application code.
  */
 function globalMenuEnabled() {
+  // `createRoot({ desktop: false })` first: handing the menu to a panel is
+  // one of the three things core turns on for you, and that is the switch
+  // that turns the group off (src/desktopintegration.js, #417).
+  if (!desktopIntegrationEnabled('globalMenu')) return false;
   const flag = process.env.REACT_X11_NO_GLOBAL_MENU;
   return !flag || flag === '0';
 }

package/src/index.d.ts

@@ -298,6 +298,43 @@ export interface RootOptions {
    * and coming back is the user's own Tab.
    */
   restoreFocusOnReveal?: boolean;
+  /**
+   * Whether this process talks to the desktop over D-Bus. On by default, and
+   * `false` turns off all three things react-x11 starts for you (#417,
+   * docs/desktop.md):
+   *
+   * | | |
+   * | --- | --- |
+   * | `appearance` | following the desktop's light/dark, accent, contrast and reduced motion (docs/appearance.md) |
+   * | `a11y` | the AT-SPI bridge that makes the app reachable by a screen reader (docs/accessibility.md) |
+   * | `globalMenu` | a `MenuBar` handing its menu to the panel instead of drawing it (docs/globalmenu.md) |
+   *
+   * ```js
+   * await createRoot({ desktop: false });                  // none of it
+   * await createRoot({ desktop: { appearance: false } });  // just that one
+   * ```
+   *
+   * For an embedder that owns those integrations itself, a kiosk or daemon
+   * that must not fork a subprocess to find the bus, and a test that wants
+   * one answer on every machine. With all three off nothing dials the
+   * session bus at startup.
+   *
+   * **Off is process-wide and it latches.** There is one desktop and one
+   * D-Bus identity per process, so a second root cannot turn back on what
+   * another turned off — and a feature already started stays started, so
+   * pass this on the first root.
+   */
+  desktop?: boolean | DesktopIntegrationOptions;
+}
+
+/** Which desktop integrations run. See {@link CreateRootOptions.desktop}. */
+export interface DesktopIntegrationOptions {
+  /** Follow the desktop's light/dark, accent, contrast and reduced motion. */
+  appearance?: boolean;
+  /** The AT-SPI bridge — whether a screen reader can see this app. */
+  a11y?: boolean;
+  /** Whether a `MenuBar` hands its menu to the panel. */
+  globalMenu?: boolean;
 }
 
 export interface ComposeOptions {

package/src/nodes.js

@@ -109,7 +109,12 @@ import {
   windowOrigin,
 } from './anchor.js';
 import { baseTheme } from './palette.js';
-import { callHandler, ownerName } from './errors.js';
+import {
+  callHandler,
+  ownerName,
+  reportStyleError,
+  STRICT_TOKENS,
+} from './errors.js';
 import {
   hooks as a11yHooks,
   isFocusable as a11yFocusable,
@@ -1218,6 +1223,19 @@ function contentSpan(node, axis, intrinsic, out) {
  * one pass by `contentSpan`. `floored` collects what was written so the next
  * measurement can take it back off — a floor left in place would be read
  * back as content that cannot give, and could then only ratchet upwards.
+ *
+ * A floor is written **unrounded**, and the measurement it came from ran
+ * with the pixel grid off (`measuringExactly`) for the reason given there:
+ * rounding a floor grows the tree a pixel per nesting level. What that
+ * leaves is a sharp edge in yoga worth knowing about before writing a
+ * measure function. A line whose items are all held at their floors is one
+ * yoga freezes item by item, subtracting each item's shrink factor from the
+ * line's total as it goes; the total only cancels to zero if the sizes add
+ * up exactly in binary. Three items of, say, 239.28 in a column that
+ * overflows do not, and yoga divides the overflow by the rounding residue
+ * instead of skipping the division — the items come back a billion pixels
+ * tall (issue #411). Whole pixels cancel exactly, which is why the text
+ * measures here answer in them (`TextNode._trim`).
  */
 function writeContentFloors(node, axis, mins, floored) {
   const axisIsMain = mainAxisOf(node) === axis;
@@ -1544,6 +1562,11 @@ export class Node {
     // subtree's hit reach, invalidated through _clearHitBounds()
     this._paintOrderCache = null;
     this._hitBoundsCache = null;
+    // a `$token` the theme does not define, held for `commitMount` to throw
+    // on this node's own fiber — see `_tokenProblem`. Strict mode only.
+    // `null` is "commitMount is still to come", `false` is "it has been and
+    // gone", and an Error is one waiting for it
+    this._tokenError = null;
     this._syncStyle(props);
     this.yoga = yoga ? createLayoutNode() : null;
     if (this.yoga) {
@@ -1575,7 +1598,7 @@ export class Node {
    * them. `baseStyle` is the flattened `style` prop; `style` is that with
    * the active state blocks overlaid.
    */
-  _syncStyle(props) {
+  _syncStyle(props, mounting = false) {
     if (DEV && this.stylable) {
       assertNoFlatStyleProps(props, this.kind, this.semanticNames);
       validateStyle(flattenStyle(props.style), `<${this.kind} style>`);
@@ -1584,12 +1607,16 @@ export class Node {
     this._usesTokens = this.stylable && styleUsesTokens(this._baseStyle);
     if (this._usesTokens) {
       const theme = this.theme;
+      const strict = this.placed;
+      const problems = strict ? [] : null;
       this._baseStyle = resolveTokens(
         this._baseStyle,
         theme,
         `<${this.kind} style>`,
-        this.placed,
+        strict,
+        problems,
       );
+      if (problems?.length) this._tokenProblem(problems, mounting);
     }
     // `disabled` is a prop, not something the pointer does, so it is read
     // straight off props rather than driven by the event manager
@@ -2228,6 +2255,46 @@ export class Node {
     return owner.isPopup ? owner.parent != null : true;
   }
 
+  /**
+   * A `$token` this node's completed ancestry does not define.
+   *
+   * The default is `reportStyleError`: say so loudly, set `process.exitCode`,
+   * and keep the property dropped. `REACT_X11_STRICT_TOKENS=1` makes it fatal
+   * again, and then *where* the throw lands is the whole question — an error
+   * boundary only catches what React invoked, on the fiber React thinks it
+   * is working on.
+   *
+   * `mounting` is the attach walk, which runs inside `appendInitialChild`
+   * while React is completing the nearest host *ancestor* — the `<window>`,
+   * for a whole tree rendered at once. A throw there is attributed to the
+   * window and sails past every boundary the app wrote inside it, which is
+   * the bug this deferral exists for (#420). Stashed instead, and thrown
+   * from `commitMount` on this node's own fiber, where the walk up finds a
+   * boundary at any depth.
+   *
+   * Every other caller already has the right fiber (`commitUpdate`) or has
+   * no React on the stack at all (`appearanceChanged`, from an X event) —
+   * for those, throwing here is both the earliest and the only option, and
+   * the second is the crash strict mode asked for.
+   *
+   * `commitMount` happens once per instance, so a node re-attached after it
+   * has been and gone has nothing left to defer *to*; stashing there would
+   * swallow the error instead of raising it late. Those throw at once, like
+   * the keyed reorder they resemble.
+   */
+  _tokenProblem(problems, mounting) {
+    if (!STRICT_TOKENS) {
+      // every one of them: two misspellings in a style are two things to
+      // fix, and a report that named only the first would send someone back
+      // for a second run to find the second
+      for (const message of problems) reportStyleError(this, message);
+      return;
+    }
+    const error = new Error(problems[0]);
+    if (mounting && this._tokenError === null) this._tokenError = error;
+    else throw error;
+  }
+
   /** The owning window resized: re-resolve, since a query block may now
    * match that did not, or the other way round. */
   _sizeQueriesChanged() {
@@ -2274,7 +2341,7 @@ export class Node {
       if (this.isWindow) this._syncWindowBackground();
       if (this._usesTokens) {
         const before = this.style;
-        this._syncStyle(this.props);
+        this._syncStyle(this.props, mounting);
         // a token change reaches the node without React re-rendering it, so
         // the invalidation a commit would have done has to happen here too
         if (localTextStyleChanged(this.style, before)) {
@@ -4587,7 +4654,12 @@ export class TextNode extends Node {
 
   /** Height for a width: the paragraph shaped into whatever is on offer.
    * The offer is `Infinity` when nothing bounds it, which is also what
-   * `textWrap: 'nowrap'` asks for, so neither needs a mode. */
+   * `textWrap: 'nowrap'` asks for, so neither needs a mode.
+   *
+   * Both answers are **whole pixels**, the trimmed one included — see
+   * `_trim` for why the rounding is not cosmetic. The glyphs are placed
+   * from the unrounded trim (`_placedLayout`), so what the rounding moves
+   * is the bottom edge of the box, by less than half a pixel. */
   measureContent({ width }) {
     const layout = this._layoutFor(this._wrapWidth(width));
     if (!layout) return { width: 0, height: 0 };
@@ -4596,7 +4668,9 @@ export class TextNode extends Node {
       width: Math.ceil(layout.width),
       height: Math.max(
         0,
-        Math.ceil(layout.height) - (trim ? trim.top + trim.bottom : 0),
+        trim
+          ? Math.round(Math.ceil(layout.height) - (trim.top + trim.bottom))
+          : Math.ceil(layout.height),
       ),
     };
   }
@@ -4852,6 +4926,21 @@ export class TextNode extends Node {
    * Measured in the coordinates the layout is **drawn** in, not the ones it
    * reports: `halfLeading` shifts it, and deriving the baseline from the
    * metrics again would silently disagree the day that shift changes.
+   *
+   * The amounts are fractions of a pixel and stay that way — the glyphs are
+   * placed from them (`_placedLayout`). What must not stay fractional is the
+   * **box** they leave behind, which is why `measureContent` rounds the
+   * height it reports and this does not (issue #411).
+   *
+   * A trimmed label measures to the cap band, and a cap height is a fraction
+   * of the em — so before the rounding, a column of trimmed titles handed
+   * yoga three or four flex items whose main size had a fraction in it and
+   * whose content floors (#249) were that same fraction. Yoga freezes a line
+   * like that item by item and divides the overflow by a total shrink factor
+   * that should have cancelled to zero; a fraction that is not exact in
+   * binary leaves a rounding residue there instead, and dividing by it laid
+   * the section titles of `examples/configurator` out 5.6 billion pixels
+   * tall. See `writeContentFloors`, which is the other end of it.
    */
   _trim(layout) {
     if (this.style.textBoxTrim !== 'cap-alphabetic') return null;
@@ -6645,8 +6734,8 @@ export class TextInputNode extends Node {
   /** A preferred width, capped to whatever is on offer — `Infinity` when
    * nothing is, which is what makes the `Math.min` the whole rule. */
   measureContent({ width }) {
-    // Not rounded here: a trimmed `<text>` hands layout the raw cap band
-    // too, and rounding one of them and not the other is a pixel of
+    // `_capBand` rounds, and a trimmed `<text>` rounds the same band the
+    // same way — rounding one of them and not the other is a pixel of
     // difference between a field and the button beside it.
     return { width: Math.min(150, width), height: this._capBand() };
   }
@@ -6896,12 +6985,16 @@ export class TextInputNode extends Node {
     };
   }
 
+  /** Whole pixels either way: a field's height is a flex item's main size,
+   *  and a fractional one costs the tree its content floors (see
+   *  `TextNode._trim`, issue #411). The face with no `capHeight` to round is
+   *  the one that reaches the fallback. */
   _capBand() {
     const style = this.resolvedTextStyle();
     const cap = this.app?.fonts
       ?.match?.(style.family, { weight: style.weight, style: style.style })
       ?.metrics?.(style.size)?.capHeight;
-    return cap ? Math.round(cap) : this._lineHeight();
+    return Math.round(cap || this._lineHeight());
   }
 
   /** Shaped layout of the current value, cached per (value, style,

package/src/style.d.ts

@@ -43,12 +43,15 @@ export function tokenNames(
   style: StyleProperties,
   out?: Set<string>,
 ): Set<string>;
-/** Replace `$token` references with values from the theme. */
+/** Replace `$token` references with values from the theme. A token the theme
+ *  does not define is dropped either way; with `strict`, the message naming
+ *  it is pushed onto `problems` for the caller to report or throw. */
 export function resolveTokens(
   style: StyleProperties,
   theme: Record<string, unknown> | null | undefined,
   where?: string,
   strict?: boolean,
+  problems?: string[] | null,
 ): StyleProperties;
 
 export function styleHasSizeQueries(style: StyleProperties): boolean;

package/src/styles.js

@@ -1206,16 +1206,37 @@ export function stripTokens(style) {
  * `strict` says the node's ancestry is complete, so a token that does not
  * resolve is a mistake. While a subtree is still being built its nodes can
  * see only part of their ancestry — the theme two levels up does not exist
- * for them yet — so resolution there is provisional: unknown tokens are
- * dropped and the node restyles when it attaches.
+ * for them yet — so resolution there is provisional.
+ *
+ * Both cases drop the property, because a value is either resolved or absent
+ * and `'$textMuted1'` is not a colour. What `strict` changes is whether
+ * anyone hears about it: mistakes are pushed onto `problems` and the caller
+ * decides what one costs. Resolving itself never throws — it runs from a
+ * commit and from an X event alike, and only the caller knows whether React
+ * is on the stack to route a throw to a boundary (src/nodes.js).
+ *
+ * A cache hit replays the problems it recorded, so the second node to wear a
+ * misspelled shared style is reported like the first.
  */
-export function resolveTokens(style, theme, where = 'style', strict = true) {
+export function resolveTokens(
+  style,
+  theme,
+  where = 'style',
+  strict = true,
+  problems = null,
+) {
   if (!theme) return stripTokens(style);
   let byTheme = strict ? resolvedCache.get(style) : null;
   if (strict && !byTheme) resolvedCache.set(style, (byTheme = new WeakMap()));
   const hit = byTheme?.get(theme);
-  if (hit) return hit;
+  if (hit) {
+    if (problems && hit.problems) problems.push(...hit.problems);
+    return hit.out;
+  }
 
+  // collected here rather than pushed straight to `problems` so the cache
+  // entry can keep them: the caller that misses is not the only one to hear
+  const found = strict ? [] : null;
   const out = {};
   for (const key of Object.keys(style)) {
     const v = style[key];
@@ -1225,11 +1246,7 @@ export function resolveTokens(style, theme, where = 'style', strict = true) {
         out[key] = theme[name];
         continue;
       }
-      if (!strict) continue;
-      throw new Error(
-        `react-x11: unknown theme token "${v}" in ${where} ` +
-          `(theme has ${Object.keys(theme).join(', ') || 'nothing'})`,
-      );
+      if (strict) found.push(unknownToken(v, theme, where));
     } else if (mentionsToken(v)) {
       let unknown = null;
       const substituted = v.replace(TOKEN_IN_VALUE, (token) => {
@@ -1245,13 +1262,10 @@ export function resolveTokens(style, theme, where = 'style', strict = true) {
       // frame instead of at the style.
       if (!unknown) out[key] = substituted;
       else if (strict) {
-        throw new Error(
-          `react-x11: unknown theme token "${unknown}" in ${where} ${key} ` +
-            `(theme has ${Object.keys(theme).join(', ') || 'nothing'})`,
-        );
+        found.push(unknownToken(unknown, theme, `${where} ${key}`));
       }
     } else if (key.charCodeAt(0) === 58 && v) {
-      out[key] = resolveTokens(v, theme, `${where} ${key}`, strict);
+      out[key] = resolveTokens(v, theme, `${where} ${key}`, strict, found);
     } else if (key === 'animation' && v && typeof v === 'object') {
       const loops = {};
       let incomplete = false;
@@ -1266,11 +1280,11 @@ export function resolveTokens(style, theme, where = 'style', strict = true) {
           theme,
           `${where} animation ${prop}`,
           strict,
+          found,
         );
-        // A provisional resolution drops what it cannot resolve, which for
-        // an ordinary property means "not styled yet". A loop with one end
-        // missing is not a shorter loop, so the whole declaration waits for
-        // the ancestry to complete rather than throwing at a half of one.
+        // A loop with one end missing is not a shorter loop, so a
+        // declaration that lost a value is dropped whole rather than run
+        // between a colour and nothing.
         if (Object.keys(resolved).length !== Object.keys(entry).length) {
           incomplete = true;
         }
@@ -1281,10 +1295,20 @@ export function resolveTokens(style, theme, where = 'style', strict = true) {
       out[key] = v;
     }
   }
-  byTheme?.set(theme, out);
+  if (found?.length && problems) problems.push(...found);
+  byTheme?.set(theme, { out, problems: found?.length ? found : null });
   return out;
 }
 
+/** The one message, written once: what was named, and what the palette in
+ *  force actually has — listing the alternatives is most of the fix. */
+function unknownToken(token, theme, where) {
+  return (
+    `react-x11: unknown theme token "${token}" in ${where} ` +
+    `(theme has ${Object.keys(theme).join(', ') || 'nothing'})`
+  );
+}
+
 export { validateStyle };
 
 /**