react-x11 2.52.0 → 2.54.0

package/docs/testing.md

@@ -2,23 +2,20 @@
 
 `react-x11/test` renders your app through a **real X11 protocol connection
 to a real X server, in this process** — no `$DISPLAY`, no Xvfb, no native
-dependency, works on macOS. So a test can read pixels back with `GetImage`
-and inject input through the server's own grab and focus machinery, which
-means a passing test has exercised the path a user actually takes.
-
-That server is node-x11's `lib/xserver`, written in JavaScript. It arrives
-with ntk, so there is nothing new to install.
+dependency, works on macOS. A test can read pixels back with `GetImage` and
+inject input through the server's own grab and focus machinery, so a
+passing test has exercised the path a user actually takes. The server is
+node-x11's `lib/xserver`, written in JavaScript; it arrives with ntk, so
+there is nothing new to install.
 
 **The harness drives the X11 backend**, on every platform including macOS —
 there is no `'cocoa'` backend for `renderX11()`, and `createRoot()`'s own
-choice does not apply here because the harness always passes it an `app`.
-That is deliberate rather than pending: the point of this harness is a real
-protocol connection to a real server in-process, and macOS has no protocol
-to connect to. What it means in practice is that an app targeting both
-backends tests its **tree, its queries and its behaviour** here — all of
-which are shared — while anything that is genuinely per-backend (a native
-bezel's pixels, an `NSMenu`, a pasteboard flavour) is covered by the
-renderer's own Cocoa tests against a fake bridge, and by looking at a Mac.
+choice does not apply because the harness always passes it an `app`. This
+is by design: macOS has no protocol to connect to in-process. An app
+targeting several backends tests its **tree, its queries and its
+behaviour** here — all shared — while anything genuinely per-backend (a
+native bezel's pixels, an `NSMenu`, a pasteboard flavour) is checked by
+running on that platform.
 
 ```js
 import { test, afterEach } from 'node:test';
@@ -45,10 +42,9 @@ test('adding a task', async () => {
 });
 ```
 
-The vocabulary is Testing Library's, because that is the one React
-developers already have. It is not Testing Library — there is no document
-for it to query — but `getByRole` / `userEvent.click` / `waitFor` mean here
-what they mean there.
+The vocabulary is Testing Library's. It is not Testing Library — there is
+no document for it to query — but `getByRole` / `userEvent.click` /
+`waitFor` mean here what they mean there.
 
 ## `renderX11(element, options)`
 
@@ -130,10 +126,9 @@ point `AT_SPI_BUS_ADDRESS` at an in-process bus instead — see
 
 ## Components
 
-The queries above see what a user sees. Sometimes a test needs the React
-side instead — _which component_ made this node, with what props and state —
-and this is the layer for it. Prefer the user-visible queries when either
-would do; reach here when the question is genuinely about a component.
+The queries above see what a user sees. When a test needs the React side
+instead — _which component_ made this node, with what props and state — this
+is the layer for it. Prefer the user-visible queries when either would do.
 
 ```js
 const row = screen.getByComponent('TaskRow'); // also RegExp or predicate
@@ -147,10 +142,10 @@ sourceOf(node); // { file, line, column } of the JSX that made it
 its output — the container `within()` wants next. Ownership is React's JSX
 owner (_who wrote the element_), so content passed as children belongs to
 the component whose JSX it appears in, and a miss lists the component names
-that are in the tree. All of this reads debug info development React records
-on every fiber (`_debugOwner`, `_debugStack` — the same data
-[click-to-component](click-to-component.md) navigates by), so it costs no
-setup and no dependency, and returns nothing in production builds.
+that are in the tree. All of this reads the debug info development React
+records on every fiber (the data [click-to-component](click-to-component.md)
+navigates by), so it needs no setup and no dependency, and returns nothing
+in production builds.
 
 ### `inspect(node)` and `setHook`
 
@@ -164,19 +159,17 @@ await c.setHook(0, 41); // set a useState/useReducer value…
 await c.setHook(1, ['filter', 'text'], 'milk'); // …or a path inside one
 ```
 
-This drives the **React DevTools backend in-process**: the same
-react-debug-tools inspection and the same override path the DevTools app
-uses, minus its WebSocket — nothing listens on anything, and `ws` is never
-loaded ([devtools.md](devtools.md) has the wiring). It needs the
-`react-devtools-core` package in your devDependencies; the queries above
-work without it.
+This drives the **React DevTools backend in-process** — the same inspection
+and override path the DevTools app uses, minus its WebSocket: nothing
+listens on anything, and `ws` is never loaded ([devtools.md](devtools.md)).
+It needs the `react-devtools-core` package in your devDependencies; the
+queries above work without it.
 
 What to know before leaning on it:
 
-- **Reading hooks re-runs the component.** That is how react-debug-tools
-  recovers hook names: the render function is invoked once under a stub
-  dispatcher, output discarded, `console` muted. A render-counting test
-  will see it.
+- **Reading hooks re-runs the component** once, output discarded and
+  `console` muted — that is how hook names are recovered. A render-counting
+  test will see it.
 - **Values:** `props` and editable hook values are the live objects;
   everything else is DevTools' copy — primitives exact, deep objects as
   the same previews the DevTools panel shows.
@@ -211,7 +204,7 @@ await userEvent.wheel(list, { deltaY: 0.25, smooth: true }); // a touchpad
 await userEvent.clickOutside(); // dismisses a menu — see below
 ```
 
-Two things this buys that emitting on the ntk window never could:
+Input goes through the server, so:
 
 **Grabs are real.** A `<popup grab>` is dismissed by a real press outside
 it. But note _where_ outside: react-x11's popups grab with **owner events**,
@@ -222,17 +215,15 @@ how a test says that; clicking another widget and expecting the menu to close
 is testing the wrong thing.
 
 **Focus is real**, so `trapFocus`, `autoFocus` and Tab traversal are
-exercised rather than simulated. Deciding which window gets the keyboard is a
-window manager's job and there is no window manager, so `renderX11` plays the
-part with one `SetInputFocus` at mount — otherwise keys would go to whatever
-the pointer happened to be over, which is a rule nobody should have to learn.
-
-**A smooth scroll is the one exception**, and says so. Whole notches go
-through the server as the button presses X really uses, but a touchpad's
-fraction of a notch is XI2, and the in-process server has no XInput — there
-are no valuators to inject. `{ smooth: true }` therefore delivers the `wheel`
-event ntk would have derived from them, straight to the window. Everything
-above it is still the real path: the dispatch, the chain, the default action.
+exercised rather than simulated. There is no window manager, so `renderX11`
+gives the window input focus once at mount — otherwise keys would go to
+whatever the pointer happened to be over.
+
+**A smooth scroll is the one exception.** Whole notches go through the
+server as the button presses X really uses, but a touchpad's fraction of a
+notch is XI2, which the in-process server lacks, so `{ smooth: true }`
+delivers the `wheel` event straight to the window. Everything above it is
+still the real path: the dispatch, the chain, the default action.
 
 **Typing works for text the layout does not have.** `userEvent.type(input,
 'héllo')` binds a spare keycode for `é` on both the server's keymap and the
@@ -349,12 +340,9 @@ event, a re-render of React state and a frame: `act` runs all three, so the
 repaint is on screen when `userEvent.hover` resolves.
 
 It `act`s once more after the attempt that passes, so what it resolves with
-is on screen. That matters for a node. What an attempt finds can have arrived
-in the pause before it — an fs read, a timer — and that commits outside
-`act`, on React's own scheduler, while the frame that lays it out runs on the
-third clock, which need not have ticked since. Without that last `act`, a
-row found that way could have no rect yet, and the click after it would throw
-`has no laid-out rect yet`.
+is on screen and laid out: a row that arrived from an fs read or a timer
+committed outside `act`, and without that last frame the click after it
+would throw `has no laid-out rect yet`.
 
 ```js
 const row = await waitFor(() => screen.getByText('notes.txt'));
@@ -397,14 +385,10 @@ await toPNG(ctx, '/tmp/shot.png', { width: 320, height: 240 });
 ```
 
 A pixel proves the tree, the layout, the clip, the paint order, the colour
-parsing and the wire encoding at once — and it is the only assertion that
-catches the class of bug where everything commits correctly and nothing
-reaches the screen. Two details it demands: the readback is straight
-**RGBA**, as on a canvas, and antialiasing means every comparison takes a
-**tolerance**.
-
-`toPNG` is also how a pull request gets a screenshot rendered by its own
-code, which this repo asks for ([AGENTS.md](../AGENTS.md), "Pull requests").
+parsing and the wire encoding at once — the only assertion that catches
+everything committing correctly and nothing reaching the screen. The
+readback is straight **RGBA**, as on a canvas, and antialiasing means every
+comparison takes a **tolerance**.
 
 ## Animations
 
@@ -420,17 +404,16 @@ clock.restore();
 
 Install it **before** the render. Every timestamp in the tree has to come
 from the same clock: mixing a real start time with a frozen `now` gives a
-transition that never progresses, which is a confusing way to spend an hour.
+transition that never progresses.
 
 ## The desktop's appearance
 
-The built-in palette follows the desktop, so `renderX11` **pins** it: an
-unpinned suite renders in whatever colours the machine running it is in, and
-a pixel assertion passes on a light desktop and fails on a dark one with
-nothing in the test to say why. The pin is light unless the render says
-otherwise, and it covers everything `useSystemAppearance()` reports — so a
-component that follows reduced motion, contrast or the accent is tested the
-way one that follows the scheme is:
+The built-in palette follows the desktop, so `renderX11` **pins** it —
+otherwise a pixel assertion would pass on a light desktop and fail on a
+dark one. The pin is light unless the render says otherwise, and it covers
+everything `useSystemAppearance()` reports, so a component that follows
+reduced motion, contrast or the accent is tested the way one that follows
+the scheme is:
 
 ```jsx
 await renderX11(<App />); // light
@@ -480,13 +463,12 @@ Three mistakes throw rather than pass quietly:
 - **`setAppearance` before `renderX11`.** The render pins as it mounts and
   would replace what was set, so it throws and says to pass `appearance`.
 
-`cleanup()` releases the pin, and only the pin: what a real desktop answered
-is not the harness's to throw away. A pinned value is never written to the
-cache a real app starts its first frame from ([appearance.md](appearance.md)),
-so a suite run on a developer's desktop leaves that desktop's remembered
-answer as it found it — and an answer the desktop sends while a pin is held,
-from a probe a `'system'` test started, is dropped rather than painted into
-the next test.
+`cleanup()` releases the pin, and only the pin. A pinned value is never
+written to the cache a real app starts its first frame from
+([appearance.md](appearance.md)), so a suite run on a developer's desktop
+leaves that desktop's remembered answer as it found it, and an answer the
+desktop sends while a pin is held is dropped rather than painted into the
+next test.
 
 ## The mock backend
 
@@ -502,13 +484,11 @@ rather than failing the mount. A component that asks before rendering one
 mounts its fallback here; one that does not still mounts.
 
 A batch records as the fills it stands for: `ctx.fillRects([[x, y, w, h], …])`
-leaves one `fillRect` operation per rectangle, because the only difference
-between them is a request count and there is no server here to send it to. So
-an assertion on what a drawing painted holds whether or not it batched.
+leaves one `fillRect` operation per rectangle, so an assertion on what a
+drawing painted holds whether or not it batched.
 
 ## Testing Library itself
 
 It does not work here and no shim will fix it: its queries are built on a
-document. The five failure modes are recorded in the
-[negative-results register](ecosystem.md#render-time). This page is the
-replacement, not a workaround for it.
+document ([ecosystem.md](ecosystem.md#render-time) lists the failure
+modes). This page is the replacement.

package/docs/typescript.md

@@ -22,43 +22,16 @@ against React's namespace, which describes the DOM.
 
 ## Why a JSX runtime and not an augmentation
 
-The usual way a library adds elements to JSX is to merge into React's
-namespace:
-
-```ts
-declare module 'react' {
-  namespace JSX {
-    interface IntrinsicElements {
-      window: WindowProps;
-    }
-  }
-}
-```
-
-That cannot work here. Five element names — `text`, `image`, `canvas`,
-`html`, `svg` — are also HTML or SVG element names, already declared by
-`@types/react` with completely different props, and declaration merging
-cannot replace an existing member:
-
-```
-Interface 'IntrinsicElements' incorrectly extends interface 'ReactX11Elements'.
-  The types of 'text.ref' are incompatible between these types.
-    Type 'Ref<SVGTextElement>' is not assignable to type 'Ref<DrawnNode>'.
-```
-
-So react-x11 provides its own JSX source instead — `react-x11/jsx-runtime`,
-which re-exports React's actual runtime and carries a `JSX` namespace of its
-own. That turns out to be the better answer regardless: the namespace holds
-the X11 elements _and nothing else_, so
+react-x11 cannot merge its elements into React's `JSX` namespace: `text`,
+`image`, `canvas`, `html` and `svg` are already declared there by
+`@types/react` with DOM props, and declaration merging cannot replace them.
+So `react-x11/jsx-runtime` re-exports React's runtime with a `JSX` namespace
+of its own that holds the react-x11 elements _and nothing else_:
 
 ```tsx
 <div /> // error: Property 'div' does not exist on type 'JSX.IntrinsicElements'
 ```
 
-is caught at compile time rather than throwing at runtime. An augmentation
-could never have done that, because `@types/react` declares every HTML and
-SVG tag unconditionally.
-
 If you need extra elements of your own, `IntrinsicElements` is an interface,
 so merging still works:
 
@@ -99,19 +72,4 @@ the four yoga values, a state block only takes paint properties (the same
 rule `createStyles` enforces at runtime), and `width` takes
 `number | '50%' | 'auto'`.
 
-## Keeping them honest
-
-Hand-written declarations drift. `test/types/api.tsx` is compiled by
-`npm run typecheck` — in CI alongside lint — and exercises the API the way
-the examples do, including `@ts-expect-error` lines for things that must
-_not_ compile:
-
-```tsx
-// @ts-expect-error — layout properties may not go in a state block
-createStyles({ bad: { ':hover': { padding: 4 } } });
-```
-
-Those fail the build if the rejection stops happening, which is the half of
-a type test that usually goes missing.
-
-When you change a prop, change the declaration and add a line to that file.
+Design notes: [design/typescript.md](../design/typescript.md).

package/docs/uri-schemes.md

@@ -27,15 +27,13 @@ const port = server.address().port;
 ```
 
 No desktop registration, no D-Bus, no install step, and it works on XQuartz,
-in a container and over ssh in ways a scheme handler does not. **For an OAuth
-flow, make this the default and reach for the rest of this page only when you
+in a container and over ssh where a scheme handler does not. **For an OAuth
+flow, make this the default and use the rest of this page only when you
 cannot.**
 
-Custom schemes still earn their place three ways: providers that only accept a
-registered private-use scheme; deep links that are not logins at all
-(`myapp://project/42` out of a chat message, a document opened from a
-launcher); and the fact that owning a name on the bus is the same machinery
-the [global menu](globalmenu.md) and a tray icon need anyway.
+Custom schemes are still needed for providers that only accept a registered
+private-use scheme, and for deep links that are not logins
+(`myapp://project/42` from a chat message, a document opened from a launcher).
 
 ## Four things have to be true
 
@@ -46,7 +44,7 @@ the [global menu](globalmenu.md) and a tray icon need anyway.
 | **Delivery**     | `org.freedesktop.Application.Open`, answered before the UI | `useAppOpen()`          |
 | **The raise**    | `_NET_ACTIVE_WINDOW`, with the right timestamp             | `activateWindow()`      |
 
-The last one is the one that decides whether a user calls the feature working;
+The raise is the one that decides whether a user calls the feature working;
 see [the raise is the part that fails](#the-raise-is-the-part-that-fails).
 
 ## The code
@@ -78,8 +76,7 @@ function App() {
 }
 ```
 
-That is the whole runtime half. What follows is why each line is shaped the
-way it is.
+That is the whole runtime half.
 
 ### `registerApplication()`
 
@@ -106,55 +103,40 @@ process_ because someone called `Open`, and that call is outstanding while the
 app boots — registering from inside a component answers it with an
 unknown-method error, and the launch is lost.
 
-**`appId` is not a free parameter.** The desktop entry spec ties three things
-to one string: the well-known bus name, the `.desktop` file's basename, and —
-by RFC 8252 §7.1 — the URI scheme. The object path follows from it too, and is
-derived rather than passed: dots become slashes, a slash goes on the front,
-and **a dash becomes an underscore**. `com.example.my-app` is served at
-`/com/example/my_app`; get that wrong and the desktop calls a path you do not
-serve, which looks exactly like nothing happening.
+**`appId` is not a free parameter.** The desktop entry spec ties the
+well-known bus name, the `.desktop` file's basename and (RFC 8252 §7.1) the URI
+scheme to one string. The object path is derived from it: dots become slashes,
+a slash goes on the front, and **a dash becomes an underscore**
+(`com.example.my-app` is served at `/com/example/my_app`).
 
 **`null` means there is no session bus** — ssh, a bare `startx`, a container,
 CI, Node 20 without the transport. The app runs as an ordinary single-window
 program. A URI that arrived in `argv` is still delivered to `useAppOpen`: a
 cold-start deep link needs no bus, only a second instance does.
 
-**A malformed `appId` or an unusable scheme throws**, and that is not a hole in
+**A malformed `appId` or an unusable scheme throws**, which is not a hole in
 [the never-throws rule](dbus.md#the-rule-everything-else-is-subordinate-to):
-`null` means "this machine has no bus", and using it for a typo would hide the
-typo on every box without one.
+`null` means "this machine has no bus", and a typo must not hide behind it.
 
 ### Two dispatch paths, and why `role` exists
 
-The desktop entry spec makes D-Bus activation sound like the whole story.
-`DBusActivatable=true`, and implementations _should_ ignore `Exec` and send a
-D-Bus message instead. _Should_ — and the most common opener does not.
-
-- **GIO honours it.** `g_app_info_launch_default_for_uri` calls `Open` on the
-  app's well-known name. `gio open`, and most of GNOME, take this path.
-- **`xdg-open`'s generic fallback does not.** It resolves the handler with
-  `xdg-mime query default`, reads the `Exec` key and runs it;
-  `DBusActivatable` is never read on that branch. Chromium shells out to
-  `xdg-open`, and `xdg-open` takes the generic branch on every desktop it
-  cannot identify — which is every WM-only session, react-x11's own persona.
-
-So on half of all desktops **a second copy of your app is spawned with the URI
-in `argv`**, and it has to hand that URI to the first copy and exit. An app
-that only exports the interface opens a second window every time.
-`registerApplication` does both halves, which is why it answers a role:
+Openers that honour `DBusActivatable=true` (GIO: `gio open`, most of GNOME)
+call `Open` on the running app. `xdg-open`'s generic fallback — which Chromium
+uses, and which every WM-only session gets — ignores it and runs the `Exec`
+line, so **a second copy of your app is spawned with the URI in `argv`**.
+`registerApplication` handles both: the second copy forwards the URI to the
+first and reports its role.
 
 | `role`        |                                                                    |
 | ------------- | ------------------------------------------------------------------ |
 | `'primary'`   | this process owns the name and will receive `Open`                 |
 | `'secondary'` | another instance owns it; this launch was forwarded — **exit now** |
 
-It does not call `process.exit()` for you. Exiting is an application decision
-and a library that takes it is a library that surprises somebody.
+It does not call `process.exit()` for you; exiting is the app's decision.
 
 A second launch with **no** URI forwards `Activate` rather than an empty
-`Open`: "the user started the app again" and "the user clicked a link" are
-different events, and an app that cannot tell them apart cannot answer the
-first one properly.
+`Open`, so "the user started the app again" and "the user clicked a link"
+arrive as different events.
 
 ### Delivery: buffered, and replayed
 
@@ -183,14 +165,12 @@ interface LaunchContext {
 }
 ```
 
-There is **nothing to wrap** — no provider, no prop drilling. An application
-has one identity on the desktop, so the registration is process-global and a
-component library can call these hooks.
+There is **nothing to wrap** — no provider, no prop drilling. The registration
+is process-global, so a component library can call these hooks.
 
 `schemes` filters what arrives: a URI whose scheme you did not register is
 dropped before your handler sees it. `file:` is always allowed alongside them,
-because `Open` is also how a file manager says "open this document with you"
-and declaring a custom scheme must not stop your app opening its own files.
+because `Open` is also how a file manager says "open this document with you".
 Declaring no schemes at all filters nothing.
 
 ### The raise is the part that fails
@@ -207,13 +187,11 @@ and this app's currently active toplevel. `target` is anything
 [`windowIdOf()`](elements.md) accepts, or nothing — in which case this app's
 only top-level window is used, its focused one when it has several.
 
-**The timestamp is the whole feature.** Per the startup-notification protocol
-the digits after `_TIME` in a startup id are the X timestamp of the user action
-that triggered the launch, and that timestamp is what a window manager's
-focus-stealing prevention weighs before letting a window come forward. Get it
-wrong and nothing reports an error: the user finishes logging in, the browser
-redirects, your app receives the code correctly, the WM declines, and the
-taskbar entry blinks. Every layer says it worked.
+**The timestamp is the whole feature.** A window manager's focus-stealing
+prevention weighs the X timestamp of the user action that triggered the launch
+(the digits after `_TIME` in the startup id). Get it wrong and nothing reports
+an error: the app receives the code, the WM declines to raise it, and the
+taskbar entry blinks.
 
 | `timestamp`     |                                                                                                               |
 | --------------- | ------------------------------------------------------------------------------------------------------------- |
@@ -221,18 +199,15 @@ taskbar entry blinks. Every layer says it worked.
 | `ctx.timestamp` | **what a deep link should pass**: the click in the browser is the user action, not whatever this app last saw |
 | `null`          | `CurrentTime`; legal, and most window managers will decline it                                                |
 
-The return value is whether the request was **issued**, not whether it worked.
-EWMH is explicit that the window manager may refuse and set
-`_NET_WM_STATE_DEMANDS_ATTENTION` instead — that is the blinking taskbar entry,
-it is the WM's call, and no client can tell the difference from here.
+The return value is whether the request was **issued**, not whether it worked:
+the window manager may refuse and set `_NET_WM_STATE_DEMANDS_ATTENTION`
+instead (the blinking taskbar entry), and no client can tell.
 
 ## Registration: the half that is not runtime code
 
-react-x11 does **not** write into `~/.local/share` for you. A library that
-edits a user's data directory on import is the kind of thing that surprises
-people, and it cannot work for a system-installed or Flatpak app anyway. Ship
-these from your installer, your package, or a one-line setup command your users
-run.
+react-x11 does **not** write into `~/.local/share` for you (that would not
+work for a system-installed or Flatpak app anyway). Ship these from your
+installer, your package, or a setup command your users run.
 
 `~/.local/share/applications/com.example.myapp.desktop` — the basename is tied
 to the bus name by the spec:
@@ -269,10 +244,6 @@ Exec=/usr/bin/my-app
 
 ### Checking it by hand
 
-Neither branch below is reachable from `npm test` — the in-process broker has
-no service activation and no security policy — so this is the pass that covers
-them:
-
 ```bash
 gio open com.example.myapp://test              # path A: D-Bus activation
 ```
@@ -292,23 +263,21 @@ into an issue.
 The URI is attacker-controlled input from an unauthenticated local caller.
 
 - **Scheme squatting is unfixable and expected.** Nothing in the MIME database
-  enforces uniqueness; the last handler to register wins. RFC 8252 §7.1 says as
-  much, which is why §6 requires PKCE for public native clients — **use it**,
-  and do not treat receiving a code as proof of anything. The reverse-domain
-  naming rule is the other half of the mitigation, and it is why `appId` is
-  validated the way it is.
+  enforces uniqueness; the last handler to register wins. RFC 8252 §6 requires
+  PKCE for public native clients — **use it**, and do not treat receiving a
+  code as proof of anything. The reverse-domain naming rule (why `appId` is
+  validated) is the other half of the mitigation.
 - **`Open` is callable by any peer on the session bus.** It is not an
-  authenticated entry point. The bus is a per-user socket, not an authorization
-  check. Validate what you receive, and never turn a URI's path into a
-  filesystem path.
+  authenticated entry point: the bus is a per-user socket, not an
+  authorization check. Validate what you receive, and never turn a URI's path
+  into a filesystem path.
 - **`platform_data` is spoofable.** A hostile local process can fabricate a
   `desktop-startup-id` and make your app raise itself. Same uid, so it is focus
   theft rather than data loss — but treat `ctx.timestamp` as a hint, not a
   credential.
 - **On the `xdg-open` path the URI lands in `argv`**, so a code is briefly
-  visible in `/proc/<pid>/cmdline` to processes of the same user. One more
-  reason to point login flows at loopback first; the D-Bus path does not have
-  this property.
+  visible in `/proc/<pid>/cmdline` to processes of the same user. The D-Bus
+  path does not have this property; loopback avoids it too.
 - **Never log the URI.** react-x11 does not: everything on
   `REACT_X11_DEBUG_URI` goes through a redaction that drops the query, the
   fragment and any userinfo. Hold your own logging to the same rule — the code
@@ -317,9 +286,8 @@ The URI is attacker-controlled input from an unauthenticated local caller.
 ## On macOS
 
 The same hooks, a different transport. On the cocoa backend the OS talks to
-the application as a whole through **Apple Events**, and `@windowkit/appkit`
-(≥ 0.5) forwards them as backend events the renderer routes into the very
-same delivery as a D-Bus `Open`:
+the application through **Apple Events**, which `@windowkit/appkit` (≥ 0.5)
+forwards into the same delivery as a D-Bus `Open`:
 
 |                                                    |                                                                                                                     |
 | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
@@ -342,39 +310,31 @@ Three things differ from the bus, and none of them changes app code:
   (see [packaging.md](packaging.md)). A bare `node` process receives nothing
   from Launch Services, because there is no bundle for it to look up.
 
-Quit is worth a sentence, because macOS asks the app before ending it. The
-bridge answers `applicationShouldTerminate:` with "cancel" and hands the
-question over, so a quit becomes the same close request the red light sends
-to the app's primary window: an `onCloseRequest` that opens a "save your
-work?" dialog has vetoed it until it decides, and one that unmounts has
-accepted it. Once the app has closed on a quit, the process ends
+A quit becomes the same close request the red light sends to the app's primary
+window: an `onCloseRequest` that opens a "save your work?" dialog has vetoed it
+until it decides, and one that unmounts has accepted it. Once the app has
+closed on a quit, the process ends
 (`createRoot({ cocoa: { exitOnQuit: false } })` turns that off for an embedder
-that owns the process). One limit to know: because the bridge's answer is
-"cancel" rather than "later", a **logout** is cancelled by macOS the moment it
-asks, and the app then quits on its own — the logout has to be started again.
+that owns the process). One limit: a **logout** is cancelled by macOS the
+moment it asks, and the app then quits on its own — the logout has to be
+started again.
 
 ## Over ssh
 
 Both mechanisms only work when the browser runs on the **same host as the
 app**. A URL pasted into your laptop's browser reaches neither a loopback port
-nor a scheme handler on the server you are `ssh -X`'d into. That is not fixable
-here; it is the shape of the problem.
+nor a scheme handler on the server you are `ssh -X`'d into.
 
 ## Deliberately not here
 
-- **`ActivateAction` beyond a correct reply.** Desktop actions (jump-list
-  entries) want a design alongside the global menu. The method answers properly
-  today, and `onAction` is there if you want it — a stub that _errors_ would
-  make a shell conclude the app is broken rather than that the action is
-  unhandled.
-- **Writing `.desktop` files.** See above. A generator belongs with the
-  packaging work ([packaging.md](packaging.md)), not on an import.
-- **A full OAuth client.** This is the transport for a redirect, not a PKCE
-  implementation or a token store.
-- **`http`/`https` handling.** Being the default browser is not this.
-- **Wayland's `xdg-activation` token.** `platform_data.activation-token` is
-  read and exposed on `ctx`, and ignored. On the
-  [Wayland backend](wayland-backend.md) `activateWindow()` does go through
-  xdg-activation, but with a token it requests itself against the seat's
-  last input serial (`src/wayland/app.js`, `activate`) — the launcher's token
-  is not handed to the compositor.
+- **Desktop actions** (jump-list entries): `ActivateAction` replies correctly
+  and `onAction` receives it; nothing more.
+- **Writing `.desktop` files** — your installer's job (see above).
+- **A full OAuth client** — no PKCE implementation or token store.
+- **`http`/`https` handling** — being the default browser is not this.
+- **The launcher's Wayland `xdg-activation` token** is exposed on
+  `ctx.activationToken` and otherwise ignored; on the
+  [Wayland backend](wayland-backend.md) `activateWindow()` requests a token of
+  its own.
+
+Design notes: [design/uri-schemes.md](../design/uri-schemes.md).