react-x11 2.51.1 → 2.53.0

package/README.md

@@ -11,12 +11,14 @@ A React renderer for **desktop applications**, whose host is a display
 system rather than a document. React's job in a renderer is to compute what
 changed; the renderer's job is to turn that into side effects on some host —
 in react-dom those are DOM mutations, here they are **X11 protocol requests**
-written to a socket, or **Core Animation layers and CoreGraphics drawing** on
-macOS. There is no DOM, no HTML and no browser engine underneath: this is not
-Electron with a different skin, and `<div>` is not an element that exists.
-Build GUI programs for a Linux desktop, for a display at the other end of an
-ssh connection, or as a native Mac app, with your React / React Native
-experience — flexbox layout, components, hooks, synthetic events.
+written to a socket, **Core Animation layers and CoreGraphics drawing** on
+macOS, **Direct2D drawing on DirectComposition surfaces** on Windows, or GL
+frames handed to a **Wayland** compositor. There is no DOM and no browser
+engine underneath: this is not Electron with a different skin, and `<div>` is
+not an element that exists. Build GUI programs for a Linux desktop, for a
+display at the other end of an ssh connection, as a native Mac app or a
+Windows one, with your React / React Native experience — flexbox layout,
+components, hooks, synthetic events.
 
 ### Four backends, one tree
 
@@ -47,21 +49,28 @@ main thread ([docs/macos.md](docs/macos.md#js-on-a-worker-a-ui-thread-of-the-bri
 
 Two more backends exist beside these, serving the goal of **full
 cross-platform support**, and both are younger than the two above.
-**native Wayland** ([docs/wayland.md](docs/wayland.md)) is opt-in rather than
-automatic, because X11 stays the default on Linux — the remote case is the
-flagship reason this project exists and Wayland has no network transparency.
-**Windows** ([docs/windows.md](docs/windows.md)) — Win32 windows, Direct2D
-and DirectWrite, DWM compositing through DirectComposition — renders and
-takes mouse input, with the desktop integrations still to come. Each is a
-backend beside the others rather than a replacement for any of them: the
-same tree, the same components, the same `style` objects.
+**native Wayland** ([docs/wayland-backend.md](docs/wayland-backend.md)) —
+the wire protocol in JavaScript and a GLES rasterizer of its own, on mutter,
+sway and labwc, with no Xwayland in the path — is opt-in
+(`REACT_X11_BACKEND=wayland`) rather than automatic, because X11 stays the
+default on Linux: the remote case is the flagship reason this project exists
+and Wayland has no network transparency. **Windows**
+([docs/windows.md](docs/windows.md)) — Win32 windows, Direct2D and
+DirectWrite, DWM compositing through DirectComposition — is the default on
+Windows, with the keyboard, an IME, a screen-reader bridge and most of the
+desktop integrations in place
+([docs/windows-integrations.md](docs/windows-integrations.md) is the
+measured list). Each is a backend beside the others rather than a
+replacement for any of them: the same tree, the same components, the same
+`style` objects.
 
 Layout is [yoga-layout](https://www.npmjs.com/package/yoga-layout) (WASM) on
-both, and text shaping is [fontkit](https://github.com/foliojs/fontkit) on
-the X11 side, CoreText on the Cocoa one. **`npm install` never compiles
-anything**: the X11 stack is JavaScript all the way down, and the two native
-addons in the tree — the Cocoa bridge and `x11-dri` for direct GL — are
-optional dependencies that ship prebuilt. And `npm test` doesn't even need
+every backend, and text shaping is [fontkit](https://github.com/foliojs/fontkit)
+through ntk on X11 and Wayland, CoreText on Cocoa and DirectWrite on Windows.
+**`npm install` never compiles anything**: the X11 stack is JavaScript all
+the way down, and the native addons in the tree — the Cocoa and win32
+bridges, and `x11-dri` for direct GL and the Wayland socket — are optional
+dependencies that ship prebuilt. And `npm test` doesn't even need
 an X server (node-x11 ships an in-process pure-JS X server that the tests
 render into and read pixels back from; every screenshot below was rendered
 that way too, by driving the real examples through the real event
@@ -92,7 +101,7 @@ composites and the pixel area those composites touch, against a checked-in
 baseline (`scripts/bench/baseline.json`, which is where the numbers in these
 docs come from).
 
-The Cocoa backend inverts this, and [docs/macos.md](docs/macos.md) is the
+The Cocoa backend inverts this, and [design/macos.md](design/macos.md) is the
 design record for why: there is no wire, the WindowServer is a retained
 compositor, and a React commit maps onto property mutations of persistent
 objects. Scrolling is a layer's `bounds.origin` rather than a repaint,
@@ -141,30 +150,41 @@ three:
   Drag and drop works both ways with the desktop, and the taskbar's own
   surfaces — a thumbnail toolbar, a jump list, recent documents — are there
   behind a capability, so an app that also runs elsewhere asks
-  `useSupports()` rather than the platform. What it does not have is **IME
-  and screen-reader support**: an app is unusable with a screen reader and
-  in CJK input. So an app that needs either on Windows _this month_ still
-  wants Electron or Tauri.
+  `useSupports()` rather than the platform. CJK input goes through an
+  IMM32 input method and screen readers through a UI Automation provider of
+  the project's own, both with gaps worth reading before you rely on them:
+  no voice typing or handwriting (those want a TSF text store), and no
+  caret-by-caret reading inside a text field yet. Nor is there activation —
+  file associations, URL schemes and second launches — so an app that needs
+  any of that on Windows _this month_ still wants Electron or Tauri.
   [docs/windows-integrations.md](docs/windows-integrations.md) is the
-  measured status and [docs/windows.md](docs/windows.md) the design. The three
+  measured status and [design/windows.md](design/windows.md) the design. The three
   targets are not the same app: the desktop-shell half of X11 (`<foreign>`
   embedding, panel struts, substructure redirect, the window-manager example
   below) has no macOS or Windows equivalent, and `react-x11/test` drives the
   X11 backend only. [docs/macos.md](docs/macos.md) says which is which.
-- **native Wayland — today.** There is no Wayland backend yet. Ordinary
-  application windows work fine on a Wayland desktop through Xwayland, which
-  is not going away — but the desktop-shell half of X11 (panel struts,
-  global key grabs, screen capture, and the window-manager example below)
-  needs a real X session. A native backend is coming too, as a **target
-  beside X11, not a migration**: [docs/wayland.md](docs/wayland.md) is the
-  RFC, from the fd transport up to what the rendering would ride on.
+- **native Wayland — today.** The native backend is opt-in and young:
+  windows, text, input, an input method, the clipboard, popups, drag and
+  drop and layer-shell docks and panels run on mutter, sway and labwc, and
+  [docs/wayland-backend.md](docs/wayland-backend.md#not-supported-yet) lists what
+  is left — no multisampling, no `<Frame>` panes, no drag icon. Ordinary
+  application windows also work on a Wayland desktop through Xwayland, which
+  is not going away — but the desktop-shell half of X11 (`<foreign>`
+  embedding, global key grabs, and the window-manager example below) needs a
+  real X session. It is a **target beside X11, not a migration**;
+  [design/wayland.md](design/wayland.md) is the RFC it was built from.
 - **reusing web components.** There is no DOM. Your MUI, your Tailwind and
   your `recharts` do not come with you; the state, data-fetching, validation
   and math libraries mostly do. [docs/ecosystem.md](docs/ecosystem.md) says
   which is which, and what the failure looks like when it is the wrong one.
-- **rendering HTML.** There is no HTML element and no webview. Rich
-  documents are markdown, through `<Markdown>` in
-  [`@react-x11/components`](https://github.com/sidorares/react-x11-components).
+- **being a browser.** There is no webview and no browser engine to embed.
+  HTML is a component rather than a substrate: `<Html>` in
+  [`@react-x11/components`](https://github.com/sidorares/react-x11-components)
+  renders an HTML + CSS document with a layout engine of its own — selectable,
+  with real widgets for its form controls, and with a page's scripts run
+  against a DOM when `scripts` turns them on — and `<Markdown>` beside it
+  renders markdown. Both are for documents an app shows; an app that _is_ a
+  web app still wants Electron or Tauri.
 - **text entry outside Latin.** See [Known issues](#known-issues).
 
 The screenshots below are the X11 backend, rendered headlessly into
@@ -184,7 +204,7 @@ protocol sent over the X connection, geometry compiled into a display list,
 a frame costing two matrices and one `CallList`. No native bindings, no GPU
 driver bindings — the same "JavaScript all the way down" story as the rest.
 (GL renders where the X server cannot read it back, so there is no
-screenshot of it here; see [docs/glx.md](docs/glx.md).)
+screenshot of it here; see [docs/gl.md](docs/gl.md#testing).)
 
 ## Quick start
 
@@ -258,6 +278,7 @@ drawn tree. See [docs/elements.md](docs/elements.md) for the full reference.
 | `<textarea>`  | the same editor, wrapped and multi-line, scrolling with its content                                                                                                                                |
 | `<image>`     | PNG/JPEG/WebP from `src` (more formats under Bun), natural-size aware; also pixels the server already has                                                                                          |
 | `<canvas>`    | escape hatch: `onDraw={(ctx, {width, height}) => …}` with a canvas-like 2d context (XRender-backed on X11, CoreGraphics on Cocoa)                                                                  |
+| `<video>`     | decoded frames the app pushes, on every backend, or a `src` the platform plays itself where it has a player                                                                                        |
 | `<svg>`       | static SVG (paths, shapes, gradients, transforms), sized like `<image>`                                                                                                                            |
 | `<glarea>`    | an OpenGL surface in the layout — see [3D](#3d)                                                                                                                                                    |
 | `<foreign>`   | another application's X window, laid out as an element. **X11 only** ([docs/embedding.md](docs/embedding.md))                                                                                      |
@@ -303,8 +324,9 @@ entry just blinks. The OAuth redirect this is for has an easier answer that
 needs none of it, and the page says so first. See
 [docs/uri-schemes.md](docs/uri-schemes.md).
 
-**Drag and drop** works with the rest of the desktop on both backends —
-XDND on X11, `NSDraggingSession` on Cocoa. `<box dropAccept={['files']}
+**Drag and drop** works with the rest of the desktop on every backend —
+XDND on X11, `NSDraggingSession` on Cocoa, OLE on Windows, `wl_data_device`
+on Wayland. `<box dropAccept={['files']}
 onDrop={…}>` takes a file dragged out of Nautilus or Finder, and
 `<box draggable dragData={…}>` can be dropped into a file manager or an
 editor. Drags that stay inside the app never touch the wire and hand their
@@ -318,16 +340,16 @@ Everything an app does outside its own windows is a **ladder**: the best
 rung the machine actually has, the same hook whichever one answers, and a
 first-class "this desktop cannot" rather than a throw.
 
-| what                                                             | rungs, best first                                                                                                                                             |
-| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [open/save panels](docs/filedialog.md) `useFileDialog()`         | `NSOpenPanel` · the XDG portal · `osascript` · one react-x11 draws                                                                                            |
-| [notifications](docs/notifications.md) `notify()`                | UNUserNotificationCenter · `org.freedesktop.Notifications` · `osascript` · `notify-send`                                                                      |
-| [light/dark, accent](docs/appearance.md) `useSystemAppearance()` | the settings portal · macOS · XSETTINGS — remembered on disk, so the first frame is not a flash                                                               |
-| [permissions](docs/permissions.md) `usePermission()`             | TCC on macOS · the Settings pane · `'unknown'` on Linux until the device portals land                                                                         |
-| [the user's real events](docs/desktop-calendar.md)               | EventKit through the bridge · EventKit through `osascript` · Evolution Data Server                                                                            |
-| [sample a screen colour](docs/eyedropper.md) `useEyedropper()`   | `NSColorSampler` · the portal's picker · a crosshair grab on plain X11                                                                                        |
-| a badge on the icon `setBadge()`                                 | `NSDockTile.badgeLabel` · `com.canonical.Unity.LauncherEntry`                                                                                                 |
-| a tray icon `useTray()`                                          | `NSStatusItem`. **Cocoa only today** — `available` is false on X11 until StatusNotifierItem lands ([#353](https://github.com/sidorares/react-x11/issues/353)) |
+| what                                                             | rungs, best first                                                                                                                             |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| [open/save panels](docs/filedialog.md) `useFileDialog()`         | `NSOpenPanel` / the Common Item Dialog · the XDG portal · `osascript` · one react-x11 draws                                                   |
+| [notifications](docs/notifications.md) `notify()`                | UNUserNotificationCenter / a tray balloon on Windows · `org.freedesktop.Notifications` · `osascript` · `notify-send`                          |
+| [light/dark, accent](docs/appearance.md) `useSystemAppearance()` | the settings portal · macOS · XSETTINGS — remembered on disk, so the first frame is not a flash                                               |
+| [permissions](docs/permissions.md) `usePermission()`             | TCC on macOS · the Settings pane · `'unknown'` on Linux until the device portals land                                                         |
+| [the user's real events](docs/desktop-calendar.md)               | EventKit through the bridge · EventKit through `osascript` · Evolution Data Server                                                            |
+| [sample a screen colour](docs/eyedropper.md) `useEyedropper()`   | `NSColorSampler` · the portal's picker · a crosshair grab on plain X11                                                                        |
+| a badge on the icon `setBadge()`                                 | `NSDockTile.badgeLabel` / a taskbar overlay icon · `com.canonical.Unity.LauncherEntry`                                                        |
+| a tray icon `useTray()`                                          | `NSStatusItem` / `Shell_NotifyIcon` · `org.kde.StatusNotifierItem` — `available` is false on a desktop with no tray host, such as stock GNOME |
 
 [docs/system.md](docs/system.md) is the rest of the machine — monitors,
 window state, idle, keyboard layout, locale — and
@@ -336,8 +358,8 @@ itself.
 
 ### 3D
 
-`<glarea>` is a GL surface in the layout, with three ways underneath it and
-the same `onDraw` over all three:
+`<glarea>` is a GL surface in the layout, with the same `onDraw` over every
+way underneath it — three on the mature backends:
 
 - **indirect GLX** (the X11 default) — the GL protocol encoded into the X
   connection, no native bindings and no GPU driver bindings, the same
@@ -352,6 +374,10 @@ the same `onDraw` over all three:
   sublayer of the window; shaders and render targets, on any Mac, with no
   X server involved.
 
+The two younger backends have their own: WGL on Windows, composited through
+DirectComposition ([design/windows-gl.md](design/windows-gl.md)), and on Wayland
+a viewport into the window's own GLES target.
+
 ```jsx
 <glarea
   style={{ flexGrow: 1 }}
@@ -364,7 +390,7 @@ the same `onDraw` over all three:
 A scene graph over it — `<mesh>`, geometries, materials, lights, and shaders
 or post-processing where the backend has them — is
 [`@react-x11/components/three`](https://github.com/sidorares/react-x11-components).
-See [docs/gl.md](docs/gl.md) and [docs/glx.md](docs/glx.md).
+See [docs/gl.md](docs/gl.md).
 
 Events are synthetic with capture/bubble phases and hit testing over the
 drawn tree: `onClick` (with DOM-style `detail` click counting),
@@ -376,8 +402,8 @@ a scroll container from scrolling, like the DOM.
 
 ## Examples
 
-On macOS these run natively, with no X server; everywhere else they need
-one — and "an X server" is a broader thing than it sounds: your Linux
+On macOS and Windows these run natively, with no X server; everywhere else
+they need one — and "an X server" is a broader thing than it sounds: your Linux
 desktop, XQuartz, `Xvfb` for automation, `Xephyr` for a disposable screen, a
 VNC server, or your own display reached over `ssh -X` from wherever the
 program actually runs — see [docs/remote.md](docs/remote.md), which is the
@@ -419,8 +445,8 @@ neither.
 ### Window manager
 
 `examples:wm` is a real reparenting window manager, and it is **X11 only** —
-substructure redirect has no macOS equivalent, so this is one of the places
-the two backends are not the same app. It takes over the root window, puts
+substructure redirect has no macOS, Windows or Wayland-client equivalent, so
+this is one of the places the backends are not the same app. It takes over the root window, puts
 every application's window inside a frame it draws, and moves, resizes,
 focuses and closes them. The frames are ordinary react-x11 `<window>`s — the
 titlebar, the buttons and the eight resize handles are components with
@@ -475,7 +501,7 @@ an element by clicking it in the app; "highlight updates when components
 render" outlines the rects that just re-rendered; the style editor edits a
 selected element's style live; and the Profiler can restart the app to
 record its mount. All of it is above the display system, so it works the
-same on both backends. `REACT_X11_DEVTOOLS_HOST` /
+same on every backend. `REACT_X11_DEVTOOLS_HOST` /
 `REACT_X11_DEVTOOLS_PORT` override the default `localhost:8097`. See
 [docs/devtools.md](docs/devtools.md).
 
@@ -570,8 +596,8 @@ indirect GLX.
 
 See [AGENTS.md](AGENTS.md) for architecture notes and contributor/agent
 guidance, [docs/](docs/README.md) for API documentation,
-[docs/architecture/](docs/architecture/) for the design records behind the
-bigger pieces, and [NEXT_STEPS.md](NEXT_STEPS.md) for the older roadmap it
+[design/](design/README.md) for the design records behind the bigger
+pieces and the backends, and [NEXT_STEPS.md](NEXT_STEPS.md) for the older roadmap it
 grew out of.
 
 The [documentation site](https://sidorares.github.io/react-x11/) lives in
@@ -602,10 +628,17 @@ the character that was actually typed.
   Cocoa the character arrives with the event, so AltGr-style levels type;
   an `NSTextInputClient` IME for CJK is not built there either.
 
+On the other two backends the input method is the platform's: the
+Wayland backend speaks `zwp_text_input_v3` to the compositor's IME, and the
+Windows one answers IMM32, so CJK composes on both
+([docs/windows-integrations.md](docs/windows-integrations.md) has Windows'
+limits).
+
 Two more places the backends genuinely differ, so you can plan around them
 rather than discover them: `react-x11/test` drives the **X11** backend only,
-and the AT-SPI accessibility bridge is X11's — on Cocoa `createRoot()`
-leaves it off, and an `NSAccessibility` bridge is not built yet
+and the accessibility bridges are AT-SPI on Linux and UI Automation on
+Windows — on Cocoa `createRoot()` leaves accessibility off, and an
+`NSAccessibility` bridge is not built yet
 ([docs/accessibility.md](docs/accessibility.md)).
 
 ## Security
@@ -650,7 +683,7 @@ against, is [docs/security.md](docs/security.md). To report something,
   desktop platforms for React Native. On Windows the new architecture's
   renderer targets Composition from the start, in Windows App SDK apps by
   default, with XAML islands for advanced controls; on macOS a fork of React
-  Native maps its UIKit views onto AppKit. [docs/windows.md](docs/windows.md)
+  Native maps its UIKit views onto AppKit. [design/windows.md](design/windows.md)
   cites its threading as prior art: JS on a thread of its own, and every
   mount posted to the UI thread that alone touches the visuals.
 - [React Native Skia](https://github.com/Shopify/react-native-skia) — 2D

package/docs/README.md

@@ -0,0 +1,256 @@
+# react-x11 documentation
+
+react-x11 renders one React tree to four backends: **X11** (a Linux desktop,
+a forwarded display, XQuartz), **Cocoa** (a native Mac app, no X server
+anywhere), **win32**, and an opt-in native **Wayland** backend. The same
+tree, components, styles and hooks run on all of them, and `createRoot()`
+picks — Cocoa on macOS and win32 on Windows where their bridges are
+installed, X11 otherwise. Every page below is about every backend unless it
+says otherwise; where a backend changes the answer, it is called out where
+the answer is.
+
+- [macos.md](macos.md) — the Cocoa backend: choosing it, its options,
+  windowing, text, input, native controls, the menu bar, app bundles, and
+  what does not map (no window manager, no cross-process embedding).
+- [elements.md](elements.md) — the host elements (`<window>`, `<popup>`,
+  `<box>`, `<text>`, `<textinput>`, `<textarea>`, `<image>`, `<canvas>`,
+  `<svg>`, `<foreign>`), their props and refs — including
+  [selecting read-only text](elements.md#selecting-text) with `selectable`.
+- [styling.md](styling.md) — the `style` prop: layout and paint properties,
+  state blocks, transitions, theme tokens, container queries, `createStyles`,
+  and [a font file of your own](styling.md#a-font-file-of-your-own).
+- [components.md](components.md) — the widgets (`Button`, `Checkbox`,
+  `Radio`, `Switch`, `ProgressBar`, `Select`, `Slider`, `Tooltip`, `Dialog`,
+  `MenuBar`/`ContextMenu`, `Tabs`, `Table`, `SplitPane`), theming, and the
+  `useAnchor` popup placement hook.
+- [globalmenu.md](globalmenu.md) — a `MenuBar` handed to wherever the
+  platform keeps menus: the macOS menu bar, a desktop panel over
+  `com.canonical.dbusmenu`, or the drawn bar.
+- [events.md](events.md) — the synthetic event system: dispatch phases,
+  event objects, focus, cursors, default actions.
+- [accessibility.md](accessibility.md) — screen readers: the AT-SPI2 bridge,
+  `role`/`aria-*` on every element, what the widgets announce, `announce()`,
+  and testing it all without a desktop.
+- [react-features.md](react-features.md) — where React knowledge carries
+  over and where a DOM habit breaks: effects, measuring a node, refs,
+  `<popup>` instead of `createPortal`, error boundaries, missing APIs.
+- [drag-and-drop.md](drag-and-drop.md) — accepting drops and starting drags,
+  in-app and with other applications: `dropAccept`, payloads,
+  `useDropTarget`/`useDragSource`, previews, and driving a drag in a test.
+- [clipboard.md](clipboard.md) — `useClipboard()`: CLIPBOARD and PRIMARY,
+  several flavours of one payload, the `text`/`files`/`uris` groups,
+  `watch()`, and the macOS pasteboard.
+- [typescript.md](typescript.md) — the bundled types: one tsconfig option,
+  and JSX from `react-x11/jsx-runtime`.
+- [extending.md](extending.md) — `registerElement()` and the subpath
+  exports: a host element from outside the package, the node contract, and
+  the damage seam for an element that draws a whole scene.
+- [gl.md](gl.md) — `<glarea>`, a GL surface in the layout: `glPolicy`, the
+  backends underneath, `<shaderMaterial>` and `<effectComposer>`.
+- [embedding.md](embedding.md) — `<foreign>`: another application's window
+  inside yours, over XEmbed or a plain reparent. **X11 only.**
+- [frame.md](frame.md) — `<Frame>`: a pane of your own app in a process of
+  its own; what the process boundary buys, and that it is not a security
+  boundary.
+- [testing.md](testing.md) — `react-x11/test`: render, query, drive and
+  assert on real pixels against an in-process X server. No display, and
+  always the **X11** backend.
+- [desktop.md](desktop.md) — what an app tells the desktop beyond drawing:
+  startup notification, the launcher badge and Dock menu, the tray, feature
+  discovery, and turning it all off.
+- [dbus.md](dbus.md) — the session and system bus: `useSessionBus()` /
+  `useSystemBus()`, `sessionBus()`, and "no bus" as a normal configuration.
+- [uri-schemes.md](uri-schemes.md) — being the app a `myapp://…` link
+  opens: `registerApplication()`, `useAppOpen()`, single-instance
+  forwarding, and the `.desktop` half.
+- [filedialog.md](filedialog.md) — `useFileDialog()`: open, save and pick a
+  folder, through a native panel, the desktop portal, `osascript` or a drawn
+  browser; cancelling is `null`.
+- [permissions.md](permissions.md) — `usePermission()` for the camera, the
+  microphone, the screen and the accessibility APIs, and its five-word
+  status vocabulary.
+- [notifications.md](notifications.md) — `notify()` and `useNotifier()`:
+  banners through the best available rung, updated in place, and what the
+  user did with them.
+- [desktop-calendar.md](desktop-calendar.md) — `useDesktopCalendarEvents()`:
+  the user's real events, with no credential, via EventKit or Evolution
+  Data Server.
+- [eyedropper.md](eyedropper.md) — `useEyedropper()`/`pickScreenColor()`:
+  sample a colour from the screen.
+- [appearance.md](appearance.md) — light or dark, accent, contrast, reduced
+  motion: `useSystemAppearance()` and `<ThemeProvider dark>`.
+- [scale.md](scale.md) — HiDPI: logical pixels, `createRoot({ scale: 'auto'
+})`, `useScale()`, and per-monitor answers.
+- [system.md](system.md) — the machine around the app: `useScreens()`,
+  `useWindowState()`, `useIdle()`/`useKeepAwake()`, `useKeyboardState()`,
+  `useDesktopSettings()`, `useLocale()`.
+- [remote.md](remote.md) — running on one machine and drawing to a display
+  on another: `ssh -X` vs `-Y`, what the protocol costs on a link, the other
+  X servers.
+- [wayland-backend.md](wayland-backend.md) — the opt-in native Wayland
+  backend: what runs, and what is still open.
+- [windows.md](windows.md) — the win32 backend: choosing it, installing the
+  bridge, what maps and what does not.
+- [windows-integrations.md](windows-integrations.md) — what an app on
+  Windows can reach today, and the gaps.
+- [security.md](security.md) — the threat model: X11 has no isolation
+  between clients, `$XAUTHORITY` is a password, and what react-x11 does and
+  does not defend against.
+- [packaging.md](packaging.md) — five ways to ship an app, the load-bearing
+  esbuild flags, and macOS signing for Developer ID and the App Store.
+- [devtools.md](devtools.md) — React DevTools integration and other
+  debugging aids.
+- [debugging.md](debugging.md) — runtime diagnostics: `REACT_X11_TRACE` and
+  `startTrace()`, `REACT_X11_DEBUG_PAINT`, invalidation reasons, and the
+  switches that turn one optimisation off.
+- [click-to-component.md](click-to-component.md) — Alt+Click a rendered
+  element to open its JSX source line in your editor.
+- [ecosystem.md](ecosystem.md) — which npm packages work with react-x11 and
+  which do not, and why. Per category:
+  [state](ecosystem/state.md), [data fetching](ecosystem/data-fetching.md),
+  [forms](ecosystem/forms.md), [icons](ecosystem/icons.md),
+  [theming](ecosystem/theming.md), [animation](ecosystem/animation.md),
+  [headless components](ecosystem/headless.md),
+  [layout](ecosystem/layout.md), [routing](ecosystem/routing.md),
+  [i18n](ecosystem/i18n.md), [testing](ecosystem/testing.md),
+  [dev tooling](ecosystem/dev-tooling.md).
+
+Contributors: the design records behind these pages — history, rejected
+alternatives, measurements, plans — are in
+[design/README.md](../design/README.md), which does not ship.
+
+## Entry points
+
+```js
+import { createRoot, Select } from 'react-x11';
+```
+
+### `await createRoot(options?)` → `{ app, render(element), unmount() }`
+
+The entry point. With no options it opens a connection to whichever backend
+this machine has: the **Cocoa** bridge on macOS, the **win32** bridge on
+Windows, or the X server named by `$DISPLAY`. Without the bridge installed
+it falls back to X11, once and out loud, so an XQuartz, WSLg or Cygwin
+setup keeps working. The returned `app` is that backend's app object — the
+[ntk](https://github.com/sidorares/ntk) App and its one X connection on
+X11.
+
+**Every root without `app` opens its own connection and owns it**, so two
+roots are two independent trees, and `await root.unmount()` closes what it
+opened — without which the socket stays up and the process does not exit.
+A root given an `app` borrows it and never closes it: that connection
+belongs to whoever made it.
+
+On macOS `'auto'` answers Cocoa, and **`$DISPLAY` in the environment does
+not change that.** Naming an X endpoint _in code_ — `display` or `stream` —
+does; from the environment, say `REACT_X11_BACKEND=x11`
+([remote.md](remote.md)).
+
+| option                                                 |                                                                                                                                                                             |
+| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `backend`                                              | `'auto'` (default), `'x11'`, `'cocoa'`, `'win32'` or `'wayland'` (opt-in; `'auto'` never picks it). Naming a bridge backend makes the bridge required rather than preferred |
+| `app`                                                  | render into a connection you already have — the option a backend choice is ignored for                                                                                      |
+| `cocoa`                                                | that backend's knobs: `presenter`, `promote`, `frameInterval`, `pumpInterval`, `appName`, `activationPolicy`, `exitOnQuit` ([macos.md](macos.md))                           |
+| `scale`                                                | device pixels per logical pixel: `'auto'` (default) or a number ([scale.md](scale.md))                                                                                      |
+| `frameRate`                                            | how windows pace frames under a flood: `'display'` (default) or `'adaptive'` ([elements.md](elements.md#framerate--pacing-the-frames-under-a-flood))                        |
+| `desktop`                                              | `false`, or `{ appearance, a11y, globalMenu }` — the three things that dial the session bus ([desktop.md](desktop.md))                                                      |
+| `startupNotification`                                  | freedesktop startup notification, on by default; `false`, or the id ([desktop.md](desktop.md))                                                                              |
+| `compose`                                              | dead keys and Compose: the built-in table by default, `'system'`, `{ file }`/`{ sequences }`, or `false`                                                                    |
+| `accelerators`                                         | which keysym a shortcut matches: `'latin'` (default), `'layout'`, or a table                                                                                                |
+| `restoreFocusOnReveal`                                 | whether a revealed subtree takes the keyboard back. Default `true`                                                                                                          |
+| `textStripBelow`                                       | the size under which `<text>` paints as a strip of ink rather than glyphs. Default 6; `0` never                                                                             |
+| `display`                                              | **X11.** `':1'`, `'host:0.0'`, a socket path. Default `$DISPLAY`. Naming one chooses the X11 backend                                                                        |
+| `stream`                                               | **X11.** an already-connected duplex stream — also a backend choice                                                                                                         |
+| `fontSource`                                           | **X11.** pluggable system-font lookup — ntk's docs/fonts.md                                                                                                                 |
+| `glPolicy` `glxVisual`                                 | **X11.** which GL backend `<glarea>` draws through, and a visual for it ([gl.md](gl.md))                                                                                    |
+| `onXError`                                             | **X11.** protocol errors nothing claimed. Default warns                                                                                                                     |
+| `onUncaughtError` `onCaughtError` `onRecoverableError` | `(error, errorInfo)`; default logs the component stack                                                                                                                      |
+| `onDisconnect(reason, err)`                            | **X11.** the connection ended — `'closed'` or `'error'`                                                                                                                     |
+
+`display`, `stream`, `fontSource`, `glxVisual`, `glPolicy` and `onXError` go
+straight to ntk's `createClient`. For anything else it understands, build
+the client yourself and pass it as `app`. A `stream` reaches a server that
+is not on `$DISPLAY` — node-x11's in-process one, for instance:
+
+```js
+import xserver from 'x11/lib/xserver/index.js';
+
+const server = xserver.createServer({ width: 640, height: 480 });
+const [serverEnd, clientEnd] = xserver.createStreamPair();
+server.addClientStream(serverEnd);
+const root = await createRoot({ stream: clientEnd }); // no $DISPLAY needed
+```
+
+`onUncaughtError` covers one channel React does not: a throw from an **event
+handler**, which no error boundary can catch because the handler ran from an
+input event rather than a render. See
+[events.md](events.md#when-a-handler-throws).
+
+`onDisconnect` fires when an X connection ends without being asked to —
+server exit, ssh drop, kill — and not for one this root closed. **A
+reconnect is not a reconnect:** every window id, pixmap, glyph set and font
+is invalidated with the connection, so tear the root down and build a new
+one.
+
+`root.render(element, callback?)` flushes the mount or update
+synchronously (`updateContainerSync` + `flushSyncWork`); painting happens a
+frame later on the window's frame clock.
+
+## Environment variables
+
+Every one of these has an option or a prop that says the same thing in code;
+the variable is for when you cannot edit the call — someone else's app, a
+`.desktop` launcher, an A/B run. `npx react-x11 help` prints every one the
+renderer reads, the diagnostic switches included.
+
+**Choosing a backend and a display**
+
+| variable                     | effect                                                                     |
+| ---------------------------- | -------------------------------------------------------------------------- |
+| `DISPLAY`                    | X server to connect to (standard X11)                                      |
+| `REACT_X11_BACKEND`          | `x11`, `cocoa`, `win32` or `wayland`, overriding `backend` and the default |
+| `REACT_X11_GL_DEVICE`        | Wayland: the DRM node to render on, where `glPolicy.devicePath` is unset   |
+| `REACT_X11_SCALE`            | device pixels per logical pixel; outranks even a pinned `scale` number     |
+| `REACT_X11_FRAME_RATE`       | `display` or `adaptive`, overriding `frameRate` and the props              |
+| `REACT_X11_TEXT_STRIP_BELOW` | the `textStripBelow` size, for a process that cannot pass the option       |
+
+**Turning desktop integration off**
+
+| variable                      | effect                                                                                   |
+| ----------------------------- | ---------------------------------------------------------------------------------------- |
+| `REACT_X11_A11Y`              | set at all: log why the AT-SPI bridge did not start. `0` turns it off                    |
+| `NO_AT_BRIDGE=1`              | the freedesktop spelling of the same off switch                                          |
+| `REACT_X11_NO_GLOBAL_MENU=1`  | `MenuBar` always draws its own bar                                                       |
+| `REACT_X11_NO_TRANSPARENCY=1` | pretend there is no compositor ([debugging.md](debugging.md#react_x11_no_transparency1)) |
+
+**Development and diagnostics**
+
+| variable                         | effect                                                                                                                                           |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `REACT_X11_DEVTOOLS=1`           | connect to a running `react-devtools` (see devtools.md); on by default under `react-x11 dev`, `=0` turns it off                                  |
+| `REACT_X11_DEVTOOLS_HOST`        | devtools host (default `localhost`)                                                                                                              |
+| `REACT_X11_DEVTOOLS_PORT`        | devtools port (default `8097`)                                                                                                                   |
+| `REACT_X11_DEBUG_LAYOUT=1`       | outline every laid-out node, color-coded by tree depth                                                                                           |
+| `REACT_X11_DEBUG_PAINT=1`        | stroke each frame's damage rects in a rotating colour; `=full` also warns on full-window repaints                                                |
+| `REACT_X11_TRACE`                | record the X11 protocol — see [debugging.md](debugging.md) for the grammar                                                                       |
+| `REACT_X11_CLICK_TO_COMPONENT=1` | Alt+Click opens the clicked element's source, using `cursor` (see click-to-component.md); on by default under `react-x11 dev`, `=0` turns it off |
+| `REACT_X11_EDITOR`               | editor CLI for click-to-component — setting this alone also enables it                                                                           |
+| `REACT_X11_STRICT_TOKENS=1`      | a `$token` the theme does not define is fatal instead of dropped                                                                                 |
+
+**The Cocoa backend**
+
+| variable                       | effect                                                                                                                                           |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `REACT_X11_COCOA_PRESENTER`    | `surface` (the measured default) or `layers`                                                                                                     |
+| `REACT_X11_COCOA_PROMOTE`      | `1`/`0`, forcing layer promotion on or off                                                                                                       |
+| `REACT_X11_COCOA_PANE_STRETCH` | `behind` (default), `never` or `always`: when a `<Frame>` pane's last frame is stretched while a resize waits on the next ([frame.md](frame.md)) |
+| `REACT_X11_CALAYERS_PATH`      | load the bridge from a checkout or an extracted tarball instead of the package                                                                   |
+
+A handful more exist only to switch off one optimisation while measuring it
+— `REACT_X11_NO_PAINT_CACHE`, `REACT_X11_NO_SCROLL_BLIT`,
+`REACT_X11_NO_PANE_SHAPE`, `REACT_X11_NO_BOUNDS_CACHE`,
+`REACT_X11_NO_STROKE_CHUNKING`, `REACT_X11_NO_SCOPED_FLOORS`,
+`REACT_X11_NO_UNREAD_WIDTHS`, `REACT_X11_NO_REFIT_HOLD`,
+`REACT_X11_NO_APPEARANCE_CACHE`. They are development instruments, not API,
+documented in [debugging.md](debugging.md) or where the thing they disable
+is.