react-x11 2.12.0 → 2.14.0

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));

package/src/types/elements.d.ts

@@ -915,6 +915,16 @@ export interface SvgProps extends DrawnProps<DrawnNode> {
 
 export type FrameLoop = 'demand' | 'always';
 
+/**
+ * `<glarea>`: a GL surface in the layout. Its **children** are 2D content
+ * drawn above the surface — laid out in its box like a `<box>`'s and cut to
+ * it, painted over the GL frame, hit before it — composited on the Cocoa
+ * backend and opaque on X11 (docs/elements.md); `useSupports('glOverlay')`
+ * asks whether they will be. The pointer over it is the tree's, as over any
+ * node: the handlers it inherits (`onMouseDown`, `onClick`, `onWheel`, …)
+ * fire at the child under the pointer or the `<glarea>` and bubble, on both
+ * backends, and `GlAreaNode.forwardsPointer` says so at run time.
+ */
 export interface GlAreaProps extends DrawnProps<DrawnNode> {
   /** CSS colour, or `[r, g, b, a]` floats. Default black. */
   clearColor?: Color | [number, number, number, number];
@@ -937,17 +947,6 @@ export interface GlAreaProps extends DrawnProps<DrawnNode> {
   onDraw?: (gl: any, info: DrawInfo) => void;
   /** No GL surface — no GLX, or no matching visual. */
   onError?: (err: Error) => void;
-  /**
-   * The wheel over the surface. Inherited from `EventHandlers` like every
-   * other element's, and listed here because it is the **only** pointer
-   * event a `<glarea>` currently reports: the surface owns its own X window,
-   * so it selects the wheel there and hands it to the window's event manager
-   * (see docs/elements.md). Deltas are pixels, `preventDefault()` takes the
-   * default scroll action back, and it bubbles from this node.
-   */
-  onWheel?: (ev: WheelEvent<DrawnNode>) => void;
-  /** A click inside the surface that hit no mesh. */
-  onPointerMissed?: (ev: MouseEvent<DrawnNode>) => void;
 }
 
 // --- embedding -------------------------------------------------------------
@@ -973,7 +972,9 @@ export interface ForeignProps extends DrawnProps<DrawnNode> {
    */
   windowId?: number;
   /** The container window's id, offered as soon as it exists, so a program
-   * can be spawned into it. Fires before there is anything embedded. */
+   * can be spawned into it. Fires before there is anything embedded — and
+   * never on a backend with no embedding (`useSupports('embedding')`), so the
+   * id is always a real window's. */
   onReady?: (info: { windowId: number; node: DrawnNode }) => void;
   /** A client is in. */
   onEmbedded?: (info: EmbeddedInfo) => void;
@@ -982,7 +983,8 @@ export interface ForeignProps extends DrawnProps<DrawnNode> {
   /** `XEMBED_REQUEST_FOCUS`: the client wants the focus. It is given through
    * the focus manager unless a handler prevents it by focusing elsewhere. */
   onRequestFocus?: (info: { node: DrawnNode }) => void;
-  /** The embed failed — no such window, or it went away mid-handshake.
+  /** The embed failed — no such window, or it went away mid-handshake — or
+   * this backend cannot embed at all, which is reported once, at mount.
    * Without a handler the failure is a console warning. */
   onError?: (err: Error) => void;
 }