react-x11 2.12.0 → 2.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.12.0",
+  "version": "2.14.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [
@@ -20,6 +20,8 @@
     "examples:appearance": "tsx examples/appearance.jsx",
     "examples:animation": "tsx examples/animation.jsx",
     "examples:simple": "tsx examples/simple.jsx",
+    "examples:wayland-gl": "node examples/wayland-gl.mjs",
+    "examples:wayland-ui": "node examples/wayland-ui.mjs",
     "examples:simple-nojsx": "node examples/simple-nojsx.js",
     "examples:xeyes": "tsx examples/xeyes.jsx",
     "examples:dashboard": "tsx examples/dashboard.jsx",
@@ -60,6 +62,7 @@
     "examples:frame": "tsx examples/frame.jsx",
     "labs:text-baseline": "tsx examples/labs/text-baseline.jsx",
     "labs:direct-gl": "tsx examples/labs/direct-gl.jsx",
+    "labs:gl-overlay": "tsx examples/labs/gl-overlay.jsx",
     "examples:viewer3d": "tsx examples/viewer3d.jsx",
     "examples:transparent": "tsx examples/transparent.jsx",
     "examples:windows": "tsx examples/windows.jsx",
@@ -99,20 +102,21 @@
     "ical.js": "^2.2.1",
     "linebreak": "^1.1.0",
     "ntk": "^8.7.0",
-    "react-reconciler": "^0.33.0",
+    "react-reconciler": "^0.34.0",
     "yoga-layout": "^3.2.1"
   },
   "optionalDependencies": {
     "@windowkit/appkit": "^0.10.0",
+    "@windowkit/wayland": "^3.1.1",
     "dbus-native": "^0.15.1",
-    "x11-dri": "^0.7.0"
+    "x11-dri": "^0.9.0"
   },
   "peerDependencies": {
     "@babel/core": "^8.0.0",
     "@babel/plugin-transform-react-jsx": "^8.0.0",
     "hot-module-replacement": "^4.0.1",
-    "react": "^19.0.0",
-    "react-refresh": "^0.18.0"
+    "react": "^19.3.0",
+    "react-refresh": "^0.19.0"
   },
   "peerDependenciesMeta": {
     "@babel/core": {
@@ -145,9 +149,9 @@
     "hot-module-replacement": "^4.0.1",
     "katex": "^0.18.1",
     "prettier": "^3.6.0",
-    "react": "^19.2.8",
-    "react-devtools-core": "^7.0.1",
-    "react-refresh": "^0.18.0",
+    "react": "^19.3.0",
+    "react-devtools-core": "^8.0.0",
+    "react-refresh": "^0.19.0",
     "tsx": "^4.23.1",
     "typescript": "^7.0.2",
     "ws": "^8.21.1"

package/src/Reconciler.js

@@ -138,17 +138,18 @@ const HostConfig = {
     return {
       isInsideText: false,
       isInsideSvg: false,
-      isInside3d: false,
     };
   },
 
   getChildHostContext(parentHostContext, type) {
+    // A `<glarea>`'s children are drawn nodes like any box's — 2D content
+    // above the surface (src/gloverlay.js) — so it opens no context of its
+    // own. A scene graph over the surface is `@react-x11/components/three`,
+    // with a reconciler of its own.
     return {
       isInsideText: parentHostContext.isInsideText || type === 'text',
       // <svg> children are declarative SVG elements, not react-x11 nodes
       isInsideSvg: parentHostContext.isInsideSvg || type === 'svg',
-      // inside <glarea> the children are scene nodes, not drawn nodes
-      isInside3d: parentHostContext.isInside3d || type === 'glarea',
     };
   },
 
@@ -194,17 +195,6 @@ const HostConfig = {
           '<text> spans and strings are.',
       );
     }
-    if (hostContext.isInside3d) {
-      // `<glarea>` is a leaf here: it owns the surface, the frame clock and
-      // the swap, and `onDraw` is the escape hatch. A *scene graph* over it
-      // — meshes, materials, lights, post-processing, on either backend —
-      // is `@react-x11/components/three`, which brings its own reconciler.
-      throw new Error(
-        `react-x11: <${type}> is not an element — <glarea> takes no ` +
-          'children. Draw through `onDraw`, or use ' +
-          '`@react-x11/components/three` for a scene graph. See docs/gl.md.',
-      );
-    }
     let node;
     switch (type) {
       case 'window':
@@ -463,6 +453,10 @@ const HostConfig = {
   },
   startSuspendingCommit() {},
   suspendInstance() {},
+  // react-reconciler 0.34 calls this on every commit whose lanes are all
+  // transition, retry or idle lanes, whether or not the tree has a
+  // <ViewTransition>. There is no view transition here to wait on.
+  suspendOnActiveViewTransition() {},
   waitForCommitToBeReady() {
     return null;
   },
@@ -584,11 +578,11 @@ const isNtkApp = (v) =>
  */
 function resolveBackend(options) {
   const asked = options.backend ?? process.env.REACT_X11_BACKEND ?? 'auto';
-  if (asked === 'x11' || asked === 'cocoa') return asked;
+  if (asked === 'x11' || asked === 'cocoa' || asked === 'wayland') return asked;
   if (asked !== 'auto') {
     throw new Error(
       `react-x11: unknown backend ${JSON.stringify(asked)} — expected ` +
-        "'x11', 'cocoa' or 'auto'.",
+        "'x11', 'cocoa', 'wayland' or 'auto'.",
     );
   }
   // Naming an X endpoint is choosing X11: a `display` or a `stream` (the
@@ -725,25 +719,34 @@ export async function createRoot(options = {}) {
     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();
+    : backend === 'wayland'
+      ? // Opt-in only, never through 'auto': X11 stays the default on Linux
+        // because the remote case (docs/remote.md) is the flagship reason
+        // this project exists and Wayland has no network transparency. The
+        // backend is opt-in; docs/wayland-backend.md says what it does
+        // and does not do.
+        import('./wayland/app.js').then(({ createWaylandApp }) =>
+          createWaylandApp(rest),
+        )
+      : 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/appcontext.js

@@ -26,7 +26,9 @@ import {
   compositingActive,
   watchCompositing,
 } from './compositing.js';
+import { canEmbed } from './embedding.js';
 import { hasDirectGL, watchDirectGL } from './glbackend.js';
+import { canOverlay } from './gloverlay.js';
 
 const AppContext = createContext(null);
 
@@ -57,17 +59,29 @@ export function useApp() {
   return app;
 }
 
-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.
+// 'nativeControls', 'embedding' and 'glOverlay' are properties of the
+// backend, decided before the first render and never changing after — so
+// their subscription has nothing to deliver and their snapshot is a property
+// test.
 const NEVER_CHANGES = () => () => {};
 
+// What `useSupports` watches and reads, per feature. `read` answers a
+// boolean, so the snapshot is stable for a given state — returning the
+// visual object for 'transparency' would tear on every render.
+const FEATURES = {
+  transparency: {
+    watch: watchCompositing,
+    read: (app) => compositingActive(app) && Boolean(argbVisual(app)),
+  },
+  shaders: { watch: watchDirectGL, read: hasDirectGL },
+  nativeControls: {
+    watch: NEVER_CHANGES,
+    read: (app) => Boolean(app.nativeBezels),
+  },
+  embedding: { watch: NEVER_CHANGES, read: canEmbed },
+  glOverlay: { watch: NEVER_CHANGES, read: canOverlay },
+};
+
 /**
  * Can this **display** do something, as a value a component can branch on?
  *
@@ -127,40 +141,55 @@ const NEVER_CHANGES = () => () => {};
  * first render already reads the final answer. A policy raised after
  * connecting has missed that probe, and re-renders its readers when it
  * settles rather than leaving them with two different answers.
+ *
+ * `'embedding'` is true when this connection can take another process's
+ * window into its own — the X11 backend; never Cocoa, which has no such
+ * primitive, and never the headless mock. It is the question to ask before
+ * rendering a `<foreign>`, which refuses with one `onError` where the answer
+ * is no:
+ *
+ * ```jsx
+ * const embedding = useSupports('embedding');
+ * <box style={{ flexGrow: 1 }}>
+ *   {embedding ? <foreign onReady={spawnInto} /> : <text>X11 only</text>}
+ * </box>
+ * ```
+ *
+ * Like `'nativeControls'`, it is a property of the backend and never changes.
+ *
+ * `'glOverlay'` is true when the children of a `<glarea>` are drawn above its
+ * GL surface on this connection — laid out in its box, painted on panes over
+ * the surface, hit before it. Both backends draw them; what differs is
+ * translucency, composited by Core Animation on the Cocoa backend and opaque
+ * on X11 (docs/elements.md says exactly how). It is the question to ask
+ * before handing a surface its HUD rather than drawing that some other way:
+ *
+ * ```jsx
+ * const overlay = useSupports('glOverlay');
+ * <glarea onDraw={drawMap}>{overlay && <Legend />}</glarea>
+ * ```
+ *
+ * A property of the backend too, and it never changes.
  */
 export function useSupports(feature) {
   const app = useApp();
-  if (!SUPPORTS_FEATURES.has(feature)) {
+  const spec = Object.hasOwn(FEATURES, feature) ? FEATURES[feature] : null;
+  if (!spec) {
     throw new Error(
       `react-x11: useSupports(${JSON.stringify(feature)}) — unknown feature ` +
-        `(expected one of ${[...SUPPORTS_FEATURES].join(', ')})`,
+        `(expected one of ${Object.keys(FEATURES).join(', ')})`,
     );
   }
-  // Both features go through the same store, so the hooks below run in the
+  // Every feature goes through the same store, so the hooks below run in the
   // same order whatever is being asked about. Where compositing comes and
   // goes for as long as the app runs, the backend settles at most once — and
   // watching that one moment is what keeps two components rendered either
   // side of it from disagreeing (see watchDirectGL).
   const subscribe = useCallback(
-    (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 === 'nativeControls'
-        ? Boolean(app.nativeBezels)
-        : feature === 'shaders'
-          ? hasDirectGL(app)
-          : compositingActive(app) && Boolean(argbVisual(app)),
-    [app, feature],
+    (onChange) => spec.watch(app, onChange),
+    [app, spec],
   );
+  const snapshot = useCallback(() => spec.read(app), [app, spec]);
   return useSyncExternalStore(subscribe, snapshot, snapshot);
 }
 

package/src/cocoa/app.js

@@ -26,6 +26,7 @@ import { setScreensForTests } from '../screens.js';
 import { setScaleForTests } from '../scale.js';
 import { BezelStore } from './bezels.js';
 import { CocoaGLArea, cocoaGLConfig, resolveCocoaGLRuntime } from './glarea.js';
+import { CocoaOverlayPane } from './overlay.js';
 import { CocoaDockMenu } from './dock.js';
 import { CocoaGlobalMenuExport } from './globalmenu.js';
 import { CocoaStatusItem } from './statusitem.js';
@@ -418,6 +419,16 @@ export class CocoaApp {
     return cocoaGLConfig(this, spec);
   }
 
+  /**
+   * The pane a `<glarea>`'s children are drawn on (src/gloverlay.js): one
+   * transparent layer above the surface's, which Core Animation composites —
+   * so the overlay blends with the GL frame here, where an X11 pane is an
+   * opaque child window. Having this at all is how the overlay knows.
+   */
+  createOverlayPane(attributes) {
+    return new CocoaOverlayPane(this, attributes);
+  }
+
   /**
    * The Frame host seam (src/frame/index.js): a pane's composited region
    * in this window. Its presence is what routes <Frame> to the shared-

package/src/cocoa/glarea.js

@@ -14,7 +14,10 @@
 // `destroy()`, `requestAnimationFrame`. On X11 that child is a real X
 // window stacked above the parent's drawing; here it is a sublayer of the
 // window's root layer with a high zPosition — the same "GL sits above the
-// 2D" semantics, by the same mechanism the platform gives us.
+// 2D" semantics, by the same mechanism the platform gives us. The layer
+// takes no input: pointer events are the NSWindow's, and the window's hit
+// test answers the surface for a point over it (`GlAreaNode.hitSurface`),
+// which is where X11's event propagation ends up too.
 //
 // ## The API ladder
 //
@@ -142,7 +145,6 @@ export class CocoaGLArea {
     this.scale = this.parent.scale ?? app.scale ?? 1;
     this.destroyed = false;
     this._reactX11Node = null;
-    this.onWheel = options.onWheel ?? null;
     this.layer = this._native.createLayer();
     this._native.addSublayer(this.parent._layer, this.layer);
     this.rect = null;

package/src/cocoa/overlay.js

@@ -0,0 +1,159 @@
+// The pane a `<glarea>`'s children are drawn on, on the Cocoa backend: a
+// transparent bitmap layer over the surface (src/gloverlay.js).
+//
+// A sublayer of the window's root layer like the surface's own
+// (src/cocoa/glarea.js), one step above it: the GL layer sits at zPosition
+// 1e7, over everything both presenters put on the root layer, and this one
+// at 1e7 + 1, over that. Core Animation composites it, so what the children
+// leave transparent shows the GL frame, and a translucent fill, an
+// antialiased edge or a shadow blends with it — the one backend where the
+// overlay is not opaque. Every surface's GL layer shares the one zPosition,
+// so where two surfaces overlap, both overlays are above both frames.
+//
+// It speaks the verbs of a window the overlay drives on X11 — `setState`,
+// `map`, `unmap`, `getContext`, `destroy` — plus `present`, which puts what
+// was painted on the layer: ntk blits an X window's backing store on its
+// own, where a layer's contents are a copy the bitmap has to be pushed to.
+import { CocoaContext2D } from './context2d.js';
+
+export const OVERLAY_Z = 1e7 + 1;
+
+export class CocoaOverlayPane {
+  constructor(app, options) {
+    this.app = app;
+    this.parent = options.parent;
+    this._native = app._native;
+    this.scale = this.parent.scale ?? app.scale ?? 1;
+    this.destroyed = false;
+    this.layer = this._native.createLayer();
+    this._native.addSublayer(this.parent._layer, this.layer);
+    this.rect = null;
+    this._surface = null;
+    this._surfaceSize = null;
+    this._gen = 0;
+    this._ctx = null;
+    this._dirty = false;
+    // Hidden until something is on it: a layer shows its contents from the
+    // moment it is added, and before the first present there are none to
+    // show, only whatever the render server makes of that.
+    this._presented = false;
+    this._hidden = false;
+    this.setState({
+      x: options.x ?? 0,
+      y: options.y ?? 0,
+      width: options.width ?? 1,
+      height: options.height ?? 1,
+    });
+  }
+
+  get width() {
+    return this.rect?.width ?? 0;
+  }
+
+  get height() {
+    return this.rect?.height ?? 0;
+  }
+
+  /** Geometry in device px, the unit the overlay's rects are in. */
+  setState(rect) {
+    if (this.destroyed) return;
+    this.rect = rect;
+    const s = this.scale;
+    this._setLayerProps({
+      frame: [rect.x / s, rect.y / s, rect.width / s, rect.height / s],
+      zPosition: OVERLAY_Z,
+      hidden: this._hidden || !this._presented,
+    });
+  }
+
+  map() {
+    this._hidden = false;
+    if (this._presented) this._setLayerProps({ hidden: false });
+  }
+
+  unmap() {
+    this._hidden = true;
+    this._setLayerProps({ hidden: true });
+  }
+
+  /** Implicit animations off, for the reason `CocoaGLArea._setLayerProps`
+   * gives: no frame's transaction covers a layer that is not a presenter's. */
+  _setLayerProps(props) {
+    if (this.destroyed) return;
+    const native = this._native;
+    native.txBegin({ disableActions: true });
+    try {
+      native.setLayerProps(this.layer, props);
+    } finally {
+      native.txCommit();
+    }
+  }
+
+  /** The bitmap, the pane's size — a new size is a new bitmap, cleared, and
+   * the old one freed now rather than by the handle's finalizer. */
+  _ensureSurface() {
+    const w = Math.max(1, this.rect?.width ?? 1);
+    const h = Math.max(1, this.rect?.height ?? 1);
+    const size = this._surfaceSize;
+    if (!this._surface || size.width !== w || size.height !== h) {
+      this._release();
+      this._surface = this._native.createSurface(w, h, this.scale);
+      this._native.ctxClearRect(this._surface, 0, 0, w, h);
+      this._surfaceSize = { width: w, height: h };
+      this._gen++;
+    }
+    return this._surface;
+  }
+
+  _release() {
+    const surface = this._surface;
+    this._surface = null;
+    if (surface && typeof this._native.releaseSurface === 'function') {
+      this._native.releaseSurface(surface);
+    }
+  }
+
+  getContext() {
+    if (!this._ctx) {
+      this._ctx = new CocoaContext2D(
+        this._native,
+        () => this._ensureSurface(),
+        () => {
+          this._ensureSurface();
+          return this._gen;
+        },
+      );
+      this._ctx._fonts = this.app.fonts;
+      this._ctx._onDirty = () => {
+        this._dirty = true;
+      };
+    }
+    return this._ctx;
+  }
+
+  /** What was painted, onto the layer — a copy, so the bitmap is free to be
+   * painted again at once. */
+  present() {
+    if (this.destroyed || !this._dirty || !this._surface) return;
+    this._dirty = false;
+    const native = this._native;
+    native.txBegin({ disableActions: true });
+    try {
+      native.surfaceToLayer(this._surface, this.layer);
+      if (!this._presented) {
+        this._presented = true;
+        if (!this._hidden) native.setLayerProps(this.layer, { hidden: false });
+      }
+    } finally {
+      native.txCommit();
+    }
+  }
+
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this._release();
+    this._ctx = null;
+    this._native.removeFromSuperlayer(this.layer);
+  }
+}

package/src/cocoa/promotion.js

@@ -142,6 +142,18 @@ function paintsSomething(node) {
   return Boolean(node.isScroller?.());
 }
 
+/**
+ * Inside a `<glarea>`: drawn on a pane above the surface (src/gloverlay.js).
+ * A layer of its own would sit on the root layer *under* the GL layer, so a
+ * promoted node there would vanish behind the surface it is drawn over.
+ */
+function insideGlArea(node) {
+  for (let n = node.parent; n && !n.isWindow; n = n.parent) {
+    if (n.isGlArea) return true;
+  }
+  return false;
+}
+
 /**
  * Can this node be a property box on a layer at all — the static half of
  * the answer, the same whatever the scene around it does: a plain box by
@@ -150,6 +162,7 @@ function paintsSomething(node) {
  */
 function promotableNode(node) {
   if (node.destroyed || !plainBox(node)) return false;
+  if (insideGlArea(node)) return false;
   if (!stylePaintsPlain(node, node._targetStyle ?? node.style)) return false;
   if (node.isScroller?.()) return false;
   return !paintsOutline(node);

package/src/components/Select.js

@@ -354,11 +354,17 @@ export function Select({
     );
     const chosenRowTop = MENU_BORDER + metrics.pad + chosen * metrics.row;
     const top = triggerCapsBottom - chosenRowTop - rowCapsBottom;
+    // `top` is where the menu starts against the trigger's own top, so it
+    // goes in as an `offset` back past the trigger's bottom — not as an `at`.
+    // Tracking asks whether `at` is still in view, and a menu opened over a
+    // trigger near the window's top edge starts above that edge: the popup
+    // is a real window and may, but the rect asked about was then "scrolled
+    // out", and the menu closed on the next unrelated layout pass (#552).
+    // What has to stay visible is the trigger.
     return {
       placement: 'bottom',
-      offset: 0,
+      offset: top - triggerHeight,
       flip: false,
-      at: { x: 0, y: top, width: node ? node.abs.width / scale : 0, height: 0 },
       alignOffset: -metrics.hang.left,
       height,
       width,

package/src/embedding.js

@@ -0,0 +1,31 @@
+// Whether a connection can take another process's window into its own.
+//
+// `<foreign>` asks before it builds a socket, and `useSupports('embedding')`
+// asks for a component deciding whether to render one. One function for
+// both, because the two have to agree: a hook that said yes over an element
+// that then refused, or the reverse, is the bug this closes (issue #531).
+//
+// A feature test on the connection, not a question about which backend this
+// is — and not "is there an `X`", which is true everywhere: the Cocoa app
+// carries an X stub for the modules with an X escape hatch, and the headless
+// mock carries the same one. Both also have a `createWindow` that takes a
+// parent, which is how `<foreign>` used to get as far as a socket over them.
+// So each part of embedding is asked about by name: a container window to
+// hold the client, `ReparentWindow` to move somebody else's window into it,
+// and the save set, which keeps that window alive if this process dies
+// holding it — the promise docs/embedding.md makes about a window we do not
+// own.
+//
+// A leaf module on purpose, for glbackend.js's reason: it imports nothing of
+// ours, so both `appcontext.js` and the node layer can use it without the
+// two importing each other.
+
+/** Can `app` host another client's window inside one of its own? */
+export function canEmbed(app) {
+  const X = app?.X;
+  return (
+    typeof app?.createWindow === 'function' &&
+    typeof X?.ReparentWindow === 'function' &&
+    typeof X?.ChangeSaveSet === 'function'
+  );
+}