react-x11 2.10.2 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.10.2",
+  "version": "2.11.0",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [
@@ -100,7 +100,7 @@
     "yoga-layout": "^3.2.1"
   },
   "optionalDependencies": {
-    "@windowkit/appkit": "^0.8.0",
+    "@windowkit/appkit": "^0.9.0",
     "dbus-native": "^0.15.1",
     "x11-dri": "^0.7.0"
   },

package/src/cocoa/app.js

@@ -30,6 +30,7 @@ import { CocoaNotifications } from './notifications.js';
 import { CocoaPaneHost } from './panehost.js';
 import { CocoaPermissions } from './permissions.js';
 import { CocoaPaneWindow } from './panewindow.js';
+import { CocoaColorSampler } from './screencolor.js';
 import { CocoaFilePanels } from './filepanels.js';
 import { CocoaFontManager } from './fonts.js';
 import { CocoaSurface } from './surface.js';
@@ -189,6 +190,17 @@ export class CocoaApp {
         ? new CocoaCalendars(this)
         : null;
 
+    // The system colour sampler, `NSColorSampler` (src/cocoa/screencolor.js).
+    // Present exactly when the bridge has it (>= 0.9), and its presence is
+    // the top rung of src/screencolor.js's ladder for this app — an older
+    // bridge leaves that ladder where it was, which on this backend is no
+    // rung at all: `useEyedropper().supported` stays false and a picker
+    // draws no dropper button.
+    this.colorSampler =
+      typeof native.sampleScreenColor === 'function'
+        ? new CocoaColorSampler(native)
+        : null;
+
     // The GL policy, glbackend.js's shape. No GLX exists here, so the
     // default is 'auto' (the direct backend where the runtime loads);
     // useSupports('shaders') stays false until the first <glarea> resolves

package/src/cocoa/screencolor.js

@@ -0,0 +1,62 @@
+// One colour off the screen on the cocoa backend — `NSColorSampler` through
+// @windowkit/appkit (>= 0.9), the top rung of src/screencolor.js's ladder on
+// this backend. `CocoaApp.colorSampler` is this object and its *presence* is
+// the capability, the rule `filePanels`, `permissions` and `calendars`
+// follow, so the ladder never names a backend.
+//
+// It is the portal's shape rather than X11's, which is why it goes on *top*
+// of the ladder and not under it: the system draws the loupe, out of
+// process, so this app needs no Screen Recording grant of its own and the
+// user gets the magnifier every other Mac colour picker shows them. There is
+// no grab here, no root window read, and nothing for the crosshair rung to
+// fall back to — the cocoa `X` is a stub (src/cocoa/app.js), which is why
+// this file existing is the difference between an eyedropper button on macOS
+// and none.
+//
+// Two things about the framework shape what is *not* here:
+//
+// - **Nothing dismisses the sampler from code.** AppKit offers no
+//   counterpart to `cancelPanel` — the session ends when the user picks or
+//   presses Escape — so there is no abort inside this wrapper the way
+//   `CocoaFilePanels.show` has one. A caller's `signal` can only stop *us*
+//   waiting; that is the rung's business, and it is spelled out there.
+// - **One session, not one per call.** `NSColorSampler` "begins or attaches
+//   to an existing color sampling session", so a second sample while a loupe
+//   is up joins it and both callers get the same colour. The bridge keeps
+//   that promise; nothing here needs the X11 rung's loud refusal, which
+//   exists because a second `GrabPointer` silently replaces the first.
+
+export class CocoaColorSampler {
+  constructor(native) {
+    this._native = native;
+  }
+
+  /**
+   * Show the system sampler and answer once.
+   *
+   * Resolves `{ r, g, b }` — sRGB, 0–1 floats, the Screenshot portal's
+   * `(ddd)` shape, which is what lets both rungs share one conversion — or
+   * **`null`** when the user dismissed the sampler without picking. A
+   * cancel is an ordinary outcome, not an error, on every rung of this
+   * ladder; a rejection here means a colour that could not be read at all
+   * (a pattern colour, which has no sRGB form).
+   *
+   * The answer arrives on the main thread, so the app has to be pumping —
+   * which a mounted react-x11 tree is by definition.
+   *
+   * @returns {Promise<{ r: number, g: number, b: number } | null>}
+   */
+  sample() {
+    return new Promise((resolve, reject) => {
+      try {
+        this._native.sampleScreenColor((err, color) =>
+          err ? reject(err) : resolve(color ?? null),
+        );
+      } catch (err) {
+        // A bad argument shape is a TypeError out of the bridge, before
+        // anything is shown. Rejecting keeps every failure on one channel.
+        reject(err);
+      }
+    });
+  }
+}

package/src/screencolor.js

@@ -1,24 +1,44 @@
 // Sample one pixel from the screen — the eyedropper, through whatever this
 // machine actually has.
 //
-// The file dialog's ladder again (docs/filedialog.md), two rungs this time:
+// The file dialog's ladder again (docs/filedialog.md), three rungs:
 //
-//   1. **the portal** — `org.freedesktop.portal.Screenshot.PickColor`. The
+//   1. **the system sampler** — `NSColorSampler` on the cocoa backend
+//      (src/cocoa/screencolor.js). macOS draws the loupe out of process, so
+//      the app needs no Screen Recording grant of its own and the user gets
+//      the magnifier every other Mac colour picker shows them. Found by the
+//      app carrying `colorSampler`, never by naming a backend here.
+//   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
 //      the Screenshot interface — XFCE ships none, GNOME and KDE ship 2 —
 //      so the gate is the interface's `version` property, not `hasService()`.
-//   2. **X11** — grab the pointer with a crosshair, wait for the click,
+//   3. **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.
 //
-// There is no third rung to draw, because the thing being read — the whole
+// 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.
+//
+// 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 the same
-// two.
+// component wants (`picking`, `supported`, the owner window) over these
+// three.
+//
+// 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
+// older than 0.9 is that place: its `app.X` is a stub with just enough on it
+// for the modules that keep an X escape hatch to no-op (src/cocoa/app.js),
+// so an app object is not by itself a connection that can grab a pointer and
+// read a root window. Rung 3 is gated on the requests it is built out of,
+// not on there being an app — the feature-detection rule `requireExtension()`
+// already follows, and the rule rung 1 follows too, one bridge verb instead
+// of three X requests.
 //
 // ## The grab is the dangerous part
 //
@@ -42,6 +62,7 @@ import {
   portalRequest,
   portalVersion,
 } from './portal.js';
+import { liveApps } from './trace-registry.js';
 import { windowIdOf } from './windowid.js';
 
 export const SCREENSHOT_IFACE = 'org.freedesktop.portal.Screenshot';
@@ -60,10 +81,11 @@ export class NoScreenColorError extends Error {
     super(
       `react-x11: ${
         message ??
-        'no way to sample a colour from the screen — there is 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 useEyedropper().'
+        '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 ' +
+          'useEyedropper().'
       }`,
       { cause },
     );
@@ -72,7 +94,91 @@ export class NoScreenColorError extends Error {
 }
 
 // --------------------------------------------------------------------------
-// Rung 1: the portal
+// Rung 1: the system sampler, on the cocoa backend
+// --------------------------------------------------------------------------
+
+/**
+ * The app whose system sampler a pick should use, or null.
+ *
+ * Never a backend check: an app that can sample the screen says so by
+ * carrying `colorSampler` (src/cocoa/screencolor.js), and this asks the app
+ * the caller named — `app`, or a `parentWindow` that points at a mounted
+ * node — before asking the connections the renderer is drawing through, the
+ * rule `filePanels` and `calendars` follow. Several of those with only one
+ * showing a window is the next case (a borrowed connection stays registered
+ * after its root unmounts); genuinely several is a real null, since the
+ * sampler belongs to one process's NSApplication.
+ */
+function samplerApp(opts) {
+  const named = appFor(opts);
+  if (named) return named.colorSampler ? named : null;
+  const apps = liveApps().filter((one) => one.colorSampler);
+  if (apps.length <= 1) return apps[0] ?? null;
+  const showing = apps.filter((one) => (one._rootChildren ?? []).length > 0);
+  return showing.length === 1 ? showing[0] : null;
+}
+
+/**
+ * Show `NSColorSampler` and wait for it.
+ *
+ * Resolves `'#rrggbb'` on a pick and `null` on a dismissal — the two
+ * outcomes every rung answers with — through the *portal's* conversion,
+ * because the bridge answers in the portal's units: sRGB in 0–1, gamut
+ * mapped from whatever space the display is in. Rejects on an abort, and on
+ * a colour with no sRGB form at all (a pattern colour), which is the
+ * bridge's one error.
+ *
+ * **An abort ends our wait, not the sampler.** AppKit has no verb to
+ * dismiss it — the session ends when the user picks or presses Escape — so
+ * where the portal rung Closes its request and the X11 rung releases its
+ * grab, this one can only stop listening: the loupe stays up, the colour
+ * that arrives afterwards is dropped, and until then the pending sample
+ * holds the event loop open the way pending I/O does. Nothing is left
+ * grabbed, which is what the abort exists to guarantee.
+ */
+function cocoaPick(opts, app) {
+  const signal = opts.signal;
+  if (signal?.aborted) {
+    return Promise.reject(signal.reason ?? new PortalCancelledError());
+  }
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(signal.reason ?? new PortalCancelledError());
+    signal?.addEventListener('abort', onAbort, { once: true });
+    // No `settle()` gate, unlike the X11 rung: that one exists because a
+    // grab must be released exactly once on every path out, and an aborted
+    // pick here holds nothing — the loupe is the user's, not ours. The
+    // colour that lands after an abort reaches an already-rejected promise
+    // and is dropped by the promise itself.
+    const done = () => signal?.removeEventListener('abort', onAbort);
+
+    app.colorSampler.sample().then(
+      (color) => {
+        done();
+        // A dismissal is an ordinary outcome, not a throw — Escape on the
+        // X11 rung, the dialog's own cancel on the portal, this here.
+        if (color == null) return resolve(null);
+        const hex = hexFromPortalColor([color.r, color.g, color.b]);
+        if (!hex) {
+          return reject(
+            new Error(
+              'react-x11: the system colour sampler answered without a ' +
+                'colour — expected sRGB { r, g, b } in 0–1, got ' +
+                `${JSON.stringify(color)}.`,
+            ),
+          );
+        }
+        resolve(hex);
+      },
+      (err) => {
+        done();
+        reject(err);
+      },
+    );
+  });
+}
+
+// --------------------------------------------------------------------------
+// Rung 2: the portal
 // --------------------------------------------------------------------------
 
 /**
@@ -131,7 +237,7 @@ async function portalCanPick(ref) {
 }
 
 // --------------------------------------------------------------------------
-// Rung 2: X11
+// Rung 3: X11
 // --------------------------------------------------------------------------
 
 // x11.eventMask bits, spelled out the way xsettings.js spells its one. No
@@ -539,28 +645,87 @@ function appOf(target) {
   return target.app ?? target.window?.app ?? target.root?.window?.app ?? null;
 }
 
-/** The connection a pick would use, or null. */
+/** The app a pick would use, or null. Not yet: a *connection*. */
 function appFor(opts) {
   return opts.app ?? appOf(opts.parentWindow);
 }
 
 /**
- * Which rung this machine lands on, without grabbing anything.
+ * Can this app run the X11 rung — is its `X` a connection at all?
  *
- * `'portal'` needs the 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); without either the
- * fallback is unreachable and the honest answer is `null`.
+ * The cocoa backend hands the renderer an app whose `X` is a stub
+ * (src/cocoa/app.js): `InternAtom` and `on` so the modules with an X escape
+ * hatch no-op cleanly, and nothing else. Reaching the rung through it used
+ * to throw `X.AllocID is not a function` out of the promise — a crash where
+ * the ladder's whole contract is a typed "not here", and one an app cannot
+ * hide a button on.
+ *
+ * So the gate is the three requests the rung is actually built out of, asked
+ * of the object rather than of `process.platform` or the backend's name:
+ * `requireExtension()`'s rule, and the one that keeps the next backend from
+ * landing here by default too.
+ */
+function canGrabOn(app) {
+  const X = app?.X;
+  return (
+    typeof X?.AllocID === 'function' &&
+    typeof X?.GrabPointer === 'function' &&
+    typeof X?.GetImage === 'function'
+  );
+}
+
+/**
+ * Why the X11 rung is out of reach, for the typed rejection — an app that
+ * cannot grab and no app at all are different mistakes with different
+ * fixes, and only one of them is the caller's.
+ */
+function noX11Reason(app, backend) {
+  if (app) {
+    return (
+      'this tree does not render through an X connection — a cocoa-backend ' +
+      'app, for instance, whose `X` cannot grab the pointer or read a root ' +
+      "window. macOS's own sampler is the rung above, and this app does not " +
+      'carry it: `@windowkit/appkit` is older than 0.9, which has no ' +
+      '`sampleScreenColor`. Until it is updated there is no rung here — ' +
+      '`useEyedropper().supported` is false, which is the signal to leave ' +
+      'the eyedropper button undrawn (docs/macos.md).'
+    );
+  }
+  if (backend === 'x11') {
+    return (
+      "backend: 'x11' needs a connection to grab on. Pass `app` (from " +
+      'createRoot() or useApp()), or a `parentWindow` that points at a ' +
+      'mounted window.'
+    );
+  }
+  return undefined;
+}
+
+/**
+ * Which rung this machine lands on, without showing or grabbing anything.
+ *
+ * `'cocoa'` is the app carrying `colorSampler` — a cocoa-backend tree on
+ * `@windowkit/appkit` >= 0.9 — and it is asked first, so a Mac never falls
+ * through to a rung that would draw a worse picker. `'portal'` needs the
+ * 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`.
  *
  * Acquires a bus reference and releases it, so it is cheap but not free —
  * `useEyedropper().supported` caches it for you.
  *
- * @returns {Promise<'portal'|'x11'|null>}
+ * @returns {Promise<'cocoa'|'portal'|'x11'|null>}
  */
 export async function screenColorBackend(options = {}) {
   const backend = options.backend;
+  if (!backend || backend === 'cocoa') {
+    if (samplerApp(options)) return 'cocoa';
+    if (backend === 'cocoa') return null;
+  }
   if (!backend || backend === 'portal') {
     const ref = await sessionBus();
     if (ref) {
@@ -572,10 +737,23 @@ export async function screenColorBackend(options = {}) {
     }
     if (backend === 'portal') return null;
   }
-  return appFor(options) ? 'x11' : null;
+  return canGrabOn(appFor(options)) ? 'x11' : null;
 }
 
 async function runPick(opts) {
+  const wantCocoa = !opts.backend || opts.backend === 'cocoa';
+  if (wantCocoa) {
+    const app = samplerApp(opts);
+    if (app) return await cocoaPick(opts, app);
+    if (opts.backend === 'cocoa') {
+      throw new NoScreenColorError(
+        "backend: 'cocoa' — no system colour sampler here: this tree does " +
+          'not render through the cocoa backend, or its `@windowkit/appkit` ' +
+          'is older than 0.9.',
+      );
+    }
+  }
+
   const wantPortal = !opts.backend || opts.backend === 'portal';
   if (wantPortal) {
     const ref = await sessionBus();
@@ -598,31 +776,27 @@ async function runPick(opts) {
   }
 
   const app = appFor(opts);
-  if (app) return x11Pick(opts, app);
-  throw new NoScreenColorError(
-    opts.backend === 'x11'
-      ? "backend: 'x11' needs a connection to grab on. Pass `app` (from " +
-          'createRoot() or useApp()), or a `parentWindow` that points at a ' +
-          'mounted window.'
-      : undefined,
-  );
+  if (canGrabOn(app)) return x11Pick(opts, app);
+  throw new NoScreenColorError(noX11Reason(app, opts.backend));
 }
 
 /**
- * Sample one pixel from the screen: the desktop's own picker where there is
- * one, a crosshair grab on plain X11 everywhere else.
+ * Sample one pixel from the screen: the system's own picker where there is
+ * one — `NSColorSampler` on macOS, the Screenshot portal on a desktop that
+ * has it — and a crosshair grab on plain X11 everywhere else.
  *
  * ```js
  * const hex = await pickScreenColor({ app });
  * if (hex) setFill(hex);            // '#rrggbb'; null means cancelled
  * ```
  *
- * Resolves to **`'#rrggbb'`**, or `null` when the user cancelled (Escape, or
- * the portal dialog's own cancel) — cancelling is an ordinary outcome and
- * should not need a `try`. Rejects with {@link NoScreenColorError} when
- * neither rung is reachable, which is the signal to hide the button;
- * `signal` aborts the pick and releases the grab before the rejection is
- * reported.
+ * Resolves to **`'#rrggbb'`**, or `null` when the user cancelled (Escape,
+ * the portal dialog's own cancel, dismissing the sampler) — cancelling is an
+ * ordinary outcome and should not need a `try`. Rejects with
+ * {@link NoScreenColorError} when no rung is reachable, which is the signal
+ * to hide the button; `signal` aborts the pick, releasing the X11 grab or
+ * closing the portal request before the rejection is reported (the system
+ * sampler cannot be dismissed from code — see docs/eyedropper.md).
  *
  * In a component, reach for {@link useEyedropper} instead — it binds the
  * connection and the owner window, and exposes `picking`/`supported` as

package/src/screencolorhooks.js

@@ -33,12 +33,16 @@ import { useTopLevelWindow } from './windowid.js';
  *
  * `pick()` resolves to `'#rrggbb'`, or `null` when the user cancelled. It
  * never rejects for lack of a backend on an X11 tree — the connection this
- * tree renders through *is* the fallback rung — so `supported` is about the
- * forced-backend and future-platform cases, not a check most apps must make.
+ * tree renders through *is* the fallback rung — nor on a cocoa tree whose
+ * bridge has the system sampler (`@windowkit/appkit` >= 0.9). Where neither
+ * is true the flag is the answer: `supported` is false, and a picker that
+ * gates its eyedropper button on it simply does not draw one.
  *
  * The portal dialog is parented to the window this component is in, the
  * `useFileDialog()` way: resolved at the moment the pick starts, with
  * `parentWindow` as the override for a tree with several top-level windows.
+ * On the cocoa rung that window is what names the app whose sampler runs;
+ * the system draws the loupe over the whole screen, owned by no window.
  *
  * While a pick is in flight, `picking` is true and another `pick()` returns
  * **the same promise** — a double-clicked button must not queue a second

package/src/types/nodes.d.ts

@@ -18,8 +18,17 @@ export interface DrawnNode {
    * was registered under. What queries and paint order match on:
    * `screen.all((n) => n.kind === 'gauge')`. */
   readonly kind: string;
-  /** Position and size within the owning window, valid after layout. */
+  /** Position and size within the owning window, valid after layout. In
+   * **device pixels**, like everything painted — a mouse event's `x`/`y`
+   * are logical, `scale` apart (docs/scale.md). `ev.nativeEvent.x`/`y` are
+   * the same point as `ev.x`/`y` already in this unit, which is what a
+   * pointer measured against a laid-out box wants. */
   readonly abs: Rect;
+  /** Device pixels per logical pixel for this node: the display's scale
+   * times any `scale` prop above it, resolved once and constant for the
+   * node's life. The number that converts between `abs` and the logical
+   * unit an app writes styles and reads events in. */
+  readonly scale: number;
   readonly parent: DrawnNode | null;
   readonly children: readonly DrawnNode[];
   /** Take the keyboard focus, if this node is focusable. Returns the node,
@@ -42,14 +51,18 @@ export interface DrawnNode {
   readonly direction: 'ltr' | 'rtl';
   /** Whether `node` is this node or a descendant of it (DOM `contains`). */
   contains(node: DrawnNode | null): boolean;
+  /** The boxes this node occupies, in **logical** pixels — already divided
+   * by `scale`, so they compare directly with an event's `x`/`y`. One rect
+   * for a box; one per line for wrapped text. */
   getClientRects(): Rect[];
 
   // --- text geometry (docs/elements.md, "Selection") ------------------------
   //
   // Every drawn node answers these; an element with no text answers `null`,
   // `0` and `[]`. Indices are **code points** and rectangles are in the
-  // owning window's coordinates — the same space as `abs` and a mouse
-  // event's `x`/`y`.
+  // owning window's coordinates — the same space as `abs`, which is device
+  // pixels: this seam speaks that unit deliberately, so a point taken from
+  // an event arrives through `ev.nativeEvent` or multiplied by `scale`.
 
   /** This element's text, or null when it has none. */
   textContent(): string | null;

package/src/types/screencolor.d.ts

@@ -6,22 +6,26 @@ import type { AbortSignalLike, WindowTarget } from './filedialog.js';
 import type { NtkApp } from './nodes.js';
 
 /** Which rung of the ladder answered — or would. */
-export type ScreenColorBackend = 'portal' | 'x11';
+export type ScreenColorBackend = 'cocoa' | 'portal' | 'x11';
 
 export interface PickScreenColorOptions {
   /**
    * The window the picker belongs to — `parent_window` for the portal, and
-   * (when it points at a mounted node) the connection the X11 rung grabs on.
-   * `useEyedropper()` infers it from the tree.
+   * (when it points at a mounted node) the app the cocoa rung samples
+   * through or the connection the X11 rung grabs on. `useEyedropper()`
+   * infers it from the tree.
    */
   parentWindow?: WindowTarget;
   /** Abort the pick. Closes the portal request, or releases the X11 grab —
-   * the grab is released **before** the rejection is reported. */
+   * the grab is released **before** the rejection is reported. On the cocoa
+   * rung it ends the wait only: `NSColorSampler` cannot be dismissed from
+   * code, so the loupe stays up until the user answers it. */
   signal?: AbortSignalLike;
   /** Force a rung, for kiosks and for tests. */
   backend?: ScreenColorBackend;
   /**
-   * The connection the X11 rung grabs and reads on. Required for that rung
+   * The app a pick runs through: the cocoa rung's `colorSampler`, or the
+   * connection the X11 rung grabs and reads on. Required for either rung
    * when `parentWindow` does not resolve to a mounted node — the hook passes
    * the tree's own.
    */
@@ -40,23 +44,25 @@ export declare class NoScreenColorError extends Error {
 }
 
 /**
- * Sample one pixel from the screen: the desktop's own picker
- * (`org.freedesktop.portal.Screenshot.PickColor`, Screenshot interface
- * version 2) where there is one, a crosshair pointer grab on plain X11
- * everywhere else.
+ * Sample one pixel from the screen: the system's own picker where there is
+ * one — `NSColorSampler` on the cocoa backend (`@windowkit/appkit` >= 0.9),
+ * `org.freedesktop.portal.Screenshot.PickColor` (Screenshot interface
+ * version 2) on a desktop that has it — and a crosshair pointer grab on
+ * plain X11 everywhere else.
  *
  * Resolves to `'#rrggbb'`, or `null` when the user cancelled — Escape on the
- * X11 rung, the dialog's own cancel on the portal. Rejects with
- * {@link NoScreenColorError} when neither rung is reachable.
+ * X11 rung, the dialog's own cancel on the portal, a dismissed sampler on
+ * cocoa. Rejects with {@link NoScreenColorError} when no rung is reachable.
  */
 export declare function pickScreenColor(
   options?: PickScreenColorOptions,
 ): Promise<string | null>;
 
 /**
- * Which rung this machine lands on, without grabbing anything. `'x11'` needs
- * a connection to answer with — pass `app`, or a `parentWindow` pointing at
- * a mounted node — and `null` means {@link pickScreenColor} would reject.
+ * Which rung this machine lands on, without showing or grabbing anything.
+ * `'cocoa'` and `'x11'` both need an app to answer through — pass `app`, or
+ * a `parentWindow` pointing at a mounted node — and `null` means
+ * {@link pickScreenColor} would reject.
  */
 export declare function screenColorBackend(
   options?: Pick<PickScreenColorOptions, 'app' | 'backend' | 'parentWindow'>,