react-x11 2.15.2 → 2.16.0

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.2",
+  "version": "2.16.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [
@@ -33,6 +33,7 @@
     "examples:attention": "tsx examples/attention.jsx",
     "examples:badge": "tsx examples/badge.jsx",
     "examples:tray": "tsx examples/tray.jsx",
+    "examples:desktop": "tsx examples/desktop.jsx",
     "examples:tooltips": "tsx examples/tooltips.jsx",
     "examples:chat": "tsx examples/chat.jsx",
     "examples:clipboard": "tsx examples/clipboard.jsx",
@@ -101,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/anchor.js

@@ -204,44 +204,86 @@ 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,
+  };
+  const area = app ? availableArea(app, { x: anchor.x, y: anchor.y }) : 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/application.js

@@ -346,6 +346,18 @@ function environmentContext() {
  * that was mounted after the launch it is asking about.
  */
 let current = null;
+/**
+ * The role of this process's registration, which is **not** the same question
+ * as `current`.
+ *
+ * `current` is the *primary* registration and is deliberately null for a
+ * second copy of an app, because a secondary must not own the badge or the
+ * launcher entry — the primary does. But "no registration at all" and "a
+ * registration that lost the race" are different facts, and a feature probe
+ * that cannot tell them apart tells an app author to call a function they
+ * already called. See `capabilities.js`.
+ */
+let currentRole = null;
 
 /**
  * The schemes the registration declared, kept beside it for the transports
@@ -675,6 +687,7 @@ export async function registerApplication(options = {}) {
     await registration.remove().catch(() => {});
     await forward(ref, dbus, { appId, objectPath, uris });
     await ref.release();
+    currentRole = 'secondary';
     const secondary = {
       role: 'secondary',
       appId,
@@ -711,7 +724,10 @@ export async function registerApplication(options = {}) {
     async release() {
       if (released) return;
       released = true;
-      if (current === primaryRegistration) current = null;
+      if (current === primaryRegistration) {
+        current = null;
+        currentRole = null;
+      }
       await ref.bus.releaseName(appId).catch(() => {});
       await registration?.remove().catch(() => {});
       registration = null;
@@ -721,6 +737,7 @@ export async function registerApplication(options = {}) {
   primaryRegistration[Symbol.asyncDispose] = () =>
     primaryRegistration.release();
   current = primaryRegistration;
+  currentRole = 'primary';
   return primaryRegistration;
 }
 
@@ -774,6 +791,12 @@ async function forward(ref, dbus, { appId, objectPath, uris }) {
   }
 }
 
+/** `'primary' | 'secondary' | null`. Not public — `capabilities.js` uses it to
+ *  tell "never registered" from "registered, but another copy is the app". */
+export function currentRegistrationRole() {
+  return currentRole;
+}
+
 /** This process's registration, or `null`. Not public; the docs use `role`. */
 export function currentRegistration() {
   return current;
@@ -782,6 +805,7 @@ export function currentRegistration() {
 /** Test seam, not public: forget every handler, buffer and registration. */
 export function _resetApplicationState() {
   current = null;
+  currentRole = null;
   currentSchemes = null;
   openHandlers.clear();
   activateHandlers.clear();