react-x11 2.12.0 → 2.14.0

package/src/gloverlay.js

@@ -0,0 +1,383 @@
+// The children of a `<glarea>`: 2D content, drawn above the GL surface.
+//
+// A surface is stacked over everything 2D in its window — a child X window
+// above the parent's drawing on X11, a layer at zPosition 1e7 over both
+// presenters on the Cocoa backend — so the window's own paint walk can never
+// put a pixel on it, and does not try: a `<glarea>` is in no paint order, and
+// so is nothing under it. Its children are otherwise ordinary. They are laid
+// out in its box like a `<box>`'s; they live in the owning window's tree, so
+// their claims land in its damage list and their input comes through its
+// event manager, the hit test asking them before the surface itself
+// (`GlAreaNode.hitSurface`). What is theirs alone is where they are painted:
+// into *panes* above the surface, from inside the owning window's frame and
+// with that frame's damage (nodes/window/flush.js, `_syncOverlays` and
+// `_paintOverlays`).
+//
+// A pane is the backend's answer to one question — can a window composite a
+// translucent child over a GL surface?
+//
+// - **The Cocoa backend: yes.** Core Animation composites every layer, so
+//   one pane holds everything — a transparent bitmap layer over the whole
+//   surface, above the GL layer — and a translucent background, an
+//   antialiased edge or a shadow blends with the GL frame under it.
+//   `app.createOverlayPane` is how a backend says it composites.
+// - **X11: no.** A child window is opaque without a compositor, and a
+//   compositor would not change that: it redirects top-level windows, not
+//   the children inside one. So a pane is a plain child window just big
+//   enough for what it holds, one per region the children reach, and the
+//   surface shows between them. Inside a pane the ground is the surface's
+//   `clearColor` — the colour its frames start from — so a pixel a child
+//   leaves unpainted there (a rounded corner, a translucent background, text
+//   with no box behind it) shows that colour, never the GL frame.
+//
+//   A window per region rather than one window shaped by the SHAPE
+//   extension, for two reasons: SHAPE is near-universal but not universal —
+//   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.
+//
+// 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
+// (src/glnodes.js, `_create`), and lands on the child it is over.
+//
+// A leaf module, like src/embedding.js: `appcontext.js` asks `canOverlay`
+// for `useSupports('glOverlay')`, and it imports nothing of ours.
+import { cssColorStraight } from 'ntk';
+
+// ConfigureWindow's stack mode: directly above the sibling it names
+const STACK_ABOVE = 0;
+
+/**
+ * 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>`.
+ */
+export function canOverlay(app) {
+  return (
+    typeof app?.createOverlayPane === 'function' ||
+    typeof app?.createWindow === 'function'
+  );
+}
+
+/** A rect grown out to whole device pixels. */
+function whole(r) {
+  const x = Math.floor(r.x);
+  const y = Math.floor(r.y);
+  return {
+    x,
+    y,
+    width: Math.ceil(r.x + r.width) - x,
+    height: Math.ceil(r.y + r.height) - y,
+  };
+}
+
+function intersect(a, b) {
+  const x = Math.max(a.x, b.x);
+  const y = Math.max(a.y, b.y);
+  const right = Math.min(a.x + a.width, b.x + b.width);
+  const bottom = Math.min(a.y + a.height, b.y + b.height);
+  return right > x && bottom > y
+    ? { x, y, width: right - x, height: bottom - y }
+    : null;
+}
+
+const overlaps = (a, b) =>
+  a.x < b.x + b.width &&
+  b.x < a.x + a.width &&
+  a.y < b.y + b.height &&
+  b.y < a.y + a.height;
+
+function around(a, b) {
+  const x = Math.min(a.x, b.x);
+  const y = Math.min(a.y, b.y);
+  return {
+    x,
+    y,
+    width: Math.max(a.x + a.width, b.x + b.width) - x,
+    height: Math.max(a.y + a.height, b.y + b.height) - y,
+  };
+}
+
+const sameRect = (a, b) =>
+  a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+
+/** On screen: nothing from here to the window hidden or `display: 'none'`. */
+function shown(node) {
+  for (let n = node; n; n = n.parent) {
+    if (n.destroyed || n.hidden || n.style?.display === 'none') return false;
+    if (n.isWindow) break;
+  }
+  return true;
+}
+
+/**
+ * Where the children put ink, as rects no two of which overlap: each drawn
+ * child's reach in whole pixels, cut to the surface, and any two that
+ * overlap merged into the box around both. A pane is a rectangle, and two
+ * panes over one pixel would each have to hold what the other draws there.
+ *
+ * The reach is `_subtreeBounds()`, the rect the damage model culls against —
+ * so a child's shadow, its outline and a descendant that sticks out of it
+ * are all inside its pane.
+ */
+export function overlayRegions(area, surface) {
+  const rects = [];
+  for (const child of area.paintOrder()) {
+    const reach = intersect(whole(child._subtreeBounds()), surface);
+    if (reach) rects.push(reach);
+  }
+  for (let merged = true; merged;) {
+    merged = false;
+    search: for (let i = 0; i < rects.length; i++) {
+      for (let j = i + 1; j < rects.length; j++) {
+        if (overlaps(rects[i], rects[j])) {
+          rects[i] = around(rects[i], rects[j]);
+          rects.splice(j, 1);
+          merged = true;
+          break search;
+        }
+      }
+    }
+  }
+  return rects;
+}
+
+/**
+ * The colour an opaque pane is filled with before its children paint: the
+ * surface's `clearColor`, what the GL frame under the pane starts from, at
+ * full alpha. The pane is opaque, and a translucent fill would pile up on
+ * the pane's own last frame rather than show anything under it.
+ */
+function groundOf(props) {
+  const value = props.clearColor ?? 'black';
+  const [r, g, b] = Array.isArray(value)
+    ? value
+    : (cssColorStraight(value) ?? [0, 0, 0, 1]);
+  const byte = (c) => Math.round(Math.max(0, Math.min(1, c)) * 255);
+  return `rgb(${byte(r)}, ${byte(g)}, ${byte(b)})`;
+}
+
+/**
+ * One pane: the window — or on the Cocoa backend the layer, which speaks the
+ * same few verbs — and what the overlay knows about it: where it is, whether
+ * all of it is owed a paint, and its 2d context, made once, since ntk builds
+ * a fresh one with subscriptions of its own on every `getContext`.
+ */
+class Pane {
+  constructor(wnd, rect, transparent) {
+    this.wnd = wnd;
+    this.rect = rect;
+    this.transparent = transparent;
+    this.full = true;
+    this.ctx = null;
+  }
+
+  context() {
+    if (!this.ctx && typeof this.wnd.getContext === 'function') {
+      this.ctx = this.wnd.getContext('2d');
+    }
+    return this.ctx;
+  }
+
+  /** Somewhere else. A new size is a new backing — a pixmap on X11, a
+   * bitmap on Cocoa — and has to be painted whole; a move keeps what the
+   * pane holds, which moved with the children it shows. */
+  place(rect) {
+    if (rect.width !== this.rect.width || rect.height !== this.rect.height) {
+      this.full = true;
+    }
+    this.rect = rect;
+    if (typeof this.wnd.setState === 'function') this.wnd.setState(rect);
+    else {
+      this.wnd.move?.(rect.x, rect.y);
+      this.wnd.resize?.(rect.width, rect.height);
+    }
+  }
+
+  show(on) {
+    if (on) this.wnd.map?.();
+    else this.wnd.unmap?.();
+  }
+
+  destroy() {
+    this.wnd.destroy?.();
+    this.ctx = null;
+  }
+}
+
+/** A `<glarea>`'s panes, from the owning window's frame. */
+export class GlOverlay {
+  constructor(area) {
+    this.area = area;
+    this.app = area.app;
+    // one pane over the whole surface, where the backend composites it
+    this.composited = typeof this.app?.createOverlayPane === 'function';
+    this.panes = [];
+  }
+
+  /**
+   * After layout: panes for where the children are now. True when a pane was
+   * made, resized or dropped — a paint the frame then owes.
+   *
+   * Nothing is made for a surface that is hidden, or has no area, or has no
+   * child on screen: a pane with nothing on it would only hide the surface.
+   * The panes of one that goes are dropped rather than kept unmapped, and
+   * the frame that brings it back makes new ones and paints them whole.
+   */
+  sync() {
+    const area = this.area;
+    const abs = area.abs;
+    let rects = [];
+    if (shown(area) && abs.width > 0 && abs.height > 0) {
+      // the surface's own rect, rounded the way its window's is
+      const surface = area._geometry();
+      if (!this.composited) rects = overlayRegions(area, surface);
+      else if (area.paintOrder().length) rects = [surface];
+    }
+    let changed = false;
+    while (this.panes.length > rects.length) {
+      this.panes.pop().destroy();
+      changed = true;
+    }
+    let made = false;
+    for (let i = 0; i < rects.length; i++) {
+      const pane = this.panes[i];
+      if (!pane) {
+        this.panes.push(this._makePane(rects[i]));
+        made = changed = true;
+      } else if (!sameRect(pane.rect, rects[i])) {
+        pane.place(rects[i]);
+        changed = true;
+      }
+    }
+    if (made) this.restack();
+    return changed;
+  }
+
+  _makePane(rect) {
+    const owner = this.area.root.window;
+    const attributes = { parent: owner, ...rect };
+    const pane = this.composited
+      ? new Pane(this.app.createOverlayPane(attributes), rect, true)
+      : // A plain child window on the owning window's visual, selecting
+        // nothing but what ntk selects for itself — the structure events and
+        // the exposures its backing store answers. The pointer is the tree's.
+        new Pane(this.app.createWindow(attributes), rect, false);
+    // ntk asks for a redraw when the backing no longer holds the picture — a
+    // resize it could not carry over — and a pane has nothing to redraw from
+    // but the children, on the next frame of the window they live in
+    pane.wnd.on?.('draw', () => this._lost(pane));
+    pane.show(true);
+    return pane;
+  }
+
+  /** A pane whose pixels are gone: all of it is owed, on the owning window's
+   * next frame, claimed as its rect so the rest of the window stays put. */
+  _lost(pane) {
+    pane.full = true;
+    const root = this.area.root;
+    if (root && !root.destroyed)
+      root.invalidate(false, { ...pane.rect }, 'expose');
+  }
+
+  /**
+   * Put the panes directly over the surface, bottom to top. Only X11 needs
+   * it: a child window is made on top of its siblings, which is right for a
+   * pane made after the surface and wrong for one made before it — the
+   * surface's window is made once its visual is known, which can be after
+   * the first frame has laid out and painted its children. So the surface
+   * restacks its panes when its own window is made, too (`_create`). On the
+   * Cocoa backend the layer's zPosition is the whole of it.
+   */
+  restack() {
+    if (this.composited) return;
+    const X = this.app?.X;
+    if (typeof X?.ConfigureWindow !== 'function') return;
+    let below = this.area.window?.id ?? null;
+    for (const pane of this.panes) {
+      const id = pane.wnd.id;
+      if (id == null) continue;
+      if (below == null) X.ConfigureWindow(id, { stackMode: STACK_ABOVE });
+      else X.ConfigureWindow(id, { sibling: below, stackMode: STACK_ABOVE });
+      below = id;
+    }
+  }
+
+  /**
+   * Paint what the frame owes: every pane whole after it was made, resized
+   * or lost its pixels, and otherwise the frame's damage cut to each pane —
+   * `null` damage meaning the whole window, as it does for the paint walk.
+   *
+   * Each pass is the window's own paint walk over the children, translated
+   * so the pane's corner is the bitmap's, clipped to the pass, with
+   * `paintDamage()` naming it — the same culling, the same paint cache, the
+   * same everything as a pass over the window, and in its coordinates.
+   */
+  paint(damage) {
+    for (const pane of this.panes) {
+      let passes;
+      if (pane.full || !damage) {
+        passes = [pane.rect];
+      } else {
+        passes = [];
+        for (const rect of damage) {
+          const hit = intersect(rect, pane.rect);
+          if (hit) passes.push(hit);
+        }
+        if (passes.length === 0) continue;
+      }
+      pane.full = false;
+      this._paintPane(pane, passes);
+    }
+  }
+
+  _paintPane(pane, passes) {
+    const area = this.area;
+    const root = area.root;
+    const ctx = pane.context();
+    if (!ctx || !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();
+        }
+      }
+    } 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
+    pane.wnd.present?.();
+  }
+
+  /** Unmapped now; `sync` drops them on the frame the hide lays out. */
+  setHidden(hidden) {
+    for (const pane of this.panes) pane.show(!hidden);
+  }
+
+  destroy() {
+    for (const pane of this.panes) pane.destroy();
+    this.panes = [];
+  }
+}

package/src/host.d.ts

@@ -21,7 +21,6 @@ import type { NtkApp } from './types/nodes.js';
 export interface HostContext {
   isInsideText: boolean;
   isInsideSvg: boolean;
-  isInside3d: boolean;
 }
 
 export interface ElementDefinition {

package/src/index.d.ts

@@ -163,8 +163,21 @@ export function useClipboard(): Clipboard;
  * branches on it through the theme's `controls: 'auto'` policy; this is for
  * application code composing its own controls to sit beside native ones. It
  * is a property of the backend and never changes over the app's life.
+ *
+ * `'embedding'` is whether this connection can take another process's window
+ * into its own — X11, never Cocoa or the headless mock. Ask it before
+ * rendering a `<foreign>`, which refuses with one `onError` where it is
+ * false. Also a property of the backend, and it never changes either.
+ *
+ * `'glOverlay'` is whether the children of a `<glarea>` are drawn above its
+ * GL surface — laid out in its box, painted on panes stacked over it, hit
+ * 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.
  */
-export type SupportsFeature = 'transparency' | 'shaders' | 'nativeControls';
+export type SupportsFeature =
+  'transparency' | 'shaders' | 'nativeControls' | 'embedding' | 'glOverlay';
 
 /**
  * Can this **display** do something? `'transparency'` is true when the
@@ -287,6 +300,11 @@ export interface RootOptions {
     | 'off'
     | {
         mode?: 'auto' | 'direct' | 'indirect' | 'off';
+        /**
+         * Wayland: the DRM node to render on. Defaults to
+         * `REACT_X11_GL_DEVICE`, then the first render node, then, on a
+         * machine with no render node, each card node in turn.
+         */
         devicePath?: string | null;
         maxInFlight?: number;
         linearFallback?: boolean;

package/src/node.d.ts

@@ -820,5 +820,16 @@ export declare class WindowNode extends Node {}
 export declare class PopupNode extends WindowNode {}
 /** The precedents for an element owning a real child X window — a surface of
  * its own, and one holding somebody else's window. */
-export declare class GlAreaNode extends Node {}
+export declare class GlAreaNode extends Node {
+  /**
+   * `true`: the pointer over the surface is dispatched through the owning
+   * window's event manager, at this node, on this backend. So an element
+   * built on `<glarea>` must not listen for the pointer on `node.window` —
+   * on X11 that selects the event on the surface's own window, and X then
+   * delivers it there instead of to the tree. Readable without rendering,
+   * as `GlAreaNode.prototype.forwardsPointer`; absent on a core that does
+   * not deliver it.
+   */
+  readonly forwardsPointer: true;
+}
 export declare class ForeignNode extends Node {}

package/src/nodes/boxpaint.js

@@ -254,6 +254,15 @@ export class NodeBoxPaint {
         ctx.fill();
         continue;
       }
+      // A context that can feather a rounded rectangle itself — the GPU
+      // backend's distance-field shadow — skips the coverage surface, the
+      // CPU blur and the paint cache entirely. Feature-detected, like
+      // `presentFrame`: an ntk context has no such method and takes the
+      // path below.
+      if (typeof ctx.fillShadow === 'function') {
+        ctx.fillShadow(rect, r, shadow.blur, color);
+        continue;
+      }
       this._paintBlurredShadow(ctx, rect, r, shadow.blur, color);
     }
   }

package/src/nodes/preedit.js

@@ -43,12 +43,18 @@ export class TextInputPreedit {
 
   /** A value index in the displayed string. The caret is at the composition
    * while it is open, so it maps to the *end* of the preedit — which is
-   * where the next keystroke of the sequence appears. */
+   * where the next keystroke of the sequence appears — unless the input
+   * method said where inside its preedit the cursor is (`_preeditCursor`,
+   * a compositor IME converting one segment of a longer phrase). */
   _displayIndex(index) {
     if (!this._preedit) return index;
-    return index >= this._preeditStart()
-      ? index + Array.from(this._preedit).length
-      : index;
+    const start = this._preeditStart();
+    if (index < start) return index;
+    const length = Array.from(this._preedit).length;
+    if (index === start && this._preeditCursor) {
+      return start + Math.min(length, this._preeditCursor.begin);
+    }
+    return index + length;
   }
 
   /** The inverse, for indices that come back out of a layout. A hit inside
@@ -61,10 +67,20 @@ export class TextInputPreedit {
     return Math.max(start, index - Array.from(this._preedit).length);
   }
 
-  _setPreedit(text) {
-    if (text === this._preedit) return;
+  /**
+   * `cursor` is `{ begin, end }` in code points into `text` — where an input
+   * method wants the caret inside its preedit, or a segment of it
+   * highlighted when the two differ — and null for the end, which is where
+   * the client-side composer's caret always is.
+   */
+  _setPreedit(text, cursor = null) {
+    const range = text && cursor ? cursor : null;
+    if (text === this._preedit && sameRange(range, this._preeditCursor)) {
+      return;
+    }
     if (!this._preedit) this._preeditAt = this._selection()[0];
     this._preedit = text;
+    this._preeditCursor = range;
     this._repaint();
   }
 
@@ -79,7 +95,18 @@ export class TextInputPreedit {
    */
   defaultComposition(ev) {
     if (ev.type !== 'compositionEnd') {
-      this._setPreedit(ev.data);
+      // `cursorBegin`/`cursorEnd` ride the event only when an input method
+      // put them there (src/wayland/textinput.js); a dead key carries none
+      const begin = ev.cursorBegin;
+      const cursor = Number.isInteger(begin)
+        ? {
+            begin,
+            end: Number.isInteger(ev.cursorEnd)
+              ? Math.max(begin, ev.cursorEnd)
+              : begin,
+          }
+        : null;
+      this._setPreedit(ev.data, cursor);
       return;
     }
     this._setPreedit('');
@@ -114,14 +141,37 @@ export class TextInputPreedit {
     // this and a composition at a wrap point is two spans — drawn as one
     // batch, so the underline costs one request however it wraps
     const rects = [];
-    for (let li = from.line; li <= to.line; li++) {
-      const line = layout.lines[li];
-      if (!line) break;
-      const x0 = li === from.line ? from.x : line.x;
-      const x1 = li === to.line ? to.x : line.x + line.width;
-      if (x1 <= x0) continue;
-      rects.push(originX + x0, originY + line.y + line.ascent + 1, x1 - x0, 1);
+    const underline = (from, to, thickness) => {
+      for (let li = from.line; li <= to.line; li++) {
+        const line = layout.lines[li];
+        if (!line) break;
+        const x0 = li === from.line ? from.x : line.x;
+        const x1 = li === to.line ? to.x : line.x + line.width;
+        if (x1 <= x0) continue;
+        rects.push(
+          originX + x0,
+          originY + line.y + line.ascent + 1,
+          x1 - x0,
+          thickness,
+        );
+      }
+    };
+    underline(from, to, 1);
+    // The segment an input method is converting, when it named one: the
+    // convention (GTK, Qt, the browsers) is a heavier line under the part of
+    // the phrase the candidates are for, and a plain one under the rest.
+    const cursor = this._preeditCursor;
+    if (cursor && cursor.end > cursor.begin) {
+      underline(
+        layout.caretPosition(start + cursor.begin),
+        layout.caretPosition(start + cursor.end),
+        2,
+      );
     }
     if (rects.length) ctx.fillRects(rects);
   }
 }
+
+function sameRange(a, b) {
+  return a === b || (!!a && !!b && a.begin === b.begin && a.end === b.end);
+}

package/src/nodes/window/flush.js

@@ -84,6 +84,29 @@ export class WindowFlush {
     this._pacer.charge(ms);
   }
 
+  /**
+   * Panes for the children of every `<glarea>` here, where this frame's
+   * layout put them (src/gloverlay.js). True when one was made, resized or
+   * dropped, which the frame then owes a paint for.
+   */
+  _syncOverlays() {
+    let changed = false;
+    for (const area of this._overlaid) {
+      if (area.destroyed || area.root !== this) {
+        this._overlaid.delete(area);
+        continue;
+      }
+      if (area._syncOverlay()) changed = true;
+    }
+    return changed;
+  }
+
+  /** …and their paint, with the frame's own damage: a claim inside a
+   * `<glarea>`'s children is in that list like any other. */
+  _paintOverlays(damage) {
+    for (const area of this._overlaid) area._paintOverlay(damage);
+  }
+
   /**
    * A frame: layout if owed, then the paint passes — or the presenter's
    * frame — then the backend's word. Runs on the window's clock through
@@ -254,6 +277,12 @@ export class WindowFlush {
     // …and the next commit's claims name the arrangement this frame leaves
     // behind again, from before whatever scroll comes with them
     this._laidOut = false;
+    // The children of a `<glarea>` get panes where they are now: after
+    // layout and the scroll's shift, before the damage is taken, so a pane
+    // made or resized in this frame is painted in it, whole
+    if (this._overlaid.size !== 0 && this._syncOverlays()) {
+      this.needsPaint = true;
+    }
     if (!this.needsPaint) return false;
     this.needsPaint = false;
     const damage = this._takeDamage(width, height);
@@ -276,6 +305,8 @@ export class WindowFlush {
     // list was still taken (its bookkeeping is what keeps the two paths one
     // code) and is simply not consumed; the presenter diffs at the layer.
     if (typeof this.window.presentFrame === 'function') {
+      // the panes are no presenter's: they paint from the damage either way
+      if (this._overlaid.size !== 0) this._paintOverlays(damage);
       this.window.presentFrame(this, damage);
       this.app._reactX11Startup?.painted();
       return true;
@@ -297,6 +328,10 @@ export class WindowFlush {
     for (const rect of damage ?? [null]) {
       this._paintRegion(ctx, rect, width, height);
     }
+    // …and the panes over the surfaces, with the same damage: a claim from
+    // a `<glarea>`'s children is theirs to repaint — the window's pass under
+    // the surface is one nobody sees. Inside the cache's frame, like a pass.
+    if (this._overlaid.size !== 0) this._paintOverlays(damage);
     // after every region: an entry drawn in one damage rect must not be
     // evicted before the next rect of the same frame asks for it
     this._paintCache?.endFrame();

package/src/nodes/window/window.js

@@ -191,6 +191,15 @@ export class WindowNode extends Scrollable(Node) {
     // behind one `size` read on the motion path, and a tree that never asked
     // for attention must not pay a property walk to find that out.
     this._attentionNodes = new Set();
+    // The GL surfaces in this window, bottom to top: `<glarea>`s, stacked
+    // above everything 2D here, which the hit test therefore asks before the
+    // tree (`EventManager._surfaceAt`). A surface joins when its window is
+    // made and leaves when it goes (src/glnodes.js).
+    this._surfaces = [];
+    // …and the ones with children, whose panes each frame syncs after layout
+    // and paints with its damage (nodes/window/flush.js, src/gloverlay.js).
+    // Empty is one `size` read a frame.
+    this._overlaid = new Set();
     this.events = new EventManager(this);
     // ids of the child windows in the order the *server* stacks them,
     // bottom to top — see _restackWindowChildren