react-x11 2.18.3 → 2.18.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.18.3",
+  "version": "2.18.5",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [

package/src/Reconciler.js

@@ -67,6 +67,7 @@ import { watchAppearance } from './appearance.js';
 import { setDesktopIntegration } from './desktopintegration.js';
 import { ForeignNode } from './foreignnodes.js';
 import { GlAreaNode } from './glnodes.js';
+import { beginGlOverlay } from './gloverlay.js';
 import {
   createRegisteredNode,
   elementDefinition,
@@ -954,11 +955,17 @@ export async function createRoot(options = {}) {
   // extension; the scale ladder; the monitor layout and the work-area
   // property), so they run concurrently: each is internally a chain of one
   // to three round trips, and awaiting them in sequence made every app pay
-  // the sum where the slowest chain is the true floor.
+  // the sum where the slowest chain is the true floor. The fourth is a
+  // single extension query, too short to set that floor: whether this is
+  // XQuartz, the X server nothing can be drawn over a GL surface on, which
+  // decides whether a `<glarea>`'s children get panes and what
+  // `useSupports('glOverlay')` answers on the first render
+  // (src/gloverlay.js).
   await Promise.all([
     beginCompositing(app),
     beginScale(app, rest.scale),
     beginScreens(app),
+    beginGlOverlay(app),
   ]);
 
   // How fast a caret blinks, how long a double click has, how far a press

package/src/appcontext.js

@@ -60,9 +60,10 @@ export function useApp() {
 }
 
 // '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.
+// backend — and 'glOverlay' of the X server too, which `createRoot` asks
+// before the first render (src/gloverlay.js) — decided before anything
+// renders 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
@@ -169,7 +170,10 @@ const FEATURES = {
  * 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
+ * on X11 (docs/elements.md says exactly how). The exception is XQuartz,
+ * where it is false: the macOS window server composites every GL surface
+ * above everything the X server draws, so nothing can be drawn over one, and
+ * the children are laid out but never drawn. It is the question to ask
  * before handing a surface its HUD rather than drawing that some other way:
  *
  * ```jsx
@@ -177,7 +181,8 @@ const FEATURES = {
  * <glarea onDraw={drawMap}>{overlay && <Legend />}</glarea>
  * ```
  *
- * A property of the backend too, and it never changes.
+ * A property of the backend and the display, settled before the first
+ * render, and it never changes.
  */
 export function useSupports(feature) {
   const app = useApp();

package/src/backend/context2d.js

@@ -324,6 +324,17 @@ export class BackendContext2D {
     // chunked stroke leaves only its last chunk behind)
     this._cmds = [];
     this._pathStale = false;
+    // A bridge that takes a whole path in one call (`ctxPath`, the Windows
+    // bridge's) is handed it that way when something paints it: the verbs
+    // below only record. A graph's edges are tens of thousands of `lineTo`s
+    // a frame, and a call across the boundary for each was milliseconds of
+    // every frame spent on the crossing. A bridge without it is handed the
+    // path a point at a time, as it is built, exactly as before.
+    // Asked with `in` as well: a test's bridge that answers every name with
+    // a no-op must not look like one that takes paths whole.
+    this._bulkPaths =
+      'ctxPath' in native && typeof native.ctxPath === 'function';
+    this._pathBuf = null;
     this._strokeChunking = !NO_STROKE_CHUNKING;
   }
 
@@ -670,6 +681,21 @@ export class BackendContext2D {
   _emit(surface, from, to) {
     const c = this._cmds;
     const n = this._native;
+    if (this._bulkPaths) {
+      // one call, through a buffer kept between paths — the record is the
+      // same stream the bridge parses, arguments and all
+      const count = to - from;
+      if (count <= 0) return;
+      let buf = this._pathBuf;
+      if (!buf || buf.length < count) {
+        buf = this._pathBuf = new Float64Array(
+          Math.max(count, (buf?.length ?? 512) * 2),
+        );
+      }
+      for (let i = 0; i < count; i++) buf[i] = c[from + i];
+      n.ctxPath(surface, buf.subarray(0, count));
+      return;
+    }
     for (let i = from; i < to;) {
       const op = c[i];
       const a = i + 1;
@@ -720,26 +746,44 @@ export class BackendContext2D {
 
   beginPath() {
     this._cmds.length = 0;
+    if (this._bulkPaths) {
+      this._s();
+      // uploaded, empty or not, when something paints it
+      this._pathStale = true;
+      return;
+    }
     this._pathStale = false;
     this._native.ctxBeginPath(this._s());
   }
 
+  /**
+   * The surface to add a path command to now, or null where the path is
+   * only recorded and handed over whole when painted (`_bulkPaths`). Either
+   * way a fresh surface drops the path first, as `_s` has always done.
+   */
+  _pathFor() {
+    if (!this._bulkPaths) return this._path();
+    this._s();
+    this._pathStale = true;
+    return null;
+  }
+
   moveTo(x, y) {
-    const surface = this._path();
+    const surface = this._pathFor();
     this._cmds.push(P_MOVE, x, y);
-    this._native.ctxMoveTo(surface, x, y);
+    if (surface !== null) this._native.ctxMoveTo(surface, x, y);
   }
 
   lineTo(x, y) {
-    const surface = this._path();
+    const surface = this._pathFor();
     this._cmds.push(P_LINE, x, y);
-    this._native.ctxLineTo(surface, x, y);
+    if (surface !== null) this._native.ctxLineTo(surface, x, y);
   }
 
   rect(x, y, w, h) {
-    const surface = this._path();
+    const surface = this._pathFor();
     this._cmds.push(P_RECT, x, y, w, h);
-    this._native.ctxRect(surface, x, y, w, h);
+    if (surface !== null) this._native.ctxRect(surface, x, y, w, h);
   }
 
   roundRect(x, y, w, h, radii) {
@@ -750,7 +794,7 @@ export class BackendContext2D {
     else if (r.length === 3) r = [r[0], r[1], r[2], r[1]];
     const cap = Math.min(Math.abs(w) / 2, Math.abs(h) / 2);
     const clamp = (v) => Math.max(0, Math.min(Number(v) || 0, cap));
-    const surface = this._path();
+    const surface = this._pathFor();
     const [r0, r1, r2, r3] = [
       clamp(r[0]),
       clamp(r[1]),
@@ -758,37 +802,40 @@ export class BackendContext2D {
       clamp(r[3]),
     ];
     this._cmds.push(P_ROUND, x, y, w, h, r0, r1, r2, r3);
-    this._native.ctxRoundRect(surface, x, y, w, h, r0, r1, r2, r3);
+    if (surface !== null)
+      this._native.ctxRoundRect(surface, x, y, w, h, r0, r1, r2, r3);
   }
 
   arc(x, y, radius, start, end, anticlockwise = false) {
-    const surface = this._path();
+    const surface = this._pathFor();
     this._cmds.push(P_ARC, x, y, radius, start, end, anticlockwise ? 1 : 0);
-    this._native.ctxArc(surface, x, y, radius, start, end, anticlockwise);
+    if (surface !== null)
+      this._native.ctxArc(surface, x, y, radius, start, end, anticlockwise);
   }
 
   ellipse(x, y, rx, ry) {
-    const surface = this._path();
+    const surface = this._pathFor();
     this._cmds.push(P_ELLIPSE, x, y, rx, ry);
-    this._native.ctxEllipse(surface, x, y, rx, ry);
+    if (surface !== null) this._native.ctxEllipse(surface, x, y, rx, ry);
   }
 
   bezierCurveTo(c1x, c1y, c2x, c2y, x, y) {
-    const surface = this._path();
+    const surface = this._pathFor();
     this._cmds.push(P_CURVE, c1x, c1y, c2x, c2y, x, y);
-    this._native.ctxCurveTo(surface, c1x, c1y, c2x, c2y, x, y);
+    if (surface !== null)
+      this._native.ctxCurveTo(surface, c1x, c1y, c2x, c2y, x, y);
   }
 
   quadraticCurveTo(cx, cy, x, y) {
-    const surface = this._path();
+    const surface = this._pathFor();
     this._cmds.push(P_QUAD, cx, cy, x, y);
-    this._native.ctxQuadTo(surface, cx, cy, x, y);
+    if (surface !== null) this._native.ctxQuadTo(surface, cx, cy, x, y);
   }
 
   closePath() {
-    const surface = this._path();
+    const surface = this._pathFor();
     this._cmds.push(P_CLOSE);
-    this._native.ctxClosePath(surface);
+    if (surface !== null) this._native.ctxClosePath(surface);
   }
 
   // --- painting ------------------------------------------------------------

package/src/glnodes.js

@@ -10,9 +10,10 @@ import { cssColorStraight } from 'ntk';
 // re-exported so the GL element layer stays one import for consumers
 export { directGLFailure, hasDirectGL } from './glbackend.js';
 
-import { GlOverlay, canOverlay } from './gloverlay.js';
+import { GlOverlay, canOverlay, overlayRefusal } from './gloverlay.js';
 import { layoutDiff } from './nodes/damage.js';
 import { Node } from './nodes/node.js';
+import { DEV } from './nodes/util.js';
 import { FramePacer, resolveFrameRate } from './pacing.js';
 
 // One visual query per (app, spec): GetFBConfigs is a round trip and every
@@ -37,6 +38,27 @@ function recordGlxFailure(app, err) {
   if (app && err && !glxFailures.has(app)) glxFailures.set(app, err);
 }
 
+// Apps already told that a <glarea>'s children are not drawn on their
+// display. Once per app, as for a <foreign> that cannot embed: the answer
+// belongs to the server, so the next surface to find out carries no news.
+const warnedNoOverlay = new WeakSet();
+
+/**
+ * Say, once per app and in development only, that the children of a
+ * `<glarea>` are not drawn here. They lay out and render like anyone's and
+ * nothing fails, so without this a HUD that never shows looks like a bug in
+ * the HUD.
+ */
+function warnNoOverlay(app) {
+  if (!DEV || !app || warnedNoOverlay.has(app)) return;
+  warnedNoOverlay.add(app);
+  const why = overlayRefusal(app);
+  console.warn(
+    'react-x11: the children of a <glarea> are not drawn on this connection, ' +
+      `and useSupports('glOverlay') is false${why ? ` — ${why}` : ''}.`,
+  );
+}
+
 /**
  * The visual and depth to create the GL child window with.
  *
@@ -121,7 +143,9 @@ const px = (v) => Math.max(1, Math.round(v || 0));
  * The X child window is stacked above everything drawn in the parent, so the
  * parent's 2D content cannot overlap it — but this node's own children do:
  * they are laid out in its box like a `<box>`'s and drawn above the surface,
- * on panes of their own (src/gloverlay.js).
+ * on panes of their own (src/gloverlay.js). Everywhere but XQuartz, where
+ * nothing can be drawn over a GL surface: there they are laid out and not
+ * drawn (`canOverlay`).
  *
  * Pointer input over the surface is the tree's, on both backends: a press,
  * a drag or a wheel over it is a synthetic event at the child under the
@@ -636,7 +660,14 @@ export class GlAreaNode extends Node {
    */
   _syncOverlay() {
     if (!this._overlay) {
-      if (this.children.length === 0 || !canOverlay(this.app)) {
+      // Where nothing can be drawn over the surface the children get no
+      // panes at all, rather than panes nobody sees: on XQuartz a pane over
+      // the whole surface is what hides the GL frame (src/gloverlay.js). So
+      // they are laid out and never drawn, and the pointer over them is the
+      // surface's.
+      const refused = this.children.length !== 0 && !canOverlay(this.app);
+      if (refused) warnNoOverlay(this.app);
+      if (this.children.length === 0 || refused) {
         this.root?._overlaid?.delete(this);
         return false;
       }

package/src/globalmenu.js

@@ -108,6 +108,13 @@ const NO_AUTO_START = 2;
  */
 const menuPathFor = (xid) => `/com/react_x11/menus/${xid}`;
 
+/**
+ * Per window, the moment it is free: settles once every exporter that has
+ * published on it so far has stopped. The next one to publish there waits for
+ * it — see `GlobalMenuExport.takeTurn()`.
+ */
+const vacancies = new Map();
+
 /**
  * The feature's off switch.
  *
@@ -167,6 +174,20 @@ export class GlobalMenuExport extends DbusMenuExport {
     this.path = null;
     this.xid = null;
     this.window = null;
+    /** The windows this exporter has queued for, by xid. Each is held until
+     *  `stop()`, so publishing on one again does not queue behind itself —
+     *  see `takeTurn()`. */
+    this.claimed = new Set();
+    /** Settles when `stop()` is called, `stopped` as a promise, so a publish
+     *  still waiting for its window stops waiting. */
+    this.halted = new Promise((resolve) => {
+      this.halt = resolve;
+    });
+    /** Settles once `stop()` has finished, which is what the next exporter on
+     *  a window this one claimed waits for — see `takeTurn()`. */
+    this.gone = new Promise((resolve) => {
+      this.markGone = resolve;
+    });
   }
 
   // ------------------------------------------------------------------ setup
@@ -281,6 +302,21 @@ export class GlobalMenuExport extends DbusMenuExport {
     // call" case rather than the "too early" one.
     if (!xid) return;
 
+    // One menu per window at a time — see `takeTurn()`.
+    const before = this.takeTurn(xid);
+    if (before) {
+      // Given up if this one is stopped meanwhile. That frees the window no
+      // sooner: whoever is next in line waits for `before` as well.
+      await Promise.race([before, this.halted]);
+      // How long that took is up to the menu ahead, and for a second bar in
+      // the window it is that bar's whole mount. So what `_sync()` decided
+      // before it is stale, and it decides again. A panel that went meanwhile
+      // would otherwise get a RegisterWindow sent to nobody, and the error
+      // ends `start()` in a teardown: a menu that never reaches the next
+      // panel either.
+      return this._sync();
+    }
+
     const dbus = await loadTransport();
     const path = menuPathFor(xid);
     if (!dbus.isValidObjectPath(path)) return;
@@ -320,6 +356,49 @@ export class GlobalMenuExport extends DbusMenuExport {
     this.onChange(true);
   }
 
+  /**
+   * Queue for a window, the first time this exporter publishes on it, and
+   * hand back what to wait for: the moment every exporter that published
+   * there before this one has stopped, or `null` when there is nothing to
+   * wait for.
+   *
+   * **One menu per window at a time.** Everything a menu holds is per window:
+   * the object at `menuPathFor(xid)`, the registrar's entry for the xid, and
+   * the two X properties. A `<MenuBar>` remounted in its window, or one with
+   * `globalMenu` switched off and on, puts a new exporter on all three while
+   * the old one is still leaving — its teardown asks `ListNames` and waits
+   * for `UnregisterWindow` before it unexports. That unexport is
+   * dbus-native's `registration.remove()`, which removes whatever is at the
+   * path when it runs, whoever exported it. So the new menu lost its object
+   * while the registrar and the properties still named it, and its bar,
+   * told `exported`, drew nothing: no menu anywhere. The old one's
+   * unregistration and property deletes race the new one's registration and
+   * property writes the same way. They happened to land first, which is
+   * harmless, but nothing made them, so the whole publish waits and not only
+   * the export. A second bar in a window that already has one waits too: it
+   * stays drawn in the window until the first one goes, rather than
+   * displacing it.
+   *
+   * Every one before it, not only the last: a menu stopped while it was
+   * still waiting is gone at once, and the one it was waiting for may not
+   * be.
+   *
+   * A window is held until this exporter stops, not only while it is
+   * published, so a panel that restarts gets the menu back from the same
+   * exporter without it queueing behind itself.
+   */
+  takeTurn(xid) {
+    if (this.claimed.has(xid)) return null;
+    this.claimed.add(xid);
+    const before = vacancies.get(xid);
+    const vacated = Promise.all([before, this.gone]);
+    vacancies.set(xid, vacated);
+    void vacated.then(() => {
+      if (vacancies.get(xid) === vacated) vacancies.delete(xid);
+    });
+    return before ?? null;
+  }
+
   /**
    * Plasma reads these instead of asking the registrar.
    *
@@ -390,15 +469,24 @@ export class GlobalMenuExport extends DbusMenuExport {
   async stop() {
     if (this.stopped) return;
     // Set first, so a publish already in flight sees it and undoes itself at
-    // its next checkpoint rather than finishing.
+    // its next checkpoint rather than finishing, and one still waiting for
+    // its window stops waiting.
     this.stopped = true;
-    // Then wait for it. `teardown()` reads `registration`, `xid` and `window`
-    // across several awaits of its own, so running it *beside* a publish lets
-    // each undo the other's work: the classic end state is `exported === true`
-    // with the object unexported and the window unregistered — no bar in the
-    // window, nothing in the panel, and no event left that could recover it.
-    await this.syncing?.catch(() => {});
-    await this.teardown();
+    this.halt();
+    try {
+      // Then wait for it. `teardown()` reads `registration`, `xid` and
+      // `window` across several awaits of its own, so running it *beside* a
+      // publish lets each undo the other's work: the classic end state is
+      // `exported === true` with the object unexported and the window
+      // unregistered — no bar in the window, nothing in the panel, and no
+      // event left that could recover it.
+      await this.syncing?.catch(() => {});
+      await this.teardown();
+    } finally {
+      // Whatever happened, the window is free: the next menu on it would
+      // otherwise wait for good, and never reach the panel.
+      this.markGone();
+    }
   }
 
   async teardown() {
@@ -427,6 +515,14 @@ export class GlobalMenuExport extends DbusMenuExport {
   }
 }
 
+/** Test seam, not public: forget which windows are held. A previous test's
+ *  menus are on a bus it has closed, so there is nothing to wait for, and one
+ *  a failed test never stopped would otherwise hold its window for the rest
+ *  of the run — every mock app numbers its first window alike. */
+export function _resetGlobalMenuState() {
+  vacancies.clear();
+}
+
 /**
  * Is this window's menu bar being drawn by the desktop?
  *

package/src/gloverlay.js

@@ -35,6 +35,15 @@
 //   node-x11's in-process server, where this is tested, has none — and a
 //   window as big as the surface would keep a backing pixmap the size of a
 //   map to show a legend in its corner.
+// - **XQuartz: no, and not opaquely either.** Every GL surface there, the
+//   direct ones Apple-DRI exports and indirect GLX's alike, is a surface of
+//   the macOS window server, composited above everything the X server draws
+//   in the window (hw/xquartz/xpr/dri.c makes it `XP_MAPPED_ABOVE`). X's
+//   stacking never reaches it: a pane stacked over the surface's window is
+//   drawn under the frame, cutting that window down with SHAPE leaves the
+//   frame covering all of it, and only a pane over the whole surface shows —
+//   by hiding the frame (issue #653). So no pane is made there, and
+//   `canOverlay` says so from the first render on (`beginGlOverlay`).
 //
 // A pane selects no input, so the pointer over one reaches the owning window
 // by the same propagation that brings it the pointer over the surface
@@ -75,18 +84,85 @@ const MOVE_BLIT_MAX_REPAINT = 0.75;
 // one variable away from the plain repaint (docs/debugging.md).
 const NO_BLIT = process.env.REACT_X11_NO_SCROLL_BLIT === '1';
 
+// Connections on which nothing can be drawn over a GL surface, each with the
+// reason (`beginGlOverlay`), and the probe that finds out, once per app.
+const refusals = new WeakMap();
+const probes = new WeakMap();
+
+const XQUARTZ =
+  'this display is XQuartz, where the macOS window server composites every ' +
+  'GL surface above everything the X server draws in its window. Draw the ' +
+  'overlay beside the surface or in GL instead, or run on the Cocoa backend ' +
+  '(the default on macOS), which composites it';
+
 /**
  * Whether the children of a `<glarea>` can be drawn over its surface on this
  * connection: a backend that composites a pane itself, or one that can make
- * the plain child window a pane is on X11. One function for the element and
- * for `useSupports('glOverlay')`, which have to agree — the rule `canEmbed`
- * follows for `<foreign>`.
+ * the plain child window a pane is on X11 — on any server but XQuartz, where
+ * nothing can be drawn over a GL surface (`beginGlOverlay`). One function
+ * for the element and for `useSupports('glOverlay')`, which have to agree —
+ * the rule `canEmbed` follows for `<foreign>`.
  */
 export function canOverlay(app) {
-  return (
-    typeof app?.createOverlayPane === 'function' ||
-    typeof app?.createWindow === 'function'
-  );
+  if (typeof app?.createOverlayPane === 'function') return true;
+  return typeof app?.createWindow === 'function' && !refusals.has(app);
+}
+
+/** Why nothing is drawn over a GL surface on this connection, for the
+ * warning a `<glarea>` with children gives there — or null. */
+export function overlayRefusal(app) {
+  return (app && refusals.get(app)) ?? null;
+}
+
+/**
+ * A backend saying nothing can be drawn over a GL surface on this app, and
+ * why: one whose child windows are not X windows, and that has no
+ * composited pane either — on Windows a window with a parent is a GL
+ * surface of its own (src/win32/glarea.js), and a bridge without layers has
+ * nothing else to offer. Before the first render, like `beginGlOverlay`, so
+ * `useSupports('glOverlay')` never changes its answer.
+ */
+export function refuseOverlay(app, reason) {
+  if (app) refusals.set(app, reason);
+}
+
+/**
+ * Is this an X server where nothing can be drawn over a GL surface? Asked
+ * in `createRoot`, with the other startup probes and before the first
+ * render, so that `canOverlay` answers the same from the first frame on —
+ * a component choosing how to draw by it would otherwise build one way and
+ * tear that down a frame later.
+ *
+ * The server is XQuartz, and the question is its Apple-DRI extension, which
+ * no other server has: every GL surface XQuartz makes comes from the
+ * machinery that extension exports, direct and indirect alike. Asked of the
+ * server rather than of `app.glCapabilities()`, because the default policy
+ * never probes direct rendering and XQuartz's indirect GLX hides the panes
+ * all the same. One QueryExtension; where ntk's direct-rendering probe has
+ * asked already, node-x11 answers it from the reply it kept.
+ */
+export function beginGlOverlay(app) {
+  if (!app) return Promise.resolve();
+  let pending = probes.get(app);
+  if (pending) return pending;
+  const X = app.X;
+  pending =
+    typeof app.createOverlayPane === 'function' ||
+    typeof X?.QueryExtension !== 'function'
+      ? Promise.resolve()
+      : new Promise((resolve) => {
+          try {
+            X.QueryExtension('Apple-DRI', (err, reply) => {
+              if (!err && reply?.present) refusals.set(app, XQUARTZ);
+              resolve();
+            });
+          } catch {
+            // a connection that cannot ask is one this cannot find out about
+            resolve();
+          }
+        });
+  probes.set(app, pending);
+  return pending;
 }
 
 /** A rect grown out to whole device pixels. */
@@ -590,35 +666,46 @@ export class GlOverlay {
   _paintPane(pane, passes) {
     const area = this.area;
     const root = area.root;
-    const ctx = pane.context();
-    if (!ctx || !root) return;
+    if (!root) return;
     // an opaque pane is filled with what the surface starts its frames from;
     // a composited one is cleared, and shows the frame itself
     const ground = pane.transparent ? null : groundOf(area.props);
-    ctx.save();
-    try {
-      ctx.translate(-pane.rect.x, -pane.rect.y);
-      for (const pass of passes) {
-        ctx.save();
-        try {
-          ctx.beginPath();
-          ctx.rect(pass.x, pass.y, pass.width, pass.height);
-          ctx.clip();
-          if (ground) {
-            ctx.fillStyle = ground;
-            ctx.fillRect(pass.x, pass.y, pass.width, pass.height);
-          } else {
-            ctx.clearRect(pass.x, pass.y, pass.width, pass.height);
-          }
-          root._paintDamage = pass;
-          area._paintChildren(ctx);
-        } finally {
-          root._paintDamage = null;
-          ctx.restore();
+    // one pass, drawn by a context in window coordinates
+    const paintPass = (ctx, pass) => {
+      ctx.save();
+      try {
+        ctx.beginPath();
+        ctx.rect(pass.x, pass.y, pass.width, pass.height);
+        ctx.clip();
+        if (ground) {
+          ctx.fillStyle = ground;
+          ctx.fillRect(pass.x, pass.y, pass.width, pass.height);
+        } else {
+          ctx.clearRect(pass.x, pass.y, pass.width, pass.height);
         }
+        root._paintDamage = pass;
+        area._paintChildren(ctx);
+      } finally {
+        root._paintDamage = null;
+        ctx.restore();
+      }
+    };
+    if (typeof pane.wnd.paintPasses === 'function') {
+      // A pane drawn a rect at a time — a DirectComposition surface hands
+      // out a context per `BeginDraw`, valid until `EndDraw` — opens each
+      // pass itself (src/win32/overlay.js), the way such a window takes its
+      // frame through `presentFrame`.
+      pane.wnd.paintPasses(passes, paintPass);
+    } else {
+      const ctx = pane.context();
+      if (!ctx) return;
+      ctx.save();
+      try {
+        ctx.translate(-pane.rect.x, -pane.rect.y);
+        for (const pass of passes) paintPass(ctx, pass);
+      } finally {
+        ctx.restore();
       }
-    } finally {
-      ctx.restore();
     }
     // A layer's contents are a copy the bitmap is pushed to; an X window's
     // backing store is blitted by ntk on its own, from the paint above

package/src/index.d.ts

@@ -216,7 +216,10 @@ export function useClipboard(): Clipboard;
  * before it. Both backends draw them; translucency is the difference,
  * composited by Core Animation on Cocoa and opaque on X11, where what a
  * child leaves unpainted shows the surface's `clearColor` (docs/elements.md).
- * Ask it before handing a surface its HUD. A property of the backend.
+ * False on XQuartz, whose GL surfaces the macOS window server composites
+ * above everything the X server draws: nothing can be drawn over one there.
+ * Ask it before handing a surface its HUD. A property of the backend and the
+ * display, settled before the first render.
  */
 export type SupportsFeature =
   'transparency' | 'shaders' | 'nativeControls' | 'embedding' | 'glOverlay';

package/src/nodes/invalidate.js

@@ -314,8 +314,16 @@ export class WindowInvalidate {
       // the whole reason this is not just `needsLayout`: a scroll moves an
       // offset applied during `absolutize` and leaves every yoga node exactly
       // as it was, at input rate, on the biggest trees in any app.
-      if (reason !== 'scroll') this._floorsDirty = true;
-      if (reason !== 'scroll' && reason !== 'resize') {
+      //
+      // Nor does a box that only moved (`'position'`, from `applyProps`):
+      // absolutely positioned and sized by its own width and height, it is
+      // out of every ancestor's flow and sizes nothing inside it by its
+      // insets. A card dragged across a graph — or a thousand of them
+      // panned — was a full measurement of the content floors a step.
+      if (reason !== 'scroll' && reason !== 'position') {
+        this._floorsDirty = true;
+      }
+      if (reason !== 'scroll' && reason !== 'resize' && reason !== 'position') {
         this._floorsContentDirty = true;
       }
     }