react-x11 2.13.0 → 2.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [
@@ -20,6 +20,8 @@
     "examples:appearance": "tsx examples/appearance.jsx",
     "examples:animation": "tsx examples/animation.jsx",
     "examples:simple": "tsx examples/simple.jsx",
+    "examples:wayland-gl": "node examples/wayland-gl.mjs",
+    "examples:wayland-ui": "node examples/wayland-ui.mjs",
     "examples:simple-nojsx": "node examples/simple-nojsx.js",
     "examples:xeyes": "tsx examples/xeyes.jsx",
     "examples:dashboard": "tsx examples/dashboard.jsx",
@@ -100,20 +102,21 @@
     "ical.js": "^2.2.1",
     "linebreak": "^1.1.0",
     "ntk": "^8.7.0",
-    "react-reconciler": "^0.33.0",
+    "react-reconciler": "^0.34.0",
     "yoga-layout": "^3.2.1"
   },
   "optionalDependencies": {
     "@windowkit/appkit": "^0.10.0",
+    "@windowkit/wayland": "^3.1.1",
     "dbus-native": "^0.15.1",
-    "x11-dri": "^0.8.0"
+    "x11-dri": "^0.9.0"
   },
   "peerDependencies": {
     "@babel/core": "^8.0.0",
     "@babel/plugin-transform-react-jsx": "^8.0.0",
     "hot-module-replacement": "^4.0.1",
-    "react": "^19.0.0",
-    "react-refresh": "^0.18.0"
+    "react": "^19.3.0",
+    "react-refresh": "^0.19.0"
   },
   "peerDependenciesMeta": {
     "@babel/core": {
@@ -146,9 +149,9 @@
     "hot-module-replacement": "^4.0.1",
     "katex": "^0.18.1",
     "prettier": "^3.6.0",
-    "react": "^19.2.8",
-    "react-devtools-core": "^7.0.1",
-    "react-refresh": "^0.18.0",
+    "react": "^19.3.0",
+    "react-devtools-core": "^8.0.0",
+    "react-refresh": "^0.19.0",
     "tsx": "^4.23.1",
     "typescript": "^7.0.2",
     "ws": "^8.21.1"

package/src/Reconciler.js

@@ -453,6 +453,10 @@ const HostConfig = {
   },
   startSuspendingCommit() {},
   suspendInstance() {},
+  // react-reconciler 0.34 calls this on every commit whose lanes are all
+  // transition, retry or idle lanes, whether or not the tree has a
+  // <ViewTransition>. There is no view transition here to wait on.
+  suspendOnActiveViewTransition() {},
   waitForCommitToBeReady() {
     return null;
   },
@@ -574,11 +578,11 @@ const isNtkApp = (v) =>
  */
 function resolveBackend(options) {
   const asked = options.backend ?? process.env.REACT_X11_BACKEND ?? 'auto';
-  if (asked === 'x11' || asked === 'cocoa') return asked;
+  if (asked === 'x11' || asked === 'cocoa' || asked === 'wayland') return asked;
   if (asked !== 'auto') {
     throw new Error(
       `react-x11: unknown backend ${JSON.stringify(asked)} — expected ` +
-        "'x11', 'cocoa' or 'auto'.",
+        "'x11', 'cocoa', 'wayland' or 'auto'.",
     );
   }
   // Naming an X endpoint is choosing X11: a `display` or a `stream` (the
@@ -715,25 +719,34 @@ export async function createRoot(options = {}) {
     rest.backend === 'cocoa' || process.env.REACT_X11_BACKEND === 'cocoa';
   const connecting = !owned
     ? Promise.resolve(borrowed)
-    : backend === 'cocoa'
-      ? import('./cocoa/app.js')
-          .then(({ createCocoaApp }) => createCocoaApp(rest))
-          .catch((err) => {
-            // Asked for by name, the bridge is required and its absence is
-            // the error (it says how to install). Reached by 'auto', a mac
-            // without it falls back to X11 so an XQuartz setup keeps
-            // working — said once, because a silent fallback would look
-            // like the native backend being broken rather than absent.
-            if (cocoaAsked) throw err;
-            if (process.env.NODE_ENV !== 'production') {
-              console.warn(
-                'react-x11: no @windowkit/appkit bridge — falling back to the ' +
-                  `X11 backend. (${err.message.split('\n')[0]})`,
-              );
-            }
-            return connectX11();
-          })
-      : connectX11();
+    : backend === 'wayland'
+      ? // Opt-in only, never through 'auto': X11 stays the default on Linux
+        // because the remote case (docs/remote.md) is the flagship reason
+        // this project exists and Wayland has no network transparency. The
+        // backend is opt-in; docs/wayland-backend.md says what it does
+        // and does not do.
+        import('./wayland/app.js').then(({ createWaylandApp }) =>
+          createWaylandApp(rest),
+        )
+      : backend === 'cocoa'
+        ? import('./cocoa/app.js')
+            .then(({ createCocoaApp }) => createCocoaApp(rest))
+            .catch((err) => {
+              // Asked for by name, the bridge is required and its absence is
+              // the error (it says how to install). Reached by 'auto', a mac
+              // without it falls back to X11 so an XQuartz setup keeps
+              // working — said once, because a silent fallback would look
+              // like the native backend being broken rather than absent.
+              if (cocoaAsked) throw err;
+              if (process.env.NODE_ENV !== 'production') {
+                console.warn(
+                  'react-x11: no @windowkit/appkit bridge — falling back to the ' +
+                    `X11 backend. (${err.message.split('\n')[0]})`,
+                );
+              }
+              return connectX11();
+            })
+        : connectX11();
   const layout = loadLayout();
   const integrations = loadIntegrations(); // null when there is nothing to install
   const [app] = await Promise.all([connecting, layout, integrations]);

package/src/components/Select.js

@@ -354,11 +354,17 @@ export function Select({
     );
     const chosenRowTop = MENU_BORDER + metrics.pad + chosen * metrics.row;
     const top = triggerCapsBottom - chosenRowTop - rowCapsBottom;
+    // `top` is where the menu starts against the trigger's own top, so it
+    // goes in as an `offset` back past the trigger's bottom — not as an `at`.
+    // Tracking asks whether `at` is still in view, and a menu opened over a
+    // trigger near the window's top edge starts above that edge: the popup
+    // is a real window and may, but the rect asked about was then "scrolled
+    // out", and the menu closed on the next unrelated layout pass (#552).
+    // What has to stay visible is the trigger.
     return {
       placement: 'bottom',
-      offset: 0,
+      offset: top - triggerHeight,
       flip: false,
-      at: { x: 0, y: top, width: node ? node.abs.width / scale : 0, height: 0 },
       alignOffset: -metrics.hang.left,
       height,
       width,

package/src/events.js

@@ -1345,8 +1345,14 @@ export class EventManager {
    * then the element's own `defaultComposition` unless one of them called
    * `preventDefault()`. Same seam, same order as `defaultKeyDown`.
    */
-  _composition(phase, target, data, native) {
-    const ev = this.dispatch('Composition' + phase, target, native, { data });
+  _composition(phase, target, data, native, extra) {
+    // `extra` is what an input method knows beyond the text — the cursor
+    // inside its preedit (`cursorBegin`/`cursorEnd`, src/wayland/textinput.js);
+    // the client-side composer has none, and the event is the same shape
+    const ev = this.dispatch('Composition' + phase, target, native, {
+      data,
+      ...extra,
+    });
     if (!ev.defaultPrevented) target.defaultComposition?.(ev);
     return ev;
   }

package/src/index.d.ts

@@ -300,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/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/scale.js

@@ -166,6 +166,18 @@ const VIRTUAL_EDID_VENDORS = new Set([
 ]);
 const VIRTUAL_MODEL = /qemu|virtual|vbox|vmware|parallels|bochs|bhyve/i;
 
+/**
+ * Whether an EDID's vendor and model name software — or a compositor's
+ * `wl_output` make and model, which are the same two strings read off the
+ * same EDID (mutter says 'RHT' / 'QEMU Monitor' for a QEMU guest's screen).
+ */
+export function isVirtualDisplay(vendor, model) {
+  return (
+    (vendor != null && VIRTUAL_EDID_VENDORS.has(vendor)) ||
+    (model != null && VIRTUAL_MODEL.test(model))
+  );
+}
+
 /**
  * The 128-byte EDID base block → what the scale ladder wants from it:
  * vendor, model name, the physical size, and the one derived judgement —
@@ -202,9 +214,7 @@ export function parseEdid(buffer) {
       break;
     }
   }
-  const virtual =
-    (vendor !== null && VIRTUAL_EDID_VENDORS.has(vendor)) ||
-    (model !== null && VIRTUAL_MODEL.test(model));
+  const virtual = isVirtualDisplay(vendor, model);
   return { vendor, model, mmWidth, mmHeight, virtual };
 }
 
@@ -352,13 +362,17 @@ export function monitorScaleFromMetadata(monitor, { perPanel = true } = {}) {
   }
 
   // No physical truth to reason from. The pixel grid alone still separates
-  // "unmistakably a retina panel" from everything else: the smallest grids
-  // this matches are 2880x1800 and 3024x1964, both shipped only as 2x
-  // panels, and every VM window covering one lands here too. 2560-wide
-  // grids stay at 1 on purpose — 2560x1440 is the commonest *1x* desk
-  // monitor there is, and only millimetres could tell it from a 13" retina
-  // lid, which is exactly the data this branch does not have.
-  if (perPanel && (Math.min(pxW, pxH) >= 1800 || Math.max(pxW, pxH) >= 3000)) {
+  // "unmistakably a retina panel" from everything else. 2560x1600, a 30"
+  // desk monitor, is the tallest grid a 1x panel ships with, and nothing is
+  // sold as 1x with a short side between that and 1800 — so a short side
+  // past 1600 is a 2x grid: the 2560x1664 and 2880x1800 laptop lids, and a
+  // VM *window* over a retina panel, which is all a guest sees of its host
+  // (2488x1668 is a UTM window on a 14" MacBook). A long side of 3000 or
+  // more catches the wide ones. 2560x1440 and 2560x1600 stay at 1 on
+  // purpose — the commonest *1x* desk monitors there are, and only
+  // millimetres could tell them from a 13" retina lid, which is exactly the
+  // data this branch does not have.
+  if (perPanel && (Math.min(pxW, pxH) > 1600 || Math.max(pxW, pxH) >= 3000)) {
     return {
       scale: 2,
       source: 'resolution',
@@ -379,6 +393,26 @@ export function monitorScaleFromMetadata(monitor, { perPanel = true } = {}) {
 // The desktop-configuration rungs
 // --------------------------------------------------------------------------
 
+/**
+ * The factor a person or the app pinned, or null for `'auto'`:
+ * `REACT_X11_SCALE` (0.5–8) first, then a numeric `createRoot({ scale })`
+ * clamped to [0.5, 8]. The ladder's first word, and the only one a backend
+ * with a scale of its own (a Wayland compositor's) lets outrank that scale.
+ */
+export function pinnedScale(option) {
+  const own = Number(process.env.REACT_X11_SCALE);
+  if (Number.isFinite(own) && own >= 0.5 && own <= 8) {
+    return { scale: own, source: 'REACT_X11_SCALE' };
+  }
+  if (typeof option === 'number' && Number.isFinite(option)) {
+    return { scale: Math.min(8, Math.max(0.5, option)), source: 'option' };
+  }
+  return null;
+}
+
+/** `REACT_X11_DEBUG_SCALE`'s line, for the backends that decide their own. */
+export const traceScale = trace;
+
 function envScale() {
   const own = Number(process.env.REACT_X11_SCALE);
   // wider bounds than `snapScale` on purpose: an explicit override is a
@@ -609,18 +643,14 @@ export async function beginScale(app, option) {
   session = new ScaleSession();
   sessions.set(app, session);
 
-  const own = Number(process.env.REACT_X11_SCALE);
-  if (Number.isFinite(own) && own >= 0.5 && own <= 8) {
-    session.scale = own;
-    session.source = 'REACT_X11_SCALE';
-    trace(`${session.scale}x from REACT_X11_SCALE`);
-    return session;
-  }
-
-  if (typeof option === 'number' && Number.isFinite(option)) {
-    session.scale = Math.min(8, Math.max(0.5, option));
-    session.source = 'option';
-    trace(`${session.scale}x from createRoot({ scale })`);
+  const pinned = pinnedScale(option);
+  if (pinned) {
+    session.scale = pinned.scale;
+    session.source = pinned.source;
+    trace(
+      `${pinned.scale}x from ` +
+        (pinned.source === 'option' ? 'createRoot({ scale })' : pinned.source),
+    );
     return session;
   }
 

package/src/screencolor.js

@@ -1,7 +1,7 @@
 // Sample one pixel from the screen — the eyedropper, through whatever this
 // machine actually has.
 //
-// The file dialog's ladder again (docs/filedialog.md), three rungs:
+// The file dialog's ladder again (docs/filedialog.md), four rungs:
 //
 //   1. **the system sampler** — `NSColorSampler` on the cocoa backend
 //      (src/cocoa/screencolor.js). macOS draws the loupe out of process, so
@@ -11,24 +11,31 @@
 //   2. **the portal** — `org.freedesktop.portal.Screenshot.PickColor`. The
 //      desktop draws its own magnifier and hands back the colour, which is
 //      also the only route that works under a compositor that would refuse a
-//      root read, and the only route Wayland has at all. Needs version 2 of
+//      root read, and GNOME's only route on Wayland. Needs version 2 of
 //      the Screenshot interface — XFCE ships none, GNOME and KDE ship 2 —
 //      so the gate is the interface's `version` property, not `hasService()`.
-//   3. **X11** — grab the pointer with a crosshair, wait for the click,
+//   3. **the Wayland backend's own picker** — where the compositor offers a
+//      screen capture protocol and layer-shell (wlroots: sway, labwc, …)
+//      but no portal, the backend freezes the output into a capture, shows
+//      it as an overlay and takes the click on that
+//      (src/wayland/screencopy.js). Below the portal because the portal is
+//      the desktop's picker and user-consented; guarded by the backend's
+//      name because the capability is a Wayland object through and through.
+//   4. **X11** — grab the pointer with a crosshair, wait for the click,
 //      `GetImage` a 1×1 at it, decode by the server's own pixel layout.
 //      Reached under a bare WM, over ssh, on XQuartz: everywhere there is a
 //      display and nothing else, which is the case react-x11 exists for.
 //
-// Rungs 1 and 2 are the same shape — ask the system, it draws the picker,
-// it hands back an sRGB triple — which is why the sampler goes on top of the
-// portal rather than under the crosshair: where the OS will do this for us,
-// it does it better, and `hexFromPortalColor()` converts for both.
+// Rungs 1 to 3 are the same shape — ask, a picker is drawn, an sRGB triple
+// comes back — which is why the sampler goes on top of the portal rather
+// than under the crosshair: where the OS will do this for us, it does it
+// better, and `hexFromPortalColor()` converts for all three.
 //
 // There is no rung to *draw*, because the thing being read — the whole
 // screen — is precisely what an application cannot draw itself. So unlike
 // `useFileDialog()`, `useEyedropper()` adds no rung; it adds the binding a
 // component wants (`picking`, `supported`, the owner window) over these
-// three.
+// four.
 //
 // Which means the ladder really can run out, and where it does the floor has
 // to be the typed rejection rather than a crash. A cocoa app on a bridge
@@ -83,8 +90,9 @@ export class NoScreenColorError extends Error {
         message ??
         'no way to sample a colour from the screen — no cocoa app with a ' +
           'system sampler, no Screenshot portal with PickColor (interface ' +
-          'version 2) on the session bus, and no X connection was given for ' +
-          'the fallback. Pass `app` (from createRoot() or useApp()), or use ' +
+          'version 2) on the session bus, no Wayland compositor with screen ' +
+          'capture and layer-shell, and no X connection was given for the ' +
+          'fallback. Pass `app` (from createRoot() or useApp()), or use ' +
           'useEyedropper().'
       }`,
       { cause },
@@ -212,7 +220,14 @@ async function portalPick(opts, ref) {
     // options)` — no title — which is the whole reason portalRequest takes a
     // signature now.
     signature: 'sa{sv}',
-    args: [parentWindowHandle(windowIdOf(opts.parentWindow))],
+    // The handle names an X window. A Wayland toplevel has none to name —
+    // an xdg-foreign export would be the equivalent — so there the dialog
+    // floats, which the portal allows.
+    args: [
+      appFor(opts)?.backend === 'wayland'
+        ? ''
+        : parentWindowHandle(windowIdOf(opts.parentWindow)),
+    ],
     options: {},
     signal: opts.signal,
   });
@@ -237,7 +252,49 @@ async function portalCanPick(ref) {
 }
 
 // --------------------------------------------------------------------------
-// Rung 3: X11
+// Rung 3: the Wayland backend's own picker
+// --------------------------------------------------------------------------
+
+/**
+ * The Wayland app whose compositor can freeze and show the screen, or null.
+ *
+ * Guarded by the backend's name, unlike the sampler: `screenCapture` is the
+ * capability, but it is a Wayland object through and through — the pick is
+ * a layer-shell overlay over a screencopy frame (src/wayland/screencopy.js)
+ * — and `canPick` is the compositor's answer, not the app's. GNOME's is no:
+ * it advertises neither protocol, and the portal above is its route.
+ */
+function waylandApp(opts) {
+  const app = appFor(opts);
+  return app?.backend === 'wayland' && app.screenCapture?.canPick ? app : null;
+}
+
+/**
+ * Freeze, show, click — the sampler's contract: `'#rrggbb'`, null on Escape,
+ * a rejection on abort. Unlike the sampler the overlay is ours, and it is
+ * down before the promise settles either way, so an abort leaves nothing on
+ * screen.
+ */
+function waylandPick(opts, app) {
+  const signal = opts.signal;
+  if (signal?.aborted) {
+    return Promise.reject(signal.reason ?? new PortalCancelledError());
+  }
+  return app.screenCapture.pickColor({ signal }).then((color) => {
+    if (color == null) return null;
+    const hex = hexFromPortalColor([color.r, color.g, color.b]);
+    if (!hex) {
+      throw new Error(
+        'react-x11: the Wayland screen pick answered without a colour — ' +
+          `expected sRGB { r, g, b } in 0–1, got ${JSON.stringify(color)}.`,
+      );
+    }
+    return hex;
+  });
+}
+
+// --------------------------------------------------------------------------
+// Rung 4: X11
 // --------------------------------------------------------------------------
 
 // x11.eventMask bits, spelled out the way xsettings.js spells its one. No
@@ -680,6 +737,16 @@ function canGrabOn(app) {
  * fixes, and only one of them is the caller's.
  */
 function noX11Reason(app, backend) {
+  if (app?.backend === 'wayland') {
+    return (
+      'this tree renders through the Wayland backend, and its compositor ' +
+      'offers neither a Screenshot portal with PickColor nor a screen ' +
+      'capture protocol (wlr-screencopy, ext-image-copy-capture) together ' +
+      'with wlr-layer-shell to draw the picker on. ' +
+      '`useEyedropper().supported` is false, which is the signal to leave ' +
+      'the eyedropper button undrawn (docs/wayland-backend.md).'
+    );
+  }
   if (app) {
     return (
       'this tree does not render through an X connection — a cocoa-backend ' +
@@ -710,15 +777,17 @@ function noX11Reason(app, backend) {
  * Screenshot interface at version 2 — the probe reads the interface's
  * `version` property, because `hasService()` cannot see which interfaces a
  * portal's backends actually provide (XFCE's provides no Screenshot at
- * all). `'x11'` needs a connection to answer with, so pass `app` (or a
- * `parentWindow` that resolves to one) — and one that can actually grab,
- * which a cocoa-backend app cannot. With none of the three the honest
- * answer is `null`.
+ * all). `'wayland'` is a Wayland-backend app (`app`, or a `parentWindow`
+ * in one) whose compositor advertises a screen capture protocol and
+ * layer-shell — wlroots without a portal. `'x11'` needs a connection to
+ * answer with, so pass `app` (or a `parentWindow` that resolves to one) —
+ * and one that can actually grab, which a cocoa-backend app cannot. With
+ * none of the four the honest answer is `null`.
  *
  * Acquires a bus reference and releases it, so it is cheap but not free —
  * `useEyedropper().supported` caches it for you.
  *
- * @returns {Promise<'cocoa'|'portal'|'x11'|null>}
+ * @returns {Promise<'cocoa'|'portal'|'wayland'|'x11'|null>}
  */
 export async function screenColorBackend(options = {}) {
   const backend = options.backend;
@@ -737,6 +806,10 @@ export async function screenColorBackend(options = {}) {
     }
     if (backend === 'portal') return null;
   }
+  if (!backend || backend === 'wayland') {
+    if (waylandApp(options)) return 'wayland';
+    if (backend === 'wayland') return null;
+  }
   return canGrabOn(appFor(options)) ? 'x11' : null;
 }
 
@@ -775,6 +848,20 @@ async function runPick(opts) {
     }
   }
 
+  const wantWayland = !opts.backend || opts.backend === 'wayland';
+  if (wantWayland) {
+    const app = waylandApp(opts);
+    if (app) return await waylandPick(opts, app);
+    if (opts.backend === 'wayland') {
+      throw new NoScreenColorError(
+        "backend: 'wayland' — no screen pick here: this tree does not " +
+          'render through the Wayland backend, or its compositor offers ' +
+          'neither a screen capture protocol (wlr-screencopy, ' +
+          'ext-image-copy-capture) nor wlr-layer-shell.',
+      );
+    }
+  }
+
   const app = appFor(opts);
   if (canGrabOn(app)) return x11Pick(opts, app);
   throw new NoScreenColorError(noX11Reason(app, opts.backend));