react-x11 2.11.0 → 2.12.0

package/README.md

@@ -7,28 +7,61 @@
 react-x11 and watch it render, in your browser, against a JavaScript X server
 running on the page.
 
-A React renderer whose host environment is an [X11
-server](https://www.x.org/wiki/Documentation/). 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. 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 the X Window
-environment (a linux desktop, or macOS +
-[XQuartz](https://www.xquartz.org/)) with your React / React Native
+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.
 
-Everything is JavaScript all the way down: ntk /
-[node-x11](https://github.com/sidorares/node-x11) implement the X11 protocol
-in pure JS (think xlib rewritten in node.js), layout is
-[yoga-layout](https://www.npmjs.com/package/yoga-layout), text shaping is
-[fontkit](https://github.com/foliojs/fontkit). `npm install` never compiles
-anything — 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 pipeline).
-
-### The wire carries drawing, not pixels
+### Two backends, one tree
+
+The same components, the same hooks and the same `style` objects run on both:
+
+- **X11** ([the flagship](docs/remote.md)) — a Linux desktop, a display
+  forwarded over `ssh -X`, `Xvfb` in CI, a thin client, or macOS through
+  [XQuartz](https://www.xquartz.org/). Everything is JavaScript all the way
+  down: ntk / [node-x11](https://github.com/sidorares/node-x11) implement
+  the X11 protocol in pure JS (think xlib rewritten in node.js).
+- **Cocoa** ([docs/macos.md](docs/macos.md)) — a real Mac app: `NSWindow`s,
+  the menu bar at the top of the screen, AppKit's own control bezels, native
+  open/save panels, native notifications, Core Animation compositing. No X
+  server anywhere. It rides on
+  [`@windowkit/appkit`](https://www.npmjs.com/package/@windowkit/appkit), a
+  thin mechanism-only Objective-C++ bridge — an optional dependency shipping
+  prebuilds, absent on Linux installs.
+
+`createRoot()` picks for you: **Cocoa on macOS** when the bridge is
+installed, X11 via `$DISPLAY` everywhere else, and X11 on a Mac without the
+bridge so an XQuartz setup keeps working. `createRoot({ backend: 'x11' })`
+or `REACT_X11_BACKEND=x11` pins it. On macOS the app's JS runs on a worker
+while AppKit keeps the main thread, so a menu, a drag or a live resize never
+stops it — `node app.js` is enough, and `REACT_X11_THREADED=0` keeps the
+main thread ([docs/macos.md](docs/macos.md#js-on-a-worker-a-ui-thread-of-the-bridges-own)).
+
+Two more backends are on the way, and the goal they serve is **full
+cross-platform support**: **Windows** — Win32 windows, Direct2D and
+DirectWrite, DWM compositing — with [docs/windows.md](docs/windows.md) as
+its PRD, and **native Wayland**, with [docs/wayland.md](docs/wayland.md)
+as its RFC. Both arrive as backends beside these two, not replacements for
+either: 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
+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
+pipeline).
+
+### On X11, the wire carries drawing, not pixels
 
 react-x11 does not rasterize a frame on the client and ship the buffer
 across. React reconciles the component tree, the renderer turns that diff
@@ -44,11 +77,22 @@ back. An update costs what the _drawing_ costs, not what the window's area
 costs. Going full-screen on a 4K panel does not multiply your bandwidth,
 because you were not sending pixels at 1080p either — which is why this
 stays comfortable on a display forwarded over ssh. Mounting a window with
-forty rows and their labels is 86 requests and 3.6 KB on the wire.
+forty rows and their labels is 110 requests and 4.2 KB on the wire, and
+stalls the pipeline on none of them.
 
 Because that is the design it is measured rather than assumed: `npm run
-bench` reports requests, bytes, replies, RENDER composites and the pixel area
-those composites touch, against a checked-in baseline.
+bench` reports requests, bytes, replies, blocking round trips, RENDER
+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
+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,
+animations run in the render server while the JS thread is busy, and Retina
+is composited at native resolution instead of quadrupling every rasterized
+pixel.
 
 ### Where this fits
 
@@ -58,7 +102,7 @@ That is the shape of the problem this is good at:
 
 - **the display is elsewhere** — a headless server over `ssh -X`, a
   container pointed at the host, a thin client, an X terminal, a
-  deliberately dumb workstation. A whole window appears for under four
+  deliberately dumb workstation. A whole window appears for about four
   kilobytes, because what crosses the link is drawing rather than pixels
   ([docs/remote.md](docs/remote.md));
 - **the machine cannot afford a browser engine** — a kiosk, an appliance, an
@@ -72,21 +116,33 @@ That is the shape of the problem this is good at:
   in-process X server, on a machine with no `$DISPLAY`, on macOS. That
   harness is published as `react-x11/test`
   ([docs/testing.md](docs/testing.md)).
+- **you want a Mac app out of the same source** — the Cocoa backend is a
+  real one: system menu bar, native panels and notifications, layer-backed
+  compositing, and a Developer-ID-signed `.app` from either node or bun
+  (the App Store's sandbox takes node only —
+  [docs/packaging.md](docs/packaging.md)).
 
 And the shape it is not good at, so you can stop here rather than in week
 three:
 
-- **three platforms.** X11 only. macOS means XQuartz — a separate install, a
-  non-native look and no menu bar integration. Windows is out; if you need
-  Windows, use Electron or Tauri.
+- **Windows — today.** There is no Windows backend yet, so an app that has
+  to ship on Windows now wants Electron or Tauri. One is coming: a native
+  backend over Win32 windows, Direct2D and DirectWrite, composited by DWM
+  through DirectComposition, on a mechanism-only bridge shaped like the
+  Cocoa one. [docs/windows.md](docs/windows.md) is the PRD, from the
+  threading model up to what each desktop integration becomes. Two targets
+  ship meanwhile — X11 and Cocoa — and they 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
+  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 researched and planned as a
-  **second 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.
+  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.
 - **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
@@ -96,6 +152,10 @@ three:
   [`@react-x11/components`](https://github.com/sidorares/react-x11-components).
 - **text entry outside Latin.** See [Known issues](#known-issues).
 
+The screenshots below are the X11 backend, rendered headlessly into
+node-x11's in-process server by `npm run screenshots` — which is why they
+are pixel-stable enough to check in.
+
 | `examples/dashboard.jsx` — context theming, hooks | `examples/tasks.jsx` — useReducer, textinput, scrolling |
 | ------------------------------------------------- | ------------------------------------------------------- |
 | ![dashboard](docs/img/dashboard.png)              | ![tasks](docs/img/tasks.png)                            |
@@ -108,8 +168,8 @@ three:
 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 `GetImage` cannot read it, so there is no screenshot of it
-here; see [docs/glx.md](docs/glx.md).)
+(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).)
 
 ## Quick start
 
@@ -156,7 +216,7 @@ function Counter() {
   );
 }
 
-const root = await createRoot(); // connects via $DISPLAY
+const root = await createRoot(); // Cocoa on macOS, else X11 via $DISPLAY
 root.render(<Counter />);
 ```
 
@@ -167,71 +227,115 @@ step).
 
 ## Elements
 
-Only `<window>`, `<popup>` and `<glarea>` map to real X11 windows.
-Everything else is laid out by yoga and drawn client-side into the window's
-double-buffered 2d context — see [NEXT_STEPS.md](NEXT_STEPS.md) for the architecture rationale
-and [docs/](docs/README.md) for the full API reference.
+Only `<window>`, `<popup>`, `<glarea>` and `<foreign>` are real windows of
+the display system. Everything else is a retained lightweight node — one
+yoga node each — drawn client-side into the owning window's double-buffered
+2d context, with events dispatched by front-to-back hit testing over the
+drawn tree. See [docs/elements.md](docs/elements.md) for the full reference.
 
 | element       | what it is                                                                                                                                                                                         |
 | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `<window>`    | a real X11 window; the flex, paint and event root                                                                                                                                                  |
-| `<popup>`     | an override-redirect window at screen coordinates — menus, tooltips, dropdowns                                                                                                                     |
+| `<window>`    | a real toplevel — an X11 window, or an `NSWindow`; the flex, paint and event root                                                                                                                  |
+| `<popup>`     | an undecorated window placed at screen coordinates — menus, tooltips, dropdowns. `anchor` places it against a node; `grab` and `trapFocus` make it modal                                           |
 | `<box>`       | flex container: layout props → yoga, plus backgrounds, borders (solid/dashed, radius), overflow clipping, zIndex. `overflow: 'scroll'` makes it a wheel-scrollable viewport with a drawn scrollbar |
 | `<text>`      | shaped, wrapped text (bidi, ligatures, font fallback); nested `<text>` elements are style spans                                                                                                    |
-| `<textinput>` | single-line editor: caret/selection via ntk's TextLayout caret API, clipboard (CLIPBOARD + X11 PRIMARY), word select, undo/redo, right-click menu                                                  |
-| `<image>`     | PNG/JPEG from `src`, natural-size aware                                                                                                                                                            |
-| `<canvas>`    | escape hatch: `onDraw={(ctx, {width, height}) => …}` with ntk's canvas-like 2d context (XRender-backed)                                                                                            |
-| `<svg>`       | static SVG through ntk SvgView, sized like `<image>`                                                                                                                                               |
-| `<glarea>`    | an OpenGL surface over indirect GLX; the 3D scene below lives inside it                                                                                                                            |
+| `<textinput>` | single-line editor: caret/selection, clipboard, word select, undo/redo, right-click menu                                                                                                           |
+| `<textarea>`  | the same editor, wrapped and multi-line, scrolling with its content                                                                                                                                |
+| `<image>`     | PNG/JPEG from `src`, 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)                                                                  |
+| `<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))                                                                                      |
+
+`registerElement()` adds one from outside the package —
+[docs/extending.md](docs/extending.md).
 
 Widget **components** (plain React on top of the primitives, themable via
 `ThemeProvider`): `Button`, `Checkbox`, `Radio`/`RadioGroup`, `Switch`,
-`Slider`, `ProgressBar`, `Select`, `Tooltip`, `MenuBar`/`ContextMenu`,
-`Calendar`/`DatePicker` — one date or a range, with days blockable and a
-seam for drawing into the cells — `PasswordInput`, whose mask is a scribble
-that moves on every keystroke rather than a countable row of bullets —
-`Dialog` — a modal built on
-`<popup trapFocus>`, which traps Tab and restores focus when it closes —
-plus the two containers an application window is built from: `Tabs`, `Tree`
-and `SplitPane`. See
-[docs/components.md](docs/components.md).
-
-**The menu bar goes where the desktop keeps menus.** On Plasma, on a panel
-running `vala-panel-appmenu`, or under one of the GNOME extensions that add a
-menu bar, `<MenuBar menus={…}/>` hands its menu to the panel over
-`com.canonical.dbusmenu` and stops drawing one; everywhere else it draws the
-bar itself. No configuration, and the same line of JSX either way — the item
-descriptors are dbusmenu's own vocabulary, so the array that draws the menu is
-the array that serialises. `npm run globalmenu:host` is a panel in a terminal,
-for seeing it work on a desktop that has none. See
+`Slider`, `ProgressBar`, `Select`, `Tooltip`, `Icon`, `MenuBar`/`ContextMenu`,
+`PasswordInput` — whose mask is a scribble that moves on every keystroke
+rather than a countable row of bullets — `Dialog`, a modal built on
+`<popup trapFocus>` which traps Tab and restores focus when it closes,
+`FileDialog`, the two containers an application window is built from —
+`Tabs` and `SplitPane` — and a virtualized `Table`. See
+[docs/components.md](docs/components.md). Richer widgets — `Markdown`,
+`Tree`, `Calendar`/`DatePicker`, a three.js scene graph — live in
+[`@react-x11/components`](https://github.com/sidorares/react-x11-components).
+
+**The menu bar goes where the desktop keeps menus.** On the Cocoa backend
+`<MenuBar menus={…}/>` becomes the **macOS menu bar** at the top of the
+screen. On Plasma, on a panel running `vala-panel-appmenu`, or under one of
+the GNOME extensions that add a menu bar, it hands its menu to the panel
+over `com.canonical.dbusmenu`. Everywhere else — a stock GNOME session,
+XQuartz, ssh, CI — it draws the bar itself. No configuration, and the same
+line of JSX every time: the item descriptors are dbusmenu's own vocabulary,
+so the array that draws the menu is the array that serialises and the array
+that becomes an `NSMenu`. `npm run globalmenu:host` is a panel in a
+terminal, for seeing the D-Bus path work on a desktop that has none. See
 [docs/globalmenu.md](docs/globalmenu.md).
 
 **`myapp://` links open the app that is already running.**
-`registerApplication({ appId, schemes })` before `createRoot()` owns the app's
-name on the bus, exports `org.freedesktop.Application`, and — on the half of
-all desktops where `xdg-open` ignores D-Bus activation and spawns a second copy
-with the URI in `argv` — forwards it to the first copy and tells that copy to
-exit. `useAppOpen()` receives the link, buffered and replayed if it arrived
-before the tree mounted, and `activateWindow()` brings the window forward with
-the launch's own timestamp, without which a window manager declines and the
-taskbar 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
+`registerApplication({ appId, schemes })` before `createRoot()` takes the two
+dispatch paths a real desktop uses: on Linux it owns the app's name on the
+bus, exports `org.freedesktop.Application`, and — on the half of all desktops
+where `xdg-open` ignores D-Bus activation and spawns a second copy with the
+URI in `argv` — forwards it to the first copy and tells that copy to exit; on
+macOS the link arrives as an Apple Event through the bridge. `useAppOpen()`
+receives it either way, buffered and replayed if it arrived before the tree
+mounted, and `activateWindow()` brings the window forward — with the launch's
+own timestamp on X11, without which a window manager declines and the taskbar
+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: `<box dropAccept={['files']}
-onDrop={…}>` takes a file dragged out of Nautilus, 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 payload over by reference, so a
-reorderable list and a cross-application file drop are the same two props.
+**Drag and drop** works with the rest of the desktop on both backends —
+XDND on X11, `NSDraggingSession` on Cocoa. `<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
+payload over by reference, so a reorderable list and a cross-application
+file drop are the same two props.
 See [docs/drag-and-drop.md](docs/drag-and-drop.md).
 
+### The desktop around the app
+
+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)) |
+
+[docs/system.md](docs/system.md) is the rest of the machine — monitors,
+window state, idle, keyboard layout, locale — and
+[docs/desktop.md](docs/desktop.md) is what the app tells the desktop about
+itself.
+
 ### 3D
 
-`<glarea>` is a GL surface in the layout, drawn over **indirect GLX**: the GL
-protocol encoded into the X connection, with no native bindings and no GPU
-driver bindings — the same "JavaScript all the way down" story as the rest.
-Geometry belongs in a server-side display list, so a frame costs matrices and
-one `CallList` whatever the triangle count.
+`<glarea>` is a GL surface in the layout, with three ways underneath it and
+the same `onDraw` over all three:
+
+- **indirect GLX** (the X11 default) — the GL protocol encoded into the X
+  connection, no native bindings and no GPU driver bindings, the same
+  "JavaScript all the way down" story as the rest. Geometry belongs in a
+  server-side display list, so a frame costs matrices and one `CallList`
+  whatever the triangle count. No shaders and no render targets: the
+  protocol encodes neither.
+- **direct** (`glPolicy: 'auto'`, ntk's optional `x11-dri` addon) — GL ES 2
+  on the GPU, with GLSL and framebuffer objects. DRI3 + Present on Linux,
+  Apple-DRI under XQuartz.
+- **Cocoa** — CGL into IOSurface-backed framebuffers, presented as a
+  sublayer of the window; shaders and render targets, on any Mac, with no
+  X server involved.
 
 ```jsx
 <glarea
@@ -243,7 +347,7 @@ one `CallList` whatever the triangle count.
 ```
 
 A scene graph over it — `<mesh>`, geometries, materials, lights, and shaders
-or post-processing on the direct backend — is
+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).
 
@@ -257,20 +361,24 @@ a scroll container from scrolling, like the DOM.
 
 ## Examples
 
-All need an X server — but "an X server" is a broader thing than it sounds:
-your Linux desktop, XQuartz on macOS, `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 case this architecture is
-categorically better at.
+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
+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
+case this architecture is categorically better at. `REACT_X11_BACKEND=x11`
+in front of any of them runs the X11 path on a Mac too, which is how the two
+get compared.
 [`examples/README.md`](examples/README.md) describes each one and how to
 explore them:
 
 ```sh
 npm run examples:simple        # hello world (JSX via tsx)
 npm run examples:app           # the showcase: Tabs + SplitPane hosting the rest
+npm run examples:widgets       # every built-in control, in one window
 npm run examples:theming       # three themes x light/dark, and a size query
 npm run examples:container-queries  # one card, two panes: '@container', and a named one
+npm run examples:custom-layout  # masonry, a justified gallery, CSS grid, and equal-row controls
 npm run examples:simple-nojsx  # the same, plain node — no build step
 npm run examples:xeyes         # canvas drawing + hooks
 npm run examples:dashboard     # context theming, custom hooks, components
@@ -279,23 +387,30 @@ npm run examples:menu          # right-click context menu via <popup>
 npm run examples:transparent   # rounded translucent <popup transparent>
 npm run examples:animation     # transitions and loops, and which backend runs them
 npm run examples:form          # <textinput> + Select dropdowns
-npm run examples:datepicker    # Calendar/DatePicker: ranges, blocked days, events
 npm run examples:password      # PasswordInput: the scribble mask, and a custom one
+npm run examples:calendar      # the desktop's own calendar events, no OAuth
+npm run examples:dnd-source    # and :dnd-target — drags in and out of the desktop
+npm run examples:frame         # <Frame>: a pane of the app in its own process
+npm run examples:stress        # the perf scenarios the benches are cut from
 npm run examples:viewer3d      # raw GL in a <glarea>: a model viewer over indirect GLX
-npm run examples:wm            # a reparenting window manager (see below)
+npm run examples:wm            # a reparenting window manager (X11 only, see below)
 ```
 
-The two GL examples additionally need a server with **indirect GLX**
-enabled (`+iglx` / `AllowIndirectGLX` — off by default on many).
+On the X11 backend the GL examples additionally need a server with
+**indirect GLX** enabled (`+iglx` / `AllowIndirectGLX` — off by default on
+many), or `glPolicy: 'auto'` and ntk's `x11-dri` addon. On Cocoa they need
+neither.
 
 ### Window manager
 
-`examples:wm` is a real reparenting window manager: 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 `onMouseDown` handlers, and the application is a foreign X
-window reparented inside.
+`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
+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
+`onMouseDown` handlers, and the application is a foreign X window reparented
+inside.
 
 Only one window manager may own a display, so run it against a nested
 server rather than the one managing your desktop:
@@ -319,8 +434,8 @@ npm run examples:tasks:hot     # then edit examples/tasks.jsx while it runs
 Runs the tasks example under the supported hot-reload entry point,
 `react-x11/refresh` (`node --import react-x11/refresh/register`, Node ≥
 22.15), with React **Fast Refresh**: saving `examples/tasks.jsx` updates
-the edited components in place. The X11 connection, the mounted window,
-and component state — the task list, even half-typed text in the input —
+the edited components in place. The connection, the mounted window, and
+component state — the task list, even half-typed text in the input —
 survive the reload (a component whose hook signature changed remounts
 alone). Any app adopts it the same way — no accept handlers, no loader
 files to copy; see
@@ -335,21 +450,27 @@ REACT_X11_DEVTOOLS=1 npm run examples:dashboard   # 2. run any example with the
 
 The component tree, props and hook state show up live in the DevTools
 window, and editing any of them re-renders the app. Hovering an element in
-the tree tints its rect in the X11 window; the toolbar's crosshair picks an
-element by clicking it in the app; "highlight updates when components
+the tree tints its rect in the app's window; the toolbar's crosshair picks
+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. `REACT_X11_DEVTOOLS_HOST` / `REACT_X11_DEVTOOLS_PORT`
-override the default `localhost:8097`. See
+record its mount. All of it is above the display system, so it works the
+same on both backends. `REACT_X11_DEVTOOLS_HOST` /
+`REACT_X11_DEVTOOLS_PORT` override the default `localhost:8097`. See
 [docs/devtools.md](docs/devtools.md).
 
-Two more debugging aids:
+Three more debugging aids:
 
 - `REACT_X11_DEBUG_LAYOUT=1` outlines every laid-out node (color = tree
   depth) — handy when a flexbox doesn't do what you expect.
+- `REACT_X11_DEBUG_PAINT=1` strokes each frame's damage rects in a rotating
+  colour, so a region repainting every frame strobes visibly;
+  `REACT_X11_TRACE` records the X11 protocol. Both are
+  [docs/debugging.md](docs/debugging.md).
 - refs give you the retained node (`abs` rect, `scrollTo`, …) for drawn
-  elements, or the live [ntk](https://github.com/sidorares/ntk) window for
-  `<window>`/`<popup>` — the whole ntk API is a ref away.
+  elements, or the live window object for `<window>`/`<popup>` — on X11
+  that is the [ntk](https://github.com/sidorares/ntk) window and the whole
+  ntk API with it.
 
 ## Click to component
 
@@ -357,16 +478,16 @@ Two more debugging aids:
 REACT_X11_EDITOR=code npm run examples:tasks
 ```
 
-Alt+Click any rendered element (Option+Click on macOS/XQuartz) to open the
-JSX line that created it in your editor. `REACT_X11_EDITOR` picks the CLI
-and enables the feature in one go; `REACT_X11_CLICK_TO_COMPONENT=1` does
-the same with the default editor
+Alt+Click any rendered element (Option+Click on macOS, either backend) to
+open the JSX line that created it in your editor. `REACT_X11_EDITOR` picks
+the CLI and enables the feature in one go; `REACT_X11_CLICK_TO_COMPONENT=1`
+does the same with the default editor
 (`cursor`). See [docs/click-to-component.md](docs/click-to-component.md).
 
 ## TypeScript
 
 Types ship with the package — no `@types/react-x11` to install. Point JSX at
-react-x11 and the X11 elements type-check:
+react-x11 and the host elements type-check:
 
 ```jsonc
 // tsconfig.json
@@ -415,17 +536,23 @@ npm test             # hermetic: mock smoke tests + in-process X server pixels
 npm run typecheck    # tsc over the declarations and the type tests
 npm run lint         # ESLint
 npm run format       # Prettier
+npm run bench        # protocol cost against scripts/bench/baseline.json
+npm run bench:frames # frame timings; bench:pixels for the pixel-hash gate
 npm run screenshots  # regenerate docs/img/*.png headlessly (no X server)
 npm run docs:dev     # the documentation site (npm install in website/ first)
 ```
 
-3D is the exception: the headless path has no GL, so a 3D shot has to be
-captured by hand from a real server
-with indirect GLX.
+The test suite drives the **X11** backend against node-x11's in-process
+server; the Cocoa backend's own tests run against a fake bridge, and its
+pixels are checked by hand on a Mac. 3D is the other exception: the headless
+path has no GL, so a 3D shot has to be captured from a real server with
+indirect GLX.
 
 See [AGENTS.md](AGENTS.md) for architecture notes and contributor/agent
-guidance, [docs/](docs/README.md) for API documentation, and
-[NEXT_STEPS.md](NEXT_STEPS.md) for the roadmap.
+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
+grew out of.
 
 The [documentation site](https://sidorares.github.io/react-x11/) lives in
 [`website/`](website/) and renders `docs/` rather than repeating it — edit
@@ -434,8 +561,10 @@ the browser, so `npm run docs:test` fails when a demo stops matching the API.
 
 ## Known issues
 
-Two that are worth knowing before you hit them, both predating the current
-release and both tracked:
+Worth knowing before you hit them. Both are **X11-backend** problems that
+come out of X's own keyboard and font models; neither applies to a Mac app
+on the Cocoa backend, where CoreText resolves families and `NSEvent` reports
+the character that was actually typed.
 
 - **`sans-serif` can resolve to a CJK font on macOS**
   ([#86](https://github.com/sidorares/react-x11/issues/86)). Font families
@@ -449,16 +578,28 @@ release and both tracked:
   layout or a third and fourth level, so they are read as a layout and left
   alone. Dead keys, Compose and layout switching all work
   ([docs/events.md](docs/events.md)); what is absent is an ibus/fcitx/XIM
-  backend, so CJK is not partially working — it is structurally absent.
+  backend, so CJK is not partially working — it is structurally absent. On
+  Cocoa the character arrives with the event, so AltGr-style levels type;
+  an `NSTextInputClient` IME for CJK is not built there either.
+
+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
+([docs/accessibility.md](docs/accessibility.md)).
 
 ## Security
 
-X11 has no isolation between clients: any program on a display can read any
-other program's window contents, grab the keyboard, and synthesize or record
-input. That is the 1987 design, not a gap in this library, and it cuts both
-ways — do not run untrusted programs on a display you use, and do not treat
-a react-x11 window as a confidential surface. Your `$XAUTHORITY` cookie is a
-bearer token; treat it like a password.
+**On X11**, there is no isolation between clients: any program on a display
+can read any other program's window contents, grab the keyboard, and
+synthesize or record input. That is the 1987 design, not a gap in this
+library, and it cuts both ways — do not run untrusted programs on a display
+you use, and do not treat a react-x11 window as a confidential surface. Your
+`$XAUTHORITY` cookie is a bearer token; treat it like a password. (macOS
+does isolate applications from one another, so a Cocoa-backend app does not
+inherit this; what it inherits instead is TCC, where the camera, the
+microphone and the screen are permissions the user grants —
+[docs/permissions.md](docs/permissions.md).)
 
 `ssh -X` runs your app as an untrusted client and restricts most of the
 above; `ssh -Y` turns the restrictions off. **Prefer `-X` — react-x11 should
@@ -473,8 +614,16 @@ against, is [docs/security.md](docs/security.md). To report something,
 - [awesome-react-renderer](https://github.com/chentsulin/awesome-react-renderer)
   — the catalogue of React renderers, which is how most people find things
   like this.
-- [ntk](https://github.com/sidorares/ntk) — the toolkit underneath: windows,
-  the XRender-backed 2d context, the text stack, the frame clock.
+- [ntk](https://github.com/sidorares/ntk) — the toolkit under the X11
+  backend: windows, the XRender-backed 2d context, the text stack, the frame
+  clock.
 - [node-x11](https://github.com/sidorares/node-x11) — the X11 protocol in
   JavaScript, including the in-process X server the tests and the playground
   run against.
+- [`@windowkit/appkit`](https://www.npmjs.com/package/@windowkit/appkit) —
+  the Cocoa bridge: `NSWindow`s, CALayer trees, CoreText, CoreGraphics
+  surfaces, and an `NSApplication` event pump driven from Node's own loop.
+  Mechanism only, no policy — the renderer owns that.
+- [`@react-x11/components`](https://github.com/sidorares/react-x11-components)
+  — widgets over the primitives: `Markdown`, `Tree`, `Calendar`, a terminal,
+  a three.js scene graph.