react-x11 2.12.0 → 2.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [
@@ -60,6 +60,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",
@@ -105,7 +106,7 @@
   "optionalDependencies": {
     "@windowkit/appkit": "^0.10.0",
     "dbus-native": "^0.15.1",
-    "x11-dri": "^0.7.0"
+    "x11-dri": "^0.8.0"
   },
   "peerDependencies": {
     "@babel/core": "^8.0.0",

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':

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/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'
+  );
+}

package/src/events.js

@@ -47,6 +47,10 @@ const WHEEL_BUTTONS = new Set([4, 5, 6, 7]);
  */
 export const WHEEL_NOTCH_PX = 48;
 const RIGHT_BUTTON = 3;
+// A LeaveNotify's detail (core protocol): the pointer went to an ancestor of
+// the window it left, or into a window inside it — see `_leftIntoSurface`.
+const NOTIFY_ANCESTOR = 0;
+const NOTIFY_INFERIOR = 2;
 
 /** How many leading entries two node paths share. */
 function sharedPrefix(a, b) {
@@ -637,8 +641,32 @@ export class EventManager {
     return node.isWindow ? node.window : node;
   }
 
+  /**
+   * The node a pointer event landed on: a surface first, then the tree,
+   * front to back. A `<glarea>` is stacked above every 2D thing in its
+   * window, so a point inside one is over it whatever the tree's order says
+   * (`GlAreaNode.hitSurface`).
+   */
   _hit(ev) {
-    return this.node.hitTest(ev.x, ev.y) ?? this.node;
+    return (
+      this._surfaceAt(ev.x, ev.y) ?? this.node.hitTest(ev.x, ev.y) ?? this.node
+    );
+  }
+
+  /**
+   * The frontmost of this window's surfaces a point is over, or null. The
+   * newest is on top on both backends (`GlAreaNode._create`). An empty list
+   * is one length read on the motion path, which is all a window with no
+   * `<glarea>` pays for this.
+   */
+  _surfaceAt(x, y) {
+    const surfaces = this.node._surfaces;
+    if (!surfaces?.length) return null;
+    for (let i = surfaces.length - 1; i >= 0; i--) {
+      const hit = surfaces[i].hitSurface(x, y);
+      if (hit) return hit;
+    }
+    return null;
   }
 
   _path(target) {
@@ -742,16 +770,7 @@ export class EventManager {
    * way somewhere rather than one, and React must be free to interrupt the
    * render it started for the notch before.
    */
-  /**
-   * @param {object} native ntk's wheel event, in this window's coordinates
-   * @param {object} [over] the node the wheel happened over, when the caller
-   *   already knows. A `<glarea>` owns its own X window, so the server
-   *   delivers the event *there* and the surface hands it back translated
-   *   (src/glnodes.js) — and a hit test would answer with the box behind it,
-   *   because a window-owning child is not in its parent's paint order.
-   *   Knowing beats guessing; everything after this line is the same.
-   */
-  _onWheel(native, over = null) {
+  _onWheel(native) {
     // The first wheel is what says this window wants smooth scrolling. It was
     // created on core events — an XI2 selection costs four times as many
     // bytes per *pointer move*, which a window that is never scrolled would
@@ -765,7 +784,7 @@ export class EventManager {
     // outside gets, and for the same reason (`_pressOutside`).
     if (this._dismissOutside(native)) return;
     runWithPriority(ContinuousEventPriority, () => {
-      const target = over ?? this._hit(native);
+      const target = this._hit(native);
       // Shift turns a vertical wheel sideways — the convention for the mouse
       // and the touchpad that have no horizontal axis. Read off the delta
       // rather than off the source: a plain wheel mouse on an XI2 connection
@@ -1043,6 +1062,13 @@ export class EventManager {
   }
 
   _onMouseOut(native) {
+    // The pointer went into one of this window's surfaces, not out of the
+    // window: X reports crossing into a child window as leaving this one,
+    // but the input over a surface still arrives here — it selects none of
+    // its own — and the next motion names it. Answered as a leave, every
+    // ancestor was told the pointer had gone and then that it was back, and
+    // `onMouseOut` that it had left a window it was still in.
+    if (this._leftIntoSurface(native)) return;
     runWithPriority(ContinuousEventPriority, () => {
       this._updateHover([], native);
       // the pointer is somewhere else entirely: whatever it was heading for
@@ -1061,6 +1087,40 @@ export class EventManager {
     });
   }
 
+  /**
+   * Whether a LeaveNotify leaves the pointer in one of this window's
+   * surfaces rather than out of the window.
+   *
+   * A real server says "into a window inside this one" with detail
+   * NotifyInferior, and says it twice over a surface: when the pointer moves
+   * onto it, and when a grab ends with the pointer on it (mode NotifyUngrab)
+   * — which every click and every wheel notch over a surface does, since the
+   * press's implicit grab is this window's. node-x11's in-process server
+   * says it with detail NotifyAncestor and the child named instead, and
+   * sends no crossings for grabs at all.
+   *
+   * Either way the point says which inferior, and only a surface's rect
+   * makes it ours: a nested `<window>` or a `<foreign>` takes its own input,
+   * so leaving for one of those is still a leave. So is a grab taken
+   * elsewhere while the pointer is over a surface — detail NotifyVirtual or
+   * NonlinearVirtual, the surface named as the child it left from — since
+   * the pointer is the grab's now. The Cocoa backend's leave carries no
+   * detail, and is always one.
+   */
+  _leftIntoSurface(native) {
+    if (!native) return false;
+    const into =
+      native.detail === NOTIFY_INFERIOR ||
+      (native.detail === NOTIFY_ANCESTOR && Boolean(native.child));
+    if (!into) return false;
+    const wnd = this.node.window;
+    const { x, y } = native;
+    if (x < 0 || y < 0 || x >= (wnd?.width ?? 0) || y >= (wnd?.height ?? 0)) {
+      return false;
+    }
+    return this._surfaceAt(x, y) !== null;
+  }
+
   /**
    * The chain of the press that is still live, as far along it as the
    * pointer has stayed. `downPath` is where the press landed and does not

package/src/foreignnodes.js

@@ -33,12 +33,18 @@
 import { XEMBED, XEmbedSocket } from 'ntk';
 
 import { isFocusable } from './a11y.js';
+import { canEmbed } from './embedding.js';
 import { lastInputTime } from './inputtime.js';
 import { Node } from './nodes/node.js';
 import { pixelFor } from './nodes/window/capabilities.js';
 
 const px = (v) => Math.max(1, Math.round(v || 0));
 
+// Apps already told, by a <foreign> with no `onError`, that they cannot
+// embed. Once per app: the answer belongs to the backend, so the second pane
+// to ask carries no news — the same rule as a display with no ARGB visual.
+const warnedCannotEmbed = new WeakSet();
+
 /**
  * `<foreign>` — another client's top-level window, laid out as an element.
  *
@@ -89,6 +95,18 @@ const px = (v) => Math.max(1, Math.round(v || 0));
  * pointer is *over* the embedded client the client receives keys directly
  * and no handler of ours runs. Chords work everywhere else in the window,
  * which is the trade a proxy would make in reverse.
+ *
+ * ### Where there is no embedding
+ *
+ * All of this needs a connection that can reparent somebody else's window,
+ * and two apps this node meets have none: the Cocoa backend and the headless
+ * mock. Both carry an X stub and a `createWindow` that takes a parent, which
+ * used to be enough to build a socket over them — on Cocoa around a child GL
+ * surface whose `id` is undefined, handed out through `onReady` and spawned
+ * `xterm -into undefined` with; on the mock, a throw from inside the commit.
+ * So `realize()` asks `canEmbed` first, the question
+ * `useSupports('embedding')` answers too, and a no is final: no container, no
+ * `onReady`, one `onError`, and an empty box in the layout.
  */
 export class ForeignNode extends Node {
   constructor(props, app) {
@@ -97,8 +115,12 @@ export class ForeignNode extends Node {
     this.socket = null;
     /** `{ id, xembed, version }` while a client is in, else null */
     this.client = null;
-    /** the error that stopped an embed, if one did */
+    /** the error that stopped an embed, if one did — or, where this
+     * connection cannot embed at all, the refusal */
     this.error = null;
+    // set once `realize()` finds this connection cannot embed, and final:
+    // the backend does not change under a node
+    this._refused = false;
     /** geometry last sent to the X windows */
     this.rect = null;
     // an embedded client is a control the user can Tab to, like a
@@ -133,9 +155,10 @@ export class ForeignNode extends Node {
    * where React can discard the work.
    */
   realize() {
-    if (this.socket || this.destroyed) return;
+    if (this.socket || this.destroyed || this._refused) return;
     const parent = this.root?.window;
-    if (!parent || typeof this.app?.createWindow !== 'function') return;
+    if (!parent) return;
+    if (!canEmbed(this.app)) return this._refuse();
     const rect = this._geometry();
     this.rect = rect;
     const socket = new XEmbedSocket(parent, {
@@ -159,6 +182,36 @@ export class ForeignNode extends Node {
     this._syncMapped();
   }
 
+  /**
+   * This connection cannot embed: say so once, and be an empty box.
+   *
+   * On a microtask for `onReady`'s reason: this runs in the commit phase, and
+   * the ordinary answer to the news is to set state. Nothing else needs
+   * undoing — with no socket, every other path through this node (layout,
+   * props, focus, keys, teardown) already finds nothing to act on.
+   */
+  _refuse() {
+    this._refused = true;
+    const err = new Error(
+      'react-x11: <foreign> needs the X11 backend — this one has no ' +
+        'cross-process window embedding, so nothing can be put in it. Ask ' +
+        "useSupports('embedding') before rendering one.",
+    );
+    this.error = err;
+    // The client is the whole reason this node is a Tab stop by default, and
+    // one that can never arrive would leave a dead one. `focusable` still
+    // wins, as it does on a box.
+    this.focusableByDefault = false;
+    queueMicrotask(() => {
+      if (this.destroyed) return;
+      if (this.props.onError) this.props.onError(err);
+      else if (this.app && !warnedCannotEmbed.has(this.app)) {
+        warnedCannotEmbed.add(this.app);
+        console.warn(err.message);
+      }
+    });
+  }
+
   /**
    * Embed `windowId`, or — with none — wait for something to put a window
    * inside the container and take that.