react-x11 2.51.0 → 2.52.0

package/docs/desktop.md

@@ -0,0 +1,648 @@
+# Desktop integration
+
+What an app has to tell the desktop about itself, beyond drawing. Today that
+is startup notification, which is on by default and has nothing to call; the
+launcher's view of the app — a badge on its icon, a bounce for attention, the
+Dock's menu; what a password field has to do to be reachable by the desktop's
+password managers; and the one switch that turns off everything here that
+talks over D-Bus.
+
+The menu bar is the other half of this and has a page of its own —
+[globalmenu.md](globalmenu.md) — because on a desktop that shows application
+menus in its panel, `MenuBar` hands the menu over and stops drawing. Same
+default shape as startup notification: on with no configuration, and one
+switch to turn it off.
+
+Everything on this page is the app talking _outwards_. The one thing that
+comes the other way — the desktop handing the app a `myapp://…` link to open,
+and the single-instance question that goes with it — is
+[uri-schemes.md](uri-schemes.md). It shares the launch timestamp described
+below: `ctx.timestamp` there is the same `_TIME` suffix `launchTimestamp()`
+parses here, and for the same reason.
+
+## Startup notification
+
+When a launcher spawns an app it opens a **startup sequence** — that is what
+the busy cursor is — and closes it when the app says it is up. An app that
+never says so leaves the sequence running until the desktop gives up on it:
+mutter's `STARTUP_TIMEOUT_MS` is 15 seconds, long after the window is on
+screen and being clicked. The mutter source is blunt about what that looks
+like, in a comment on the constant itself: people assume the launch failed
+and start it again.
+
+Two other things ride on the same handshake:
+
+- **Focus.** `_NET_WM_USER_TIME` is the evidence focus-stealing prevention
+  weighs when deciding whether a new window may come to the front. With
+  none, a strict desktop opens the window behind whatever the user was
+  doing — correctly, from its point of view, since nothing said a user asked
+  for this.
+- **Placement.** The sequence records which workspace the launch happened
+  on. Without one the window goes wherever new windows go.
+
+react-x11 does all of it with no configuration:
+
+```jsx
+const root = await createRoot(); // that is the whole of it
+```
+
+`DESKTOP_STARTUP_ID` is read from the environment and **removed from it**.
+That is deliberate and it matters: the variable names one launch, so a child
+process that inherits it would claim a sequence that is not its own and end
+it early — the parent's cursor stops when the child starts. Every toolkit
+that gets this wrong produces that same bug.
+
+With no id in the environment — a terminal, CI, XQuartz — nothing is set and
+nothing is sent.
+
+### When is an app "started"?
+
+The default is **the first frame that actually painted**.
+
+GTK ends the sequence when the toplevel maps, and copying that here would be
+subtly wrong. This renderer does not paint on map: `invalidate()` schedules
+through the frame clock and the drawing lands in `flush()` a frame later. So
+a mapped window is an empty rectangle, and stopping the busy cursor there is
+compliant and dishonest — it says "ready" over a blank window.
+
+A suspense fallback counts as painted, and should. If the first frame is a
+spinner because the tree is waiting on data, that is exactly the right
+moment to stop the _system's_ spinner: the app is up and is telling the user
+what it is doing. There is no signal for "finished loading", and guessing at
+one is how this ends back at fifteen seconds.
+
+`completeOn` is there for apps the default does not suit:
+
+```jsx
+await createRoot({ startupNotification: { completeOn: 'map' } });
+```
+
+| `completeOn` |                                                         |
+| ------------ | ------------------------------------------------------- |
+| `'paint'`    | the first frame that drew (default)                     |
+| `'map'`      | the first toplevel mapping — earlier, and what GTK does |
+| `'manual'`   | nothing automatic; call `notifyStartupComplete()`       |
+
+`'map'` suits an app whose first frame is expensive enough that it would
+rather the cursor stopped before it. `'manual'` suits one that is not up
+until it says so — restoring a session behind a splash, say:
+
+```jsx
+import { notifyStartupComplete } from 'react-x11';
+
+await createRoot({ startupNotification: { completeOn: 'manual' } });
+await restoreSession();
+notifyStartupComplete(); // idempotent, and a no-op if there is no sequence
+```
+
+**A backstop ends the sequence regardless**, ten seconds after the window
+maps, whichever mode is in force. An app that never paints, or that forgets
+to call, cannot leave the cursor spinning — which would be this feature
+reproducing the bug it exists to fix. Ten is chosen to beat mutter's fifteen
+by a margin while being far longer than any honest first frame.
+
+### Turning it off, and supplying an id
+
+```jsx
+await createRoot({ startupNotification: false });
+await createRoot({ startupNotification: 'launcher/app/1-0_TIME9876' });
+```
+
+`false` is for an app that runs its own sequence, or an embedder that owns
+the toplevel. Note that opting out leaves `DESKTOP_STARTUP_ID` in the
+environment — if you are managing the sequence yourself, the id is yours to
+read and yours to clear.
+
+A string supplies the id for a launch where it did not arrive in the
+environment. A D-Bus-activated app gets it in `platform_data` instead.
+
+### `launchTimestamp()`
+
+```jsx
+import { launchTimestamp } from 'react-x11';
+
+const when = launchTimestamp(); // number | null
+```
+
+The X server timestamp of the user action that launched the app, parsed from
+the id's `_TIME` suffix. **`null` is a real answer**, not a failure: an app
+started from a shell has no launch timestamp and never will.
+
+It is the "when" that any later request to come forward is weighed against.
+Do not substitute `0` for a missing one — EWMH gives zero its own meaning,
+"do not focus this window when it maps".
+
+### On macOS
+
+quartz-wm implements none of this, so on XQuartz the messages go to a root
+window nobody is listening at and `_NET_WM_USER_TIME` is ignored. Harmless,
+and worth knowing before concluding from a Mac that the feature is broken.
+
+### What is deliberately not here
+
+- **The launcher half.** An app that spawns _another_ app should generate an
+  id, send `new:`, put `DESKTOP_STARTUP_ID` in the child's environment and
+  close the sequence itself. Same encoder, different persona.
+- **Ongoing `_NET_WM_USER_TIME` maintenance.** Setting it once at launch is
+  this. Keeping it current on every keypress is a separate design with a
+  real cost — EWMH is explicit that storing a frequently-changing property
+  on the toplevel wakes every client watching that window, which is what
+  `_NET_WM_USER_TIME_WINDOW` exists to avoid.
+
+### Security
+
+The id is broadcast to the root window, so every client on the display sees
+it. On X11 that is the pre-existing no-isolation story rather than a new
+exposure — see [security.md](security.md) — but it is the reason the
+messages carry the id the launcher gave us and nothing invented, and the
+reason the variable's value is never logged.
+
+## The launcher: a badge, attention, and the Dock menu
+
+The one thing an app says to the desktop that the user reads without opening
+it is the mark on its icon — an unread count on the Dock tile, a dot on the
+taskbar entry. What lives here is on a backend only where that backend has a
+mechanism for it:
+
+|                       | Linux (`launcherentry`)                                                                            | macOS (`cocoa`)                                      | Windows (`taskbar`)                                                                                                                                                                                  |
+| --------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| a **badge**           | `com.canonical.Unity.LauncherEntry` — KDE, elementary, Cairo-Dock listen; GNOME needs an extension | `NSDockTile.badgeLabel`                              | an overlay icon with the label drawn into it                                                                                                                                                         |
+| badge **text**        | — the protocol carries a count and nothing else                                                    | any label                                            | up to three glyphs; longer clamps to `99+`, and it is ~16px on screen                                                                                                                                |
+| **progress**          | `useProgress(0…1)` — a bar across the tile                                                         | — `NSDockTile` has none                              | `ITaskbarList3::SetProgressValue`, across the taskbar button                                                                                                                                         |
+| **attention**         | `states={['demands_attention']}`, or `setUrgent()` for the launcher entry itself                   | the same prop: the Dock icon bounces until activated | `FlashWindowEx`                                                                                                                                                                                      |
+| the **launcher menu** | `useLauncherMenu(items)` — the launcher protocol's quicklist                                       | `useLauncherMenu(items)`                             | — the taskbar button's menu is the jump list, whose entries start a _new_ process, so it is `features.tasks` and `useJumpList` rather than this ([windows-integrations.md](windows-integrations.md)) |
+| **tasks**             | — `Actions=` in the `.desktop` file, not driven from here                                          | —                                                    | `useJumpList(tasks)` — the jump list's Tasks category                                                                                                                                                |
+| a **hover toolbar**   | —                                                                                                  | —                                                    | `useThumbnailToolbar(buttons)` — up to seven, under the preview                                                                                                                                      |
+| **recent documents**  | —                                                                                                  | — the platform has one; this backend does not use it | `useRecentDocument(path)` — the shell's Recent lists                                                                                                                                                 |
+
+### The badge
+
+```jsx
+import { setBadge, useBadge } from 'react-x11';
+
+useBadge(unread); // a count: 3 shows "3", 0 clears
+await setBadge(null); // the imperative twin, for code with no component
+```
+
+A badge is a **count**, because that is the one shape both desktops agree
+on: a number shows on both. A string (`'•'`, `'!'`) shows on macOS, where the
+tile takes any label, and is a visible count of nothing on Linux, where the
+protocol has no text field — pass one only where the Mac is the audience.
+`0`, `null` and `''` all clear it. `useBadge` clears on unmount; `setBadge`
+resolves to whether a launcher was told and never rejects for anything about
+the machine.
+
+On Linux the count travels as one D-Bus signal, `LauncherEntry.Update`,
+attributed to the app by `application://<appId>.desktop` — so it needs the
+identity [`registerApplication({ appId })`](uri-schemes.md) establishes and
+a `.desktop` file of that name, or the launcher has nothing to pin the
+count to and `setBadge` resolves `false`. The entry stays on the bus while
+a badge is shown and is released when it is cleared. A launcher that starts
+after the badge was set will not see it until the next `setBadge`; the
+protocol has no query.
+
+### Progress
+
+```jsx
+import { useProgress, setProgress } from 'react-x11';
+
+useProgress(downloaded / total); // 0…1; null or undefined clears it
+await setProgress(null); // the imperative twin
+```
+
+A bar drawn across the app's icon, for a download, an export, a long build.
+Out-of-range values are clamped rather than refused — a caller dividing by a
+total that briefly went to zero should not get an exception.
+
+**Linux launchers only.** `NSDockTile` has no progress bar; an app that wants
+one on a Mac draws it into a custom tile view, which is app-side art rather
+than a call. `useDesktopCapability('launcher').features.progress` is the
+honest answer to branch on.
+
+### Attention
+
+Nothing new to call: `<window states={['demands_attention']}>` is the
+existing request, and on the cocoa backend it is
+`NSApp.requestUserAttention` — the Dock icon bounces until the user
+activates the app, and stops when the prop drops the state or the window
+goes away. AppKit ignores the request while the app is already active, which
+is the same outcome a window manager gives a focused window's urgency hint.
+`fullscreen`, `maximized` and `hidden` are AppKit's full-screen Space, zoom
+and miniaturize there (@windowkit/appkit 0.30.0), and the other `states`
+names are inert on that backend.
+
+### The Dock menu
+
+```jsx
+useLauncherMenu([
+  { label: 'New Window', onSelect: openWindow },
+  { type: 'separator' },
+  {
+    label: 'Recent',
+    items: recent.map((r) => ({ label: r.name, onSelect: () => open(r) })),
+  },
+]);
+```
+
+The same `items` vocabulary `MenuBar` and `ContextMenu` take ([menuitem
+names](globalmenu.md)), so one authoring model covers the window's menu, the
+panel's, the tray's and the Dock's. Installed while the component is mounted,
+replaced when `items` changes, taken down on unmount.
+
+`NSDockTile`'s menu on the cocoa backend; on Linux it is the launcher
+protocol's **quicklist** — an object path to a `com.canonical.dbusmenu` tree,
+which is the same menu protocol the tray and the global menu already speak.
+ubuntu-dock/Dash-to-Dock, Plank and the Unity-heritage launchers render it.
+
+> An earlier version of this page said the freedesktop counterpart was
+> `Actions=` in the `.desktop` file, an install step rather than runtime code.
+> That is a different feature wearing a similar hat: desktop actions are the
+> right place for entries that must work **while the app is not running**, and
+> the quicklist is the right place for a menu that follows the app's state.
+
+Like the badge, it needs the identity
+[`registerApplication({ appId })`](uri-schemes.md) establishes and a
+`.desktop` file of that name for a launcher to attach it to.
+
+### The app's presence
+
+Two things the Dock and the ⌘-Tab switcher show that a bare `node` process
+gets wrong, as root options on the cocoa backend:
+
+```js
+await createRoot({
+  cocoa: {
+    appName: 'Notes', // what the Dock, ⌘-Tab and the app menu print (was "node")
+    activationPolicy: 'regular', // 'accessory' for a menu-bar app: no tile, no ⌘-Tab entry
+  },
+});
+```
+
+`activationPolicy` is fixed before the app finishes launching — a Regular
+launch registers a Dock tile, and an agent app that switched afterwards would
+already have flashed its icon — so it is a root option rather than a hook.
+`appName` renames LaunchServices' record of an unbundled process; a bundle's
+`Info.plist` wins, as it should.
+
+## The tray
+
+```jsx
+import { useTray } from 'react-x11';
+
+const { available, backend, features, error } = useTray({
+  icon: 'mail-unread', // a themed icon name (an SF Symbol on macOS), or PNG bytes
+  tooltip: 'Notifications',
+  menu: [
+    { label: 'Open', onSelect: open },
+    { type: 'separator' },
+    { label: 'Quit', onSelect: quit },
+  ],
+});
+```
+
+An icon in the system tray for as long as the component is mounted. With
+`menu` a click opens it — the same `items` vocabulary as `MenuBar` and the
+Dock menu, so the three menus an app puts on the desktop are one authoring
+model. Without one, `onClick` gets the button, where the click was and, where
+the backend knows it, the item's screen rect — all in logical screen pixels,
+the unit a `<popup>`'s `x`/`y` are in, and what a popover under the item
+anchors to ([elements.md](elements.md#a-popover-under-a-tray-item)). `title` shows text beside the icon or alone;
+`visible`, `tooltip`, `attention` and the rest follow their values while
+mounted, and the item is removed on unmount. `null` means no item.
+
+Several trays coexist: each is its own item.
+
+|                 | Linux (`statusnotifier`)                | macOS (`cocoa`)              | Windows (`shellnotifyicon`) |
+| --------------- | --------------------------------------- | ---------------------------- | --------------------------- |
+| mechanism       | `org.kde.StatusNotifierItem` over D-Bus | `NSStatusItem`               | `Shell_NotifyIcon`          |
+| menu            | `com.canonical.dbusmenu`                | `NSMenu`                     | a tracked popup menu        |
+| icon by name    | the desktop's icon theme                | SF Symbols                   | — no icon theme to name     |
+| icon by bytes   | ARGB32 pixmap                           | a template image             | an `HICON` from RGBA        |
+| title           | text beside the icon                    | text beside the icon         | — an icon and a tooltip     |
+| attention       | `Status = NeedsAttention`               | —                            | —                           |
+| click rect      | —                                       | the item's frame             | —                           |
+| click modifiers | —                                       | shift/control/option/command | —                           |
+| scroll          | `Scroll(delta, orientation)`            | —                            | —                           |
+
+**On Linux** this is StatusNotifierItem, which is D-Bus only — so it works
+identically under X11, XWayland and Wayland. It needs something _hosting_ a
+tray: KDE Plasma and most panels do out of the box, and GNOME needs an
+AppIndicator extension. A stock GNOME session with no extension has no tray,
+`available` is `false`, and nothing is logged, because that is a
+configuration rather than a fault.
+
+**A click's position on Linux** is a point whose unit the protocol never
+names, and hosts differ. Plasma sends device pixels, and so does GNOME in its
+physical layout, the default up to GNOME 49. GNOME's logical layout — the
+default from 50, and on Fedora and Debian 13 before it — sends logical
+pixels, as xfce4-panel, LXQt and Cinnamon do. So the point is read both
+ways: a reading that lands on no monitor is dropped, then the one the pointer
+is on is kept, and otherwise the numbers are taken as sent. What that cannot
+tell apart is a device-pixel host under XWayland whose tray, read as logical
+pixels, still lands on a monitor — in the top-left quarter of the screen, or
+with another monitor beyond it — and there the point is `scale` times as far
+from the screen's origin as the click was.
+
+**On the cocoa backend** this is `NSStatusItem`, the menu-bar extra. A
+menu-bar app that wants no Dock tile pairs it with
+`createRoot({ cocoa: { activationPolicy: 'accessory' } })` above. A PNG icon
+is drawn as a **template** — its shape in the bar's ink, so it follows light
+and dark the way a symbol does; `template: false` keeps its colours. AppKit
+is handed a new `NSMenu` only when the menu's items change, so a title that
+ticks every second leaves the menu alone, whether `menu` is memoized or
+written inline.
+
+### What the hook hands back
+
+`available` **settles**. Finding a freedesktop tray takes a bus round trip, so
+it is `false` on the first frame and `true` a tick later if a host is there —
+render the fallback first and upgrade, never the other way round. It follows
+the host for the life of the item, so a panel that exits flips it back.
+
+**`settled` says whether `available` is an answer yet.** For a feature inside
+a window the order above is all an app needs. For an app whose whole UI is its
+tray item, the fallback _is_ a window, and rendering it first flashes a window
+up and away on every start on a desktop that has a tray. So wait for the
+answer instead:
+
+```jsx
+const tray = useTray({ icon: 'waveform', onClick: open });
+if (!tray.settled) return null; // a bus round trip, not a timeout
+if (!tray.available) return <window title="Hush">{controls}</window>;
+return popover;
+```
+
+It is `true` on the first frame on macOS, where the status item is made there
+and then, and for `useTray(null)`; on the freedesktop tray it turns `true` once
+the host has taken or refused the item, and stays so.
+
+`features` is the same vocabulary [feature discovery](#feature-discovery)
+uses, for the rung that answered. Read it instead of testing the platform:
+
+```jsx
+// Right: ask about the thing you need.
+{
+  features.clickModifiers && <ShiftClickHint />;
+}
+```
+
+`error` is the fourth field because **"this desktop has no tray" and "there is
+a tray and it refused me" are different facts**, and only one of them has a
+fix. A missing tray leaves `error` null; a host that rejected the registration
+puts the reason there.
+
+## Feature discovery
+
+Everything on this page is a _ladder_, and which rung a machine lands on
+changes what the app may do. `available` alone is not enough to branch on,
+because it is true on machines that mean very different things by it — a
+notification daemon with `actions` gives you a banner with buttons that call
+back, and `notify-send` gives you one-way text with an urgency and an icon.
+An app that posts reply buttons on the second one gets a banner with no
+buttons and no callback, silently.
+
+So the unit of discovery is a **feature set**, not a flag:
+
+```jsx
+import { useDesktopCapability } from 'react-x11';
+
+const notifications = useDesktopCapability('notifications');
+
+if (notifications.features.actions) return <ReplyFromBanner />;
+if (notifications.available) return <BannerThenOpenApp />;
+return <InAppToastOnly />;
+```
+
+`{ available, backend, features, settled }`. `backend` names the **mechanism** —
+`'dbus'`, `'cocoa'`, `'statusnotifier'`, `'launcherentry'`, `'notify-send'`,
+`'osascript'`, `'win32'`, `'shellnotifyicon'`, `'taskbar'` — and never the
+platform, so that a second Linux mechanism does not need a second name for
+Linux.
+
+A backend **declares** its mechanism rather than having one inferred from it,
+because backends install the same method names for the same rung on purpose —
+that sharing is what makes `useTray` one hook — so there is nothing in the
+methods to tell two of them apart. Branch on `features`; `backend` is for logs
+and bug reports.
+
+`settled` is `false` until the first probe answers and `true` from then on, so
+an app can hold its fallback back rather than flash it; it is `true` on the
+first frame for the answers that need nothing asked, the tray and the Dock tile
+on macOS.
+
+Capability names are `'notifications'`, `'tray'` and `'launcher'`.
+`desktopCapability(name)` is the imperative twin for code with no component.
+
+### Which one to ask
+
+A hook that _does_ the thing already knows whether it worked, and that
+measurement beats any prediction:
+
+- **`useTray(options)`** — "did my icon get taken?" It tried; it knows.
+- **`useDesktopCapability('tray')`** — "would one be taken if I asked?" This
+  is what a settings screen needs: a "Show tray icon" checkbox has to render
+  correctly _without_ putting an icon in the tray to find out.
+
+Prefer the feature hook wherever the feature is actually mounted. Both read
+the same probe, so they cannot disagree.
+
+### Degrading well
+
+Three rules, in the order they matter:
+
+1. **Render the fallback first.** Every desktop answer takes a round trip, so
+   the first frame has none. Upgrading a fallback is invisible; downgrading a
+   feature the user already reached for is not.
+2. **Never disable a feature permanently on a `false`.** A panel restarts, an
+   extension is enabled, a daemon is installed. The hooks re-probe on
+   `NameOwnerChanged` and nothing is cached — an app that latched the first
+   answer would outlive every one of those fixes.
+3. **A missing desktop service is not an error.** No bus, no tray host, no
+   notification daemon and no launcher are all ordinary states of a healthy
+   machine. Nothing is logged and nothing throws; the feature is simply not
+   there. Reserve `error` for a service that answered and then refused.
+
+### All of it, in one app
+
+`examples/desktop.jsx` (`npm run examples:desktop`) is a backup agent that
+uses every hook on this page at once — the tray icon with its attention state
+and its overlay, the badge, the progress bar, the quicklist, the urgency flag,
+and a banner whose buttons are offered only where the daemon has `actions` —
+and whose second pane renders `useDesktopCapability()` for each of
+`CAPABILITIES` beside the live answers, so the prediction and the measurement
+are on screen together. It is the one to read when the question is what an app
+will get on a machine you do not have. The three feature-sized examples are
+`badge.jsx` (the launcher), `tray.jsx` (the tray) and `notify.jsx` (the
+notification).
+
+## Turning the desktop off
+
+Three things react-x11 turns on for you reach the **session bus**, and none
+of them was asked for:
+
+|              |                                                                         |                                      |
+| ------------ | ----------------------------------------------------------------------- | ------------------------------------ |
+| `appearance` | following the desktop's light/dark, accent, contrast and reduced motion | [appearance.md](appearance.md)       |
+| `a11y`       | the AT-SPI bridge — whether a screen reader can see the app             | [accessibility.md](accessibility.md) |
+| `globalMenu` | a `MenuBar` handing its menu to the panel instead of drawing it         | [globalmenu.md](globalmenu.md)       |
+
+Each is the right default: an app that follows the desktop looks like it
+belongs there, one a screen reader can read is one more person can use, and a
+menu in the panel is what the panel is for. But sooner or later an embedder
+owns the thing we assumed was ours, and until
+[#417](https://github.com/sidorares/react-x11/issues/417) the only way out was
+an **environment variable** — `NO_AT_BRIDGE=1`,
+`REACT_X11_NO_GLOBAL_MENU=1`, or unsetting `DBUS_SESSION_BUS_ADDRESS`. That is
+a seam an app cannot reach for itself: the environment is inherited, so
+setting one before `createRoot()` sets it for every child process too, and the
+D-Bus one takes the portals and the app's own exported services down with the
+follower.
+
+```jsx
+await createRoot({ desktop: false }); // none of the three
+await createRoot({ desktop: { appearance: false } }); // just that one
+```
+
+With all three off, **nothing dials the session bus at startup** — no
+connection, no subprocess, no portal probe. That is the shape an embedder
+wants, and a kiosk, and a test that needs the same answer on every machine.
+
+Turning `appearance` off means the app draws in its own palette rather than
+the desktop's: `useSystemAppearance()` reports `'no-preference'` with
+`source: null`, and the remembered answer on disk is not read either — an
+opted-out app that started in whatever colours the machine was in last time
+would be the opposite of what the switch is for.
+
+**Off is process-wide, and it latches.** There is one desktop, one D-Bus
+identity and one AT-SPI bridge per process, so the policy cannot honestly be
+per-root: a second root turning back on what the first turned off would be a
+bug rather than a feature. Nothing turns an integration back on, and a
+feature already started stays started — pass this on the first root.
+
+## Not blocking the first frame on the bus
+
+Worth knowing because it is invisible when it works, and was worth ~150 ms
+when it did not.
+
+On macOS the session bus address is not in the environment; D-Bus advertises
+it through **launchd**, and finding it means running `launchctl getenv`.
+`dbus-native`'s entry point is synchronous, so it has to do that with
+`spawnSync` — 120–150 ms of _blocked event loop_ on a cold page cache, landing
+in front of the X handshake, the layout engine's WebAssembly and the first
+paint, all so the accessibility bridge could find out there was nothing to
+connect to.
+
+Every dial now goes through one asynchronous, once-per-process lookup instead,
+and hands `dbus-native` a resolved `unix:path=…`. The same wall clock is
+spent, none of it on the loop: the handshake and the layout engine run
+straight through it. There is nothing to configure — it is the same address,
+found the same way, off the critical path.
+
+Linux is unaffected: `$DBUS_SESSION_BUS_ADDRESS` or `$XDG_RUNTIME_DIR/bus`
+answers without a subprocess, and always did.
+
+## Password fields and password managers
+
+There is **no password-field protocol on the Linux desktop.** No toolkit
+publishes "this is a password field, fill it", and no manager asks. What
+exists instead are four seams, none of which a widget can opt into by
+declaring itself — they are things an application either supports or does
+not. `PasswordInput` supports the two that reach a field, and this is what
+they turn out to be.
+
+### 1. Typing — XTEST auto-type, and the keymap race
+
+The mechanism nearly every desktop manager uses is **auto-type**: KeePassXC
+matches the focused window's **title** against its entries, then synthesises
+the keystrokes. Its X11 backend is the whole of the story — `SendKeyEvent()`
+sends `XTestFakeKeyEvent()`, and for a character the current layout cannot
+type, `RemapKeycode()` writes the keysym into a spare keycode with
+`XkbSetMap()` first, `XSync`ing before it types.
+
+For us that is good news and one hazard:
+
+- **A faked key is an ordinary key.** XTEST events are delivered by the
+  server through the normal event path, so `PasswordInput` — and every other
+  focusable node — cannot tell auto-type from a person, and nothing has to be
+  done to support it. An auto-type sequence of `{USERNAME}{TAB}{PASSWORD}
+{ENTER}` walks a react-x11 form because Tab moves focus and Enter reaches
+  `onSubmit`.
+- **The window needs a title worth matching.** Auto-type's default matching is
+  on the window title, so `<window title="…">` is the integration surface.
+  A window titled after the document with nothing identifying the app is one
+  a user cannot write an auto-type rule for; `appId` is worth setting too,
+  since a manager that grew a smarter matcher would read that.
+- **The keymap race is real.** ntk refetches the mapping when the server sends
+  `MappingNotify`, which is what makes a remapped keycode decode correctly —
+  but the refetch is a round trip, and a manager that remaps, syncs and types
+  immediately can land its key before the reply does. The window is small and
+  only affects characters outside the user's layout, but a password of ASCII
+  is not the case that fails. Nothing here can close it; the fix belongs where
+  the map lives.
+
+### 2. Pasting — the clipboard, and the hint that keeps it out of history
+
+The other path every manager offers is copy-to-clipboard, usually with a
+countdown before it clears. That is ordinary `CLIPBOARD` interop
+([clipboard.md](clipboard.md)); `PasswordInput` takes Ctrl+V and
+Shift+Insert, and strips control characters so a manager's trailing newline
+does not end up inside the secret.
+
+If your app ever puts a secret **on** the clipboard — this widget never does
+— offer `x-kde-passwordManagerHint` with the value `secret` beside the text.
+Klipper drops such an offer from its history, KDE Connect refuses to forward
+it, and `wl-clipboard` marks the state sensitive. It is a convention rather
+than a specification, and it is the only thing standing between a copied
+password and a clipboard manager's on-disk history:
+
+```js
+clipboard.write({ UTF8_STRING: secret, 'x-kde-passwordManagerHint': 'secret' });
+```
+
+`PasswordInput` also never takes the **PRIMARY** selection, which a
+`<textinput>` does on every selection: PRIMARY is pasted by a middle click in
+any window on the display, and a secret does not belong in a selection that
+can be spent by accident.
+
+### 3. Fetching it yourself — the Secret Service
+
+When the app has an account of its own to unlock, the seam is not a field at
+all: the **Secret Service** D-Bus API, `org.freedesktop.secrets`, which
+gnome-keyring, KWallet and KeePassXC all implement, and which `libsecret`
+speaks for C applications. react-x11 has no wrapper for it and does not need
+one — `useSessionBus()` reaches it directly ([dbus.md](dbus.md)) — and the
+shape is: search by attributes, unlock the collection if it is locked, read
+the secret back. An app that does this shows no password field on most
+launches, which is a better outcome than any field can offer.
+
+Inside a sandbox that name is not there. Flatpak's answer is
+`org.freedesktop.portal.Secret`, whose `RetrieveSecret` hands the app a
+per-application master secret down a pipe; libsecret switches to it
+automatically and encrypts a local store with it.
+
+### 4. Reading the field — AT-SPI, which does not mark it yet
+
+The accessibility bus is the only channel through which an outside program
+can see a field's _contents and role_ rather than guess at a window title:
+AT-SPI2 gives a password entry the role `password text`, which is how a
+screen reader knows to announce "bullet" instead of the character. Some
+automation leans on the same tree. react-x11 does publish one
+([accessibility.md](accessibility.md)), but `PasswordInput` is a plain
+`role="textbox"` in it and nothing maps a node to `password text`
+(`src/a11y.js` declares the role and no node takes it), so this seam is still
+closed — worth opening as a role in the shared model rather than as a
+password-shaped hole beside it.
+
+### What a field can still do wrong
+
+None of the above stops the field itself from leaking. What `PasswordInput`
+does about that, and what it cannot:
+
+- the masked value is **never laid out or drawn** — no glyphs of the secret
+  reach ntk's shaping cache or the X server, and the mask's width is measured
+  from one reference character;
+- there is **no copy, no selection, no undo history**;
+- the value is still a JavaScript string, and strings are immutable. It
+  cannot be zeroed, it lives until the garbage collector takes it, and every
+  intermediate value typed on the way lives alongside it. A design that needs
+  more than that needs the secret to never enter this process.