react-x11 2.11.0 → 2.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.11.0",
+  "version": "2.13.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [
@@ -15,6 +15,8 @@
     "examples:app": "tsx examples/app.jsx",
     "examples:theming": "tsx examples/theming.jsx",
     "examples:container-queries": "tsx examples/container-queries.jsx",
+    "examples:schedule": "tsx examples/schedule.jsx",
+    "examples:custom-layout": "tsx examples/custom-layout.jsx",
     "examples:appearance": "tsx examples/appearance.jsx",
     "examples:animation": "tsx examples/animation.jsx",
     "examples:simple": "tsx examples/simple.jsx",
@@ -58,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",
@@ -74,7 +77,8 @@
     "docs:build": "npm --prefix website run build",
     "docs:test": "npm --prefix website test",
     "bench:presenters": "node --import tsx scripts/bench/presenters.js",
-    "bench:touched": "node scripts/bench/touched.js"
+    "bench:touched": "node scripts/bench/touched.js",
+    "bench:grid": "node --import tsx scripts/bench/grid/bench.mjs"
   },
   "repository": {
     "type": "git",
@@ -100,9 +104,9 @@
     "yoga-layout": "^3.2.1"
   },
   "optionalDependencies": {
-    "@windowkit/appkit": "^0.9.0",
+    "@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",
@@ -206,6 +210,10 @@
     "./keysyms": {
       "types": "./src/keysyms.d.ts",
       "default": "./src/keysyms.js"
+    },
+    "./cocoa-main": {
+      "types": "./src/cocoa/main.d.ts",
+      "default": "./src/cocoa/main.js"
     }
   },
   "types": "./src/index.d.ts"

package/src/Reconciler.js

@@ -1,5 +1,5 @@
 // The react-reconciler host config plus the public render entry points.
-// Host instances are the retained nodes from nodes.js; only <window> and
+// Host instances are the retained nodes from src/nodes/; only <window> and
 // <popup> map to real X11 windows (see NEXT_STEPS.md), and those windows
 // are created top-down in the commit phase (WindowNode.realize) so every
 // CreateWindow names its actual parent from the start — createInstance
@@ -18,21 +18,19 @@ import {
 } from './priority.js';
 import {
   WindowNode,
-  PopupNode,
-  BoxNode,
-  TextNode,
-  TextChunkNode,
-  ImageNode,
-  CanvasNode,
-  TextInputNode,
-  TextAreaNode,
-  appearanceChanged,
   beginWindowMaps,
   flushWindowMaps,
   flushWindowRestacks,
-  windowAttributes,
-  setTextStripBelow,
-} from './nodes.js';
+} from './nodes/window/window.js';
+import { PopupNode } from './nodes/window/popup.js';
+import { BoxNode } from './nodes/box.js';
+import { TextNode, TextChunkNode, setTextStripBelow } from './nodes/text.js';
+import { ImageNode } from './nodes/image.js';
+import { CanvasNode } from './nodes/canvas.js';
+import { TextInputNode } from './nodes/textinput.js';
+import { TextAreaNode } from './nodes/textarea.js';
+import { appearanceChanged } from './nodes/cascade.js';
+import { windowAttributes } from './nodes/window/hints.js';
 import { setFrameRateDefault } from './pacing.js';
 import { hasDropProps } from './dnd.js';
 import { AppProvider } from './appcontext.js';
@@ -140,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',
     };
   },
 
@@ -162,7 +161,7 @@ const HostConfig = {
 
   prepareForCommit() {
     // …so that a <window> realized during the mutation phase waits to be
-    // mapped until React has finished hiding whatever it hides (nodes.js,
+    // mapped until React has finished hiding whatever it hides (nodes/window/window.js,
     // beginWindowMaps)
     beginWindowMaps();
     traceHooks.commitStart?.();
@@ -196,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':
@@ -313,7 +301,7 @@ const HostConfig = {
     // 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
+    // holds that node's own fiber (nodes/cascade.js `_tokenProblem`). Gated on the
     // flag so the default mount pays nothing for a debugging mode.
     return (
       type === 'popup' ||
@@ -328,7 +316,7 @@ const HostConfig = {
     // 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`).
+    // will never come (nodes/cascade.js `_tokenProblem`).
     const tokenError = instance._tokenError;
     instance._tokenError = false;
     if (tokenError) throw tokenError;
@@ -793,7 +781,7 @@ export async function createRoot(options = {}) {
   beginCompose(app, rest.compose);
 
   // Under what size a paragraph is painted as a strip of its ink instead
-  // of as glyphs (nodes.js, `TextNode._paintsStrip`): six logical pixels by
+  // of as glyphs (nodes/text.js, `TextNode._paintsStrip`): six logical pixels by
   // default, 0 for glyphs at every size.
   setTextStripBelow(app, rest.textStripBelow);
 

package/src/a11y.js

@@ -1,7 +1,7 @@
 // The accessibility model: standard `role` / `aria-*` props resolved against
 // the retained node tree, plus the hook slots the renderer polls.
 //
-// This file is the cheap half. It is imported unconditionally by nodes.js,
+// This file is the cheap half. It is imported unconditionally by src/nodes/,
 // events.js and Reconciler.js, so it must cost nothing when accessibility is
 // off: no D-Bus, no node builtins, no side effects — the hot paths pay one
 // property read per hook (`hooks.focus?.(…)`), exactly the trace-registry
@@ -941,7 +941,7 @@ export function a11yAttributes(node) {
  * **The one thing "activatable" means**: there is a click here to make.
  *
  * Three input routes stand on this — the pointer, an AT's `DoAction`, and
- * the keyboard's Space/Enter (`Node.defaultKeyDown`, nodes.js) — and they
+ * the keyboard's Space/Enter (`Node.defaultKeyDown`, nodes/node.js) — and they
  * all dispatch the same click, so a control cannot answer one of them and
  * not another. It lives here, beside the bridge's rule, because the bridge
  * is the layer that already had to write the rule down.

package/src/anchor.js

@@ -8,7 +8,8 @@
 // `realize()`, between the measurement and `CreateWindow`, which is after
 // the last moment React could have computed a position for it. So the
 // window places *itself* from the same functions (`WindowNode._followAnchor`,
-// nodes.js), and the two paths agree because they are the same code.
+// nodes/window/anchoring.js), and the two paths agree because they are the
+// same code.
 
 import { availableArea } from './screens.js';
 
@@ -48,7 +49,7 @@ export function screenRect(node) {
 /** Where the node's owner window is on the screen. Exported for the one
  * caller that anchors to a *point* rather than to a node's rect — the edit
  * menu opens at the pointer, whose coordinates arrive window-relative on the
- * event (`openEditMenu`, nodes.js). */
+ * event (`openEditMenu`, nodes/editmenupopup.js). */
 export function windowOrigin(node) {
   const win = node?.root?.window;
   return win?._screenOrigin ?? { x: win?.x ?? 0, y: win?.y ?? 0 };
@@ -93,9 +94,10 @@ function deviceAt(at, s) {
 
 /**
  * Has the thing this popup points at scrolled out of view? The check paint
- * culling uses (`Node._offscreen`), asked about the sub-rect rather than
- * about the node: an editor scrolls its own text, so the caret leaves the
- * viewport a long time before the editor does.
+ * culling uses (`Node._offscreen`), without the pixel paint allows for ink
+ * past a box, and asked about the sub-rect rather than about the node: an
+ * editor scrolls its own text, so the caret leaves the viewport a long time
+ * before the editor does.
  *
  * A degenerate rect counts as its own thinnest visible version — a caret is
  * a line with no width and a `{x, y}` anchor is a point with neither, and

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/bootstrap.js

@@ -0,0 +1,14 @@
+// What runs the moment react-x11 is imported, before any of the app's own
+// code: each backend's chance to put the app where its platform wants it.
+// Only the cocoa backend has one — AppKit keeps the process main thread, so
+// an app on macOS moves onto a worker (src/cocoa/relaunch.js), and on that
+// worker the same import sets it up. A Windows backend's UI thread will be
+// the addon's own, and X11 has none, so neither needs this step
+// (docs/windows.md §"Three shapes on Windows"). Imported first by
+// src/index.js, so that it runs before the rest of the package.
+import { isMainThread, workerData } from 'node:worker_threads';
+
+import { bootstrapWorker, relaunchOnImport } from './cocoa/relaunch.js';
+
+if (isMainThread) relaunchOnImport(import.meta.url);
+else if (workerData?.reactX11State) bootstrapWorker(workerData.reactX11State);

package/src/clientmessage.js

@@ -75,7 +75,7 @@ function atomName(X, id) {
  * hands it to `dispatch` in arrival order.
  *
  * `dispatch` is the caller's, so the priority and the paint stay with the
- * other window events in nodes.js; what lives here is the naming and the
+ * other window events in nodes/window/; what lives here is the naming and the
  * ordering it has to preserve.
  */
 export function createClientMessages(node, dispatch) {