react-x11 2.52.0 → 2.53.0

package/docs/eyedropper.md

@@ -24,47 +24,34 @@ function StrokePicker({ value, onChange }) {
 
 Cancelling — Escape, the desktop dialog's own cancel, a dismissed macOS
 sampler — resolves to `null`. It is an ordinary outcome, not an exception,
-on every rung, so the whole error path is one `if`. The same contract as the
-[file dialogs](filedialog.md), on purpose.
+on every rung, so the whole error path is one `if`, as with the
+[file dialogs](filedialog.md).
 
 ## The ladder
 
-|     |                        |                                                                                                                                                                                                                                                                                                                                                            |
-| --- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 1   | **the system sampler** | `NSColorSampler` on the [cocoa backend](macos.md), where the app the tree renders through carries `colorSampler` (`@windowkit/appkit` >= 0.9). 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.                                            |
-| 2   | **the portal**         | `org.freedesktop.portal.Screenshot.PickColor` over D-Bus. The desktop draws its own magnifier and hands the colour back. GNOME and KDE ship it; it is also GNOME's only route on Wayland.                                                                                                                                                                  |
-| 3   | **the Wayland picker** | On the [Wayland backend](wayland-backend.md), where the compositor offers screen capture and layer-shell but no portal (wlroots: sway, labwc, …): the output is frozen into a capture, shown as an overlay, and the click is taken on that (`src/wayland/screencopy.js`). Below the portal because the portal is the desktop's own, user-consented picker. |
-| 4   | **X11**                | The classic route: grab the pointer with a crosshair, wait for the click, read the 1×1 under it, decode by the server's own pixel layout. Works under a bare WM, over ssh, on XQuartz — everywhere there is a display and nothing else.                                                                                                                    |
+|     |                        |                                                                                                                                                                                                                              |
+| --- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **the system sampler** | `NSColorSampler` on the [cocoa backend](macos.md) (`@windowkit/appkit` >= 0.9). macOS draws the loupe out of process, so the app needs no Screen Recording grant and the user gets the usual Mac magnifier.                  |
+| 2   | **the portal**         | `org.freedesktop.portal.Screenshot.PickColor` over D-Bus. The desktop draws its own magnifier and hands the colour back. GNOME and KDE ship it; it is also GNOME's only route on Wayland.                                    |
+| 3   | **the Wayland picker** | On the [Wayland backend](wayland-backend.md) where the compositor offers screen capture and layer-shell but no portal (wlroots: sway, labwc, …): the output is frozen into a capture overlay and the click is taken on that. |
+| 4   | **X11**                | Grab the pointer with a crosshair, wait for the click, read the pixel under it. Works under a bare WM, over ssh, on XQuartz — everywhere there is a display and nothing else.                                                |
 
 `screenColorBackend()` reports which rung this machine lands on without
 grabbing anything; `useEyedropper().supported` is the same answer as render
 state.
 
-The first three rungs 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 and not under the crosshair: where the OS will do this for us,
-it does it better.
-
-There is no rung to _draw_, and that is the difference from the file dialog's
-ladder: the thing being read — the whole screen — is precisely what an
-application cannot draw itself. So the hook adds binding, not a fallback of
-its own — and the ladder can therefore run out. Where it does, the floor is
-the typed rejection and `supported: false`, never a crash. A cocoa app on a
-bridge **older than 0.9** is that place: its `app.X` is a stub, so there is
-no pointer to grab and no root window to read either ([macos.md](macos.md)).
-Both system rungs are gated on what they are built out of — one bridge verb,
-three X requests — rather than on there being an app, so a picker there draws
-no eyedropper button instead of one that throws on its first press.
+There is no rung that react-x11 draws itself — the screen is exactly what an
+app cannot draw — so the ladder can run out. Where it does, `supported` is
+`false` and a pick rejects with a typed error, never a crash. A cocoa app on a
+bridge **older than 0.9** is that place ([macos.md](macos.md)): hide the
+button there.
 
 ### The version gate
 
-`PickColor` arrived in **version 2** of the Screenshot interface, and the
-portal being on the bus says nothing about that: `hasService()` sees the
-service, not what its backends provide. XFCE's portal, for example, ships no
-Screenshot interface at all — a machine where every FileChooser call works
-and every PickColor would fail. So the probe reads the interface's own
-`version` property, via `portalVersion()` (exported, since the next portal
-feature will need the same question answered):
+`PickColor` arrived in **version 2** of the Screenshot interface, and a portal
+on the bus may not have it (XFCE's ships no Screenshot interface at all). The
+probe reads the interface's own `version` with `portalVersion()`, which is
+exported:
 
 ```js
 import { portalVersion } from 'react-x11';
@@ -73,8 +60,7 @@ const v = await portalVersion('org.freedesktop.portal.Screenshot');
 // 0 — not there at all; 1 — there, but before PickColor; 2+ — usable
 ```
 
-Where the answer is below 2, the ladder falls through to the X11 rung
-rather than calling a method the portal would refuse.
+Below 2, the ladder falls through to the X11 rung.
 
 ## `useEyedropper()`
 
@@ -94,21 +80,17 @@ picking: boolean;   // a pick is in flight — the button's pressed state
 
 Options given to the hook are defaults for every pick; options given to a
 call win. The portal's dialog is parented to the window the component is in,
-resolved when the pick starts — the `useFileDialog()` inference, with
+resolved when the pick starts — the
+[`useFileDialog()` inference](filedialog.md#the-dialog-parents-itself), with
 `parentWindow` as the override for a tree with several top-level windows.
 
-Two things the hook does beyond forwarding:
-
-- **`picking` is the pressed state**, and it is honest: while it is true, a
-  second `pick()` returns the promise already in flight rather than starting
-  a second grab — so a double-clicked button cannot make the user click
-  twice.
-- **`supported` is almost always true on this toolkit.** An X11 tree has a
-  connection by definition, and the connection _is_ the fallback rung; a
-  cocoa tree has the system sampler. It goes false when a forced
-  `backend: 'portal'` finds no portal, and on a cocoa app whose bridge
-  predates the sampler — which is what keeps the button honest on whatever
-  platform comes next.
+- **`picking` is the pressed state.** While it is true, a second `pick()`
+  returns the promise already in flight rather than starting a second grab,
+  so a double-clicked button cannot make the user click twice.
+- **`supported` is almost always true.** An X11 tree's connection _is_ the
+  fallback rung, and a cocoa tree has the system sampler. It goes false when a
+  forced `backend: 'portal'` finds no portal, and on a cocoa app whose bridge
+  predates the sampler.
 
 ## The bare function
 
@@ -118,82 +100,55 @@ import { pickScreenColor, screenColorBackend } from 'react-x11';
 const hex = await pickScreenColor({ app });
 ```
 
-Same options, same results. The one addition is `app`: the X11 rung needs a
-connection to grab and read on and the cocoa rung needs the app whose
-sampler to show, and a bare function has no tree to take one from — pass the
-app `createRoot()` returned (or `useApp()` in a component, or a
-`parentWindow` that points at a mounted node, which carries its app with
-it). With no app named, the connections the renderer is currently drawing
-through are asked, the way `openFile()` finds its native panel. Where no
-rung answers it rejects with `NoScreenColorError` — a **typed** rejection,
-so it reads as "hide the button", not as a crash.
+Same options, same results. The one addition is `app`, because a bare function
+has no tree to take a connection from: pass the app `createRoot()` returned
+(or `useApp()` in a component, or a `parentWindow` that points at a mounted
+node). With no app named, the connections the renderer is currently drawing
+through are asked. Where no rung answers it rejects with `NoScreenColorError`
+— a **typed** rejection, so it reads as "hide the button", not as a crash.
 
 One pick per connection at a time **on the X11 rung**: a second concurrent
-`pickScreenColor()` on the same app is refused loudly, because a second grab
-from the same client would silently _replace_ the first and one pick would
-settle with the other's click. The hook's shared in-flight promise is the
-friendly version of the same rule. The system sampler needs no such refusal:
-`NSColorSampler` "begins or attaches to an existing color sampling session",
-so a second pick joins the loupe that is up and both callers get the same
-colour.
+`pickScreenColor()` on the same app is refused loudly (two grabs from one
+client would steal each other's click). The hook's shared in-flight promise is
+the friendly version of the same rule. On the system sampler a second pick
+joins the loupe that is up, and both callers get the same colour.
 
 ## What differs between the rungs
 
-- **The system rungs draw a magnifier; the X11 rung deliberately does not.**
-  On X11 it is grab, crosshair, click — and Escape cancels. The desktops
-  whose users expect a loupe have a portal or an `NSColorSampler` that draws
-  one; a hand-rolled loupe on the bottom rung would be a screenshot of the
-  screen re-rendered at 8×, permanently slightly wrong about scaling and
-  colour management.
-- **Only the system rungs need no permission.** Both the portal and
-  `NSColorSampler` run the picker in another process and hand back a
-  colour, so nothing here asks for a screen-capture grant — on macOS that
-  is the difference between a dropper button and a TCC prompt for Screen
-  Recording.
+- **The system rungs draw a magnifier; the X11 rung does not.** On X11 it is
+  grab, crosshair, click — and Escape cancels.
+- **Only the system rungs need no permission.** The portal and
+  `NSColorSampler` run the picker in another process, so nothing asks for a
+  screen-capture grant (on macOS, no TCC prompt for Screen Recording).
 - **On the X11 rung the keyboard also picks.** Return, KP Enter or space
-  samples the pixel under the pointer without a click — GTK's shape — and
-  the keyboard is grabbed for the duration so Escape works wherever the
-  focus happens to be.
+  samples the pixel under the pointer without a click, and the keyboard is
+  grabbed for the duration so Escape works wherever the focus is.
 - **What is sampled is what is on the screen.** The X11 rung reads the
   rendered pixel, so a colour under a translucent overlay is the blend, not
-  the window's own value. What exactly the portal samples is the desktop's
-  choice, not this API's — GNOME's and KDE's pickers read the composited
-  screen too.
-- **`signal` means less on the cocoa rung.** AppKit offers no way to dismiss
-  a sampler from code — the session ends when the user picks or presses
-  Escape — so an abort there ends the wait and nothing else: the loupe stays
-  up, and the colour it eventually reports is dropped. Until then that
-  pending sample holds the process's event loop open, the way pending I/O
-  does. The portal's request is Closed and the X11 grab is released, which
-  is what an abort has to guarantee where something _is_ held.
-- **Every rung answers `'#rrggbb'`.** The portal and the sampler hand back
-  sRGB floats and X11 hands back server-layout words; every consumer wants a
-  CSS colour it can paint with, so the conversion happens once, here — the
-  same function for the two float rungs. If something later needs the
-  unrounded values, an option can widen the return — starting with channels
-  would have made the common case do arithmetic.
+  the window's own value. The portal's pickers (GNOME's, KDE's) read the
+  composited screen too.
+- **`signal` means less on the cocoa rung.** AppKit cannot dismiss a sampler
+  from code, so an abort there ends the wait and nothing else: the loupe stays
+  up until the user picks or presses Escape, its colour is dropped, and until
+  then the pending sample holds the process's event loop open. On the portal
+  and X11 rungs an abort closes the request or releases the grab.
+- **Every rung answers `'#rrggbb'`**, converted from the portal's and
+  sampler's sRGB floats or X11's server-layout pixel.
 
 ## The grab, and what it displaces
 
-The X11 rung holds a **server pointer grab** while it waits. That is the
-dangerous part of the feature — an application that leaks a grab leaves a
-desktop that has stopped answering clicks — and it is why the grab's whole
-lifecycle belongs to core rather than to apps:
+The X11 rung holds a **server pointer grab** while it waits, and core owns its
+whole lifecycle:
 
 - Every way out — click, Escape, abort, error — releases the grab before the
-  promise settles. The `signal` option releases it too; that is guaranteed
-  here, not delegated to the caller.
-- A `<popup grab>` that was open when the pick started — an open `Select`,
-  a menu, the colour panel the eyedropper button itself sits in — had its
-  grab silently replaced by the pick's (same client, so X raises no error
-  and tells no one). When the pick ends, core hands that popup its grab
-  back, so dismiss-on-outside-click still works afterwards.
-- A grab released out from under a pick — this client's own popup teardown
-  calls `UngrabPointer`, which releases whatever the client's active grab is
-  — is detected (the server announces it with a `LeaveNotify` of mode
-  `Ungrab` on the grab window) and taken back, rather than leaving a pick
-  that never resolves while the app answers clicks as if nothing were
-  happening.
+  promise settles.
+- A `<popup grab>` that was open when the pick started (an open `Select`, a
+  menu, the colour panel the button sits in) gets its grab back when the pick
+  ends, so dismiss-on-outside-click still works afterwards.
+- If this client's own popup teardown releases the grab mid-pick, the pick
+  takes it back rather than hanging.
+
+Design notes: [design/eyedropper.md](../design/eyedropper.md).
 
 ## Running it anywhere
 
@@ -207,17 +162,3 @@ lifecycle belongs to core rather than to apps:
 | Node 20, where npm skips `dbus-native`               | X11                                                                                          |
 | the Wayland backend, a portal with Screenshot ≥ 2    | portal                                                                                       |
 | the Wayland backend on wlroots (sway, labwc, …)      | wayland — the backend's own picker; there is no root window to read, so no X11 rung under it |
-
-## Building a colour picker on it
-
-The eyedropper is the one part of a colour picker that cannot be composed
-out of public elements, which is why it lives in core and the picker panel
-does not. A `<ColorPicker>` in `@react-x11/components` consumes it as a
-function prop:
-
-```jsx
-<ColorPicker eyedropper={pickScreenColor} value={fill} onChange={setFill} />
-```
-
-and once that component exists, this function is its default and no app
-changes.

package/docs/filedialog.md

@@ -28,27 +28,19 @@ every backend — so the whole error path for a file dialog is one `if`.
 
 ## The ladder
 
-There is no single answer to "show a file dialog" across the machines this
-runs on, so this is a ladder and the rung is chosen for you:
+The rung is chosen for you, top to bottom:
 
-|     |                         |                                                                                                                                                                                                                                                                                                                                                                             |
-| --- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 1   | **the native panel**    | `NSOpenPanel` / `NSSavePanel` in this process, on the [cocoa backend](macos.md) (`@windowkit/appkit` ≥ 0.5). A **sheet** on the window that asked, with every filter the OS type database knows. On the [win32 backend](windows.md) Windows' own open/save dialog, owned by the window that asked, takes the same rung (`fileDialogBackend()` reports it as `'cocoa'` too). |
-| 2   | **the portal**          | `org.freedesktop.portal.FileChooser` over D-Bus. The desktop's own dialog, drawn by GTK or KDE in another process, with the user's bookmarks and recent files.                                                                                                                                                                                                              |
-| 3   | **`osascript`**         | macOS on the X11 backend with no portal — which is every XQuartz install that has not gone out of its way. `choose file` _is_ `NSOpenPanel`, in a third process.                                                                                                                                                                                                            |
-| 4   | **the built-in dialog** | A browser react-x11 draws itself. ssh, a bare `startx`, a container: everywhere there is a display and nothing else.                                                                                                                                                                                                                                                        |
+|     |                         |                                                                                                                                                                                                                                                                                                                                                            |
+| --- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | **the native panel**    | `NSOpenPanel` / `NSSavePanel` on the [cocoa backend](macos.md) (`@windowkit/appkit` ≥ 0.5): a **sheet** on the window that asked, with every filter the OS type database knows. On the [win32 backend](windows.md), Windows' own open/save dialog, owned by the window that asked, takes the same rung (`fileDialogBackend()` reports `'cocoa'` for both). |
+| 2   | **the portal**          | `org.freedesktop.portal.FileChooser` over D-Bus: the desktop's own GTK or KDE dialog, with the user's bookmarks and recent files.                                                                                                                                                                                                                          |
+| 3   | **`osascript`**         | macOS on the X11 backend with no portal (every ordinary XQuartz install). `choose file` _is_ `NSOpenPanel`, in a third process.                                                                                                                                                                                                                            |
+| 4   | **the built-in dialog** | A browser react-x11 draws itself. ssh, a bare `startx`, a container: everywhere there is a display and nothing else.                                                                                                                                                                                                                                       |
 
-The top rung is never chosen by naming a backend: the dialog asks the window
-it belongs to which connection it is on, and an app that can show native
-panels says so. That is what keeps the ladder one ladder as backends join it.
-
-`fileDialogBackend()` reports which one this machine lands on, without showing
-anything — useful for a diagnostics panel, and for a menu that wants to say so.
-
-**The ladder is the design, not a fallback chain bolted on.** react-x11's
-flagship case is an app running on one machine and drawing to another, and a
-file dialog that only worked on a full GNOME session would be useless to
-exactly the person the renderer exists for.
+The top rung is chosen by the window the dialog belongs to, never by naming a
+backend. `fileDialogBackend()` reports which rung this machine lands on,
+without showing anything — for a diagnostics panel, or a menu that wants to
+say so.
 
 ## `useFileDialog()`
 
@@ -60,8 +52,8 @@ saveFile(options?): Promise<string | null>;      // one path, may not exist yet
 selectFolder(options?): Promise<string[] | null>;
 ```
 
-The hook is the surface to reach for, because it is the only one with a tree to
-draw in — so it never runs out of rungs and never rejects for lack of a dialog.
+The hook is the surface to reach for: it has a tree to draw the built-in dialog
+in, so it never runs out of rungs and never rejects for lack of a dialog.
 
 | option                        |                                                   |
 | ----------------------------- | ------------------------------------------------- |
@@ -80,39 +72,29 @@ win.
 
 ### The dialog parents itself
 
-The dialog is `transientFor` the window the component is in — `parent_window`
-for the portal — which is what makes the window manager treat it as belonging
-to your window: stacked above it, and not a second entry in the task switcher.
-
-**You do not pass anything for that.** `useFileDialog()` resolves the owner
-window through `useTopLevelWindow()` at the moment a dialog opens, by which
-time the window is mounted and has an XID.
-
-On the [native Wayland backend](wayland-backend.md) the window has no XID,
-and the portal is handed an **xdg-foreign** export of it instead —
-`wayland:<handle>`, which GNOME and KDE both parent to. Where the compositor
-has no xdg-foreign the handle is empty and the dialog opens unparented.
-
-Why inference rather than a lookup: a hook has no position in the host tree.
-React context cannot come from a host element, the host context
-`getChildHostContext` builds reaches `createInstance` and not components, and a
-`<window>` has no XID until the commit phase. So it answers from what the
-renderer does know — the top-level windows this connection is rendering:
-
-- **one top-level window is exact.** The component is in it, because there is
-  nowhere else to be. That is nearly every app.
-- several, one focused: that one. You clicked in it a moment ago, which is why
-  a dialog is opening.
-- several with nothing to separate them: the most recently opened, plus a
-  development warning naming `parentWindow` as the way to be exact.
-- **none at all: the root-level `<popup>` that took the keyboard.** A menu-bar
-  app is a tray item and the popover a click on it opens, and nothing else
-  ([elements.md](elements.md#a-popover-under-a-tray-item)) — so the popup is
-  the top of that tree, and answering nothing left every hook that reads this
-  one with no owner to belong to.
-
-So `parentWindow` survives as the **override for multi-window apps**, and takes
-a `<window>` ref, an XID, or anything `windowIdOf()` accepts:
+The dialog is `transientFor` the window the component is in (`parent_window`
+for the portal), so the window manager stacks it above your window and keeps
+it out of the task switcher. **You do not pass anything for that**:
+`useFileDialog()` resolves the owner window through `useTopLevelWindow()` when
+the dialog opens.
+
+On the [native Wayland backend](wayland-backend.md) the portal is handed an
+**xdg-foreign** export of the window (`wayland:<handle>`), which GNOME and KDE
+both parent to. Where the compositor has no xdg-foreign the dialog opens
+unparented.
+
+The owner is inferred from the top-level windows this connection is rendering:
+
+- **one top-level window** — that one; nearly every app.
+- several, one focused — the focused one.
+- several with nothing to separate them — the most recently opened, plus a
+  development warning naming `parentWindow`.
+- **none at all** — the root-level `<popup>` that took the keyboard (a
+  menu-bar app's popover,
+  [elements.md](elements.md#a-popover-under-a-tray-item)).
+
+`parentWindow` is the **override for multi-window apps**, and takes a
+`<window>` ref, an XID, or anything `windowIdOf()` accepts:
 
 ```jsx
 const win = useRef(null);
@@ -126,8 +108,9 @@ first render, so a value read then would be `null` on the render that matters
 which drops into `parentWindow`, `transientFor`, or `windowIdOf()`.
 
 **The portal never embeds the dialog.** It is a top-level window in another
-process, and logical parenting is all there is. There is no version of this
-where the file list appears inside your window.
+process; the file list never appears inside your window.
+
+Design notes: [design/filedialog.md](../design/filedialog.md).
 
 ## The imperative functions
 
@@ -145,41 +128,30 @@ to hang off. In a component, use the hook.
 
 ## What differs between the rungs
 
-Most of the API is the same everywhere. These are the places it genuinely is
-not, stated here rather than discovered:
-
 - **MIME-type filters do not reach `osascript`.** `extensions` translate
   exactly to every rung; `mimeTypes` reach the portal and the native panel
-  (the cocoa backend asks the OS's own type database, so `image/png` is
-  `public.png` there) and are dropped by `osascript`, because AppleScript's
-  `of type` wants extensions or UTIs and guessing a UTI wrong hides the user's
-  file with no way to get at it. Give `extensions` where you can.
+  (the cocoa backend maps `image/png` to `public.png` through the OS type
+  database) and are dropped by `osascript`, where a wrong UTI guess would hide
+  the user's file. Give `extensions` where you can.
 - **`osascript` ignores `parentWindow`; the native panel is a sheet on it.**
-  XQuartz windows are `NSWindow`s owned by X11.app, macOS has no cross-process
-  transient-for, and `osascript` is a third process besides: its panel
-  appears over the app but is not attached to it, and application modality
-  works only because your code is awaiting the promise. On the cocoa backend
-  the panel is a **sheet** on that window, and the app keeps running while it
-  is up. With no window at all — a bare `openFile()` with nothing in
+  The `osascript` panel appears over the app but is not attached to it;
+  application modality holds only because your code is awaiting the promise.
+  On the cocoa backend the panel is a **sheet**, and the app keeps running
+  while it is up. With no window at all — a bare `openFile()` with nothing in
   `parentWindow` and no tree to infer one from — the native panel is
   app-modal and **blocks the process**, timers included, until it is
   dismissed. `useFileDialog()` always names the window, so it never lands
   there.
 - **The built-in dialog has never seen the user's bookmarks.** It offers the
-  filesystem, a filter, hidden files, and a path you can type into. It is
-  deliberately not a re-creation of GTK's chooser.
+  filesystem, a filter, hidden files, and a path you can type into — not a
+  re-creation of GTK's chooser.
 - **`multiple` in the built-in dialog is a tick column**, not ctrl-click.
 
 In the built-in dialog a double click opens a directory or picks a file, Enter
-does the same to the selected row, `Up` goes to the parent, and Escape cancels
-— and a selected directory is drawn in the selection's own text colour rather
-than the accent it wears at rest, since the selected row is filled with that
-accent in both schemes.
+does the same to the selected row, `Up` goes to the parent, and Escape cancels.
 
 ## Running it where there is no bus
 
-The interesting configurations, and what each one does:
-
 | where                                                  | rung                                                                                                              |
 | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
 | macOS, the **cocoa backend**                           | the native panel                                                                                                  |
@@ -190,17 +162,13 @@ The interesting configurations, and what each one does:
 | Node 20, where npm skips `dbus-native`                 | built-in on Linux, `osascript` on a Mac                                                                           |
 
 The `osascript` rung is reached by _not_ finding a portal, so it also covers a
-Mac that has a session bus for other reasons. If you do run a portal shim on a
-Mac (see [issue #111](https://github.com/sidorares/react-x11/issues/111)), it
-wins on the X11 backend, which is what you asked for by running it; on the
-cocoa backend the native panel is above it either way.
+Mac that has a session bus for other reasons. A portal shim on a Mac wins on
+the X11 backend; on the cocoa backend the native panel is above it either way.
 
 ## The portal machinery, if you need it directly
 
-`portalRequest()` is exported for building other portals on. Every portal
-method that shows UI returns an object path immediately and answers later with
-a `Request.Response` signal — and the path is predictable **by design**, so the
-client subscribes _before_ it calls and cannot lose the answer:
+`portalRequest()` is exported for building other portals on. It calls a portal
+method that shows UI and resolves with its `Request.Response`:
 
 ```js
 const { response, results } = await portalRequest(busRef, {
@@ -212,16 +180,15 @@ const { response, results } = await portalRequest(busRef, {
 });
 ```
 
-It owns the three things every portal caller otherwise re-solves: subscribing
-first, `Request.Close()` on abort (which emits **no** `Response`, so the
-promise has to be settled locally), and no timeout on the answer — a dialog can
-legitimately be open for an hour, and only the initial call is deadlined.
+It subscribes to the response before calling, so the answer cannot be lost;
+an abort sends `Request.Close()` and settles the promise locally (the portal
+emits no `Response` for it); and only the initial call has a deadline — the
+answer has none, because a dialog can legitimately be open for an hour.
 
-The default argument shape is FileChooser's, `(s parent_window, s title, a{sv}
-options)` — and that shape is FileChooser's alone. Every other Request-shaped
-portal has its own leading arguments, so a caller states them, as `signature`
-and `args` together; the [eyedropper](eyedropper.md)'s `PickColor`, which has
-no title, is the worked example:
+The default argument shape, `(s parent_window, s title, a{sv} options)`, is
+FileChooser's alone. Any other Request-shaped portal states its leading
+arguments as `signature` and `args` together; the
+[eyedropper](eyedropper.md)'s `PickColor`, which has no title:
 
 ```js
 await portalRequest(busRef, {
@@ -232,21 +199,18 @@ await portalRequest(busRef, {
 });
 ```
 
-The signature must end in `a{sv}` — the options dict is where `handle_token`
-rides, so a method without one does not answer through a `Request` and wants a
-plain `bus.invoke` instead.
+The signature must end in `a{sv}` (the options dict carries `handle_token`); a
+method without one does not answer through a `Request` and wants a plain
+`bus.invoke` instead.
 
 `hasService(name)` answers whether a service is reachable — owned now **or
-activatable on demand**. `NameHasOwner` alone is the wrong question:
-`org.freedesktop.portal.Desktop` is D-Bus-activatable, so on a healthy desktop
-where no app has touched a portal yet it has no owner, and a feature gated on
-that takes the fallback path forever.
-
-`portalVersion(iface)` answers the question `hasService()` cannot: whether the
-portal's backends provide one _interface_, and at what version — `0` when it
-is not there at all. Capability lives in the interface's own `version`
-property, and gating on the service alone breaks exactly on the desktops that
-provide some portals and not others (XFCE has FileChooser and no Screenshot).
+activatable on demand**. (`NameHasOwner` alone is the wrong question: the
+portal is D-Bus-activatable and often has no owner until first use.)
+
+`portalVersion(iface)` answers whether the portal's backends provide one
+_interface_, and at what version — `0` when it is not there at all. Gate on
+this rather than on the service: desktops provide some portals and not others
+(XFCE has FileChooser and no Screenshot).
 
 See [dbus.md](dbus.md) for the connection these sit on.