react-x11 2.14.0 → 2.15.0

package/src/wayland/device.js

@@ -0,0 +1,55 @@
+// Who owns the GL state right now.
+//
+// Every 2d context on this backend draws through one GLES context: a
+// window's, the pane a `<glarea>`'s children are painted on, and each
+// offscreen surface's are all the same device, differing only in which
+// framebuffer they bind and what they left the blend, scissor and stencil
+// state saying. That is unlike every other backend react-x11 has — an
+// XRender context is an encoder aimed at a drawable, a Cocoa one is a CGL
+// bitmap that carries its own state — and it is why ntk's advice to hold a
+// surface's context and draw into it whenever you like did not hold here:
+// a held context's draws landed wherever the *last* context had pointed the
+// device (issue #566).
+//
+// So the device gets an owner. A context claims it before it touches GL,
+// and claiming is where the target is bound and the state it assumes is put
+// back. Whoever drew in between does not have to know who comes next, and a
+// caller does not have to know there is a device at all.
+//
+// One record per `gl`, keyed weakly: a GPU that goes away takes its record
+// with it.
+const devices = new WeakMap();
+
+/** Whether this `gl` can key the table — a context may be built without one. */
+const shared = (gl) =>
+  gl !== null && (typeof gl === 'object' || typeof gl === 'function');
+
+/**
+ * The record for a device. `owner` is the context whose state is installed,
+ * or null when something outside this bookkeeping — foreign GL in a
+ * `<glarea>`, a framebuffer blit — has had its way with it.
+ *
+ * A context built with no GL behind it — `new WaylandContext2D(null)`, the
+ * seams above the first draw that `test/wayland/pure.test.js` and
+ * `glyph-runs.test.js` exercise — shares nothing, and gets a record of its
+ * own rather than an error.
+ *
+ * @param {object} gl the GLES entry points
+ * @returns {{ owner: object|null }}
+ */
+export function glDevice(gl) {
+  if (!shared(gl)) return { owner: null };
+  let device = devices.get(gl);
+  if (!device) devices.set(gl, (device = { owner: null }));
+  return device;
+}
+
+/**
+ * Say that the state no longer belongs to whoever last claimed it, so the
+ * next context to draw re-establishes its own. Call after touching GL
+ * behind the contexts' backs.
+ */
+export function releaseDevice(gl) {
+  const device = shared(gl) ? devices.get(gl) : null;
+  if (device) device.owner = null;
+}

package/src/wayland/framewatch.js

@@ -0,0 +1,190 @@
+// Noticing that the compositor has stopped showing this surface.
+//
+// After the first present the frame loop has exactly one source of liveness:
+// `wl_surface.frame`, which a compositor is entitled never to send to a
+// surface it is not showing — occluded, on another workspace, minimised, the
+// screen locked. That is the right behaviour to drive a client with (drawing
+// into a surface nobody sees is work for nothing) and it has one hole: a
+// callback that never fires is not an error. Nothing rejects, nothing throws,
+// the frame stays armed, and every later `_armFrame()` returns at its guard.
+// The app above goes on re-rendering into a tree that reaches no screen, and
+// from outside the process that is indistinguishable from a hang (#567).
+//
+// So the loop is watched. A frame callback outstanding longer than
+// `REACT_X11_WAYLAND_FRAME_STALL_MS` (2s; `0` turns the watch off) is taken
+// as "the compositor has parked us", which is
+//
+//   - **said once on stderr, in development**, when the window still had
+//     something to draw — the line that the debugging session behind #567
+//     would have ended at; and
+//   - **published**, as `useWindowState().presenting`, so an app can stop
+//     animating and simulating instead of feeding a loop nobody is turning.
+//
+// Nothing here paces or re-arms anything: the parked callback is still queued
+// with the compositor and fires the moment the surface is shown again, which
+// is what un-parks the loop and flips `presenting` back. A timer that painted
+// anyway would be drawing into a surface nobody sees, which is the thing the
+// frame callback is right about.
+
+import { writeSync } from 'node:fs';
+
+const DEV = process.env.NODE_ENV !== 'production';
+
+/** How long a frame callback may be outstanding before the loop counts as
+ *  parked, in milliseconds. `0` — or anything that is not a number — turns
+ *  the watch off entirely: no timer, no warning, `presenting` always true. */
+export const FRAME_STALL_MS = (() => {
+  const raw = process.env.REACT_X11_WAYLAND_FRAME_STALL_MS;
+  if (raw === undefined || raw === '') return 2000;
+  const ms = Number(raw);
+  return Number.isFinite(ms) && ms >= 0 ? ms : 0;
+})();
+
+/**
+ * The one line. It names the three things the symptom does not: that this is
+ * the compositor's decision and not a crash, that the window is the thing to
+ * look at, and where to read the state from in code.
+ */
+export function stallMessage(id, ms) {
+  return (
+    `react-x11 (wayland): window ${id} has had a frame callback outstanding ` +
+    `for ${(ms / 1000).toFixed(1)}s with a repaint waiting — the compositor ` +
+    'is not showing this surface (covered, on another workspace, minimised, ' +
+    'or the screen is locked), so nothing this app draws will reach the ' +
+    'screen until it does. The app is not hung. Read it in the tree as ' +
+    'useWindowState().presenting, which is false until the next frame ' +
+    'callback arrives. Said once per window; ' +
+    'REACT_X11_WAYLAND_FRAME_STALL_MS=0 turns it off.\n'
+  );
+}
+
+// Synchronous, like the frame trace in backendwindow.js and for the same
+// reason: Bun buffers `process.stderr` to a file, and a buffer is what a
+// SIGINT leaves behind — which is exactly how a run that looks hung ends.
+const toStderr = (message) => writeSync(2, message);
+
+/**
+ * One window's frame-callback liveness.
+ *
+ * Three calls from the frame loop, and they are the whole interface:
+ * `waiting()` when a `wl_surface.frame` has been asked for, `arrived()` when
+ * one comes back, `idle()` when the loop stops waiting for one at all (a
+ * rejected request, a closing connection). `presenting` is the answer, and
+ * `onChange` fires only when it turns over.
+ *
+ * The timers are injected so the policy above can be tested without a
+ * compositor, a GPU, or two seconds of wall clock.
+ */
+export class FrameWatch {
+  /**
+   * @param {object} opts
+   * @param {number|string} [opts.id] the window's id, for the message
+   * @param {number} [opts.stallMs] how long is too long
+   * @param {() => boolean} [opts.pending] is a repaint waiting? — only then
+   *   is the silence worth a line on stderr
+   * @param {(presenting: boolean) => void} [opts.onChange]
+   * @param {(message: string) => void} [opts.warn]
+   * @param {boolean} [opts.dev] whether to warn at all
+   */
+  constructor({
+    id = 0,
+    stallMs = FRAME_STALL_MS,
+    pending = () => false,
+    onChange = () => {},
+    warn = toStderr,
+    dev = DEV,
+    setTimer = (fn, ms) => {
+      const t = setTimeout(fn, ms);
+      // a diagnostic must never be the reason a process stays up
+      t.unref?.();
+      return t;
+    },
+    clearTimer = (t) => clearTimeout(t),
+  } = {}) {
+    this.id = id;
+    this.stallMs = stallMs;
+    this.presenting = true;
+    this._pending = pending;
+    this._onChange = onChange;
+    this._warn = warn;
+    this._dev = dev;
+    this._setTimer = setTimer;
+    this._clearTimer = clearTimer;
+    this._timer = null;
+    this._warned = false;
+    this._stopped = false;
+  }
+
+  /** A frame callback has been asked for. */
+  waiting() {
+    // An already-running timer is left alone: it measures the age of the
+    // oldest outstanding request, which is the one that matters.
+    if (this._stopped || this._timer || !(this.stallMs > 0)) return;
+    this._timer = this._setTimer(() => {
+      this._timer = null;
+      this._stall();
+    }, this.stallMs);
+  }
+
+  /** A frame callback arrived: the compositor is showing this surface. */
+  arrived() {
+    this._disarm();
+    this._publish(true);
+  }
+
+  /** Nothing is outstanding — a rejected request, a frame that drew nothing
+   *  and asked for no other. Says nothing about whether we are being shown. */
+  idle() {
+    this._disarm();
+  }
+
+  /**
+   * A repaint was asked for while a frame was already in flight.
+   *
+   * There is nothing to arm — the flight is armed, and the request will ride
+   * it — but if that flight is the compositor's silence then this is the
+   * moment the app starts drawing for nobody, and it is the other order the
+   * bug arrives in: a window can park while it has nothing to draw (nothing
+   * to warn about) and be given work a minute later, by which time the
+   * deadline has come and gone.
+   */
+  workArrived() {
+    if (this._stopped || this.presenting) return;
+    this._maybeWarn();
+  }
+
+  /** The window is going away. */
+  stop() {
+    this._stopped = true;
+    this._disarm();
+  }
+
+  _disarm() {
+    if (this._timer === null) return;
+    this._clearTimer(this._timer);
+    this._timer = null;
+  }
+
+  _stall() {
+    if (this._stopped) return;
+    this._maybeWarn();
+    this._publish(false);
+  }
+
+  /**
+   * The line, once per window, and only where the app had something to draw:
+   * a window that is simply idle is not being let down by anyone, and a
+   * warning there would fire on every app that comes to rest.
+   */
+  _maybeWarn() {
+    if (!this._dev || this._warned || !this._pending()) return;
+    this._warned = true;
+    this._warn(stallMessage(this.id, this.stallMs));
+  }
+
+  _publish(presenting) {
+    if (this.presenting === presenting) return;
+    this.presenting = presenting;
+    this._onChange(presenting);
+  }
+}

package/src/wayland/glarea.js

@@ -336,6 +336,7 @@ export class WaylandOverlayPane {
       this._ctx = new WaylandContext2D(this.app.gl, {
         fontManager: this.app.fonts,
         target: this.target,
+        makeCurrent: () => this.app.makeCurrent(),
       });
       this._ctx.init();
       this._ctx.begin(this.target.width, this.target.height);

package/src/wayland/protocols/index.json

@@ -78,6 +78,10 @@
   "zxdg_decoration_manager_v1",
   "zxdg_toplevel_decoration_v1"
  ],
+ "kde-server-decoration": [
+  "org_kde_kwin_server_decoration_manager",
+  "org_kde_kwin_server_decoration"
+ ],
  "primary-selection-unstable-v1": [
   "zwp_primary_selection_device_manager_v1",
   "zwp_primary_selection_device_v1",

package/src/wayland/protocols/kde-server-decoration.json

@@ -0,0 +1 @@
+[{"name":"org_kde_kwin_server_decoration_manager","version":1,"requests":[{"name":"create","args":[{"name":"id","type":"new_id","interface":"org_kde_kwin_server_decoration"},{"name":"surface","type":"object","interface":"wl_surface"}]}],"events":[{"name":"default_mode","args":[{"name":"mode","type":"uint"}]}],"enums":{"mode":{"entries":[{"name":"none","value":0},{"name":"client","value":1},{"name":"server","value":2}]}}},{"name":"org_kde_kwin_server_decoration","version":1,"requests":[{"name":"release","type":"destructor","args":[]},{"name":"request_mode","args":[{"name":"mode","type":"uint"}]}],"events":[{"name":"mode","args":[{"name":"mode","type":"uint"}]}],"enums":{"mode":{"entries":[{"name":"none","value":0},{"name":"client","value":1},{"name":"server","value":2}]}}}]

package/src/wayland/ssd.js

@@ -1,4 +1,5 @@
-// Server-side decorations, through xdg-decoration.
+// Server-side decorations: asking the compositor to draw the frame, and
+// falling back to drawing it ourselves only when nothing will.
 //
 // The compositor may draw the frame — wlroots compositors and KDE do, when
 // asked, and GNOME does not advertise the protocol at all — so "who draws the
@@ -11,6 +12,25 @@
 // client_side — which is the state the backend was already in, so
 // `decorations.js` stays and is switched off rather than removed.
 //
+// ## Two protocols say the same thing
+//
+// `xdg-decoration-unstable-v1` is the one to ask with, and where it is
+// offered it is the only one used. But it arrived late (2018) and KDE had
+// shipped `org_kde_kwin_server_decoration` years before, so a compositor may
+// advertise only the older one — KWin still carries both, and a handful of
+// smaller compositors never picked up the xdg protocol. Asking with whatever
+// is there is the difference between a real titlebar and an imitation, so
+// `createServerDecoration` tries them in that order and only gives up on
+// server-side when neither global exists.
+//
+// The KDE protocol is the same conversation in different words: it hangs off
+// the `wl_surface` rather than the `xdg_toplevel`, its enum has a third value
+// (`none`, no frame at all), its destructor is `release`, and — the one
+// difference that matters — its `mode` event is not part of a configure
+// sequence. Nothing promises a configure will follow it, so that driver
+// flushes itself (`flushesOutsideConfigure`); the xdg one keeps the stricter
+// discipline below.
+//
 // The mode is adopted, not applied on arrival, for the reason the configure
 // ack is deferred (window.js): a mode change is a size change — the surface
 // loses or gains its own titlebar — and the frame that adopts it has to be
@@ -22,6 +42,15 @@ import { EventEmitter } from 'node:events';
 /** `zxdg_toplevel_decoration_v1.mode`. */
 export const DECORATION_MODE = { CLIENT_SIDE: 1, SERVER_SIDE: 2 };
 
+/**
+ * `org_kde_kwin_server_decoration.mode`. The two that overlap with
+ * xdg-decoration share its numbering; `NONE` — no frame from either side —
+ * has no xdg equivalent and is only ever received, never asked for. A window
+ * that wants no frame asks for `CLIENT` and then draws nothing, which is the
+ * same picture and one less thing for `decorationPolicy` to express.
+ */
+export const KDE_DECORATION_MODE = { NONE: 0, CLIENT: 1, SERVER: 2 };
+
 /**
  * What `decorations` means, at the app (`createRoot({ decorations })`) and
  * per window (`<window decorations={false}>`, the one value the tree passes):
@@ -45,7 +74,63 @@ export function decorationPolicy(appOption, windowOption) {
   return { draw, prefer };
 }
 
-export class ServerDecoration extends EventEmitter {
+/**
+ * What both protocols have in common: a mode that arrives from the
+ * compositor, is held until the frame that can paint it adopts it, and an
+ * object that has to be destroyed before the thing it decorates.
+ */
+class Decoration extends EventEmitter {
+  constructor() {
+    super();
+    /** the mode in effect: 'server' | 'client', null before the first answer */
+    this.mode = null;
+    /** a mode the compositor sent that the next configure adopts */
+    this.pending = null;
+    this.destroyed = false;
+  }
+
+  /**
+   * Whether an answer can arrive with no configure behind it, in which case
+   * whoever owns this has to flush it rather than wait (window.js). False
+   * for xdg-decoration, whose mode is part of the configure sequence.
+   */
+  get flushesOutsideConfigure() {
+    return false;
+  }
+
+  /** The compositor's answer, held until `adopt()`. */
+  _answer(mode) {
+    this.pending = mode;
+    if (this.flushesOutsideConfigure) this.emit('pending');
+  }
+
+  /**
+   * Adopt the pending mode, if there is one.
+   *
+   * @returns {boolean} whether the mode in effect changed
+   */
+  adopt() {
+    if (this.pending == null) return false;
+    const changed = this.pending !== this.mode;
+    this.mode = this.pending;
+    this.pending = null;
+    if (changed) this.emit('mode', this.mode);
+    return changed;
+  }
+
+  /** Before the toplevel: destroying them the other way round is a protocol error. */
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    try {
+      this._release();
+    } catch {
+      /* the connection may already be gone */
+    }
+  }
+}
+
+export class ServerDecoration extends Decoration {
   /**
    * Create the decoration object and state a preference. Must run before
    * the toplevel's first commit; `WaylandWindow.createSync` calls it there.
@@ -58,13 +143,8 @@ export class ServerDecoration extends EventEmitter {
   constructor({ manager, toplevel, prefer = 'server' }) {
     super();
     this.proxy = manager.$.get_toplevel_decoration(toplevel.id);
-    /** the mode in effect: 'server' | 'client', null before the first configure */
-    this.mode = null;
-    /** a mode the compositor sent that the next xdg_surface.configure adopts */
-    this.pending = null;
-    this.destroyed = false;
     this.proxy.on('configure', (mode) => {
-      this.pending = mode === DECORATION_MODE.SERVER_SIDE ? 'server' : 'client';
+      this._answer(mode === DECORATION_MODE.SERVER_SIDE ? 'server' : 'client');
     });
     this.prefer(prefer);
   }
@@ -79,28 +159,76 @@ export class ServerDecoration extends EventEmitter {
     );
   }
 
+  _release() {
+    this.proxy.$.destroy();
+  }
+}
+
+/**
+ * The same conversation over `org_kde_kwin_server_decoration`, for the
+ * compositors that have only that one. It decorates the `wl_surface`, so it
+ * is created from the surface rather than the toplevel — but the ordering
+ * rule is the toplevel's all the same, since that is what carries the frame.
+ */
+export class KdeServerDecoration extends Decoration {
   /**
-   * Adopt the pending mode, if there is one.
-   *
-   * @returns {boolean} whether the mode in effect changed
+   * @param {object} opts
+   * @param {object} opts.manager the `org_kde_kwin_server_decoration_manager`
+   * @param {object} opts.surface the `wl_surface` proxy
+   * @param {'server'|'client'} [opts.prefer='server']
    */
-  adopt() {
-    if (this.pending == null) return false;
-    const changed = this.pending !== this.mode;
-    this.mode = this.pending;
-    this.pending = null;
-    if (changed) this.emit('mode', this.mode);
-    return changed;
+  constructor({ manager, surface, prefer = 'server' }) {
+    super();
+    this.proxy = manager.$.create(surface.id);
+    this.proxy.on('mode', (mode) => {
+      // `none` is not server-side, and this side draws nothing for it: the
+      // window that asked for no frame is already drawing nothing.
+      this._answer(mode === KDE_DECORATION_MODE.SERVER ? 'server' : 'client');
+    });
+    this.prefer(prefer);
   }
 
-  /** Before the toplevel: destroying them the other way round is a protocol error. */
-  destroy() {
+  /** Nothing sequences this protocol's `mode` event; window.js flushes it. */
+  get flushesOutsideConfigure() {
+    return true;
+  }
+
+  prefer(prefer) {
     if (this.destroyed) return;
-    this.destroyed = true;
-    try {
-      this.proxy.$.destroy();
-    } catch {
-      /* the connection may already be gone */
-    }
+    this.proxy.$.request_mode(
+      prefer === 'client'
+        ? KDE_DECORATION_MODE.CLIENT
+        : KDE_DECORATION_MODE.SERVER,
+    );
+  }
+
+  _release() {
+    this.proxy.$.release();
   }
 }
+
+/**
+ * Ask whichever protocol the compositor has, preferring the standard one.
+ * Returns null only when there is nobody to ask — the case where the frame
+ * has to be this backend's own (GNOME).
+ *
+ * @param {object} opts
+ * @param {object} [opts.manager] `zxdg_decoration_manager_v1`, if bound
+ * @param {object} [opts.kdeManager] `org_kde_kwin_server_decoration_manager`
+ * @param {object} opts.toplevel the `xdg_toplevel` proxy
+ * @param {object} opts.surface the `wl_surface` proxy
+ * @param {'server'|'client'} [opts.prefer='server']
+ * @returns {Decoration|null}
+ */
+export function createServerDecoration({
+  manager,
+  kdeManager,
+  toplevel,
+  surface,
+  prefer = 'server',
+}) {
+  if (manager) return new ServerDecoration({ manager, toplevel, prefer });
+  if (kdeManager)
+    return new KdeServerDecoration({ manager: kdeManager, surface, prefer });
+  return null;
+}

package/src/wayland/surface.js

@@ -13,6 +13,16 @@
 // only one surface is current at a time. Every target here shares the app's
 // one EGL context, so `render()` asks the app to make it current before
 // binding the target — which normally costs nothing, because it already is.
+//
+// Sharing one device is also why `getContext('2d')` used to be a trap. ntk
+// tells callers who draw often to hold a context rather than take one per
+// frame, and a held context here drew wherever the device was last pointed
+// — which, outside `render()`, was the window: the draws went nowhere
+// visible and nothing said so (#566). The context now takes the device back
+// whenever it finds it in someone else's hands (device.js), so holding one
+// works as ntk documents, and a node that painted into a surface in the
+// middle of the window's frame no longer has to put the window's GL state
+// back by hand either.
 
 import { WaylandContext2D } from './context2d.js';
 import { GLTarget } from './target.js';
@@ -57,6 +67,10 @@ export class WaylandSurface {
       this._ctx = new WaylandContext2D(this.app.gl, {
         fontManager: this.app.fonts,
         target: this.target,
+        // A surface may be drawn into between frames, when the app's notion
+        // of a current GL surface is whatever it last was; the context asks
+        // for one before it re-takes the device, as `render()` does.
+        makeCurrent: () => this.app.makeCurrent(),
       });
       this.app.makeCurrent();
       this._ctx.init();
@@ -67,6 +81,10 @@ export class WaylandSurface {
   /**
    * Draw into the surface through a context that starts clean — identity
    * transform, no clip — and is flushed when the callback returns.
+   *
+   * Drawing through `getContext('2d')` directly works too, and keeps the
+   * transform and clip it was left with; this is the scoped form, for a
+   * caller that wants a frame's worth of state rather than a canvas's.
    */
   render(fn) {
     if (this._destroyed) return this;

package/src/wayland/target.js

@@ -21,6 +21,8 @@
 // asking EGL for it means the window's own config no longer has to carry
 // stencil bits at all; the request in glcontext.js stays as belt and braces.
 
+import { releaseDevice } from './device.js';
+
 export class GLTarget {
   /**
    * @param {object} gl the GLES entry points
@@ -164,6 +166,9 @@ export class GLTarget {
       );
     }
     gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    // The framebuffer and the scissor were the 2d contexts' to say; they are
+    // not any more, so the next one to draw re-establishes them (device.js).
+    releaseDevice(gl);
   }
 
   /**
@@ -229,6 +234,7 @@ export class GLTarget {
       gl.NEAREST,
     );
     gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    releaseDevice(gl);
     return true;
   }
 

package/src/wayland/window.js

@@ -39,7 +39,7 @@
 // is emitted, so the frame that acks it is painted at the right insets.
 
 import { EventEmitter } from 'node:events';
-import { ServerDecoration } from './ssd.js';
+import { createServerDecoration } from './ssd.js';
 import { createLayerSurface } from './layershell.js';
 
 /** `xdg_toplevel.state` values. */
@@ -264,14 +264,17 @@ export class WaylandWindow extends EventEmitter {
     if (minSize) toplevel.$.set_min_size(minSize.width | 0, minSize.height | 0);
     if (maxSize) toplevel.$.set_max_size(maxSize.width | 0, maxSize.height | 0);
     // Who draws the frame is asked before the first commit; the answer rides
-    // the first configure (ssd.js).
-    if (decorations?.manager) {
-      win.decoration = new ServerDecoration({
-        manager: decorations.manager,
-        toplevel,
-        prefer: decorations.prefer,
-      });
-    }
+    // the first configure (ssd.js). Whichever protocol the compositor has is
+    // asked — the standard one first — and only a compositor with neither
+    // leaves the frame to this backend.
+    win.decoration = createServerDecoration({
+      manager: decorations?.manager,
+      kdeManager: decorations?.kdeManager,
+      toplevel,
+      surface,
+      prefer: decorations?.prefer,
+    });
+    win._wireDecoration();
     // the empty commit that asks for the first configure
     surface.$.commit();
     return win;
@@ -406,6 +409,30 @@ export class WaylandWindow extends EventEmitter {
     this.surface.on('preferred_buffer_transform', () => {});
   }
 
+  /**
+   * The KDE protocol's `mode` event is not part of a configure sequence
+   * (ssd.js), so a change of heart after the window is up would otherwise
+   * sit in `pending` waiting for a configure that nothing promises. Flush it
+   * in a microtask: a configure in the same batch of messages still gets
+   * there first and adopts it the ordinary way, and only a mode that really
+   * arrived alone is applied on its own — `setMargins` already knows how to
+   * resize outside a configure.
+   *
+   * Before the first configure there is nothing to flush: that configure is
+   * coming, and riding it keeps the first frame at the right insets.
+   */
+  _wireDecoration() {
+    const decoration = this.decoration;
+    if (!decoration?.flushesOutsideConfigure) return;
+    decoration.on('pending', () => {
+      if (!this.configured) return;
+      queueMicrotask(() => {
+        if (this.destroyed) return;
+        if (decoration.adopt()) this.emit('decorationmode', decoration.mode);
+      });
+    });
+  }
+
   /**
    * The shell's configure — xdg_surface's, or the layer surface's with its
    * size already taken — holds the serial for the frame that adopts it. A