react-x11 2.11.0 → 2.13.0

package/src/errors.js

@@ -59,6 +59,35 @@ export function reportHandlerError(node, handler, error) {
   markFailed();
 }
 
+/**
+ * A throw from a layout or a placement (docs/extending.md) — code that runs
+ * inside a frame, where no error boundary is on the stack either. Reported
+ * the way a handler's throw is, `onUncaughtError` included, and the frame
+ * carries on with the fallback `consequence` names: one bad algorithm must
+ * not stop the window from painting.
+ */
+export function reportLayoutError(node, what, error, consequence) {
+  const element = node?.kind ? `<${node.kind}>` : '(unknown)';
+  const owner = ownerName(node);
+  const custom = node?.app && perContainer.get(node.app);
+  if (custom) {
+    custom(error, {
+      componentStack: owner ? `\n    in ${owner}` : undefined,
+      element,
+      handler: what,
+      node,
+    });
+    return;
+  }
+  console.error(
+    `react-x11: ${what} on ${element}${owner ? ` in ${owner}` : ''} threw. ` +
+      'It ran inside a frame rather than a render, so no error boundary ' +
+      `could catch it. ${consequence}.`,
+    error,
+  );
+  markFailed();
+}
+
 /**
  * `REACT_X11_STRICT_TOKENS=1` makes a `$token` the theme does not define
  * fatal again, for a build that would rather stop than paint something
@@ -104,6 +133,23 @@ export function reportStyleError(
   markFailed();
 }
 
+/**
+ * A style that asks for something that is not there — a layout or a
+ * placement nobody registered, an option of the wrong type. Reported and
+ * carried on from, once per node and message, the way an unknown token is;
+ * with no strict switch, because the fallback it names is a real one and
+ * not a property silently dropped.
+ */
+export function reportStyleProblem(node, message, consequence) {
+  const seen = reportedStyleErrors.get(node);
+  if (seen?.has(message)) return;
+  if (seen) seen.add(message);
+  else reportedStyleErrors.set(node, new Set([message]));
+  const owner = ownerName(node);
+  console.error(`${message}${owner ? ` — in ${owner}` : ''}. ${consequence}.`);
+  markFailed();
+}
+
 /** Wrap a call to user code so a throw is reported instead of escaping. */
 export function callHandler(node, handler, fn, ev) {
   try {

package/src/events.js

@@ -42,11 +42,15 @@ const WHEEL_BUTTONS = new Set([4, 5, 6, 7]);
  * every registered element that answers the wheel), so the conversion happens
  * here, once, and `deltaX`/`deltaY` mean pixels wherever they are read.
  *
- * The same step an arrow key takes (`SCROLL_KEY_STEP`, nodes.js), so a notch
+ * The same step an arrow key takes (`SCROLL_KEY_STEP`, nodes/scrollable.js), so a notch
  * and an arrow press move a list by the same amount.
  */
 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) {
@@ -301,7 +305,7 @@ export function discrete(fn) {
  * One function, because there is more than one way to ask for it and they
  * must not drift: an AT's `DoAction("activate")` (atspi.js) and the
  * keyboard's Space/Enter on a focused control (`Node.defaultKeyDown`,
- * nodes.js) both land here, so a control that acts on the *press* — `Select`
+ * nodes/node.js) both land here, so a control that acts on the *press* — `Select`
  * and `MenuBar` drop their menus on mousedown, the way real menus do — is
  * reached by either, and neither can be the one input route a widget forgot.
  *
@@ -621,7 +625,7 @@ export class EventManager {
     if (!changed) return;
     // …and the things that keep a window of their own open on the strength
     // of this one having focus — a menu, a dropdown — which the focused node
-    // keeping its focus would otherwise never tell (`WindowNode`, nodes.js)
+    // keeping its focus would otherwise never tell (`WindowNode`, nodes/window/window.js)
     this.node._notifyWindowFocus?.(focused);
     a11yHooks.windowFocus?.(this.node, focused);
     runWithPriority(DiscreteEventPriority, () => {
@@ -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,20 +770,11 @@ 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
-    // pay for nothing — and takes the selection here, once (nodes.js,
+    // pay for nothing — and takes the selection here, once (nodes/window/window.js,
     // `upgradeToXI2`). Ahead of the dismiss check, because a scroll this
     // window heard is a scroll this window heard whatever it does with it.
     this.node.upgradeToXI2?.();
@@ -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
@@ -802,7 +821,7 @@ export class EventManager {
       // **The default action moves whole pixels and keeps the change.** A
       // scroll offset that is not an integer costs the scroll blit — the
       // server-side copy that makes a scroll cheap can only shift by whole
-      // pixels, so `_applyScrollBlits` (nodes.js) declines a fractional one
+      // pixels, so `_applyScrollBlits` (nodes/scrollblit.js) declines a fractional one
       // and repaints the viewport instead. A touchpad reporting a third of a
       // notch would therefore turn every frame of the smoothest gesture the
       // renderer has into a full repaint, which is the opposite of the
@@ -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
@@ -1695,7 +1755,7 @@ export class EventManager {
    * focusable, and still on screen.
    *
    * Three callers ask it — a focus scope closing, an edit menu closing
-   * (`closeEditMenu`, nodes.js) and a subtree coming out of hiding — and the
+   * (`closeEditMenu`, nodes/editmenupopup.js) and a subtree coming out of hiding — and the
    * third is why the question includes visibility. Whatever a modal was
    * opened from may have suspended while it was up, and handing the keyboard
    * back to it would put keys on an invisible control by the other route.

package/src/foreignnodes.js

@@ -15,7 +15,7 @@
 //     render that is then thrown away has moved somebody else's window for
 //     real. So this node holds no socket until the owning `WindowNode`
 //     realizes it in the commit phase, exactly as `<glarea>` is realized
-//     (`_realizeChildWindows`, nodes.js).
+//     (`_realizeChildWindows`, nodes/window/window.js).
 //
 //  2. **Where the rect comes from.** Yoga, like any other child. Every
 //     change is a ConfigureWindow on the client plus the synthetic
@@ -33,11 +33,18 @@
 import { XEMBED, XEmbedSocket } from 'ntk';
 
 import { isFocusable } from './a11y.js';
+import { canEmbed } from './embedding.js';
 import { lastInputTime } from './inputtime.js';
-import { Node, pixelFor } from './nodes.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.
  *
@@ -88,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) {
@@ -96,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
@@ -132,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, {
@@ -158,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.

package/src/frames.js

@@ -1,9 +1,9 @@
 // Which windows owe a frame.
 //
-// Shared between the paint root (nodes.js — it records the debt in
+// Shared between the paint root (`WindowNode` — it records the debt in
 // `invalidate()` and pays it in `flush()`) and the event dispatcher
 // (events.js — it pays early, for discrete input). Its own module because
-// nodes.js already imports events.js, and the dispatcher cannot import the
+// src/nodes/ already imports events.js, and the dispatcher cannot import the
 // node back without a cycle.
 //
 // The set answers "which windows have unpainted damage" in O(1) at event

package/src/glnodes.js

@@ -10,7 +10,8 @@ import { cssColorStraight } from 'ntk';
 // re-exported so the GL element layer stays one import for consumers
 export { directGLFailure, hasDirectGL } from './glbackend.js';
 
-import { Node } from './nodes.js';
+import { GlOverlay, canOverlay } from './gloverlay.js';
+import { Node } from './nodes/node.js';
 import { FramePacer, resolveFrameRate } from './pacing.js';
 
 // One visual query per (app, spec): GetFBConfigs is a round trip and every
@@ -105,13 +106,22 @@ const px = (v) => Math.max(1, Math.round(v || 0));
  *   vocabulary as `<window frameRate>`. Defaults to the owning window's.
  * - `glx` — a `chooseGLXConfig` spec, e.g. `{ DEPTH_SIZE: 24 }`.
  *
- * The X child window is stacked above everything drawn in the parent, so 2D
- * content cannot overlap it — put HUD content in a sibling `<popup>`.
+ * 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).
+ *
+ * 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
+ * pointer, or at this node, bubbling to its ancestors like anyone else's
+ * (`hitSurface` says how).
  */
 export class GlAreaNode extends Node {
   constructor(props, app) {
     super('glarea', props, app);
     this.window = null;
+    // the panes the children are drawn on, while there are children
+    this._overlay = null;
     this.gl = null;
     this.rect = null; // geometry last sent to the X window
     this._realizing = false;
@@ -150,11 +160,21 @@ export class GlAreaNode extends Node {
 
   _setRoot(root) {
     super._setRoot(root);
+    // Children mounted along with this node — React builds a subtree before
+    // it attaches it — are drawn from the first frame of the window it joins.
+    if (this.children.length) root?._overlaid?.add(this);
     // the owning window may already exist (a <glarea> mounted into a live
     // tree); otherwise WindowNode.realize picks the subtree up
     if (root?.window) this.realize();
   }
 
+  insertBefore(child, beforeChild) {
+    super.insertBefore(child, beforeChild);
+    // 2D content above the surface: the owning window's next frame gives it
+    // a pane (`_syncOverlay`), and the child-list claim asks for that frame
+    this.root?._overlaid?.add(this);
+  }
+
   /** Create the GL child window. Async: the visual comes from the server. */
   realize() {
     if (this.window || this.destroyed || this._realizing) return;
@@ -199,6 +219,9 @@ export class GlAreaNode extends Node {
     recordGlxFailure(this.app, err);
     this.gl = null;
     if (this.window) {
+      // the children's panes stay, over whatever the fallback draws, and
+      // stay hittable; with none, nothing of this node covers the rect
+      if (!this._overlay) this._leaveSurfaces();
       this.window.destroy?.();
       this.window = null;
       this.rect = null;
@@ -222,26 +245,32 @@ export class GlAreaNode extends Node {
       // GL draws into the window itself: no 2d backing pixmap, and the
       // frame clock is ours to drive
       backingStore: false,
-      // The wheel, and only the wheel. A GL surface owns a real X window, so
-      // the pointer events over it are delivered *there* rather than to the
-      // window the rest of the tree is hit-tested in — which is why nothing
-      // over a `<glarea>` reached an application before. Selecting it here
-      // and handing it back to the owning window's manager (`_onWheel`
-      // below) is the whole of it: from there the event is an ordinary
-      // synthetic `Wheel` at this node, so it bubbles, `preventDefault()`
-      // takes it back for a scene that zooms instead, and the default action
-      // scrolls the nearest container the way it does anywhere else.
+      // No pointer input is selected here, and that is the whole of how the
+      // pointer over the surface reaches the tree. X reports a device event
+      // to the first window up the hierarchy that selected it, so a press,
+      // a motion or a wheel over this window arrives at the owning window
+      // instead — in its coordinates and under its implicit grab, so a drag
+      // that leaves the surface keeps coming — and its event manager takes
+      // it from there like any other (`hitSurface` names this node).
       //
-      // Selected unconditionally rather than when a handler is declared: the
-      // default action is what a reader expects from a wheel over a page,
-      // and an element that wants it back has `preventDefault()`. One
-      // ButtonPress per notch is not a cost worth a conditional.
-      onWheel: (ev) => this._onWheel(ev),
+      // Selecting one here takes it away from the tree, which is how the
+      // wheel alone used to be handled: the surface selected ButtonPress to
+      // hear it and handed it back, and so every *press* on the surface
+      // ended here too, with the drag and the release that should have
+      // followed it. A listener on `node.window` does the same — ntk selects
+      // what a window is listened to for — which is what `forwardsPointer`
+      // exists to tell an element built on this one.
     });
     this.window = wnd;
     this.rect = rect;
     this.config = config;
     wnd._reactX11Node = this;
+    // Above everything 2D in the owning window on both backends, and above
+    // every surface made before this one: X stacks a new child window over
+    // its siblings, and Core Animation a layer added later over one at the
+    // same zPosition. The window's hit test reads the list in that order
+    // (`EventManager._surfaceAt`).
+    this._joinSurfaces();
     this.gl = wnd.getContext('opengl', config);
     // a buffer freed by the display is a frame that can be drawn again
     if (typeof this.gl?.onFrameAvailable !== 'undefined') {
@@ -256,6 +285,9 @@ export class GlAreaNode extends Node {
     });
     wnd.on?.('expose', () => this.requestFrame());
     wnd.map?.();
+    // made on top of its siblings — over the panes of children that were
+    // laid out and painted before the visual query answered
+    this._overlay?.restack();
     this.requestFrame();
   }
 
@@ -385,31 +417,117 @@ export class GlAreaNode extends Node {
   }
 
   /**
-   * A wheel over the surface, handed to the window the tree lives in.
+   * `true`: pointer input over this surface is the tree's on this backend —
+   * dispatched through the owning window's event manager, at this node, and
+   * bubbling from it like anyone else's.
    *
-   * ntk reports the position inside *this* window; the manager hit-tests in
-   * the owning window's space, so the node's own origin goes back on. Both
-   * are device pixels — the scale is applied at the far end, where a handler
-   * reads `ev.x` (src/events.js).
+   * It is here to be asked by an element built on `<glarea>` that listens on
+   * `node.window` for the pointer, which it had to do before core delivered
+   * it. That listener has to go wherever this is true: on X11 it selects the
+   * event on the surface's own window, and X then delivers it *there*
+   * instead of to the tree (see `_create`) — every press, and the wheel with
+   * them, since both are ButtonPress.
    *
-   * Smooth deltas are not part of this yet: XI2 is selected on the window
-   * the manager owns, not on this child, so a touchpad's fractions arrive
-   * here as whole notches from buttons 4-7.
+   * A getter on the class rather than a flag on each instance, so it can be
+   * read without rendering anything: `GlAreaNode.prototype.forwardsPointer`,
+   * from `react-x11/node`.
    */
-  _onWheel(native) {
-    const events = this.root?.events;
-    if (!events || this.destroyed) return;
-    events._onWheel(
-      {
-        ...native,
-        x: (native.x ?? 0) + this.abs.x,
-        y: (native.y ?? 0) + this.abs.y,
-      },
-      // named rather than hit-tested: a window-owning child is not in its
-      // parent's paint order, so the hit test would answer with the box
-      // behind this surface
-      this,
-    );
+  get forwardsPointer() {
+    return true;
+  }
+
+  /**
+   * What a point in the owning window's space lands on, if it is over this
+   * surface: the child under it where there is one — the children are drawn
+   * above the surface (src/gloverlay.js) — and otherwise this node.
+   *
+   * A point that is over the surface is over it whatever the tree's own
+   * order says: X stacks the child window above the parent's drawing, and
+   * the Cocoa backend puts the layer at a zPosition over both presenters. So
+   * the window asks its surfaces before it hit-tests its tree
+   * (`EventManager._hit`), and a point inside lands here rather than on the
+   * box behind — which is all a tree walk can find, a window-owning node not
+   * being in its parent's paint order. It is the same answer X gives: the
+   * event it propagates to the owning window names this window, or a pane
+   * over it, as the child the pointer is in.
+   *
+   * The rect is the surface's own, in whole pixels, since the server decides
+   * by those. With no GL surface — not made yet, or given up after
+   * `onError` — only the children answer, and a point between them is the
+   * tree's. Hidden, or `pointerEvents: 'none'` here or above, lets the
+   * pointer through to what the tree has behind, as it does for any node.
+   */
+  hitSurface(x, y) {
+    const panes = this._overlay?.panes.length ?? 0;
+    if (!this.window && panes === 0) return null;
+    const rect = this.rect ?? this._geometry();
+    if (
+      x < rect.x ||
+      y < rect.y ||
+      x >= rect.x + rect.width ||
+      y >= rect.y + rect.height
+    ) {
+      return null;
+    }
+    for (let n = this; n; n = n.parent) {
+      if (n.destroyed || n.hidden) return null;
+      if (n.style?.display === 'none' || n.style?.pointerEvents === 'none') {
+        return null;
+      }
+      if (n.isWindow) break;
+    }
+    if (panes !== 0) {
+      // front to back, as the tree's own hit test walks a box's children
+      const order = this.paintOrder();
+      for (let i = order.length - 1; i >= 0; i--) {
+        const hit = order[i].hitTest(x, y);
+        if (hit) return hit;
+      }
+    }
+    return this.window ? this : null;
+  }
+
+  /** Into the owning window's hit test, once: a GL window or a pane covers
+   * the rect now (`EventManager._surfaceAt`). */
+  _joinSurfaces() {
+    const surfaces = this.root?._surfaces;
+    if (surfaces && !surfaces.includes(this)) surfaces.push(this);
+  }
+
+  /** Out of the owning window's hit test: nothing covers the rect any more,
+   * and what the tree has behind it answers again. */
+  _leaveSurfaces() {
+    const surfaces = this.root?._surfaces;
+    const at = surfaces ? surfaces.indexOf(this) : -1;
+    if (at !== -1) surfaces.splice(at, 1);
+  }
+
+  /**
+   * The owning window's frame, after layout (`WindowNode._syncOverlays`):
+   * panes for where the children are now. True when a pane was made,
+   * resized or dropped — a paint the frame then owes.
+   */
+  _syncOverlay() {
+    if (!this._overlay) {
+      if (this.children.length === 0 || !canOverlay(this.app)) {
+        this.root?._overlaid?.delete(this);
+        return false;
+      }
+      this._overlay = new GlOverlay(this);
+    }
+    const changed = this._overlay.sync();
+    if (this._overlay.panes.length) this._joinSurfaces();
+    if (this.children.length === 0 && this._overlay.panes.length === 0) {
+      this._overlay = null;
+      this.root?._overlaid?.delete(this);
+      if (!this.window) this._leaveSurfaces();
+    }
+    return changed;
+  }
+
+  /** …and the paint it owes them, with the frame's damage. */
+  _paintOverlay(damage) {
+    this._overlay?.paint(damage);
   }
 
   applyProps(newProps, oldProps) {
@@ -424,14 +542,27 @@ export class GlAreaNode extends Node {
     super.setHidden(hidden);
     if (hidden) this.window?.unmap?.();
     else this.window?.map?.();
+    this._overlay?.setHidden(hidden);
   }
 
-  // the child window covers this rect: nothing to paint into the parent's
-  // 2d context, and no drawn children are allowed under it
+  // The surface covers this rect: nothing of this node is painted into the
+  // parent's 2d context, and its children are painted above the surface on
+  // panes of their own (src/gloverlay.js) rather than in the window's walk.
   paint() {}
 
+  // …which is also why they are cut to its box: a pane never reaches past
+  // the surface, and the hit test and the damage model have to agree with
+  // the panes about where the children can be
+  clipsChildren() {
+    return true;
+  }
+
   destroySubtree() {
     if (this.destroyed) return;
+    this._leaveSurfaces();
+    this.root?._overlaid?.delete(this);
+    this._overlay?.destroy();
+    this._overlay = null;
     super.destroySubtree();
     this._pacer.cancel();
     this.gl?.destroy?.();