react-x11 2.2.0 → 2.3.0

package/README.md

@@ -79,12 +79,14 @@ three:
 - **three platforms.** X11 only. macOS means XQuartz — a separate install, a
   non-native look and no menu bar integration. Windows is out; if you need
   Windows, use Electron or Tauri.
-- **native Wayland.** There is no Wayland backend and there is not going to
-  be one; that would be a different renderer, not a flag. Ordinary
+- **native Wayland — today.** There is no Wayland backend yet. Ordinary
   application windows work fine on a Wayland desktop through Xwayland, which
   is not going away — but the desktop-shell half of X11 (panel struts,
   global key grabs, screen capture, and the window-manager example below)
-  needs a real X session.
+  needs a real X session. A native backend is researched and planned as a
+  **second target beside X11, not a migration**:
+  [docs/wayland.md](docs/wayland.md) is the RFC, from the fd transport up
+  to what the rendering would ride on.
 - **reusing web components.** There is no DOM. Your MUI, your Tailwind and
   your `recharts` do not come with you; the state, data-fetching, validation
   and math libraries mostly do. [docs/ecosystem.md](docs/ecosystem.md) says

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [
@@ -34,6 +34,7 @@
     "xi2:probe": "node scripts/xi2-probe.mjs",
     "globalmenu:host": "node scripts/globalmenu-host.mjs",
     "devtools:proxy": "node scripts/devtools-proxy.mjs",
+    "examples:configurator": "tsx examples/configurator/index.jsx",
     "examples:fonts": "tsx examples/fonts.jsx",
     "examples:form": "tsx examples/form.jsx",
     "examples:rules": "tsx examples/rules.jsx",
@@ -59,12 +60,13 @@
     "stress:check": "tsx scripts/check-stress.jsx",
     "screenshots": "tsx scripts/screenshots.jsx",
     "screenshots:framed": "tsx scripts/screenshots-framed.jsx",
-    "bench": "tsx scripts/bench/protocol.js",
+    "bench": "node --expose-gc --import tsx scripts/bench/protocol.js",
     "bench:pixels": "tsx scripts/bench/pixels.js",
     "bench:frames": "tsx scripts/bench/frames.js",
     "docs:dev": "npm --prefix website start",
     "docs:build": "npm --prefix website run build",
-    "docs:test": "npm --prefix website test"
+    "docs:test": "npm --prefix website test",
+    "bench:presenters": "node --import tsx scripts/bench/presenters.js"
   },
   "repository": {
     "type": "git",
@@ -83,12 +85,14 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "ntk": "^8.5.0",
+    "ntk": "^8.7.0",
     "react-reconciler": "^0.33.0",
     "yoga-layout": "^3.2.1"
   },
   "optionalDependencies": {
-    "dbus-native": "^0.15.1"
+    "@windowkit/appkit": "^0.1.0",
+    "dbus-native": "^0.15.1",
+    "x11-dri": "^0.7.0"
   },
   "peerDependencies": {
     "@babel/core": "^8.0.0",
@@ -118,6 +122,9 @@
     "@babel/core": "^8.0.1",
     "@babel/plugin-transform-react-jsx": "^8.0.1",
     "@eslint/js": "^9.32.0",
+    "@fontsource/instrument-serif": "^5.3.0",
+    "@fontsource/inter": "^5.3.0",
+    "@fontsource/jetbrains-mono": "^5.3.0",
     "@types/react": "^19.2.17",
     "eslint": "^9.32.0",
     "eslint-plugin-react": "^7.37.5",

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,
@@ -303,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);
     }
@@ -553,6 +571,36 @@ async function connect(options) {
 const isNtkApp = (v) =>
   Boolean(v) && typeof v.createWindow === 'function' && typeof v.X === 'object';
 
+/**
+ * Which display system a root that opens its own connection talks to.
+ *
+ * `'auto'` — the default — is one rule: macOS gets the native Core
+ * Animation backend, everything else gets X11 via `$DISPLAY`. (More rungs —
+ * Wayland — join this ladder, not a new one; docs/wayland.md.) On a mac
+ * without the `@windowkit/appkit` bridge installed, auto falls back to X11 so
+ * an XQuartz setup keeps working; asking for `'cocoa'` by name means the
+ * bridge is required, and its absence is an error that says how to fix it.
+ * `REACT_X11_BACKEND` overrides for A/B runs without touching code.
+ */
+function resolveBackend(options) {
+  const asked = options.backend ?? process.env.REACT_X11_BACKEND ?? 'auto';
+  if (asked === 'x11' || asked === 'cocoa') return asked;
+  if (asked !== 'auto') {
+    throw new Error(
+      `react-x11: unknown backend ${JSON.stringify(asked)} — expected ` +
+        "'x11', 'cocoa' or 'auto'.",
+    );
+  }
+  // Naming an X endpoint is choosing X11: a `display` or a `stream` (the
+  // tests' in-process server, a tunnel) would be silently ignored by any
+  // other backend, and an ignored connection option is worse than either
+  // answer.
+  if (options.display !== undefined || options.stream !== undefined) {
+    return 'x11';
+  }
+  return process.platform === 'darwin' ? 'cocoa' : 'x11';
+}
+
 // What a root that opens its own connection forwards to ntk. `stream` is
 // how you reach a server that is not on the other end of $DISPLAY — an
 // in-process one, a tunnel — and is what the tests connect through.
@@ -634,11 +682,24 @@ export async function createRoot(options = {}) {
   }
   const { app: borrowed, onDisconnect, ...rest } = options;
   const owned = borrowed === undefined;
+  // Which display system this root speaks — resolved before anything runs,
+  // because the desktop-integration default below depends on it. A borrowed
+  // app already IS a backend, so the option only steers owned connections.
+  const backend = owned ? resolveBackend(rest) : null;
   // 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 cocoa backend's desktop is not freedesktop's: the AT-SPI bridge and
+  // the D-Bus global menu have nothing to register against there, so they
+  // default off (their macOS replacements are their own workstream —
+  // docs/macos.md). The appearance ladder stays on: its macOS rung is the
+  // one that answers. An explicit `desktop` option still wins.
+  setDesktopIntegration(
+    rest.desktop ??
+      (backend === 'cocoa' ? { a11y: false, globalMenu: false } : undefined),
+  );
   // 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
@@ -651,16 +712,38 @@ export async function createRoot(options = {}) {
   // synchronous block, and only where the handshake takes longer than it. It
   // is not measurable on a Unix socket, and it is lost in the noise on a link
   // slow enough to matter. This is the right order, not a fast one.
-  const connecting = owned
-    ? connect(
-        Object.fromEntries(
-          CONNECT_OPTIONS.filter((k) => rest[k] !== undefined).map((k) => [
-            k,
-            rest[k],
-          ]),
-        ),
-      )
-    : Promise.resolve(borrowed);
+  const connectX11 = () =>
+    connect(
+      Object.fromEntries(
+        CONNECT_OPTIONS.filter((k) => rest[k] !== undefined).map((k) => [
+          k,
+          rest[k],
+        ]),
+      ),
+    );
+  const cocoaAsked =
+    rest.backend === 'cocoa' || process.env.REACT_X11_BACKEND === 'cocoa';
+  const connecting = !owned
+    ? Promise.resolve(borrowed)
+    : backend === 'cocoa'
+      ? import('./cocoa/app.js')
+          .then(({ createCocoaApp }) => createCocoaApp(rest))
+          .catch((err) => {
+            // Asked for by name, the bridge is required and its absence is
+            // the error (it says how to install). Reached by 'auto', a mac
+            // without it falls back to X11 so an XQuartz setup keeps
+            // working — said once, because a silent fallback would look
+            // like the native backend being broken rather than absent.
+            if (cocoaAsked) throw err;
+            if (process.env.NODE_ENV !== 'production') {
+              console.warn(
+                'react-x11: no @windowkit/appkit bridge — falling back to the ' +
+                  `X11 backend. (${err.message.split('\n')[0]})`,
+              );
+            }
+            return connectX11();
+          })
+      : connectX11();
   const layout = loadLayout();
   const integrations = loadIntegrations(); // null when there is nothing to install
   const [app] = await Promise.all([connecting, layout, integrations]);

package/src/anchor.js

@@ -28,11 +28,20 @@ import { availableArea } from './screens.js';
 export function screenRect(node) {
   if (!node?.abs) return null;
   const origin = windowOrigin(node);
+  // Logical pixels, like every rect application code touches: this is a
+  // public export, and the rects it is compared against — `anchorRect`'s
+  // result, `anchorArea` — answer in logical too. The device-pixel sum
+  // (origin + abs) divides once, here; a caller that needs the device rect
+  // is placement math and multiplies back by `node.scale` itself. On a 1x
+  // display the two units coincide, which is how a mix survived until the
+  // first 2x backend ran the tooltip arrow into the wrong half of the
+  // bubble.
+  const s = node.scale ?? 1;
   return {
-    x: origin.x + node.abs.x,
-    y: origin.y + node.abs.y,
-    width: node.abs.width,
-    height: node.abs.height,
+    x: (origin.x + node.abs.x) / s,
+    y: (origin.y + node.abs.y) / s,
+    width: node.abs.width / s,
+    height: node.abs.height / s,
   };
 }
 
@@ -136,7 +145,8 @@ export function deviceAnchorArea(node) {
   const app = node?.app;
   if (!app) return null;
   const at = screenRect(node);
-  return availableArea(app, at ? { x: at.x, y: at.y } : null);
+  const s = node.scale ?? 1;
+  return availableArea(app, at ? { x: at.x * s, y: at.y * s } : null);
 }
 
 /**

package/src/appcontext.js

@@ -57,7 +57,16 @@ export function useApp() {
   return app;
 }
 
-const SUPPORTS_FEATURES = new Set(['transparency', 'shaders']);
+const SUPPORTS_FEATURES = new Set([
+  'transparency',
+  'shaders',
+  'nativeControls',
+]);
+
+// 'nativeControls' is a property of the backend, decided before the first
+// render and never changing after — so its subscription has nothing to
+// deliver and its snapshot is a property test.
+const NEVER_CHANGES = () => () => {};
 
 /**
  * Can this **display** do something, as a value a component can branch on?
@@ -105,6 +114,13 @@ const SUPPORTS_FEATURES = new Set(['transparency', 'shaders']);
  * disagree exactly when the policy did not ask. The capabilities also say
  * *why* this is false; see docs/gl.md.
  *
+ * `'nativeControls'` is true when this backend renders the platform's own
+ * control bezels — today the Cocoa backend, never X11. The widget set
+ * already branches on it through the theme's `controls: 'auto'` policy, so
+ * this hook is for application code composing its own controls that wants
+ * to sit beside native ones. It is a property of the backend and never
+ * changes over the app's life.
+ *
  * Unlike `'transparency'`, which comes and goes with the compositor, this
  * settles once and then holds still: under a policy that could pick direct,
  * `createRoot()` waits for ntk's probe before handing the app back, so the
@@ -127,18 +143,22 @@ export function useSupports(feature) {
   // side of it from disagreeing (see watchDirectGL).
   const subscribe = useCallback(
     (onChange) =>
-      feature === 'shaders'
-        ? watchDirectGL(app, onChange)
-        : watchCompositing(app, onChange),
+      feature === 'nativeControls'
+        ? NEVER_CHANGES()
+        : feature === 'shaders'
+          ? watchDirectGL(app, onChange)
+          : watchCompositing(app, onChange),
     [app, feature],
   );
   // a boolean, so the snapshot is stable for a given state — returning the
   // visual object here would tear on every render
   const snapshot = useCallback(
     () =>
-      feature === 'shaders'
-        ? hasDirectGL(app)
-        : compositingActive(app) && Boolean(argbVisual(app)),
+      feature === 'nativeControls'
+        ? Boolean(app.nativeBezels)
+        : feature === 'shaders'
+          ? hasDirectGL(app)
+          : compositingActive(app) && Boolean(argbVisual(app)),
     [app, feature],
   );
   return useSyncExternalStore(subscribe, snapshot, snapshot);