react-x11 2.51.1 → 2.53.0

package/docs/uri-schemes.md

@@ -0,0 +1,340 @@
+# Custom URI schemes and single instances
+
+Being the app that `com.example.myapp://…` opens: a link clicked in a browser,
+a chat message or a launcher reaches the **already-running** app, and its
+window comes to the front.
+
+The flow this exists for is logging in through the browser. The app opens the
+system browser, the provider redirects to
+`com.example.myapp://auth?code=…`, the desktop routes that URI back, and the
+app finishes the login without asking anyone to paste anything.
+
+## Read this first: for a login, you probably want a loopback port
+
+RFC 8252 §7.3 has a second answer that needs none of the machinery below —
+redirect to `http://127.0.0.1:<port>/cb` and listen on it:
+
+```js
+import { createServer } from 'node:http';
+
+const server = createServer((req, res) => {
+  const url = new URL(req.url, 'http://127.0.0.1');
+  res.end('You can close this tab.');
+  finishLogin(url.searchParams.get('code'));
+});
+server.listen(0); // "Authorization servers MUST allow any port" — RFC 8252 §7.3
+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 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 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
+
+|                  |                                                            | where                   |
+| ---------------- | ---------------------------------------------------------- | ----------------------- |
+| **Registration** | a `.desktop` entry claiming `x-scheme-handler/…`           | an install step         |
+| **Dispatch**     | the URI reaching the running process                       | `registerApplication()` |
+| **Delivery**     | `org.freedesktop.Application.Open`, answered before the UI | `useAppOpen()`          |
+| **The raise**    | `_NET_ACTIVE_WINDOW`, with the right timestamp             | `activateWindow()`      |
+
+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
+
+```js
+import { createRoot, registerApplication } from 'react-x11';
+
+const app = await registerApplication({
+  appId: 'com.example.myapp',
+  schemes: ['com.example.myapp'],
+});
+if (app?.role === 'secondary') process.exit(0); // we do not exit for you
+
+const root = await createRoot();
+root.render(<App />);
+```
+
+```jsx
+import { activateWindow, useAppOpen } from 'react-x11';
+
+function App() {
+  const win = useRef(null);
+  useAppOpen((uris, ctx) => {
+    activateWindow(win, { timestamp: ctx.timestamp });
+    const code = new URL(uris[0]).searchParams.get('code');
+    finishLogin(code);
+  });
+  return <window ref={win}>…</window>;
+}
+```
+
+That is the whole runtime half.
+
+### `registerApplication()`
+
+```ts
+function registerApplication(options: {
+  appId: string;
+  schemes?: string[];
+  onOpen?: (uris: string[], ctx: LaunchContext) => void;
+  onActivate?: (ctx: LaunchContext) => void;
+  onAction?: (name: string, params: unknown[], ctx: LaunchContext) => void;
+  argv?: string[];
+}): Promise<AppRegistration | null>;
+
+interface AppRegistration {
+  readonly role: 'primary' | 'secondary';
+  readonly appId: string;
+  readonly objectPath: string;
+  release(): Promise<void>;
+}
+```
+
+**Call it before `createRoot()`.** On the D-Bus path the bus _started this
+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 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**, 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 a typo must not hide behind it.
+
+### Two dispatch paths, and why `role` exists
+
+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 the app's decision.
+
+A second launch with **no** URI forwards `Activate` rather than an empty
+`Open`, so "the user started the app again" and "the user clicked a link"
+arrive as different events.
+
+### Delivery: buffered, and replayed
+
+`Open` is answered on the turn it arrives — never when the UI is ready. The
+URIs are buffered and replayed to the **first handler that attaches**, so an
+app whose React tree mounts a second later loses nothing, and an app whose
+first frame is slow does not creep towards the caller's 25-second timeout.
+
+Replay happens once. A second subscriber does not get the same login again.
+
+```ts
+function useAppOpen(
+  handler: (uris: string[], ctx: LaunchContext) => void,
+): void;
+function useAppActivate(handler: (ctx: LaunchContext) => void): void;
+
+// the same two, for code that has no component to hang off
+function onAppOpen(handler): () => void;
+function onAppActivate(handler): () => void;
+
+interface LaunchContext {
+  readonly platformData: Readonly<Record<string, unknown>>;
+  readonly timestamp: number | null;
+  readonly startupId: string | null;
+  readonly activationToken: string | null;
+}
+```
+
+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".
+Declaring no schemes at all filters nothing.
+
+### The raise is the part that fails
+
+```ts
+function activateWindow(
+  target?: NtkWindow | DrawnNode | RefObject<…> | number | null,
+  options?: { timestamp?: number | null; source?: 1 | 2 },
+): boolean;
+```
+
+Sends `_NET_ACTIVE_WINDOW` to the root window: source indication, timestamp,
+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.** 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`     |                                                                                                               |
+| --------------- | ------------------------------------------------------------------------------------------------------------- |
+| omitted         | the last input this app saw — EWMH's own definition of the field                                              |
+| `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:
+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 (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:
+
+```ini
+[Desktop Entry]
+Type=Application
+Name=My App
+Exec=my-app %u
+Icon=com.example.myapp
+DBusActivatable=true
+StartupWMClass=com.example.myapp
+MimeType=x-scheme-handler/com.example.myapp;
+```
+
+`StartupWMClass` must match the `appId` prop on your `<window>`, or the
+window manager cannot match the window that appears to the launch that asked
+for it.
+
+Then tell the MIME database it changed:
+
+```bash
+update-desktop-database ~/.local/share/applications
+```
+
+And, so that the bus can _start_ the app when it is not running,
+`~/.local/share/dbus-1/services/com.example.myapp.service`:
+
+```ini
+[D-BUS Service]
+Name=com.example.myapp
+Exec=/usr/bin/my-app
+```
+
+### Checking it by hand
+
+```bash
+gio open com.example.myapp://test              # path A: D-Bus activation
+```
+
+```bash
+env -u XDG_CURRENT_DESKTOP xdg-open com.example.myapp://test   # path B: Exec %u
+```
+
+Run each twice: once with the app closed (it should start and handle the link)
+and once with it running (it should come to the front, and no second window
+should appear). `REACT_X11_DEBUG_URI=1` narrates what this module decided —
+with every URI's query and fragment stripped, so the output is safe to paste
+into an issue.
+
+## Security
+
+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 §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.
+- **`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. 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
+  is _in_ the URI.
+
+## On macOS
+
+The same hooks, a different transport. On the cocoa backend the OS talks to
+the application through **Apple Events**, which `@windowkit/appkit` (≥ 0.5)
+forwards into the same delivery as a D-Bus `Open`:
+
+|                                                    |                                                                                                                     |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `kAEGetURL` — a URL for a scheme the bundle claims | `useAppOpen(uris, ctx)`, filtered by the registration's `schemes` like an `Open`                                    |
+| `kAEOpenDocuments` — a document from the Finder    | `useAppOpen`, as `file://` URLs (`file:` is always allowed)                                                         |
+| `kAEReopenApplication` — a Dock click, `open -a`   | `useAppActivate(ctx)`, with `ctx.platformData['has-visible-windows']`                                               |
+| `kAEQuitApplication` — Dock › Quit, ⌘Q, a logout   | the **primary window's close request**: `onCloseRequest` where there is one, else the default, which closes the app |
+
+Three things differ from the bus, and none of them changes app code:
+
+- **Single instance is the platform default.** Launch Services activates the
+  running app rather than starting a second one, so there is no `secondary`
+  role to exit from; `registerApplication()` resolves `null` on a Mac with no
+  D-Bus (the normal Mac) and its `schemes` still filter what arrives.
+- **`ctx.timestamp` is `null`.** Apple Events carry no startup id, and the
+  raise does not need one: `activateWindow()` there is `NSApp.activate`, which
+  no focus-stealing rule weighs.
+- **Registration is `Info.plist`, not a `.desktop` file** — `CFBundleURLTypes`
+  for the scheme and `CFBundleDocumentTypes` for documents, in an app bundle
+  (see [packaging.md](packaging.md)). A bare `node` process receives nothing
+  from Launch Services, because there is no bundle for it to look up.
+
+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: 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.
+
+## Deliberately not here
+
+- **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).

package/docs/wayland-backend.md

@@ -0,0 +1,332 @@
+# The Wayland backend
+
+**Status: a working backend, opt-in.** react-x11's own reconciler renders a
+window on a real Wayland compositor (mutter/GNOME, sway, labwc) with
+decorations — the compositor's where it draws them, client-side where it
+does not — text, shadows, paths, images, live partial repaints, pointer,
+touch, pen and keyboard input decoded against the compositor's keymap, an
+input method, a clipboard, drag and drop, popups, layer-shell docks and
+panels, and a screen capture with an eyedropper on top — drawn on the GPU
+and handed over as dma-buf, on **Node or Bun**, with no X server and no
+Xwayland anywhere in the path.
+
+It implements the research RFC in [design/wayland.md](../design/wayland.md);
+where the two disagree, this page is what ran. How it is built, what was
+measured and what is left are in the
+[design notes](../design/wayland-backend.md).
+
+```bash
+REACT_X11_BACKEND=wayland node your-app.mjs     # x11-dri >= 0.9 (native socket)
+REACT_X11_BACKEND=wayland bun  your-app.mjs     # or Bun's bun:ffi transport
+node examples/wayland-gl.mjs                    # GPU plasma, paced by the compositor
+node examples/wayland-ui.mjs                    # every drawing primitive, no React
+node --import tsx --test 'test/wayland/*.test.js'   # the suite: no display needed
+```
+
+The two packages it needs beyond react-x11's own are optional dependencies,
+installed with it: [`@windowkit/wayland`](https://github.com/windowkit/wayland),
+the protocol layer — a fork of `wayland-client` that passes file descriptors
+— and [`x11-dri`](https://github.com/sidorares/node-x11-dri) 0.9 or later,
+the GPU context and, on Node, the socket: Wayland passes file descriptors
+(the keymap, shm pools, clipboard pipes) and Node's own sockets cannot. Under
+Bun the socket is node-x11's `bun:ffi` transport instead.
+
+The backend is never chosen by `'auto'`: X11 stays the default on Linux
+because the remote case ([remote.md](remote.md)) is the flagship reason this
+project exists and Wayland has no network transparency.
+
+## How to tell it is not Xwayland
+
+A GNOME session answers `$DISPLAY` too, through Xwayland, so "the window
+appeared" proves nothing. Three checks that do:
+
+- **Unset `DISPLAY`.** The Wayland backend never opens it; the X11 backend
+  cannot start without it.
+  ```bash
+  env -u DISPLAY REACT_X11_BACKEND=wayland node app.mjs   # works only natively
+  ```
+- **Ask the app.** `root.app.backend === 'wayland'`, and `root.app.X` is a
+  stand-in — no `display.screen`, no `X.require`. The examples print the
+  transport they connected through (`connected via x11-dri` or
+  `fdpass-bun`) and never import an X module at all.
+- **Ask the desktop.** `xlsclients` and `xwininfo -root -tree` list Xwayland
+  clients; a native window is absent from both. GNOME's Looking Glass
+  (`Alt+F2`, `lg`, Windows tab) shows it as a `MetaWindowWayland`, and its
+  frame is this backend's own titlebar rather than mutter's Adwaita frame,
+  which only Xwayland windows get.
+
+## What runs
+
+| piece              | what an app gets                                                                        |
+| ------------------ | --------------------------------------------------------------------------------------- |
+| windows and popups | xdg toplevels and popups, fractional scale ([below](#windows-what-maps-what-bends))     |
+| 2d context         | rects, rounded rects, paths, exact clips, gradients, patterns, images, text, glyph runs |
+| `<glarea>`         | GLES drawing into a rectangle of the window, its children composited over it            |
+| offscreen surfaces | the paint cache and scroll blits; a held `Surface` context draws at any time            |
+| input              | pointer, keyboard decoded against the compositor's keymap, key repeat                   |
+| touch and tablet   | fingers and pens drive the pointer, with pen fields; raw touches                        |
+| input methods      | the compositor's IME (`zwp_text_input_v3`) into the composition events                  |
+| decorations        | the compositor's frame where it offers one, client-side otherwise                       |
+| layer surfaces     | docks, panels, wallpapers, overlays — wlr-layer-shell                                   |
+| screen capture     | wlr-screencopy / ext-image-copy-capture; the eyedropper                                 |
+| clipboard          | clipboard and primary selection                                                         |
+| drag and drop      | both directions, in-app drops keep `e.items` by reference; no drag icon yet             |
+| screens, keyboard  | `useScreens()` and `useKeyboardState()` ([system.md](system.md#on-wayland))             |
+| tests              | `test/wayland/`: an in-process compositor, no display needed                            |
+
+The keymap is the compositor's own, so AltGr and levels 3 and 4 work
+because the keymap says which modifier they are, not because one is
+assumed. Compositors do not repeat keys; the backend repeats them at the
+seat's advertised rate.
+
+**Touch and pen.** A finger or a tablet tool drives the same mouse events
+as a mouse, and only those events carry `pointerType` (`'touch'`, `'pen'`,
+`'eraser'`, `'mouse'`), `pressure`, `tiltX`/`tiltY`, `rotation`,
+`distance` and `tangentialPressure`, in the DOM's names and ranges
+([events.md](events.md#event-object)); a mouse event is unchanged. Only
+the first finger of a gesture emulates the pointer. Every finger also
+arrives raw on the window as `touchstart`/`touchmove`/`touchend`/
+`touchcancel` (the X11 backend's XI2 names, with `touchId`), each with the
+active `touches`, batched per touch frame. Barrel buttons map as the
+desktop does — BTN_STYLUS is button 3, BTN_STYLUS2 button 2 — and a tool
+leaving proximity releases whatever it still held.
+
+**Input methods.** IBus or whatever the compositor runs reaches
+`<textinput>` and `onCompositionStart`/`Update`/`End` exactly as a dead key
+does. Keys the IME consumes never arrive as key events. A `sensitive`
+field offers the IME no surrounding text and says `sensitive_data`;
+`inputMode` on a `<textinput>` becomes the content purpose (`email`, `url`,
+`tel`, …).
+
+**`<glarea>`** is a rectangle of the window's own GPU target, not a child
+surface: the area gets the shared GLES context with `viewport`, `scissor`
+and `bindFramebuffer(null)` re-based on its rect, the tree's 2D is drawn
+under it and the panes its children paint on are blended over it.
+
+**Perspective images.** `ctx.drawImageProjected(image, m)` draws an image
+through a 3×3 projection (a plane turned out of the page, as CSS
+`rotateY()` in a `perspective` turns one) as one exact quad. It answers
+`false` and draws nothing where a corner is behind the viewer, for the
+caller to draw the part in front some other way. Only this backend has it
+(XRender on glamor folds the image, CoreGraphics and Direct2D draw through
+an affine matrix alone): test with `'drawImageProjected' in ctx` and tile
+where it is absent.
+
+**Glyph runs.** `ctx.drawGlyphs(op, src, positioned)`, for callers that
+place their own glyphs (a terminal grid, a tabular column), is spelled as on
+X11 and Cocoa: the op `ctx.Render.PictOp.Over`, the source
+`ctx.createSolidPicture(r, g, b, a)` — or, as Cocoa also takes, a CSS
+colour string, a premultiplied `[r, g, b, a]`, or `null` for the fill style
+in force.
+
+### Running the examples
+
+Every example runs on this backend the way it runs on X11, with the display
+taken away so nothing can fall back:
+
+```bash
+env -u DISPLAY REACT_X11_BACKEND=wayland bun examples/widgets.jsx   # or node --import tsx
+```
+
+Two are X11 by nature and say so: `examples/wm.jsx` is a window manager and
+`examples/xeyes.jsx` reads the root window's pointer — neither has a
+Wayland counterpart. `examples/viewer3d.jsx` draws its model here through
+its direct half, GLES on the window's own GPU target — the same half X11
+uses under `NTK_GL_POLICY=direct`.
+
+Environment variables, for desktops with no screenshot API and for
+debugging:
+
+- `REACT_X11_WAYLAND_TRACE=1` writes a line per presented frame.
+- `REACT_X11_WAYLAND_SNAPSHOT=/tmp/frame.png` writes the backing target of
+  the first window at its 30th present (`REACT_X11_WAYLAND_SNAPSHOT_AT`
+  changes which) — the pixels the compositor was handed, read back from the
+  GPU.
+- `REACT_X11_WAYLAND_FRAME_STALL_MS` is how long a frame callback may go
+  unanswered before the window counts as not shown (2000; `0` turns that
+  off) — see
+  [A surface the compositor stops showing stops drawing](#a-surface-the-compositor-stops-showing-stops-drawing).
+- `REACT_X11_GL_DEVICE` names the DRM node to render on.
+
+The GPU context is made on `glPolicy.devicePath`, else on
+`REACT_X11_GL_DEVICE`, else on the first render node, and a device named
+either way is the only one tried. A machine with no render node at all — a
+GitHub-hosted runner, a Hyper-V or VirtualBox guest — usually still has a
+card node Mesa renders on in software, so the backend then tries each
+`/dev/dri/card*` in turn; headless weston with its GL renderer accepts what
+it makes on a hosted runner.
+
+## Windows: what maps, what bends
+
+The compositor owns placement, stacking and focus, so some of what a
+`<window>` asks for on X11 means less here:
+
+- **Position.** A toplevel cannot place itself: `x`/`y` on a `<window>` are
+  ignored, not an error, and the compositor's placement is final. A
+  toplevel's own position reads `0, 0`; no client knows where it is on
+  screen.
+- **Popups** are placed relative to their parent window, and the compositor
+  slides and flips them to stay on screen — the policy `anchorRect` gets
+  from react-x11 on X11. A press outside a grabbing popup, or Escape, is
+  the compositor's to act on; it hides the popup and the tree hears
+  `onDismiss` as it would on X11.
+- **Focus and raising** are the compositor's to give. `focus()` asks
+  through xdg-activation and is ignored without a recent user interaction;
+  attention requests go the same way; `raise()` and `lower()` do nothing.
+- **States.** Maximised, fullscreen and minimised map; there is no
+  un-minimise request. Always-on-top, sticky and workspaces have no
+  equivalent.
+- **Size.** A window sizes itself, except while the compositor imposes a
+  size — maximised, tiled, or mid-resize — when the size it asks for is
+  not applied.
+- **Type and class.** `windowType` matters only where layer-shell exists
+  ([below](#layer-surfaces-docks-panels-wallpapers)); the window's class
+  (`app_id`) is fixed at creation.
+- **A window the compositor is not showing does not draw** — next section.
+
+## A surface the compositor stops showing stops drawing
+
+After the first present a window draws only when the compositor sends it a
+frame callback, and a compositor is entitled never to send one to a
+surface it is not showing — covered, on another workspace, minimised, the
+screen locked. There is no timer-driven fallback, on purpose: painting
+into a surface nobody sees is work for nothing.
+
+The silence is **not an error**: nothing rejects, and React goes on
+re-rendering into a window that does not draw, which from outside looks
+like a hang. So the stall is reported twice over:
+
+- **On stderr, once per window, in development**, when the window still had
+  something to draw. One line, naming the compositor as the reason and saying
+  the app is not hung.
+- **In the tree**, as [`useWindowState().presenting`](system.md#presenting-and-the-wayland-frame-clock),
+  which also folds into `visible` — so an app can stop animating and
+  simulating rather than feeding a loop nobody is turning, which is what
+  every map, chart and game on this backend wants anyway.
+
+Nothing has to be done to recover: the pending frame callback fires the
+moment the surface is shown again, drawing resumes and `presenting` flips
+back. The deadline is two seconds; `REACT_X11_WAYLAND_FRAME_STALL_MS`
+changes it, and `0` turns the watch off entirely, timer, warning and all.
+
+## Decorations: whose frame
+
+The backend draws its own titlebar where the compositor will not (mutter),
+and asks for the compositor's frame where `zxdg_decoration_manager_v1` is
+offered — wlroots (sway, labwc), KDE. When the compositor agrees, the
+client-side frame goes away and the content grows into the whole surface,
+which the tree sees as a resize; a window not yet shown comes up the size
+it was declared, not a titlebar taller.
+
+`createRoot({ decorations })` says what to ask for: `undefined`/`true`/
+`'server'` prefer the compositor's frame, `'client'` never asks for it, and
+`false` — as does `<window decorations={false}>` — wants no frame at all.
+A frameless window still creates the decoration object where the protocol
+exists, to _decline_ server-side: sway frames every toplevel that has not
+said `client_side`.
+
+## Layer surfaces: docks, panels, wallpapers
+
+Where the compositor advertises `zwlr_layer_shell_v1`, a `<window>` whose
+`windowType` is one of these is not an `xdg_toplevel` but a layer surface,
+the same `wl_surface`, frame loop and input underneath:
+
+| `windowType`     | layer        | anchored to                                       | exclusive zone |
+| ---------------- | ------------ | ------------------------------------------------- | -------------- |
+| `'dock'`         | `top`        | the edge its shape and position imply (see below) | its thickness  |
+| `'desktop'`      | `background` | all four edges                                    | -1             |
+| `'notification'` | `top`        | top and right, 12px in                            | 0              |
+| `'splash'`       | `overlay`    | nothing — the compositor centres it               | 0              |
+
+A dock's edge is read the way an X window manager reads the same window:
+wide and at `y={0}` is a top panel, wide otherwise a bottom one; tall and at
+`x={0}` a left dock, tall otherwise a right one. Its size is what the tree
+measured (or `width`/`height`), so a 560×56 dock sits centred on its edge
+with 56px reserved; anchoring it to both ends of the edge stretches it:
+
+```jsx
+<window windowType="dock" height={56}>…</window>
+<window windowType="dock" height={40} layerShell={{ anchor: ['bottom', 'left', 'right'] }}>…</window>
+<window layerShell={{ layer: 'overlay', anchor: 'bottom', margin: { bottom: 40 } }}>an OSD</window>
+```
+
+`layerShell` names anything the type's default gets wrong — `layer`,
+`anchor` (an edge, an array of edges, `'all'`, `'none'`), `exclusiveZone`
+(a number, `'auto'` for the thickness, `-1`), `margin`,
+`keyboardInteractivity` (`'none'`, `'on-demand'`, `'exclusive'`),
+`namespace`, `output` — and `layerShell={false}` keeps a dock-typed window
+an ordinary toplevel. Popups from a layer surface work (a dock's menus). A
+stretched axis is the compositor's: `resize()` on it is not granted, and
+the configured size wins. Without layer-shell — GNOME — the same JSX is a
+toplevel.
+
+## Screen capture, and the eyedropper
+
+`app.screenCapture` is there when the compositor offers either
+`ext_image_copy_capture_manager_v1` (wlroots 0.19+, KDE 6.2+) or
+`zwlr_screencopy_manager_v1` (sway 1.10 has this one), and null otherwise
+(GNOME). `capture({ output, cursor })` resolves to one frame of the output
+as straight RGBA, `{ width, height, data }`; `pixelAt(x, y)` to one device
+pixel of it, as 0–255 channels. Each call is a fresh capture of the whole
+output — for many pixels, `capture()` once; for anything per frame, not at
+all.
+
+`pickColor()` is the eyedropper, the way every wlroots colour picker works:
+it freezes the output into a capture, shows it as a full-screen
+layer-shell overlay that takes the keyboard, and reads the pixel under the
+click — so it needs layer-shell as well as a capture protocol. Escape
+cancels; Return, space and KP_Enter pick at the pointer. It answers
+`{ r, g, b }` in 0–1. `useEyedropper()` uses it below the Screenshot portal
+(the desktop's own, user-consented picker — GNOME's only route, and what
+sway with xdg-desktop-portal-wlr uses too), so `useEyedropper().supported`
+is true on a bare sway. Where the compositor has neither the portal's
+picker nor capture plus layer-shell, `supported` is false: leave the
+eyedropper button undrawn.
+
+Two limits. With several outputs, the one captured by default is the one
+the compositor advertised last; `capture({ output })` and
+`layerShell.output` take another `wl_output` proxy. And a portal dialog (file chooser, colour picker) is modal
+to its window only where the compositor has **xdg-foreign**; without it, or
+from a popup, the dialog floats.
+
+## Under a second compositor
+
+The backend runs on sway and labwc as well as mutter, nested
+(`WLR_BACKENDS=wayland`) or headless (`WLR_BACKENDS=headless`). Headless
+sway plus `grim` is a way to screenshot an app with no desktop at all —
+`grim` needs wlr-screencopy, which mutter refuses:
+
+```bash
+WLR_BACKENDS=headless sway -c sway.conf &          # output * resolution 1280x800
+WAYLAND_DISPLAY=wayland-1 REACT_X11_BACKEND=wayland node --import tsx examples/simple.jsx &
+WAYLAND_DISPLAY=wayland-1 grim shot.png
+```
+
+## Not supported yet
+
+- **Multisampling.** Paths filled with a gradient, solid paths larger than
+  512×512 after clipping, and clips to anything but one axis-aligned
+  rectangle have aliased edges; rounded rectangles, smaller solid paths and
+  text are antialiased.
+- **`<Frame>` panes.** A `<Frame>` fails at once: its `fallback` renders and
+  no pane is started ([frame.md](frame.md)).
+- **The drag icon.** Drag and drop works both ways, but the drag shows no
+  icon: `<popup dragPreview>` is not drawn.
+- **Input methods, the rest of it.** A preedit that hides its cursor puts
+  the caret at the end, and the only content hints sent are `multiline`
+  and `sensitive_data`.
+- **Tablet pads** — the buttons, rings and strips on the tablet itself are
+  ignored.
+- **`useScreens().source` reads `'test'`**, as it does on macOS and Windows.
+- **`fillText`** uses only the first family of a `font` shorthand, and
+  strokes text as a fill.
+- **`ext-image-copy-capture`** has not been run against a compositor yet
+  (sway 1.10 offers only wlr-screencopy).
+
+## Things that are gone, not missing
+
+Window managers (`examples/wm.jsx`), global grabs, reading other windows,
+screen coordinates, `GetImage`, XEmbed/`<foreign>`, and `ssh -X` are
+compositor-private by design. Panels and docks are `layer-shell`, and a
+screen read is `screencopy` — both wlroots and KDE, neither GNOME, where the
+same JSX is a toplevel and the same pick is the portal's.