react-x11 2.52.0 → 2.53.0

package/docs/appearance.md

@@ -46,61 +46,36 @@ const { accent } = useSystemAppearance();
 <box style={{ borderColor: accent ?? '#2980b9' }} />;
 ```
 
-`accentText` is the ink the desktop puts on that fill, and it comes from the
-one source that has an opinion: AppKit writes white on every accent a Mac
-offers, including the orange and the pink a contrast ratio would put dark
-letters on, and every native control does. The portal names a fill and nothing
-about what goes on it, so there it is null and the palette picks the legible
-ink by contrast, as it does for any theme that names a fill and stops there.
-
-`selection` is the third colour a desktop names, and macOS is again the one
-that does: a selected menu row or list row is filled not with the accent but
-with `selectedContentBackgroundColor`, a darker cut of it — same hue,
-lightness 0.54 → 0.40 in dark and 0.45 in light for the orange, hand-tuned per
-accent rather than computed from it. The built-in palette uses it as
-`hoverBackground`; a menu lit in the raw accent beside a native one reads as
-too bright.
+`accentText` is the ink the desktop puts on that fill. Only macOS names one —
+white, on every accent it offers, as its native controls draw it. Elsewhere
+it is null, and the palette picks the legible ink by contrast, as it does for
+any theme that names a fill and stops there.
+
+`selection` is the fill under a selected menu or list row, which macOS draws
+not in the accent but in a darker cut of it (`selectedContentBackgroundColor`).
+The built-in palette uses it as `hoverBackground`; a menu lit in the raw
+accent beside a native one reads as too bright.
 
 ## The desktop's palette
 
-On macOS the rung reads the rest as well: the semantic colours AppKit paints
-its own windows and controls with, in the appearance the desktop is in. They
-arrive as `palette`, already in react-x11's vocabulary, and the built-in
-palette merges them over the scheme's own the way a `<ThemeProvider>` value
-merges — so an app that says nothing about colour comes up in the desktop's
-greys, inks and status colours, and follows every retune macOS ships.
-
-Two settings drive it, and they are not one colour. **Accent colour** is an
-index into a table of eight, each entry hand-tuned per appearance: the fill,
-the darker cut under a selected row, the focus ring and the pressed steps are
-all separate table entries, not a formula. **Highlight colour** is a free
-sRGB triple that only text selection and the caret read. Everything else is
-fixed per appearance.
-
-| token                          | AppKit source                                              | how                                                     |
-| ------------------------------ | ---------------------------------------------------------- | ------------------------------------------------------- |
-| `background`                   | `windowBackgroundColor`                                    | as is: `#ececec` light, `#323232` dark                  |
-| `surface`                      | `controlBackgroundColor`                                   | as is: white, `#1e1e1e`                                 |
-| `surfaceHover`                 | the second `alternatingContentBackgroundColors`            | composited over `surface`                               |
-| `text`, `textMuted`            | `labelColor`, `secondaryLabelColor`                        | black or white at 85% and 50–55%, over the ground       |
-| `border`                       | `separatorColor`                                           | 10% ink over the ground                                 |
-| `focusRing`, `borderFocus`     | `keyboardFocusIndicatorColor`                              | the 50% ring over the ground                            |
-| `track`                        | `unemphasizedSelectedContentBackgroundColor`               | as is                                                   |
-| `accent`, `accentText`         | `controlAccentColor`, `alternateSelectedControlTextColor`  | as is; the ink is white for all eight                   |
-| `accentHover`, `accentActive`  | the accent with the pressed and deep-pressed effects       | as is — darker in light, lighter in dark                |
-| `hoverBackground`, `hoverText` | `selectedContentBackgroundColor`, the same ink             | as is                                                   |
-| `selection`                    | `selectedTextBackgroundColor`                              | the Highlight colour; dark is each channel less 116/255 |
-| `caret`                        | `textInsertionPointColor`                                  | the accent of the Highlight colour's name               |
-| `link`                         | `linkColor`                                                | as is, never the accent                                 |
-| `danger`, `dangerHover`        | `systemRedColor`, pressed                                  | as is                                                   |
-| `success`, `warning`, `info`   | `systemGreenColor`, `systemOrangeColor`, `systemBlueColor` | orange for warning: yellow fails as letters             |
-
-AppKit's inks are translucent and every token here is a colour, so each is
-flattened over the window ground on the way in. The status inks and the
-pressed steps a table does not name come from `resolveTheme`, as for any
-theme. What this cannot see is desktop tinting: a dark window on macOS is
-`#323232` with a little of the wallpaper in it, and the wallpaper is not in
-any colour AppKit will hand out.
+On macOS the rung also reads the semantic colours AppKit paints its own
+windows and controls with, in the appearance the desktop is in. They arrive
+as `palette`, already in react-x11's vocabulary, and the built-in palette
+merges them over the scheme's own the way a `<ThemeProvider>` value merges —
+so an app that says nothing about colour comes up in the desktop's greys,
+inks and status colours, and follows every retune macOS ships.
+
+The tokens it sets: `background`, `surface`, `surfaceHover`, `text`,
+`textMuted`, `border`, `focusRing`, `borderFocus`, `track`, `accent`,
+`accentText`, `accentHover`, `accentActive`, `hoverBackground`, `hoverText`,
+`selection`, `caret`, `link`, `danger`, `dangerHover`, `success`, `warning`
+and `info`. The accent family follows the user's **Accent colour**;
+`selection` and `caret` follow the **Highlight colour**, a separate setting;
+`link` is never the accent, and `warning` is orange, since yellow fails as
+letters. Every token is an opaque colour, flattened over the window ground,
+and the status inks and pressed steps it does not name come from
+`resolveTheme`, as for any theme. Desktop tinting — the little of the wallpaper in a dark window — is
+not in any colour AppKit hands out, so it is not reproduced.
 
 The portal names none of this, so on Linux the built-in palette stands and
 only the accent is taken.
@@ -113,11 +88,10 @@ visible flash.
 
 So **the answer from last time is on disk**, in
 `$XDG_CACHE_HOME/react-x11/appearance.json`, and it is read synchronously
-before the first render — 0.1 ms, no D-Bus, no await. None of these values
-changes more than a few times in a machine's life, so the remembered answer is
-almost always the right one; the ladder revalidates it in the background and
-replaces it if it moved. Stale-while-revalidate, where the stale value is
-nearly always the fresh one.
+before the first render — 0.1 ms, no await. These values change a few times
+in a machine's life, so the remembered answer is almost always the right
+one; the ladder revalidates it in the background and replaces it if it
+moved.
 
 `source` is how you tell them apart:
 
@@ -132,8 +106,7 @@ run 2   {colorScheme: 'dark',          accent: '#ed5b00', source: 'cache'}   ←
 ```
 
 Revalidation costs one re-render even when nothing moved, because `source`
-itself changed. That is deliberate: a `source` that stayed `'cache'` after the
-desktop had actually answered would be worth less than the render it saved.
+itself changed.
 
 That leaves the very first launch on a machine, where there is nothing to
 remember. An app that must be exact rather than probably right waits:
@@ -146,12 +119,9 @@ root.render(<App />); // useSystemAppearance() is already correct
 ```
 
 `systemAppearance()` is the imperative twin of the hook, and never rejects.
-
-**Why it is not simply part of `createRoot()`.** Measured cold on a GNOME
-session: `createRoot()` alone 85 ms, `createRoot()` with a concurrent portal
-probe 124 ms. `dbus-native`'s import is CPU-bound, so it does not hide behind
-ntk's startup — and an app that never asks what colour the desktop is should
-not pay 40 ms to find out.
+It is not part of `createRoot()` because the probe adds about 40 ms to a cold
+start, which an app that never asks what colour the desktop is should not
+pay.
 
 `REACT_X11_NO_APPEARANCE_CACHE=1` turns the file off for a process that must
 not touch the disk.
@@ -219,14 +189,12 @@ is dark, for a design whose two schemes are not one recolour of the other:
 <ThemeProvider value={{ background: '#fffdf7' }} dark={{ background: '#141210' }}>
 ```
 
-**The accent is followed on the same terms as the scheme.** The reason is
-the one that decided the scheme: an app that says nothing is asking to look
-like it belongs, and on a desktop that has an accent every control beside it is
-already that colour — on the Cocoa backend the app's own native checkboxes and
-default buttons are drawn by AppKit in the user's accent, so a `<Tabs>`
-indicator that stayed blue next to them looked like a bug. A brand keeps its
-own colour by naming it; a following provider's `value` wins over the desktop
-token for token, so name the family rather than the one colour:
+**The accent is followed on the same terms as the scheme**: on a desktop
+that has an accent, every control beside the app is already that colour — on
+the Cocoa backend the app's own native checkboxes and default buttons are
+drawn by AppKit in it. A following provider's `value` wins over the desktop
+token for token, so a brand keeps its own colour by naming the family rather
+than the one colour:
 
 ```jsx
 <ThemeProvider value={{ accent: '#e17055', accentHover: '#c0563a', hoverBackground: '#e17055' }}>
@@ -239,23 +207,10 @@ they say in any accent.
 
 ### Resizing
 
-The colour a window is _painted_ is only half of it. Dragging a window larger
-exposes area before the app can possibly have drawn it, and something has to
-be in that area meanwhile — so a window that never says what flashes a default
-on every drag of the corner, which on a dark palette is a bright rectangle.
-
-There are two copies of that colour, because a window here is double-buffered:
-the X **attribute** the server paints exposed area with, and the colour ntk
-clears the part of its backing store that a grow adds. react-x11 sets both —
-to the window's own `backgroundColor`, or the palette's — and keeps them in
-step when either moves. Nothing to do; it is worth knowing only because they
-are the pieces of the palette that live outside this renderer.
-
-Needs **ntk >= 6.6.1**, where `setBackgroundPixel` sets the pair together.
-Before that the backing store cleared to the screen's white whatever the
-window said, so enlarging a dark window flashed a white strip — and it
-survived, because a grow inside the pixmap's headroom reallocates nothing and
-so nothing damages it.
+Dragging a window larger exposes area before the app can have drawn it.
+react-x11 fills it with the window's own `backgroundColor`, or the
+palette's, and keeps that in step when either moves, so a dark window does
+not flash a bright rectangle on every drag of the corner. Nothing to do.
 
 ### Testing
 
@@ -302,49 +257,32 @@ new to learn. See [styling](styling.md) for what a transition covers.
 
 ## The ladder
 
-There is no cross-toolkit palette protocol. Nothing on a Linux desktop lets
-one toolkit ask another what colour a window background is; what exists is a
-shared theme _name_, and exactly four standardised appearance _values_. Those
-four are what this reads, from the best source the machine has:
-
-1. **`org.freedesktop.portal.Settings`** — the real contract, and the only
-   source with an accent colour. `ReadAll(['org.freedesktop.appearance'])`,
-   live over `SettingChanged`. libadwaita, Qt 6.5+, Firefox and Electron all
-   read this one.
-2. **macOS** — `NSUserDefaults` and `NSWorkspace` through one long-lived
-   `osascript` child, and only where the _process_ is running on a Mac. It
-   comes before XSETTINGS on purpose: on a Mac, the Mac's own preference is
-   the one the user set, and an XSETTINGS daemon there is something they
-   installed by hand. It is in practice the only source on a Mac, on either
-   backend — a stock XQuartz has no portal, no XSETTINGS manager and an
-   unset `RESOURCE_MANAGER`. A _Linux_ process drawing to an XQuartz display
-   never reaches this rung at all, which is correct: it cannot read that
-   Mac's defaults.
-3. **Windows** — answered by the win32 backend itself: the Personalize key
-   for light or dark, DWM for the accent, `SystemParametersInfo` for contrast
-   and reduced motion, live over `WM_SETTINGCHANGE` and its siblings. Before
-   XSETTINGS for the same reason macOS is, and asked of the app rather than
-   of the platform, so only a tree on the win32 backend reaches it.
-4. **XSETTINGS** — pre-D-Bus, X11-only. `Net/ThemeName` is a _name_, so "is
-   this dark" comes down to trusting the `-dark` suffix — which is exactly
-   what the portal was invented to replace, so it is a fallback and never a
-   correction. Live over `PropertyNotify`.
-
-`RESOURCE_MANAGER` is not a rung. It is where `Xft.dpi`, `Xft.rgba` and
-`Xcursor.*` live — font and cursor rendering — and there has never been an X
-resource for colour scheme, accent or contrast.
-
-**The first rung that answers owns all four values.** The rungs disagree:
-measured on one GNOME session, at one moment, the portal reported
-`reduced-motion: 0` while GNOME's own `enable-animations` was `false`. Taking
-the best-answered field from each would describe a desktop that does not
-exist.
-
-Nothing here holds the process open. The `SettingChanged` subscription leaves
-the match rule on the shared connection and releases its reference, so the
-socket goes back to `unref()`d: an app whose windows have closed still exits,
-and an app with a window on screen is awake anyway and gets the signal. The
-macOS child is spawned `unref()`d and killed on exit.
+There is no cross-toolkit palette protocol: what a desktop exposes is a
+shared theme _name_ and four standardised appearance _values_. Those four
+are read from the best source the machine has:
+
+1. **`org.freedesktop.portal.Settings`** — the real contract on Linux, and
+   the only Linux source with an accent colour; live over `SettingChanged`.
+   libadwaita, Qt 6.5+, Firefox and Electron all read this one.
+2. **macOS** — only where the _process_ is running on a Mac, on either
+   backend; before XSETTINGS, because on a Mac the Mac's own preference is
+   the one the user set. A _Linux_ process drawing to an XQuartz display
+   never reaches this rung: it cannot read that Mac's settings.
+3. **Windows** — answered by the win32 backend itself: light or dark, the
+   accent, contrast and reduced motion, live. Before XSETTINGS for the same
+   reason as macOS, and only a tree on the win32 backend reaches it.
+4. **XSETTINGS** — X11 only. "Is this dark" comes down to a `-dark` suffix
+   on `Net/ThemeName`, so it is a fallback and never a correction. Live.
+
+`RESOURCE_MANAGER` is not a rung: there has never been an X resource for
+colour scheme, accent or contrast.
+
+**The first rung that answers owns all four values.** The rungs can
+disagree, and taking the best-answered field from each would describe a
+desktop that does not exist.
+
+Nothing here holds the process open: an app whose windows have closed still
+exits.
 
 ### Not climbing it at all
 
@@ -371,46 +309,9 @@ off along with the other two integrations that talk to the session bus.
 | `contrast`      | yes                                  | yes   | from the theme name |
 | `reducedMotion` | version 2 of the interface           | yes   | rarely — see below  |
 
-`Gtk/EnableAnimations` is in GTK's key list but a settings daemon need not
-export it, and gnome-settings-daemon does not — 53 settings on the session
-this was written against, and it is not among them. So on GNOME the XSETTINGS
-rung reports no reduced motion rather than inventing an answer.
-
-## Notes on the sources
-
-**1 is dark and 2 is light** in the portal's `color-scheme`. The ordering
-reads backwards, and getting it wrong inverts the appearance of every desktop
-that expressed a preference — which is precisely the set of machines that
-care.
-
-**The accent colour is a `(ddd)` of sRGB floats in [0, 1]**, and "unset" is
-spelled as values outside that range. It is converted to a `'#rrggbb'` string
-here, because every style in this renderer takes a CSS colour and
-`rgb(0.93, 0.36, 0)` is black.
-
-**The subscription goes on before the read.** A change landing between the
-read and the match rule is lost and nothing corrects it — the app stays stale
-for its whole lifetime. It is the same shape as the portal `Request` race in
-[the file dialog](filedialog.md).
-
-**On macOS the frameworks are read, not `defaults`.** Three of the four
-plausible `defaults` keys — `AppleHighlightColor`, `AppleAccentColor`,
-`com.apple.universalaccess increaseContrast` — do not exist until the user
-changes that setting, so "key not found" is the normal answer rather than the
-error case, and `AppleAccentColor` is an index into a table that has to be
-maintained by hand. `NSColor.controlAccentColor` is the colour itself, with
-Multicolor already resolved, `alternateSelectedControlTextColor` is the ink
-AppKit writes on it, `selectedContentBackgroundColor` is the shade under a
-selected row (both resolved in the appearance the desktop is in, since a
-dynamic colour in a bare `osascript` resolves as Aqua otherwise), and
-`NSWorkspace` answers the two accessibility flags directly.
-
-**A process reads the colours once.** `controlAccentColor` is resolved on
-first use and cached for the life of the process: after the user picks another
-accent, the same process still answers the old one, with or without an
-`NSApplication`. So the watcher prints its values once and, on the change
-notifications, exits — and react-x11 spawns another, whose first read is
-fresh. A watcher that re-read in place re-announced the same values, and a
-running app never saw the change. The Cocoa backend
-reads the same child: it is one source for both backends, and the accent it
-reports is the one AppKit draws the native bezels in.
+On GNOME the XSETTINGS rung reports no reduced motion:
+`Gtk/EnableAnimations` is in GTK's key list, but gnome-settings-daemon does
+not export it.
+
+Design notes — how each source is read, and the macOS colour mapping:
+[design/appearance.md](../design/appearance.md).

package/docs/click-to-component.md

@@ -54,60 +54,27 @@ when DevTools is absent, which is the usual case.
 `REACT_X11_EDITOR` picks the editor (`cursor` by default): `code`,
 `code-insiders`, `windsurf`, `vim`, `nvim`, or any other value, treated as a
 custom URI scheme. `react-x11 dev`'s error window opens a line the same way,
-through the same variable (`src/editor.js`, shared by both).
+through the same variable.
 
 ## How it works
 
-`src/ClickToComponent.js`, installed from `Reconciler.js` when either
-`REACT_X11_CLICK_TO_COMPONENT` or `REACT_X11_EDITOR` is set, and
-`REACT_X11_CLICK_TO_COMPONENT` is not `0` — the way to turn it off under
-`react-x11 dev`, which sets it to `1` when it is unset. No
-babel/jsx-source plugin, no build-time instrumentation:
-
-- every host node already carries a reference to the fiber that created it
-  (`node._reactFiber`, set in `createInstance`). It is this feature's own
-  back-reference, not a DevTools one: `findFiberByHostInstance` is gone
-  from react-reconciler 0.33, and click-to-component works with DevTools
-  absent;
-- React 19 captures a real `Error` at every JSX call site in development
-  mode (`fiber._debugStack`) and tracks who rendered what
-  (`fiber._debugOwner`) — no `__source`/`__self` babel transform needed;
-- Node's `--enable-source-maps` (already on for both the plain `tsx`
-  examples and `examples:tasks:hot`'s loader) has rewritten that Error's
-  stack to original source before we ever see it, so resolving a location
-  is just parsing stack-trace text and skipping the frames React and this
-  renderer add on top of the call site (`react`, `react-reconciler`,
-  `scheduler`, `react-x11`'s own `src/`) — no source-map library required
-  (this is the one place
-  the design diverges from a browser DOM version of the same idea: a
-  browser doesn't remap `Error.stack` for you, so a tool like
-  [show-component](https://github.com/sidorares/show-component) has to
-  resolve source maps itself at runtime).
-
-Frames from _other_ packages are deliberately kept rather than skipped: a
-call site inside an installed component is a real location, it just isn't
-one in your source, and telling those apart is what lets the resolver climb
-the `_debugOwner` chain to the line that is. Skipping every `node_modules`
-frame instead walks past the library component entirely and lands on
-whichever frame of yours happens to be deeper in the render stack — usually
-the `render()` call at startup, which looks like an answer and isn't.
-
-Alt+Click is recognized in `EventManager._onMouseDown`
-(`src/events.js`) — `native.buttons & MOD.Alt` is X11's `Mod1Mask` bit, the
-same `buttons` bitmask every synthetic event's `altKey` reads — ahead of the
-normal press handling, so it never also starts a drag or moves focus.
-
-GUI editors (cursor/code/code-insiders/windsurf, or any unrecognized
-`REACT_X11_EDITOR` value treated as a raw scheme) are opened by navigating
-their registered URI scheme — `open cursor://file/abs/path:line:col` on
-macOS, `xdg-open` elsewhere — the same idea show-component uses in a
-browser via `window.location.href`, just handed to the OS instead. This is
-noticeably faster than spawning the editor's CLI shim directly: a CLI like
-`cursor -g ...` is a wrapper script that re-detects and re-execs the real
-app on every call, while the URI scheme is delivered straight to the
-already-running instance by Launch Services / xdg-open. vim and nvim have
-no URI scheme to navigate, so those are still spawned directly with a
-`+call cursor(line, column)` argument.
+It is installed when `REACT_X11_CLICK_TO_COMPONENT` or `REACT_X11_EDITOR` is
+set, unless `REACT_X11_CLICK_TO_COMPONENT=0` — the way to turn it off under
+`react-x11 dev`, which sets it to `1` when it is unset. No babel/jsx-source
+plugin and no build step: React 19's development-mode call-site stacks and
+owner chain are all it reads.
+
+- **Locations are as good as the stack.** It reads the source location off
+  `Error.stack`, so run with Node's `--enable-source-maps` (on in the `tsx`
+  examples) or locations point at compiled output.
+- **Alt+Click is taken before normal press handling**, so it never also
+  starts a drag or moves focus.
+- **GUI editors are opened through their URI scheme** —
+  `open cursor://file/abs/path:line:col` on macOS, `xdg-open` elsewhere — which
+  reaches the already-running instance; vim and nvim are spawned with a
+  `+call cursor(line, column)` argument.
+
+Design notes: [design/click-to-component.md](../design/click-to-component.md#how-it-works).
 
 ## Caveats
 

package/docs/clipboard.md

@@ -20,20 +20,17 @@ middle-click paste, select-to-own. This page is for everything else: a
 canvas that copies an image, a list that pastes files, a document view with
 its own Copy item.
 
-> **On the Cocoa backend** the clipboard is `NSPasteboard.general`, and the
-> difference from X11 is structural rather than cosmetic: X's model is
-> _ownership of a selection_, negotiated per paste, and macOS's is a
-> _pasteboard the system holds_. Everything below works there — writing,
+> **On the Cocoa backend** the clipboard is `NSPasteboard.general`: a
+> pasteboard the system holds, rather than X's _ownership of a selection_
+> negotiated per paste. Everything below works there — writing,
 > [reading](#reading) any type the pasteboard carries, `targets()` and
 > [`watch()`](#knowing-when-it-changes) — with three differences, each
-> described where it applies: [`PRIMARY`](#primary-is-x11-only) is X11-only
-> rather than missing, since nothing on macOS is filled by selecting text;
+> described where it applies: [`PRIMARY`](#primary-is-x11-only) is X11-only;
 > `targets()` names the pasteboard's types rather than an owner's atoms; and
-> `watch()` asks the pasteboard's change count while something is watching,
-> since nothing announces a copy. A [multi-flavour payload](#writing) is
-> written whole when the bridge has `pasteboardWrite` (windowkit/appkit#119);
-> an older bridge keeps the text and says once, in development, what it
-> dropped.
+> `watch()` polls the pasteboard's change count. A
+> [multi-flavour payload](#writing) is written whole when the bridge has
+> `pasteboardWrite`; an older bridge keeps the text and says once, in
+> development, what it dropped.
 
 ## Two clipboards
 
@@ -53,9 +50,8 @@ which is what the built-in text controls do.
 Two consequences worth knowing, because neither matches a browser:
 
 - **The data lives in this process.** Nothing is stored by the server, so
-  when the app exits the clipboard goes with it — normal X behaviour, and
-  the reason desktops run clipboard managers. Nothing negotiates with one
-  yet.
+  when the app exits the clipboard goes with it (normal X behaviour; there is
+  no clipboard-manager handoff).
 - **Someone else copying takes it away.** Ownership is exclusive; there is
   no "clipboard history" to fall back on.
 
@@ -71,22 +67,15 @@ your own — is one nobody can paste from:
   X's answers for a selection nobody owns;
 - `clear()` leaves the pasteboard alone, and `watch()` never fires.
 
-The **win32** backend answers every selection but `CLIPBOARD` the same way,
-since Windows has no equivalent either (and writes only text there so far).
-The **Wayland** backend is the other X-like one: it has `PRIMARY` too, over
-the primary-selection protocol where the compositor offers it
-(`src/wayland/clipboard.js`), so "X11-only" here means "not on macOS or
-Windows".
-
-That is what keeps selecting from being copying. A drag across a
-`selectable` surface, a select-all, shift+arrows in a field: each takes
-`PRIMARY` on X11, and on macOS none of them replaces what the user copied
-somewhere else. Code written to the X11 convention needs no platform check.
-
-`PRIMARY` is deliberately not kept inside the app instead. Its point is the
-paste in _another_ application; all an in-process copy could keep is a
-middle click that types into a text field, which no Mac text field does. An
-app that wants select-to-copy on macOS anyway — a terminal emulator, say —
+The **win32** backend answers every selection but `CLIPBOARD` the same way
+(and writes only text there so far). The **Wayland** backend has `PRIMARY`
+too, over the primary-selection protocol where the compositor offers it — so
+"X11-only" here means "not on macOS or Windows".
+
+So selecting is never copying there: a drag across a `selectable` surface, a
+select-all or shift+arrows takes `PRIMARY` on X11 and leaves the macOS
+pasteboard alone. Code written to the X11 convention needs no platform check.
+An app that wants select-to-copy on macOS anyway — a terminal emulator, say —
 can write `CLIPBOARD` itself: a surface's `selectedText()` is the text, and
 `onSelectionChange` says when it moved.
 
@@ -129,9 +118,8 @@ text-ish types to a string. It answers `null` when the owner has nothing of
 that kind, because "is there an image on the clipboard?" is a question, not
 an error.
 
-The groups exist because the same payload arrives under different names
-depending on who copied it, and exact-match filtering silently misses most
-of the desktop:
+The same payload arrives under different names depending on who copied it,
+so a group matches all of them:
 
 | group     | matches                                                                                                    |
 | --------- | ---------------------------------------------------------------------------------------------------------- |
@@ -139,28 +127,21 @@ of the desktop:
 | `'files'` | `text/uri-list`, `application/x-kde4-urilist`, `x-special/gnome-copied-files`                              |
 | `'uris'`  | `text/uri-list`, `text/x-moz-url`, `_NETSCAPE_URL`                                                         |
 
-This is the same table [drag and drop](drag-and-drop.md) uses, and
-deliberately so: the flavours a file manager offers on a drop are the ones
-it offers on a copy. Groups do not overlap — a Firefox link is
+This is the same table [drag and drop](drag-and-drop.md) uses. Groups do not
+overlap — a Firefox link is
 `text/x-moz-url`, which is in `uris`, not `text`.
 
 On the Cocoa backend `targets()` lists the pasteboard's types in these
 names: a type with a MIME type under that (`public.png` is `image/png`,
 Finder's `public.file-url` is `text/uri-list`), text under both its X and
-MIME names, and any other type under its own identifier. That last rule is
-what lets an app honour a password manager: one that copies a secret puts
-[`org.nspasteboard.ConcealedType`](http://nspasteboard.org) beside it, the
-macOS convention for "keep this out of clipboard history", and a clipboard
-history should skip any copy whose `targets()` include it (or
-`org.nspasteboard.TransientType`). Files copied in Finder are one item each,
-and `read('files')` reads them as one uri-list.
-
-Text is read through the bridge's own text verb. Anything else is read from
-the pasteboard's items: through `pasteboardItems`/`pasteboardItemData` on a
-bridge that has them, and otherwise through `osascript -l JavaScript`, one
-short-lived child of about 60 ms per `targets()` or `read()`. The type list
-is kept against the pasteboard's change count, so asking again with nothing
-copied in between costs nothing.
+MIME names, and any other type under its own identifier. So an app can honour
+a password manager: a clipboard history should skip any copy whose
+`targets()` include [`org.nspasteboard.ConcealedType`](http://nspasteboard.org)
+or `org.nspasteboard.TransientType`. Files copied in Finder are one item each,
+and `read('files')` reads them as one uri-list. Reading anything but text
+costs an `osascript` child (about 60 ms per `targets()` or `read()`) on a
+bridge without `pasteboardItems`; asking again with nothing copied in between
+costs nothing.
 
 `readFiles()` is `read('files')` with the RFC 2483 parsing applied: CRLF
 separators, `#` comment lines, percent-decoding. `path` is present only for
@@ -195,15 +176,13 @@ something changes. `owner === 0` means nothing is on the clipboard, which is
 the case a Paste menu item wants. It rejects on a server without XFixes;
 every X server since about 2004 has it.
 
-On the Cocoa backend nothing announces a copy, so `watch()` is a poll after
-all: it asks the pasteboard's change count, which every write bumps, every
-250 ms while anything is watching, and stops with the last unsubscribe. The
-count is a published number on the bridge, under a microsecond to read, and
-a change costs one look at what the pasteboard now holds, to say whether
-`owner` is `0`. No window owns the pasteboard, so `owner` is `-1` when it
-holds anything; `ev.changeCount` is the pasteboard's own count. Two copies
-inside one poll are one change, and the app's own copies are changes too, as
-they are on X11. It rejects on a bridge without `pasteboardChangeCount`.
+On the Cocoa backend nothing announces a copy, so `watch()` polls the
+pasteboard's change count every 250 ms while anything is watching (cheap; it
+stops with the last unsubscribe). No window owns the pasteboard, so `owner` is
+`-1` when it holds anything; `ev.changeCount` is the pasteboard's own count.
+Two copies inside one poll are one change, and the app's own copies are
+changes too, as they are on X11. It rejects on a bridge without
+`pasteboardChangeCount`.
 
 ## Timestamps
 
@@ -279,3 +258,5 @@ raw protocol. See ntk's own clipboard documentation for the ICCCM details.
   a bare `writeText()` offers both.
 - **No image decoding.** `read('image/png')` hands back the bytes; turning
   them into something drawable is yours.
+
+Design notes: [design/clipboard.md](../design/clipboard.md).