react-x11 2.51.1 → 2.53.0

package/src/components/Menu.js

@@ -984,7 +984,9 @@ function useMenuAccelerators(
  *
  * The wrapper is focusable and takes focus when the menu opens, because the
  * popup is override-redirect and never gets focus itself — the same trick
- * `Select` uses to keep arrow keys working while its menu is open.
+ * `Select` uses to keep arrow keys working while its menu is open. It is not
+ * a Tab stop: it has no role or name, so Tab landing on it would announce
+ * nothing, and the controls inside are stops of their own.
  */
 export function ContextMenu({
   items = [],
@@ -1087,7 +1089,10 @@ export function ContextMenu({
     'box',
     {
       ref,
-      focusable: true,
+      // focusable by a press and by `focus()` above, but out of the Tab
+      // cycle: a stop here is a nameless "filler" around content whose own
+      // controls are already reachable
+      tabIndex: -1,
       onMouseDown: (ev) => {
         if (ev.button !== 3 && rect) close();
       },

package/src/components/Switch.js

@@ -98,7 +98,7 @@ export function Switch({
   );
 
   // NSSwitch's own pixels, on/off as two cached bezels. The knob slide is
-  // the fidelity this loses for now (docs/macos.md flags the switch as the
+  // the fidelity this loses for now (design/macos.md flags the switch as the
   // one control worth revisiting if that disappoints); the press keeps its
   // answer as the wash, since NSSwitch renders no pressed state offscreen.
   if (nativeControls) {

package/src/components/native.js

@@ -1,4 +1,4 @@
-// The native half of the widget set (docs/macos.md §Native controls).
+// The native half of the widget set (design/macos.md §Native controls).
 //
 // House rule: **default native, seam out.** On a backend that renders the
 // platform's own control bezels — today the Cocoa backend — the core

package/src/desktopintegration.js

@@ -8,7 +8,8 @@
 //
 //   `appearance`  the light/dark, accent, contrast and reduced-motion ladder
 //                 (src/appearance.js) — the settings portal, then macOS, then
-//                 XSETTINGS
+//                 XSETTINGS — and, on the Wayland backend, the interaction
+//                 settings read off the same portal (src/desktopsettings.js)
 //   `a11y`        the AT-SPI bridge, started from `createRoot()`
 //                 (src/a11y.js, docs/accessibility.md)
 //   `globalMenu`  a `MenuBar` handing its menu to the panel instead of drawing

package/src/desktopsettings.js

@@ -11,17 +11,30 @@
 //
 // `appearance.js` climbs three sources for colour scheme and accent, because
 // those are answered by three different things and the portal is the modern
-// one. Nothing here has a portal equivalent: `org.freedesktop.appearance` has
-// four keys and none of them is a timing. XSETTINGS is the whole story, and
-// where there is no settings daemon — a bare `startx`, most window managers,
-// XQuartz — the defaults below stand.
+// one. Nothing here has a *standard* portal equivalent:
+// `org.freedesktop.appearance` has four keys and none of them is a timing.
+// On X11, XSETTINGS is the whole story, and where there is no settings
+// daemon — a bare `startx`, most window managers, XQuartz — the defaults
+// below stand.
 //
-// So this reads the map `xsettings.js` already maintains, rather than
-// standing up a source of its own. The one exception is macOS, which has no
-// XSETTINGS and answers exactly one of these — "reduce motion", through
-// `NSWorkspace` — so the Cocoa app exposes that behind a two-method seam
-// (`accessibilityDisplayOptions`, `watchAccessibilityDisplay`) and this
-// module reads it the way it reads the map: synchronously, cached, live.
+// So on X11 this reads the map `xsettings.js` already maintains, rather than
+// standing up a source of its own. There are two exceptions, one per backend
+// that has no X server to ask:
+//
+// - **macOS** answers exactly one of these — "reduce motion", through
+//   `NSWorkspace` — so the Cocoa app exposes that behind a two-method seam
+//   (`accessibilityDisplayOptions`, `watchAccessibilityDisplay`) and this
+//   module reads it the way it reads the map: synchronously, cached, live.
+//
+// - **The Wayland backend** has no XSETTINGS either, but the settings portal
+//   is not limited to `org.freedesktop.appearance`: the GNOME and GTK portal
+//   backends pass whole GSettings schemas through it, and
+//   `org.gnome.desktop.interface` and `org.gnome.desktop.peripherals.mouse`
+//   are exactly what gsd-xsettings translates into the XSETTINGS keys this
+//   reads on X11. Same numbers, one hop closer to the source. Read once at
+//   startup and again on `SettingChanged`; a desktop whose portal does not
+//   carry them (KDE, a bare compositor) keeps the defaults, as a bare
+//   `startx` does.
 //
 // ## Two of these are read synchronously, which is what shapes the module
 //
@@ -34,8 +47,26 @@
 // desktop's cadence from the next focus onward; that is the one seam, and it
 // is worth more than the round trips on every app's startup path.
 
+import { sessionBus } from './bus.js';
+import { desktopIntegrationEnabled } from './desktopintegration.js';
+import { PORTAL_NAME, PORTAL_PATH } from './portal.js';
 import { beginXSettings, watchXSettings, xsettings } from './xsettings.js';
 
+const SETTINGS_IFACE = 'org.freedesktop.portal.Settings';
+const INTERFACE_NS = 'org.gnome.desktop.interface';
+const MOUSE_NS = 'org.gnome.desktop.peripherals.mouse';
+
+/** The keys a `SettingChanged` has to name for a re-read to be worth it —
+ *  `org.gnome.desktop.interface` also carries the clock format, the font
+ *  and the icon theme, and none of those is a reason to re-render. */
+const WATCHED = new Set([
+  `${INTERFACE_NS}/cursor-blink`,
+  `${INTERFACE_NS}/cursor-blink-time`,
+  `${INTERFACE_NS}/enable-animations`,
+  `${MOUSE_NS}/double-click`,
+  `${MOUSE_NS}/drag-threshold`,
+]);
+
 /**
  * What is true with no settings daemon to ask.
  *
@@ -71,24 +102,15 @@ const sessions = new WeakMap();
  *  export a key with a string value or a nonsense one, and a caret with a
  *  blink period of `'fast'` would never come back on. */
 function positive(map, key) {
-  const value = map?.get(key);
+  return positiveValue(map?.get(key));
+}
+
+function positiveValue(value) {
   return typeof value === 'number' && Number.isFinite(value) && value > 0
     ? value
     : undefined;
 }
 
-/**
- * An XSETTINGS map → the settings. Pure, and exported for the test: the
- * in-process X server has no settings daemon, so this is the part of the
- * path worth pinning without one.
- *
- * **`Net/CursorBlinkTime` is a full cycle**, on and off together — that is
- * what GTK means by `gtk-cursor-blink-time` and what every daemon writes —
- * and `caretBlinkMs` is how long the caret stays in *each* state, because
- * that is the number that goes into a timer. Halving it is the whole
- * conversion, and forgetting to is a caret that blinks at half speed and
- * looks broken rather than wrong.
- */
 /**
  * macOS's accessibility display options → the settings. Only `animations`
  * comes from the system there: it is the one of these macOS publishes at all
@@ -105,6 +127,18 @@ export function fromMacOS(options) {
   });
 }
 
+/**
+ * An XSETTINGS map → the settings. Pure, and exported for the test: the
+ * in-process X server has no settings daemon, so this is the part of the
+ * path worth pinning without one.
+ *
+ * **`Net/CursorBlinkTime` is a full cycle**, on and off together — that is
+ * what GTK means by `gtk-cursor-blink-time` and what every daemon writes —
+ * and `caretBlinkMs` is how long the caret stays in *each* state, because
+ * that is the number that goes into a timer. Halving it is the whole
+ * conversion, and forgetting to is a caret that blinks at half speed and
+ * looks broken rather than wrong.
+ */
 export function fromXSettings(map) {
   if (!map) return DEFAULTS;
   const cycle = positive(map, 'Net/CursorBlinkTime');
@@ -134,6 +168,39 @@ export function fromXSettings(map) {
   });
 }
 
+/**
+ * The settings portal's GNOME namespaces → the settings. Pure, and exported
+ * for the test. `all` is a `ReadAll` reply, namespace → key → value.
+ *
+ * The same keys gsd-xsettings turns into the XSETTINGS ones above, so the
+ * same rules: `cursor-blink-time` is a full cycle and is halved, only an
+ * explicit `false` turns blinking or animation off, and a value of the wrong
+ * type is no answer. GNOME has no double-click *distance*; GTK's is a
+ * constant there, so the default stands.
+ *
+ * `null` when neither namespace came back — a portal that does not pass
+ * GSettings through has not answered, and the source stays null.
+ */
+export function fromGnomePortal(all) {
+  const iface = all?.[INTERFACE_NS];
+  const mouse = all?.[MOUSE_NS];
+  if (!iface && !mouse) return null;
+  const cycle = positiveValue(iface?.['cursor-blink-time']);
+  return Object.freeze({
+    ...DEFAULTS,
+    caretBlink: iface?.['cursor-blink'] !== false,
+    caretBlinkMs: cycle
+      ? Math.max(1, Math.round(cycle / 2))
+      : DEFAULTS.caretBlinkMs,
+    doubleClickMs:
+      positiveValue(mouse?.['double-click']) ?? DEFAULTS.doubleClickMs,
+    dragThreshold:
+      positiveValue(mouse?.['drag-threshold']) ?? DEFAULTS.dragThreshold,
+    animations: iface?.['enable-animations'] !== false,
+    source: 'portal',
+  });
+}
+
 /**
  * The settings for a connection, **synchronously**. Always a complete answer:
  * the defaults before the daemon has been read, and on a display with none.
@@ -148,7 +215,9 @@ export function desktopSettings(app) {
   if (!session.snapshot) {
     session.snapshot = session.macos
       ? fromMacOS(app.accessibilityDisplayOptions())
-      : fromXSettings(xsettings(app));
+      : session.wayland
+        ? (fromGnomePortal(session.portal) ?? DEFAULTS)
+        : fromXSettings(xsettings(app));
   }
   return session.snapshot;
 }
@@ -173,6 +242,20 @@ export function beginDesktopSettings(app) {
     });
     return;
   }
+  // The Wayland backend: no X server, so no XSETTINGS — the portal instead,
+  // behind the same switch as the appearance ladder that reads the portal
+  // too. `createRoot({ desktop: false })` keeps the defaults, which is what a
+  // test or an embedder that asked for determinism wants.
+  if (app?.backend === 'wayland') {
+    session.wayland = true;
+    if (desktopIntegrationEnabled('appearance')) {
+      portalSettings(app, session).catch(() => {
+        // no bus, no portal, a portal without the GNOME namespaces: the
+        // defaults stand, which is what they are for
+      });
+    }
+    return;
+  }
   beginXSettings(app).then(
     () => {
       if (!sessions.has(app)) return;
@@ -190,6 +273,92 @@ export function beginDesktopSettings(app) {
   );
 }
 
+/**
+ * Read the GNOME namespaces off the settings portal, and again whenever one
+ * of the keys this cares about changes.
+ *
+ * The order is `appearance.js`'s portal rung, for the same reasons: the
+ * match rule and the handler go in **before** the first read, so a change
+ * that lands while it is in flight is not lost; and reads are sequenced, so
+ * a slow reply never publishes over a newer one. The bus ref is released as
+ * soon as the first read settles — the subscription outlives it, and holding
+ * it would keep the process alive for as long as the app cared how fast its
+ * caret blinks.
+ */
+async function portalSettings(app, session) {
+  const ref = await sessionBus();
+  if (!ref) return;
+  const { bus } = ref;
+  let sub = null;
+  let handler = null;
+  const key = bus.mangle(PORTAL_PATH, SETTINGS_IFACE, 'SettingChanged');
+  const stop = () => {
+    if (handler) bus.signals.removeListener(key, handler);
+    handler = null;
+    sub?.remove().catch(() => {});
+    sub = null;
+  };
+  try {
+    sub = await bus.watch(
+      `type='signal',sender='${PORTAL_NAME}',` +
+        `interface='${SETTINGS_IFACE}',member='SettingChanged'`,
+    );
+
+    let started = 0;
+    let published = 0;
+    const refresh = async () => {
+      const mine = ++started;
+      const all = await bus.invoke(
+        {
+          destination: PORTAL_NAME,
+          path: PORTAL_PATH,
+          interface: SETTINGS_IFACE,
+          member: 'ReadAll',
+          signature: 'as',
+          body: [[INTERFACE_NS, MOUSE_NS]],
+        },
+        { timeout: 5_000 },
+      );
+      if (mine <= published || sessions.get(app) !== session) return;
+      published = mine;
+      const next = fromGnomePortal(all);
+      if (!next) return;
+      const before = desktopSettings(app);
+      session.portal = all;
+      session.snapshot = null;
+      // A re-read that changed nothing this reads notifies nobody: the hook
+      // re-renders on identity, and so would every subscriber.
+      if (!sameSettings(before, desktopSettings(app))) notify(session);
+      else session.snapshot = before;
+    };
+
+    handler = ([namespace, name]) => {
+      if (!WATCHED.has(`${namespace}/${name}`)) return;
+      refresh().catch(() => {
+        // the portal went away mid-session; the last answer stands
+      });
+    };
+    bus.signals.on(key, handler);
+
+    // Torn down while the bus was connecting: undo, and publish nothing.
+    if (sessions.get(app) !== session) return stop();
+    session.stop = stop;
+    await refresh();
+  } catch (err) {
+    stop();
+    throw err;
+  } finally {
+    await ref.release();
+  }
+}
+
+function sameSettings(a, b) {
+  for (const key of Object.keys(DEFAULTS)) {
+    if (a[key] !== b[key]) return false;
+  }
+  return true;
+}
+
 function notify(session) {
   for (const fn of [...session.listeners]) {
     try {

package/src/dnd.js

@@ -1,7 +1,7 @@
 // XDND drag and drop, the drop-target half: react-x11 windows accept drags
 // from other X11 applications (file managers, editors, browsers).
 //
-// Design: docs/architecture/drag-and-drop.md; protocol: XDND version 5.
+// Design: design/architecture/drag-and-drop.md; protocol: XDND version 5.
 // The advertisement (`XdndAware`) is a 4-byte property written
 // unconditionally on every top-level window at realize time — it creates no
 // X windows, so it is orthogonal to the windowed/windowless split.
@@ -1080,7 +1080,7 @@ export class DropSession {
 // ---------------------------------------------------------------------------
 // The drag source.
 //
-// One drag session, two transports (docs/architecture/drag-and-drop.md §6.3):
+// One drag session, two transports (design/architecture/drag-and-drop.md §6.3):
 // while the pointer is over this process's own windows the drag is local —
 // no wire, live JS payloads, the DropSession above delivering to the same
 // handlers with `e.source === 'internal'`. The moment it leaves them, the

package/src/filedialog.js

@@ -46,14 +46,14 @@ import {
   RESPONSE_CANCELLED,
   RESPONSE_OK,
   hasService,
-  parentWindowHandle,
   pathBytes,
+  portalParentFor,
   portalRequest,
   variant,
 } from './portal.js';
 import { sessionBus } from './bus.js';
 import { liveApps } from './trace-registry.js';
-import { windowIdOf, windowOf } from './windowid.js';
+import { windowOf } from './windowid.js';
 
 const FILE_CHOOSER = 'org.freedesktop.portal.FileChooser';
 
@@ -149,7 +149,7 @@ async function portalDialog(kind, opts, ref) {
   const { response, results } = await portalRequest(ref, {
     iface: FILE_CHOOSER,
     member,
-    parentWindow: parentWindowHandle(windowIdOf(opts.parentWindow)),
+    parentWindow: await portalParentFor(opts.parentWindow),
     title: opts.title ?? defaultTitle(kind),
     options: await portalOptions(opts, {
       save: kind === 'save',

package/src/glnodes.js

@@ -95,7 +95,7 @@ export function glxConfig(app, spec) {
           process.platform === 'win32'
             ? 'react-x11: <glarea> is not built on the win32 backend yet — it ' +
                 'needs ANGLE (EGL and GLES over Direct3D 11), which ' +
-                'docs/windows.md plans as an optional dependency the way ' +
+                'design/windows.md plans as an optional dependency the way ' +
                 'x11-dri is on X11. Everything else on this backend works ' +
                 'without it; for GL content today, use the X11 backend.'
             : 'react-x11: <glarea> needs ntk >= 3.6.0 (app.chooseGLConfig)',

package/src/grid.js

@@ -1,5 +1,5 @@
 // CSS grid, built in (docs/styling.md "Grid"; the design record is
-// docs/architecture/grid-layout.md). A box with `display: 'grid'` — or
+// design/architecture/grid-layout.md). A box with `display: 'grid'` — or
 // `layout: 'grid'`, the same request under the name every layout goes by —
 // arranges its children by CSS Grid's placement and track sizing algorithms
 // (css-grid-2 §8.5 and §12), inside the pass that lays the window out. It is

package/src/keyboardstate.js

@@ -32,6 +32,18 @@
 // it answers atoms that have to be interned back one round trip each, and
 // what it returns is a description like `English (US)` where an indicator in
 // a status bar wants `us`.
+//
+// ## A backend with no X server
+//
+// The native Wayland backend has no XKB extension to ask, but its seat holds
+// the same three answers: the locked modifiers and the group from
+// `wl_keyboard.modifiers`, and the layout codes from the name of the keymap
+// the compositor sent (src/wayland/xkb.js, `layoutsFromKeymap`). It hands
+// them over through a two-method seam — `keyboardState()` and
+// `watchKeyboardState(fn)` — and this module publishes what it says the way
+// it publishes a StateNotify. The one difference is the protocol's:
+// a compositor tells only the focused client, so the locks are as of the last
+// time this app had the keyboard.
 
 import { requireExtension } from './extensions.js';
 
@@ -71,6 +83,7 @@ class KeyboardSession {
     this.armed = false;
     this.stopped = false;
     this._handler = null;
+    this._unwatch = null;
   }
 
   publish(values) {
@@ -106,6 +119,8 @@ class KeyboardSession {
 
   stop() {
     this.stopped = true;
+    this._unwatch?.();
+    this._unwatch = null;
     if (this._handler && this.app?.X?.off) {
       try {
         this.app.X.off('event', this._handler);
@@ -157,6 +172,19 @@ async function arm(session) {
   if (session.armed) return;
   session.armed = true;
   const app = session.app;
+
+  // A backend that answers for itself (the Wayland seat): subscribe, then
+  // read, for the same reason the XKB path below does.
+  if (typeof app?.watchKeyboardState === 'function') {
+    const read = () => {
+      const state = !session.stopped && app.keyboardState?.();
+      if (state) session.publish(state);
+    };
+    session._unwatch = app.watchKeyboardState(read);
+    read();
+    return;
+  }
+
   const xkb = await requireExtension(app, 'xkb');
   if (!xkb || session.stopped) return;
 

package/src/layouts.js

@@ -1,5 +1,5 @@
 // Layout algorithms and positions from outside the renderer — the two seams
-// docs/architecture/custom-layout.md is the design record for.
+// design/architecture/custom-layout.md is the design record for.
 //
 // A **layout** arranges a box's children. It is asked how big the box is for
 // the room on offer, and then where each child goes in the room the box got.

package/src/node.d.ts

@@ -39,12 +39,13 @@ export interface ImageDataLike {
 }
 
 /**
- * The 2d context a node paints into — the canvas-shaped subset **both**
- * backends implement: ntk's `RenderingContext2D` over XRender on X11, and
- * `BackendContext2D` over CoreGraphics on macOS. Declared as the contract an
- * element may rely on rather than as either class: what is here is on
- * both, and a member one backend has and the other does not is optional
- * here or absent. Coordinates are device pixels in the owning window's
+ * The 2d context a node paints into — the canvas-shaped subset **every**
+ * backend implements: ntk's `RenderingContext2D` over XRender on X11, the
+ * Wayland backend's GLES rasterizer, and `BackendContext2D` over CoreGraphics
+ * on macOS and Direct2D on Windows. Declared as the contract an element may
+ * rely on rather than as any one class: what is here is on all of them, and
+ * a member some backends have and others do not is optional here or
+ * absent. Coordinates are device pixels in the owning window's
  * space — `abs`, `contentBox()` — unless a transform says otherwise.
  * Anything ntk documents beyond this is reachable at runtime and is
  * ntk's to change.
@@ -67,10 +68,9 @@ export interface Context2D {
   shadowOffsetY: number;
   shadowColor: string;
   /**
-   * X11 only: XRender's compositing operator — `'source-over'` (the
-   * default), `'copy'`, and the rest ntk documents. Absent on the cocoa
-   * backend, whose bridge has no blend-mode verb yet; test for it with
-   * `'globalCompositeOperation' in ctx`.
+   * The compositing operator — `'source-over'` (the default), `'copy'`,
+   * and the rest ntk documents on X11. A native context (macOS, Windows)
+   * takes only the modes its bridge draws: assign and read back to know.
    */
   globalCompositeOperation?: string;
   /**

package/src/nodes/animation.js

@@ -310,7 +310,7 @@ export class NodeAnimation {
   // loop-stop rule and `sameAnimation` all see it — but it contributes no
   // value to the style, is skipped by the tick, and keeps the node out of the
   // window's animating set. The X11 path has none of these hooks and is
-  // byte-identical (docs/architecture/animation.md §4).
+  // byte-identical (design/architecture/animation.md §4).
 
   _offload(prop, entry) {
     const wnd = this.root?.window;

package/src/nodes/invalidate.js

@@ -361,7 +361,7 @@ export class WindowInvalidate {
     }
     // A retained presenter keeps a per-node diff instead of damage rects,
     // and this is the one channel every change already announces itself on
-    // (docs/macos.md §"One renderer, two presenters"). Feature-detected: an
+    // (design/macos.md §"One renderer, two presenters"). Feature-detected: an
     // ntk window has no ear here and the X11 path is byte-identical. A
     // presenter that answers `true` has taken the claim onto a layer of its
     // own (src/cocoa/promotion.js): the bitmap owes nothing for it, and the

package/src/nodes/layouthost.js

@@ -2,7 +2,7 @@
 // in layouts.js arranges its children itself. Each child is a yoga root of
 // its own, and the host is a measured leaf in its parent — so what the
 // algorithm decides is on screen in the frame that asked.
-// docs/architecture/custom-layout.md is the design record.
+// design/architecture/custom-layout.md is the design record.
 
 import {
   createLayoutNode,

package/src/nodes/video.js

@@ -1,6 +1,6 @@
 // <video>: frames an application decodes (`frames`, a VideoFrames sink), or a
 // file or URL the platform plays (`src`, where there is a player), fitted
-// into the node's box (docs/architecture/video.md §6–7).
+// into the node's box (design/architecture/video.md §6–7).
 //
 // A drawn node like `<image>`: it joins yoga, it is in the paint order and it
 // is hit like anything else — which is the whole point. A video in a form
@@ -18,9 +18,10 @@
 // - **drawn** — everywhere else, and in every frame the presenter declines
 //   the part (something is painted over it, it fades, a rounded card does
 //   not hold it): the newest frame is copied into a surface of the node's
-//   own at paint, natively where the backend can (`app.writeVideoFrame`) and
-//   through `frameToRGBA` where it cannot, and composited at the picture's
-//   rect like an `<image>` whose pixels changed. A push claims the picture.
+//   own at paint, natively where the backend can (`writeVideoFrame`,
+//   src/videobackend.js) and through `frameToRGBA` where it cannot, and
+//   composited at the picture's rect like an `<image>` whose pixels
+//   changed. A push claims the picture.
 //
 // `src` needs a platform player, which this backend has when
 // `useSupports('mediaPlayback')` says so — the app's `createPlayer`, on macOS
@@ -41,6 +42,7 @@ import {
 } from '../imagesource.js';
 import { canPlayMedia, NoMediaPlaybackError } from '../mediaplayback.js';
 import { Surface } from '../offscreen.js';
+import { videoBackendOf } from '../videobackend.js';
 import { frameToRGBA, isVideoFrames } from '../videoframes.js';
 import { fitRect, objectFitOf } from './fit.js';
 import { intrinsicSize } from './layout.js';
@@ -592,10 +594,18 @@ export class VideoNode extends Node {
   }
 
   _upload(surface, sink, frame) {
-    // natively where the backend converts in its own code (the Cocoa
-    // bridge's writeVideoSurface: a copy for BGRA, VideoToolbox for YCbCr,
-    // colour-matched to what a layer shows)
-    if (this.app?.writeVideoFrame?.(surface, sink, frame)) return;
+    // natively where the backend converts in its own code: the Cocoa
+    // bridge's writeVideoSurface (a copy for BGRA, VideoToolbox for YCbCr,
+    // colour-matched to what a layer shows), the Wayland context's shader,
+    // an Xv port on X11 (src/videobackend.js)
+    if (
+      videoBackendOf(this.app)?.writeVideoFrame?.(surface, sink, frame, this)
+    ) {
+      // a frame converted in JavaScript earlier — the first, on X11, before
+      // the window was mapped — left a buffer the native path does not need
+      this._rgba = null;
+      return;
+    }
     const w = sink.width;
     const h = sink.height;
     if (this._rgba?.width !== w || this._rgba?.height !== h) {
@@ -632,6 +642,7 @@ export class VideoNode extends Node {
     this._surface = null;
     this._rgba = null;
     this._drawn = -1;
+    if (surface) videoBackendOf(this.app)?.releaseVideoFrame?.(surface);
     try {
       surface?.destroy();
     } catch {

package/src/nodes/window/droptarget.js

@@ -1,4 +1,4 @@
-// The window's half of XDND (docs/architecture/drag-and-drop.md): the drop
+// The window's half of XDND (design/architecture/drag-and-drop.md): the drop
 // targets registered under it and the types they accept.
 
 import {

package/src/pacing.js

@@ -49,7 +49,7 @@
 // Off by default: `'display'` is the built-in, and paints every frame the
 // clock gives, after React's own batching — a UI answers its input as
 // quickly as it can unless it says otherwise. `'adaptive'` is what a window
-// that streams asks for. docs/architecture/frame-pacing.md is the account.
+// that streams asks for. design/architecture/frame-pacing.md is the account.
 
 export const DEFAULT_FRAME_RATE = 'display';
 

package/src/portal.js

@@ -29,6 +29,7 @@
 // re-solve.
 
 import { loadTransport, sessionBus } from './bus.js';
+import { windowIdOf, windowOf } from './windowid.js';
 
 export const PORTAL_NAME = 'org.freedesktop.portal.Desktop';
 export const PORTAL_PATH = '/org/freedesktop/portal/desktop';
@@ -439,6 +440,36 @@ export function parentWindowHandle(xid) {
   return typeof xid === 'number' && xid > 0 ? `x11:${xid.toString(16)}` : '';
 }
 
+/**
+ * The `parent_window` handle for whatever names a window — a ref, a node, a
+ * backend window, an XID — on whichever backend it belongs to.
+ *
+ * - **X11**: `x11:<xid>`, as `parentWindowHandle` spells it.
+ * - **Wayland**: `wayland:<handle>`, from an xdg-foreign export of the
+ *   toplevel (src/wayland/app.js, `exportHandle`) — what the portal needs to
+ *   make the dialog modal to the window and stack it there. `''` where the
+ *   compositor has no xdg-foreign, or the window is a popup; never an `x11:`
+ *   handle, because a Wayland window's id names no X window, and on a desktop
+ *   running Xwayland it could name somebody else's.
+ *
+ * `app` is the fallback for a target that resolves to no window object — a
+ * bare number on Wayland is that app's id for one of its own windows.
+ *
+ * @param {any} target
+ * @param {any} [app]
+ * @returns {Promise<string>}
+ */
+export async function portalParentFor(target, app = null) {
+  let win = windowOf(target);
+  const owner = win?.app ?? app;
+  if (owner?.backend !== 'wayland') {
+    return parentWindowHandle(windowIdOf(target));
+  }
+  if (!win && typeof target === 'number') win = owner.windowById?.(target);
+  const handle = win ? await owner.exportHandle?.(win) : null;
+  return handle ? `wayland:${handle}` : '';
+}
+
 /**
  * `Variant`, from the one copy of the transport the bus layer loaded.
  *

package/src/refresh/index.js

@@ -1,6 +1,7 @@
 // react-x11/refresh — the runtime half of state-preserving hot reload
 // (Fast Refresh). The loader half is ./loader.js; `react-x11/refresh/register`
-// wires both up for `node --import`. See docs/ecosystem/dev-tooling.md.
+// wires both up for `node --import`. See docs/ecosystem/dev-tooling.md, and
+// design/ecosystem/dev-tooling.md §"How it reloads" for the loader's rules.
 //
 // Import order is what this module exists to own:
 //