react-x11 2.15.3 → 2.16.1

package/README.md

@@ -609,6 +609,43 @@ The full threat model, including what react-x11 does and does not defend
 against, is [docs/security.md](docs/security.md). To report something,
 [SECURITY.md](SECURITY.md).
 
+## Similar projects
+
+- [GPUIX](https://github.com/remorses/gpuix) — React for
+  [GPUI](https://github.com/zed-industries/zed/tree/main/crates/gpui), Zed's
+  GPU UI framework. Each commit crosses a napi-rs addon as one batch of
+  mutations to a retained Rust tree, which GPUI lays out with Taffy's flexbox
+  and paints through Metal, DirectX or Vulkan, on macOS, Windows and Linux.
+- [react-native-gpui](https://github.com/natew/react-native-gpui) — React
+  Native's component API (`View`, `Text`, `Pressable`, `TextInput`,
+  `FlatList`) on GPUI as well, hosted the other way round: a Rust binary
+  embeds the system's JavaScriptCore and runs the bundled app, and commits
+  reach GPUI in memory. macOS on Apple silicon only, for now.
+- [GTKX](https://github.com/gtkx-org/gtkx) — React for GNOME: every GObject
+  is a JSX element, so the tree is the platform's own GTK4 and Adwaita
+  widgets. The TypeScript bindings are generated from GObject-Introspection
+  and call into GTK through a Rust core on Node.js. Linux-only by design.
+- React Native for [Windows](https://github.com/microsoft/react-native-windows)
+  and [macOS](https://github.com/microsoft/react-native-macos) — Microsoft's
+  desktop platforms for React Native. On Windows the new architecture's
+  renderer targets Composition from the start, in Windows App SDK apps by
+  default, with XAML islands for advanced controls; on macOS a fork of React
+  Native maps its UIKit views onto AppKit. [docs/windows.md](docs/windows.md)
+  cites its threading as prior art: JS on a thread of its own, and every
+  mount posted to the UI thread that alone touches the visuals.
+- [React Native Skia](https://github.com/Shopify/react-native-skia) — 2D
+  graphics for React Native, with a React renderer of its own: the
+  components inside a `<Canvas>` become a Skia display list, cheap to
+  animate with Reanimated. On iOS, Android, macOS and tvOS, in the browser
+  through CanvasKit, and headless on Node. Its experimental Graphite builds
+  render through Dawn and can share a GPU device with React Native WebGPU.
+- [React Native WebGPU](https://github.com/wcandillon/react-native-webgpu) —
+  not a renderer but a GPU surface for React Native: the WebGPU API
+  (`navigator.gpu` and a `<Canvas>` view) on iOS, Android, macOS and
+  visionOS, implemented over Dawn, Chrome's WebGPU implementation. It runs
+  three.js's WebGPU renderer and React Three Fiber. The nearest thing in
+  react-x11 is [`<glarea>`](#3d), which speaks GL instead.
+
 ## See also
 
 - [awesome-react-renderer](https://github.com/chentsulin/awesome-react-renderer)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.15.3",
+  "version": "2.16.1",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [
@@ -102,12 +102,12 @@
   "dependencies": {
     "ical.js": "^2.2.1",
     "linebreak": "^1.1.0",
-    "ntk": "^8.7.0",
+    "ntk": "^8.9.0",
     "react-reconciler": "^0.34.0",
     "yoga-layout": "^3.2.1"
   },
   "optionalDependencies": {
-    "@windowkit/appkit": "^0.10.0",
+    "@windowkit/appkit": "^0.12.0",
     "@windowkit/wayland": "^3.1.1",
     "dbus-native": "^0.15.1",
     "x11-dri": "^0.9.0"

package/src/Reconciler.js

@@ -24,6 +24,13 @@ import {
 } from './nodes/window/window.js';
 import { PopupNode } from './nodes/window/popup.js';
 import { BoxNode } from './nodes/box.js';
+import { THEME_SCOPE } from './nodes/kinds.js';
+import {
+  ThemeBoxNode,
+  ThemeScopeNode,
+  attachTopLevel,
+  detachTopLevel,
+} from './nodes/scope.js';
 import { TextNode, TextChunkNode, setTextStripBelow } from './nodes/text.js';
 import { ImageNode } from './nodes/image.js';
 import { CanvasNode } from './nodes/canvas.js';
@@ -60,7 +67,11 @@ 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';
+import {
+  createRegisteredNode,
+  elementDefinition,
+  registeredElements,
+} from './registry.js';
 import { SvgNode, SvgChildNode } from './svgnodes.js';
 import { loadLayout } from './yoga.js';
 
@@ -97,6 +108,36 @@ export const HOST_TYPES = [
   'foreign',
 ];
 
+// The host context of the root's own children. `atRoot` is what lets
+// `createInstance` see that an element has no window above it — there is no
+// other moment to know it: a node is built bottom-up, before it has a parent
+// to ask, and appended to the container only in the commit.
+const ROOT_CONTEXT = Object.freeze({
+  isInsideText: false,
+  isInsideSvg: false,
+  atRoot: true,
+  inWindow: false,
+});
+
+// What the root of the tree can hold: the elements that are windows of their
+// own, and the provider's node, which holds more of them. Everything else
+// draws into a window, so it has to be inside one.
+const ROOT_TYPES = new Set(['window', 'popup', THEME_SCOPE]);
+
+/**
+ * A drawn element with no window above it. Without this it reached
+ * `appendChildToContainer` and failed there as `child.realize is not a
+ * function` — or, under a `<ThemeProvider>`, as a `<window>` nested in a
+ * `<box>` the app never wrote (#584).
+ */
+function notAtRoot(type) {
+  return new Error(
+    `react-x11: <${type}> must be inside a <window> — it is at the root of ` +
+      'the tree, which holds only <window> and <popup> elements. Render it ' +
+      `inside one: <window><${type} …/></window>.`,
+  );
+}
+
 const HostConfig = {
   supportsMutation: true,
   supportsPersistence: false,
@@ -135,10 +176,7 @@ const HostConfig = {
   scheduleMicrotask: queueMicrotask,
 
   getRootHostContext() {
-    return {
-      isInsideText: false,
-      isInsideSvg: false,
-    };
+    return ROOT_CONTEXT;
   },
 
   getChildHostContext(parentHostContext, type) {
@@ -150,6 +188,12 @@ const HostConfig = {
       isInsideText: parentHostContext.isInsideText || type === 'text',
       // <svg> children are declarative SVG elements, not react-x11 nodes
       isInsideSvg: parentHostContext.isInsideSvg || type === 'svg',
+      // Still at the root under a `<ThemeProvider>` written there, which
+      // draws nothing; under anything else, inside a window.
+      atRoot: parentHostContext.atRoot && type === THEME_SCOPE,
+      // Directly inside a window, where a provider can hand a nested window
+      // on to it.
+      inWindow: type === 'window' || type === 'popup',
     };
   },
 
@@ -195,6 +239,17 @@ const HostConfig = {
           '<text> spans and strings are.',
       );
     }
+    // Asked here, in the render phase, rather than when the node reaches the
+    // container: an error boundary above can catch it, and nothing has been
+    // built yet. A name nobody knows gets the unknown-element error below,
+    // which lists what there is.
+    if (
+      hostContext.atRoot &&
+      !ROOT_TYPES.has(type) &&
+      (HOST_TYPES.includes(type) || elementDefinition(type))
+    ) {
+      throw notAtRoot(type);
+    }
     let node;
     switch (type) {
       case 'window':
@@ -216,6 +271,18 @@ const HostConfig = {
       case 'box':
         node = new BoxNode(props, rootContainer);
         break;
+      case THEME_SCOPE:
+        // `<ThemeProvider>`'s node (nodes/kinds.js). Above the windows it
+        // draws nothing and hands its palette to the windows under it; inside
+        // a window it is the box that fills its parent it has always been, so
+        // `style` means what it says and a `$token` beneath resolves — and
+        // directly inside one, a box that passes nested windows on to it.
+        node = hostContext.atRoot
+          ? new ThemeScopeNode(props, rootContainer)
+          : hostContext.inWindow
+            ? new ThemeBoxNode(props, rootContainer)
+            : new BoxNode(props, rootContainer);
+        break;
       case 'textinput':
         node = new TextInputNode(props, rootContainer);
         break;
@@ -278,6 +345,13 @@ const HostConfig = {
   },
 
   createTextInstance(text, rootContainer, hostContext) {
+    if (hostContext.atRoot) {
+      throw new Error(
+        `react-x11: raw text ${JSON.stringify(text)} must be inside a ` +
+          '<window>, in a <text> element — it is at the root of the tree, ' +
+          'which holds only <window> and <popup> elements.',
+      );
+    }
     if (!hostContext.isInsideText && !hostContext.isInsideSvg) {
       throw new Error(
         `react-x11: raw text ${JSON.stringify(text)} must be wrapped in a ` +
@@ -338,19 +412,11 @@ const HostConfig = {
     parentInstance.insertBefore(child, null);
   },
 
+  // The root holds windows, popups and theme scopes (`createInstance` turned
+  // everything else away), and nodes/scope.js is what knows how to put each
+  // of them there — a scope's windows can arrive after the scope did.
   appendChildToContainer(container, child) {
-    if (!child.window) {
-      // Top-level window: realize the whole subtree top-down against the
-      // screen root.
-      child.realize(null);
-    }
-    // React's getPublicRootInstance answers from the root fiber's first
-    // child, and only when that child is a host component. `render()` wraps
-    // the tree in a context provider, which is not one, so it would answer
-    // null — the container keeps the list instead. Same answer as before:
-    // the first top-level node the tree put here.
-    (container._rootChildren ??= []).push(child);
-    a11yHooks.rootMounted?.(child);
+    attachTopLevel(container, child);
   },
 
   insertBefore(parentInstance, child, beforeChild) {
@@ -358,7 +424,7 @@ const HostConfig = {
   },
 
   insertInContainerBefore(container, child) {
-    HostConfig.appendChildToContainer(container, child);
+    attachTopLevel(container, child);
   },
 
   removeChild(parentInstance, child) {
@@ -366,11 +432,8 @@ const HostConfig = {
   },
 
   removeChildFromContainer(container, child) {
-    const roots = container._rootChildren;
-    const at = roots ? roots.indexOf(child) : -1;
-    if (at !== -1) roots.splice(at, 1);
     // before the destroy, while the subtree is still walkable
-    a11yHooks.rootUnmounted?.(child);
+    detachTopLevel(container, child);
     child.destroySubtree();
   },
 

package/src/acceleratorhooks.js

@@ -11,6 +11,35 @@ import { useEffect, useMemo, useRef } from 'react';
 import { matchesShortcut } from './accelerators.js';
 import { useTopLevelWindow } from './windowid.js';
 
+/**
+ * A binding whose anchor resolved to nothing binds nothing — there is no
+ * event manager to register it with, and the effect runs once, so it will
+ * not come back. Silent, that is a shortcut that simply never fires, with
+ * the tree, the chord and the handler all looking correct (issue #616).
+ *
+ * Once per process, in development: the mistake is structural, and an app
+ * that made it once made it for every chord it declares.
+ */
+let warnedAboutAnchor = false;
+export function resetAcceleratorWarningForTests() {
+  warnedAboutAnchor = false;
+}
+
+function warnUnanchored() {
+  if (process.env.NODE_ENV === 'production' || warnedAboutAnchor) return;
+  warnedAboutAnchor = true;
+  console.warn(
+    'react-x11: a shortcut was bound in a component with no window to hang ' +
+      'it off, so it is bound to nothing and will never fire. By default a ' +
+      "binding belongs to the tree's top-level <window> or, in an app with " +
+      'none, the root-level <popup> holding the keyboard. Anchor it ' +
+      'explicitly with `scope`:\n' +
+      '  const here = useRef(null);\n' +
+      "  useAccelerator([['space']], onToggle, { scope: here });\n" +
+      '  return <box ref={here}>…</box>;',
+  );
+}
+
 /**
  * Bind a chord for as long as this component is mounted, anchored at
  * `anchorRef` — the node the binding belongs to, which is what decides
@@ -30,7 +59,10 @@ export function useAcceleratorEntry(anchorRef, handle, enabled = true) {
   useEffect(() => {
     if (!enabled) return undefined;
     const manager = anchorRef.current?.root?.events;
-    if (!manager) return undefined;
+    if (!manager) {
+      warnUnanchored();
+      return undefined;
+    }
     return manager.registerAccelerator({
       anchor: () => anchorRef.current ?? null,
       handle: (ev) => live.current?.(ev) ?? false,
@@ -52,11 +84,13 @@ export function useAcceleratorEntry(anchorRef, handle, enabled = true) {
  * The handler is called with the key event, and the key is consumed.
  *
  * By default the binding belongs to the window the component is in, which is
- * what an application-wide shortcut wants. Two options for when it is not:
- * `enabled: false` unbinds it without unmounting anything, and `scope` takes
- * a ref to a node the binding hangs off instead — the way to give a modal
- * `<Dialog>` a shortcut of its own, since a binding on the window behind it
- * is one the modal has taken the keyboard from.
+ * what an application-wide shortcut wants — or, in an app with no `<window>`
+ * at all, to the root-level `<popup>` that took the keyboard, which is the
+ * whole of a tray popover's UI (`useTopLevelWindow`). Two options for when
+ * that is not it: `enabled: false` unbinds it without unmounting anything,
+ * and `scope` takes a ref to a node the binding hangs off instead — the way
+ * to give a modal `<Dialog>` a shortcut of its own, since a binding on the
+ * window behind it is one the modal has taken the keyboard from.
  */
 export function useAccelerator(shortcut, handler, options = {}) {
   const { enabled = true, scope } = options;

package/src/anchor.js

@@ -148,7 +148,20 @@ export function deviceAnchorArea(node) {
   if (!app) return null;
   const at = screenRect(node);
   const s = node.scale ?? 1;
-  return availableArea(app, at ? { x: at.x * s, y: at.y * s } : null);
+  // The whole rect, not its corner: a window straddling two monitors has
+  // nodes on each, and the monitor a node is on is the one it covers most of
+  // (`monitorAt`, src/screens.js).
+  return availableArea(
+    app,
+    at
+      ? {
+          x: at.x * s,
+          y: at.y * s,
+          width: at.width * s,
+          height: at.height * s,
+        }
+      : null,
+  );
 }
 
 /**
@@ -204,44 +217,91 @@ export function anchorRect(node, options = {}) {
   // popup's `x`/`y` props. The math between runs in device pixels, because
   // `abs`, the window origin and the monitor area are (src/scale.js).
   const s = node.scale ?? 1;
+  // The anchor is the sub-rect where there is one, all the way through:
+  // the side that flips, the edge that aligns, and — since a popup with no
+  // size of its own is as wide as the thing it hangs off — the default
+  // width.
+  const anchor = subRect(node, deviceAt(options.at, s));
+  // the rect the *alignment* reads, which is the anchor's own unless the
+  // caller split the two axes — one origin serves both, since both nodes are
+  // in the same window
+  const cross = options.alignTo ? (subRect(options.alignTo) ?? anchor) : anchor;
+  const origin = windowOrigin(node);
+  const onScreen = (r) => ({
+    x: origin.x + r.x,
+    y: origin.y + r.y,
+    width: r.width,
+    height: r.height,
+  });
+  return placeAgainst(
+    onScreen(anchor),
+    onScreen(cross),
+    deviceAnchorArea(node),
+    s,
+    { ...options, direction: options.direction ?? node.direction },
+  );
+}
+
+/**
+ * The same placement against a rect **on the screen**, with no node behind
+ * it: the frame of the tray item a click reports, or a point where the
+ * pointer was. `rect` is logical screen pixels, the unit a popup's `x`/`y`
+ * are in, and `{ x, y }` alone is a point; the result is logical too.
+ *
+ * `scale` is the display's, since there is no node to ask, and `direction`
+ * decides what `'start'` and `'end'` mean — a node's anchor takes both from
+ * the node. The popup is kept on the monitor the rect is on.
+ */
+export function anchorScreenRect(app, rect, options = {}) {
+  if (typeof rect?.x !== 'number' || typeof rect?.y !== 'number') return null;
+  const s = options.scale ?? 1;
+  const anchor = {
+    x: rect.x * s,
+    y: rect.y * s,
+    width: (rect.width ?? 0) * s,
+    height: (rect.height ?? 0) * s,
+  };
+  // The monitor is picked from the whole rect rather than its top-left
+  // corner, because a tray item's frame is not inside its own display: a
+  // menu-bar button reports a rect that starts a few points above the top
+  // edge, and the corner alone lands on whichever display happens to reach
+  // up past it — a different one, on a desk with a taller head (#618).
+  const area = app ? availableArea(app, anchor) : null;
+  return placeAgainst(anchor, anchor, area, s, options);
+}
+
+/**
+ * The placement both anchors share, in device pixels: `anchor` is the rect
+ * the popup hangs off, `cross` the one it aligns to, both on the screen, and
+ * `area` what it is kept inside — null where there is nothing to ask, and it
+ * then neither flips nor clamps.
+ */
+function placeAgainst(anchor, cross, area, s, options) {
   const {
     placement = 'bottom',
     align = 'start',
     alignOffset: logicalAlignOffset = 0,
     offset: logicalOffset = 2,
-    at,
-    alignTo,
     // A popup that covers its own anchor — a native popup button's menu,
     // which opens with the chosen row over the control — has no other side
     // to flip to: it is clamped into the screen instead, as AppKit clamps.
     flip = true,
-    direction = node.direction,
+    direction,
   } = options;
   const alignOffset = logicalAlignOffset * s;
   const offset = logicalOffset * s;
   const rtl = direction === 'rtl';
 
-  // The anchor is the sub-rect where there is one, all the way through:
-  // the side that flips, the edge that aligns, and — since a popup with no
-  // size of its own is as wide as the thing it hangs off — the default
-  // width.
-  const anchor = subRect(node, deviceAt(at, s));
   const width = options.width !== undefined ? options.width * s : anchor.width;
   const height = options.height !== undefined ? options.height * s : 0;
 
-  const origin = windowOrigin(node);
-  const ax = origin.x + anchor.x;
-  const ay = origin.y + anchor.y;
+  const ax = anchor.x;
+  const ay = anchor.y;
   const aw = anchor.width;
   const ah = anchor.height;
-  // the rect the *alignment* reads, which is the anchor's own unless the
-  // caller split the two axes — one origin serves both, since both nodes are
-  // in the same window
-  const cross = alignTo ? (subRect(alignTo) ?? anchor) : anchor;
-  const cx = origin.x + cross.x;
-  const cy = origin.y + cross.y;
+  const cx = cross.x;
+  const cy = cross.y;
 
-  const area = deviceAnchorArea(node);
   const left = area?.x ?? 0;
   const top = area?.y ?? 0;
   const right = area ? area.x + area.width : null;

package/src/capabilities.js

@@ -176,8 +176,8 @@ async function probeNotifications({ app } = {}) {
 // tray
 // ---------------------------------------------------------------------------
 
-async function probeTray({ app } = {}) {
-  const target = app ?? soleApp();
+/** The tray on an app that has one of its own, which needs nothing asked. */
+function trayNow(target) {
   if (typeof target?.createStatusItem === 'function') {
     return frozen('cocoa', {
       menu: true,
@@ -194,6 +194,12 @@ async function probeTray({ app } = {}) {
       scroll: false,
     });
   }
+  return null;
+}
+
+async function probeTray({ app } = {}) {
+  const now = trayNow(app ?? soleApp());
+  if (now) return now;
 
   const ref = await sessionBus();
   if (!ref) return NONE;
@@ -226,8 +232,8 @@ async function probeTray({ app } = {}) {
 // launcher
 // ---------------------------------------------------------------------------
 
-async function probeLauncher({ app } = {}) {
-  const target = app ?? soleApp();
+/** The Dock tile on an app that has one, which needs nothing asked. */
+function launcherNow(target) {
   if (typeof target?.setDockBadge === 'function') {
     return frozen('cocoa', {
       badge: true,
@@ -239,6 +245,12 @@ async function probeLauncher({ app } = {}) {
       needsDesktopFile: false,
     });
   }
+  return null;
+}
+
+async function probeLauncher({ app } = {}) {
+  const now = launcherNow(app ?? soleApp());
+  if (now) return now;
 
   // The Linux rung needs two things that are not the bus: an app id to
   // attribute the entry to, and a `.desktop` file of that name for the
@@ -322,3 +334,16 @@ export async function desktopCapability(name, options = {}) {
 /** The "nothing here" answer, exported so a caller can compare against it and
  *  so the hook has something stable to return on the first frame. */
 export const NO_CAPABILITY = NONE;
+
+/**
+ * The answer for a capability where it is known without asking anything —
+ * the Cocoa app's own tray and Dock tile — or null where finding out takes a
+ * round trip. What lets `useDesktopCapability` be settled on its first frame
+ * where the answer never needed waiting for.
+ */
+export function capabilityNow(name, { app } = {}) {
+  const target = app ?? soleApp();
+  if (name === 'tray') return trayNow(target);
+  if (name === 'launcher') return launcherNow(target);
+  return null;
+}