react-x11 2.51.1 → 2.53.0

package/docs/appearance.md

@@ -0,0 +1,317 @@
+# System appearance
+
+What the desktop looks like — light or dark, the accent colour, contrast, and
+whether the user asked for less motion — as four values an app renders from.
+
+```jsx
+import { useSystemAppearance } from 'react-x11';
+
+const { colorScheme, accent, contrast, reducedMotion } = useSystemAppearance();
+```
+
+**Most apps never need it.** react-x11's built-in palette already follows the
+desktop, so an app that says nothing about colour is dark on a dark desktop
+and light on a light one, and its buttons, tabs and menu highlights are the
+desktop's accent where the desktop has one — see
+[following the desktop](#following-the-desktop) below. Reach for the hook when
+you want the values themselves: reduced motion, the accent as a colour for
+something that is not a widget, or a design decision that is not a palette.
+
+## The four values
+
+|                 |                                                                                                |
+| --------------- | ---------------------------------------------------------------------------------------------- |
+| `colorScheme`   | `'light'`, `'dark'` or `'no-preference'`                                                       |
+| `accent`        | `'#ed5b00'`, or **null**                                                                       |
+| `accentText`    | the ink the desktop writes on its accent — `'#ffffff'` on macOS — or **null**                  |
+| `selection`     | the fill under a selected menu or list row — a darker cut of the accent on macOS — or **null** |
+| `palette`       | the desktop's whole palette as tokens, on macOS — or **null**                                  |
+| `contrast`      | `'normal'` or `'high'`                                                                         |
+| `reducedMotion` | `true` when the user asked for less animation                                                  |
+| `source`        | which rung answered — `'portal'`, `'xsettings'`, `'macos'`, `'windows'`, `'cache'`, or null    |
+
+Two of these are easy to get wrong.
+
+**`'no-preference'` means _use your own default_**, not "use light". It is
+what a desktop says when it has no opinion, and an app whose own design is
+dark should stay dark there.
+
+**`accent` is null far more often than it is not.** Most portal backends
+implement `color-scheme` and nothing else, and XSETTINGS has no accent key at
+all. Fall back to your own brand colour rather than to grey — an app that goes
+colourless on a desktop that simply did not answer the question looks broken.
+
+```jsx
+const { accent } = useSystemAppearance();
+<box style={{ borderColor: accent ?? '#2980b9' }} />;
+```
+
+`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 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.
+
+## The first frame
+
+None of this can be known synchronously — the answer is a D-Bus call away —
+and an app that renders light and then switches to dark a moment later has a
+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 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:
+
+```
+run 1   {colorScheme: 'no-preference', accent: null,      source: null}      ← nothing remembered
+        {colorScheme: 'dark',          accent: '#ed5b00', source: 'portal'}  ← 78 ms later
+
+run 2   {colorScheme: 'dark',          accent: '#ed5b00', source: 'cache'}   ← 0.1 ms, first render
+        {colorScheme: 'dark',          accent: '#ed5b00', source: 'portal'}  ← revalidated
+
+(`accentText`, `selection`, `contrast` and `reducedMotion` travel with them.)
+```
+
+Revalidation costs one re-render even when nothing moved, because `source`
+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:
+
+```jsx
+import { createRoot, systemAppearance } from 'react-x11';
+
+const [root] = await Promise.all([createRoot(), systemAppearance()]);
+root.render(<App />); // useSystemAppearance() is already correct
+```
+
+`systemAppearance()` is the imperative twin of the hook, and never rejects.
+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.
+
+## Following the desktop
+
+**Nothing.** That is the whole section.
+
+react-x11's built-in palette _is_ the desktop's: an app that says nothing
+about colour is dark on a dark desktop and light on a light one, the way a
+GTK or Qt app is, and where the desktop reports an accent — macOS always,
+GNOME 47+ and KDE through the portal — `$accent` and the family around it
+(`accentHover`, the pressed step, `hoverBackground`, the focus ring) are that
+colour, and `hoverBackground` is the desktop's own selection shade where it
+names one. On macOS the whole palette is the desktop's — see
+[the desktop's palette](#the-desktops-palette). The window background, the widgets and every `$token` in a style all
+come from it.
+
+```jsx
+// this app follows the desktop
+function App() {
+  return (
+    <window width={400} height={200}>
+      <box style={{ flexGrow: 1, padding: 16, backgroundColor: '$background' }}>
+        <text style={{ color: '$text' }}>Hello</text>
+        <Button primary label="Save" />
+      </box>
+    </window>
+  );
+}
+```
+
+A `<window>` with no `backgroundColor` takes the palette's, so even that line
+is optional.
+
+### Overriding
+
+`<ThemeProvider value={…}>` layers your palette **over the scheme in force**,
+so it names what your app changes and everything else keeps following:
+
+```jsx
+<ThemeProvider value={{ accent: '#e17055', radius: 10 }}>
+```
+
+That app has its own accent and corner radius on both a light and a dark
+desktop, and never wrote a second palette.
+
+`colorScheme` pins a subtree, for a design that only works one way or a
+preference the app owns rather than the desktop:
+
+```jsx
+<ThemeProvider value={brand} colorScheme="light">          // never follows
+<ThemeProvider value={brand} colorScheme={settings.theme}> // the app decides
+```
+
+**Pinning is also the complete opt-out.** A pinned provider subscribes to
+nothing and the widgets under it read the palette it published, so an app that
+says `colorScheme="light"` once at the top never has react-x11 ask the desktop
+anything.
+
+`dark` is the other half — a palette layered on only when the scheme in force
+is dark, for a design whose two schemes are not one recolour of the other:
+
+```jsx
+<ThemeProvider value={{ background: '#fffdf7' }} dark={{ background: '#141210' }}>
+```
+
+**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' }}>
+```
+
+And a pinned `colorScheme` follows nothing, the accent included. What does
+**not** move with the accent is `info`: a note is blue everywhere, under a
+green accent as under an orange one, and `success`/`warning`/`danger` say what
+they say in any accent.
+
+### Resizing
+
+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
+
+`react-x11/test` **pins the colour scheme to light**, and that is not a
+convenience: with a palette that follows the desktop, an unpinned suite renders
+in whatever colours the machine running it happens to be in, so a pixel
+assertion would be green on a light desktop and red on a dark one with nothing
+in the test to say so.
+
+```js
+await renderX11(<App />, { fonts: FONTS }); // light
+await renderX11(<App />, { fonts: FONTS, colorScheme: 'dark' }); // dark
+await renderX11(<App />, { fonts: FONTS, colorScheme: 'system' }); // the real one
+```
+
+`createMockApp()` pins the same way. `'system'` is for a test that is _about_
+what the desktop reports.
+
+The other values pin too, from the first render or under a mounted tree —
+which is how a component that follows `reducedMotion`, `contrast` or the
+accent is tested, change included. A pinned appearance reports
+`source: 'test'`.
+
+```js
+await renderX11(<App />, { appearance: { reducedMotion: true } });
+await setAppearance({ reducedMotion: false }); // re-renders, repaints
+```
+
+See [testing](testing.md#the-desktops-appearance) for the rules.
+
+## Reduced motion
+
+`reducedMotion` is reported, not applied. Nothing in the renderer switches
+animation off behind your back — an app with `transition: 150` keeps it until
+the app decides otherwise:
+
+```jsx
+const { reducedMotion } = useSystemAppearance();
+<box style={{ transition: reducedMotion ? 0 : 150, backgroundColor: fill }} />;
+```
+
+`transition: 0` is already how "no animation" is spelled, so there is nothing
+new to learn. See [styling](styling.md) for what a transition covers.
+
+## The ladder
+
+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
+
+```jsx
+await createRoot({ desktop: { appearance: false } });
+```
+
+For an app that owns its palette, an embedder that follows the desktop its own
+way, and a test that needs the same answer on every machine. The ladder does
+not run and **the remembered answer is not read either**: `colorScheme` stays
+`'no-preference'` with `source: null`, which means use your own default. See
+[desktop.md](desktop.md#turning-the-desktop-off) — `desktop: false` turns this
+off along with the other two integrations that talk to the session bus.
+
+## What each rung can actually answer
+
+|                 | portal                               | macOS | XSETTINGS           |
+| --------------- | ------------------------------------ | ----- | ------------------- |
+| `colorScheme`   | yes                                  | yes   | from the theme name |
+| `accent`        | yes, where the backend implements it | yes   | **no such key**     |
+| `accentText`    | no — the palette picks by contrast   | yes   | no                  |
+| `selection`     | no — the accent itself               | yes   | no                  |
+| `palette`       | no                                   | yes   | no                  |
+| `contrast`      | yes                                  | yes   | from the theme name |
+| `reducedMotion` | version 2 of the interface           | yes   | rarely — see below  |
+
+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

@@ -0,0 +1,92 @@
+# Click to component
+
+Alt+Click any rendered element to jump straight to the JSX line that created
+it, in your editor. On macOS that's **Option+Click**, on both backends: the
+Cocoa backend maps ⌥ to Mod1 itself, and XQuartz maps it there by default
+("Option keys send Alt_L and Alt_R" in its Input preferences). The
+installed-feature log line says whichever one applies to your platform.
+
+## Setup
+
+Under `react-x11 dev` it is already on. Elsewhere:
+
+```sh
+REACT_X11_EDITOR=code npm run examples:tasks   # naming an editor enables it
+# or, to use the default (cursor):
+REACT_X11_CLICK_TO_COMPONENT=1 npm run examples:tasks
+```
+
+Alt/Option+Click a task row, a button, anything — its owning component's source
+opens at the exact line, the clicked element flashes blue for a moment, and
+the console prints what was resolved:
+
+```
+[click-to-component] TaskRow → examples/tasks.jsx:42:7
+```
+
+Alt+Shift+Click also logs the full ownership chain (who rendered who, up to
+the root) to the console — handy when the immediate owner is a shared
+wrapper rather than the component you actually meant.
+
+## Elements you didn't write
+
+An element rendered by an installed component — a design system's
+`<Toolbar>`, a chart library's internals — has its JSX call site inside that
+package, not in your code. Clicking one resolves to the nearest owner up the
+chain that _is_ your source: the `<Toolbar ... />` line in your file that put
+it on screen. The console line says how far it had to climb, so a location
+that doesn't match what you clicked is never a surprise:
+
+```
+[click-to-component] App → src/ui/App.tsx:432:7 (1 owner up from the clicked <box>)
+```
+
+When no owner in the chain is application source (a screen rendered entirely
+by a package), the package's own file is opened instead and the line is
+marked `— inside an installed package`. Only a tree with no React debug info
+at all resolves to nothing.
+
+With React DevTools attached as well (`REACT_X11_DEVTOOLS=1`, see
+[devtools.md](devtools.md)), the same click also selects that element in the
+DevTools tree — one click to the source _and_ to its props. Nothing changes
+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.
+
+## How it works
+
+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
+
+- Needs React running in development mode (fiber debug fields are stripped
+  in production builds).
+- The editor is launched detached, so a failure is only visible as a
+  warning: an editor whose URI scheme nothing claims (`REACT_X11_EDITOR`
+  naming an editor that isn't installed) prints
+  `click-to-component — \`open cursor://...\` exited 1` next to the
+  resolved location rather than silently doing nothing.
+- A node's `_reactFiber` is only refreshed on mount, not on every update —
+  usually harmless (the JSX call site of a given element rarely moves
+  between renders of the same tree shape), but a node that was
+  conditionally re-typed can point at a stale-but-structurally-similar
+  fiber.

package/docs/clipboard.md

@@ -0,0 +1,262 @@
+# Clipboard
+
+```jsx
+import { useClipboard } from 'react-x11';
+
+function Editor({ value }) {
+  const clipboard = useClipboard();
+  return (
+    <box
+      onKeyDown={(e) => {
+        if (e.ctrlKey && e.key === 'c') clipboard.writeText(value);
+      }}
+    />
+  );
+}
+```
+
+`<textinput>` and `<textarea>` already do all of this for you — Ctrl+C/X/V,
+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`: 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;
+> `targets()` names the pasteboard's types rather than an owner's atoms; and
+> `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
+
+X has no clipboard buffer. "Copy" means owning a **selection** — a named
+thing the server tracks — and answering conversion requests from whoever
+pastes. There are two in everyday use, and they are independent:
+
+| selection   | filled by                                  | pasted with          |
+| ----------- | ------------------------------------------ | -------------------- |
+| `CLIPBOARD` | an explicit Copy or Cut                    | Ctrl+V, an Edit menu |
+| `PRIMARY`   | _selecting text at all_, with no Copy step | middle click         |
+
+Every call below takes `{ selection }` and defaults to `CLIPBOARD`. The
+X11-native behaviour is to write `PRIMARY` whenever your selection changes,
+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; there is
+  no clipboard-manager handoff).
+- **Someone else copying takes it away.** Ownership is exclusive; there is
+  no "clipboard history" to fall back on.
+
+### `PRIMARY` is X11-only
+
+macOS has one pasteboard, and it is `CLIPBOARD`'s: nothing there is filled
+by selecting text, and a middle click pastes nothing. So on the Cocoa
+backend every selection but `CLIPBOARD` — `PRIMARY`, `SECONDARY`, a name of
+your own — is one nobody can paste from:
+
+- `write()` and `writeText()` resolve and leave the pasteboard alone;
+- `read()` answers `null`, `readText()` rejects and `targets()` is `[]` —
+  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
+(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.
+
+## `useClipboard()`
+
+Returns the clipboard for the connection this tree renders onto. Stable, so
+it is safe in a dependency array. Everything on it returns a promise.
+
+### Writing
+
+```js
+await clipboard.writeText('hello');
+await clipboard.write({
+  'text/html': '<b>hello</b>',
+  'text/plain': 'hello',
+  'image/png': pngBytes,
+});
+```
+
+`write()` takes a map of **type name to payload** — strings are encoded
+UTF-8, `Buffer`s and typed arrays are served as they are. Offering several
+flavours of the same thing is the point: a rich-text editor takes the HTML,
+a terminal takes the plain text, and each asks for what it understands.
+There is no size limit worth naming; large payloads transfer incrementally.
+
+`clear()` gives the selection back, so nothing is served for it any more.
+
+### Reading
+
+```js
+const text = await clipboard.read('text'); //  'hello'  | null
+const files = await clipboard.readFiles(); //  [{ uri, path? }]
+const png = await clipboard.read('image/png'); //  Uint8Array | null
+const offered = await clipboard.targets(); //  ['text/html', …]
+```
+
+**`read(type)` is the one to reach for.** It accepts a concrete type name or
+a **group**, resolves it against what the owner actually offers, and decodes
+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 same payload arrives under different names depending on who copied it,
+so a group matches all of them:
+
+| group     | matches                                                                                                    |
+| --------- | ---------------------------------------------------------------------------------------------------------- |
+| `'text'`  | `text/plain;charset=utf-8`, `UTF8_STRING`, `text/plain`, `STRING`, `TEXT`, `COMPOUND_TEXT` (in that order) |
+| `'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. 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. 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
+genuinely local `file:` URIs — a remote `file://otherhost/…` gets a `uri`
+and no `path` rather than a path that does not exist here.
+
+`readText()` is the plain-text shortcut and asks only for `UTF8_STRING` then
+`STRING`. It **rejects** when there is no owner or the owner offers neither,
+where `read('text')` returns `null` and walks the whole preference list. If
+you are not sure which you want, use `read('text')`.
+
+### Knowing when it changes
+
+```js
+useEffect(() => {
+  let stop;
+  clipboard
+    .watch((ev) => setCanPaste(ev.owner !== 0))
+    .then((fn) => (stop = fn));
+  return () => stop?.();
+}, [clipboard]);
+```
+
+The built-in edit menu on `<textinput>`/`<textarea>` already does this for
+its Paste row — see [elements.md](elements.md#the-right-click-menu). This is
+the same mechanism, for your own menus. If what you are building _is_ an edit
+menu, open the standard one instead and the Paste row comes with it
+([extending.md](extending.md#the-standard-edit-menu)).
+
+`watch()` is a server-side subscription, not a poll — it costs nothing until
+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()` 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
+
+X arbitrates between two clients copying at the same moment by **timestamp**,
+and ICCCM is explicit that the right one is the event that caused the copy —
+never "now". You do not have to pass one: react-x11 remembers the last input
+event on the connection and uses it, so a copy from a Ctrl+C handler is
+stamped with that keystroke. Pass `{ time }` if you have a better answer.
+
+This is also why a `write()` can fail: if another client copied with a newer
+timestamp, the server refuses ours, and the promise rejects rather than
+pretending.
+
+### Owning a selection of your own
+
+The same rule governs every other selection — a system tray takes
+`_NET_SYSTEM_TRAY_S<screen>`, a clipboard manager takes `CLIPBOARD_MANAGER`,
+an input method takes `XIM_SERVERS` — and there the timestamp is yours to
+supply. Both of the values worth supplying are exported:
+
+```jsx
+import { lastInputTime, serverTime, useApp } from 'react-x11';
+
+const app = useApp();
+
+// the user did something, and ICCCM wants that event's own time
+const take = (wid, selection) =>
+  app.X.SetSelectionOwner(wid, selection, lastInputTime(app));
+
+// nothing did — a tray takes its selection when it starts
+const claim = async (wid, selection) =>
+  app.X.SetSelectionOwner(wid, selection, await serverTime(app));
+```
+
+`lastInputTime(app)` is free: it is the timestamp of the last input event
+this connection saw, which is what react-x11 already stamps copies with, and
+what EWMH calls `_NET_WM_USER_TIME`. It is `undefined` before any input has
+arrived.
+
+`serverTime(app)` is one round trip and always answers. Reach for it when
+there is no user action to name — and **do not** write `lastInputTime(app) ??
+0` instead. Zero is `CurrentTime`, which ICCCM 2.1 forbids for exactly the
+reason above: the server accepts it, two clients racing for one selection
+cannot be ordered by it, and the loser is never told it lost.
+
+`serverTime` resolves `0` if the server has not answered within five seconds.
+It never rejects and never hangs.
+
+## Reaching ntk directly
+
+`useClipboard()` is a thin layer over ntk's `app.clipboard` and adds only the
+vocabulary, the timestamps and the React access. Anything it does not cover
+is one step away:
+
+```js
+const app = useApp();
+await app.clipboard.write(data, { selection: 'MY_SELECTION', time });
+```
+
+`app` is the whole ntk connection — `app.fonts`, `app.cursors`, `app.X` for
+raw protocol. See ntk's own clipboard documentation for the ICCCM details.
+
+## Limits
+
+- **On the Cocoa backend `watch()` polls**, a quarter second behind a copy
+  made elsewhere, and a read of anything but text spawns `osascript` until
+  the bridge has `pasteboardItems`. `PRIMARY` is not a limit there but a
+  platform difference: see [`PRIMARY` is X11-only](#primary-is-x11-only).
+- **No clipboard-manager handoff** (`SAVE_TARGETS`), so the data really does
+  vanish when the app exits.
+- **`STRING` is latin-1 by definition**, so codepoints above U+00FF are lossy
+  in that target. Modern requestors ask for `UTF8_STRING`, which is not — and
+  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).