react-x11 2.51.0 → 2.52.0

package/docs/click-to-component.md

@@ -0,0 +1,125 @@
+# 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 (`src/editor.js`, shared by both).
+
+## 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.
+
+## 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,281 @@
+# 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`, 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,
+> [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;
+> `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.
+
+## 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, and
+  the reason desktops run clipboard managers. Nothing negotiates with one
+  yet.
+- **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,
+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 —
+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 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:
+
+| 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, 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
+`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.
+
+`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()` 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`.
+
+## 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.