react-x11 2.52.0 → 2.53.0

package/docs/macos.md

@@ -1,3295 +1,592 @@
 # A native macOS backend
 
-**Status: shipped, and still being extended.** This began life as a research
-RFC written 2026-09-01 against react-x11 2.2.1, and the backend it planned is
-now in the tree: `src/cocoa/` is ~15,400 lines across 33 modules, the bridge
-published as **[`@windowkit/appkit`](https://www.npmjs.com/package/@windowkit/appkit)**
-(an `optionalDependency`, `^0.30.1` as of react-x11 2.51.1), and
-`createRoot()` selects it **by default on macOS**. Where this document says
-`node-calayers`, read `@windowkit/appkit`: that is what the POC was called
-before it was published.
-
-What has landed, against §"The plan" at the foot of this page: **Phase 0**
-(the bridge contract) and **Phase 1** (the surface presenter, still the
-measured default), then most of **Phases 4 and 5** — the system menu bar,
-native control bezels, native file panels, notifications, appearance,
-screens and scale, the pasteboard, drag and drop, `<glarea>` over CGL,
-`NSStatusItem` and the Dock, Apple-Event app lifecycle,
-`useSupports('nativeControls')`, and layer promotion for animation.
-
-**Phase 2 did not happen, and that is the good news.** It proposed
-extracting X11's paint/damage/flush into a presenter behind a formal
-invalidate/flush contract, as an X11-neutral refactor pinned by the pixel
-gates. What the code does instead is cheaper and safer: the surface
-presenter _is_ the existing paint machinery, drawing into the window's
-bitmap, and the seam is a handful of **optional hooks feature-detected on
-the window object** — `presentFrame`, `noteInvalidate`, `scrollRegion`,
-`animateNode`, `cancelNodeAnimation` (`src/cocoa/window.js`, read at
-`src/nodes/animation.js`). A window that does not define them gets today's path
-byte for byte, which is the guarantee Phase 2 wanted without the refactor
-it asked for. Nothing is documented in `extending.md` terms because there
-is no interface to document.
-
-**Phase 3** is therefore partial rather than blocked: the full layer
-presenter is real (`src/cocoa/presenter.js`, `CocoaLayerPresenter` — one
-CALayer per drawn node) but stays behind `cocoa: { presenter: 'layers' }`
-while §"Measure first" is open, and layer promotion covers the animation
-case on the default path.
-
-**Not built**, and honestly the interesting remainder: an `NSAccessibility`
-bridge over the a11y model (on Cocoa `createRoot()` leaves the AT-SPI bridge
-off and puts nothing in its place), IME through `NSTextInputClient`, a
-`'cocoa'` backend for `react-x11/test`, `transform` as a style property,
-and the `Primary` chord token. §"Open questions" is still live,
-and the name question (§Public API #8) was answered by inaction: the package
-is still `react-x11`.
-
-The line counts and inventories below are measurements taken when this was
-written, not estimates; where a companion number comes from
-[wayland.md](wayland.md), it is cited rather than re-measured. Sections
-titled "Measured:" were added as the work landed and each names the commit
-it was measured at.
-
-## What this is, and is not
-
-This is a plan for a **third target, second backend family**: the same
-React tree, the same components and the same application code running as a
-first-class macOS app — real `NSWindow`s, the system menu bar, native
-control rendering, Core Animation compositing — with no X server anywhere.
-X11 stays what it is: the flagship remote target ([remote.md](remote.md)),
-the window-manager story, and the only backend for `<foreign>`/XEmbed.
-Nothing here proposes changing how the X11 path works, and the plan is
-explicitly shaped so that its refactors are pinned by the existing pixel
-and bench gates before any macOS code lands on top of them.
-
-The relationship to the [Wayland RFC](wayland.md) matters, because the two
-inversions are opposite and one architecture has to hold both:
-
-- **Wayland deletes the drawing protocol downward** — the client
-  rasterizes finished pixels. Its natural seam is _below_ ntk's 2d
-  context: a span compositor behind the same `getContext('2d')` name.
-- **macOS deletes the drawing protocol upward** — the WindowServer is a
-  retained compositor and the client's job is to _mutate a persistent
-  layer tree_, not to encode draw calls and not to rasterize (except
-  where it chooses to). Its natural seam is _above_ the 2d context: at
-  the node tree itself.
-
-Both seams can exist at once, and the extraction this document proposes
-(§"One renderer, two presenters") leaves the Wayland plan intact — a
-Wayland presenter is the X11 presenter with a different surface under it.
-
-Goals, unchanged from the project's standing ones: perceived performance
-first (input-to-photon), then stability, then client CPU and memory; the
-whole range of desktop UI that the platform permits; a small portable
-codebase, with a native module admissible where the runtime leaves no
-other way to reach a required OS facility — and macOS is the clearest
-case of that clause: there is no wire protocol to speak, only
-frameworks, so the bridge is a compiled addon by necessity. What keeps
-the spirit of the rule is keeping the addon **thin and mechanism-only**
-(create/set/add/remove/pump — no policy, no widget logic), which is
-exactly the shape `node-calayers` already has.
-
-Out of scope on this backend, honestly and up front, the same way
-wayland.md declares its walls:
-
-- **A window manager cannot be written against Cocoa.** `examples/wm.jsx` and
-  the substructure-redirect half of the API remain X11-only.
-- **Cross-process window embedding does not exist on macOS.** `<foreign>`, the
-  XEmbed half of `<Frame>`, `@react-x11/components`' tray-host and its mpv/VLC
-  `--wid` embedding have no equivalent. `<Frame>` on macOS was planned as a
-  parented toplevel or an in-process pane, the fate wayland.md assigns it, and
-  shipped as neither: its pane draws into IOSurfaces a host sublayer shows
-  (`src/cocoa/panehost.js`, [frame.md](frame.md)). A `<foreign>` rendered here
-  says so — one `onError`, no `onReady`, an empty box — and
-  `useSupports('embedding')` is false, so a component can ask before rendering
-  one (#531).
-- **XQuartz is not deprecated by this.** react-x11 already runs on macOS today
-  through XQuartz; that path remains the way to run the X11 backend (and the
-  WM example) on a Mac. This backend is for shipping _native_ apps.
-
-## What macOS actually changes
-
-X11 is "the client encodes drawing, the server rasterizes and composites."
-Wayland is "the client rasterizes, the compositor composites." macOS is a
-third shape: **the client owns a retained scene graph (the CALayer tree)
-and the render server composites it on the GPU** — geometry, colors,
-corner radii, shadows, opacity, transforms, filters, and whole animations
-are _properties of persistent objects_, committed atomically in
-transactions and interpolated server-side without the client's further
-involvement.
-
-That shape is not an obstacle to this renderer; it is this renderer's own
-architecture, one level down. react-x11 is already a retained tree — every
-drawn element is a lightweight node holding style, a yoga node and an
-absolute rect, and React commits arrive as property diffs against it
-(`commitUpdate` → `applyProps(new, old)`). On X11 those diffs then have to
-be _flattened into paint_: damage rects, a paint walk, clip bounding,
-scroll blits, a paint cache — ~1,000 lines of machinery whose entire job
-is to turn retained-tree diffs back into efficient immediate-mode drawing.
-On macOS the diff **is** the drawing: a commit maps to one `CATransaction`
-of `layer.set(...)` calls, layout writes frames inside the same
-transaction, and the WindowServer recomposites what changed. The
-reconciler's native output format and Core Animation's native input format
-are the same thing — a property diff over a retained tree — with no
-serialization through an immediate-mode bottleneck between them.
-
-Three consequences are worth naming before any code, because they shape
-the whole plan:
-
-- **Animation leaves the JS thread.** A CA animation runs in the render
-  server; the POC's spinner stays smooth while JS is stalled. The
-  project's first goal is answering the input on the frame it arrived —
-  a `transition:` on `:active` that the _system_ interpolates is that
-  goal with the JS thread taken out of the loop entirely.
-- **Scrolling becomes a property.** The scroll-blit fast path — gates,
-  ledger, claim clipping, `CopyArea` (AGENTS.md §protocol efficiency) —
-  exists because scrolling on X11 is repainting. On a layer tree,
-  scrolling is `bounds.origin` on one clipping layer: constant cost,
-  server-side, and the entire fast-path apparatus does not need to exist
-  in that presenter.
-- **Retina inverts from cost to freebie.** On the X11 path a 2× display
-  quadruples every rasterized pixel; layers carry `contentsScale` and the
-  GPU composites at native resolution, with rasterization confined to the
-  nodes that actually rasterize (text, images, custom drawing).
-
-The other thing macOS changes is _expectation_: a Mac app has the menu bar
-at the top of the screen, native-looking controls, native open/save
-dialogs, ⌘-shortcuts. This project's answer to the same question on Linux
-was built desktop-first (D-Bus global menu with in-window fallback,
-portals, XSETTINGS), and this document keeps that stance: the menu bar
-becomes `NSMenu`, controls prefer native rendering with an escape hatch,
-dialogs go native — each behind the same "default that serves the main
-customer, seam for everyone else" rule the codebase already follows.
-
-## What the POC already proves
-
-_Kept as written, because it is the record of what was de-risked before any
-of this was built. The package is published as `@windowkit/appkit` now, and
-every "known POC limit" at the foot of this section has since been closed._
-
-`node-calayers` (then local, `~/tmp/node-calayers`) settles the risky
-mechanisms, which is what a POC is for:
-
-- **A Node process can own NSApplication.** Node's main thread _is_ the
-  process main thread on macOS; the addon initializes the app and JS
-  drives an event pump (`nextEventMatchingMask:` with `distantPast`) off
-  a timer. No `[NSApp run]`, no second process, no thread hop.
-- **Retained layers behave.** `Layer`/`TextLayer`/`GradientLayer`/
-  `ShapeLayer` wrappers over real `CALayer`s: frame/bounds/position,
-  backgroundColor, cornerRadius, borderWidth, shadows, opacity,
-  zPosition, masks, `masksToBounds`, transforms — mutated with
-  `layer.set(props)`, batched with `CATransaction`, suppressed with
-  `disableActions` (the reconciler-commit mode), animated implicitly and
-  explicitly (`CABasicAnimation` on any keyPath, running in the render
-  server through a JS stall).
-- **Top-left coordinates work.** A layer-hosting, flipped `NSView` makes
-  the hosted tree top-left-origin (`geometryFlipped`); the two flip
-  gotchas (`hitTest:` stays bottom-up, `renderInContext:` ignores the
-  flip) are handled in native code, and snapshots read the window's real
-  composited pixels via `CGWindowListCreateImage` — no screen-recording
-  permission needed for the process's own windows.
-- **CoreText measures and rasterizes.** `text.measure()` →
-  `{width, ascent, descent, leading}` via `CTLine`;
-  `text.render()` → CGImage via `CTFramesetter`, set as layer contents —
-  the glyph path a text visual needs. `CATextLayer` works too, taking the
-  WindowServer path for retina-crisp static text.
-- **Native control bezels render offscreen** — the WebKit/Firefox form
-  technique: `NSButtonCell`/`NSPopUpButtonCell` via `drawWithFrame:`
-  under `performAsCurrentDrawingAppearance:` (so dark mode and the user's
-  accent apply), and the two controls modern AppKit refuses to draw as
-  cells (`NSSlider`, `NSSwitch`) via a real unparented control's
-  `displayRectIgnoringOpacity:`. Push (incl. accent-filled default),
-  checkbox, radio, popup, slider, switch — interactive states, both
-  appearances, re-renderable live.
-- **Events arrive.** Mouse/key/wheel from the real pump to a JS callback;
-  synthetic event posting through the same pump for tests
-  (`postMouseEvent`), which is the `fireEvent` transport a test harness
-  wants.
-- **Hit testing round-trips.** `-[CALayer hitTest:]` maps back to JS
-  wrapper objects by layer name. (react-x11 will not use it — the node
-  tree already hit-tests — but it validates the tree's integrity.)
-
-Known POC limits, all of which are Phase-0 work items rather than
-unknowns: no modifier flags on events, one shared event callback with no
-per-window routing, no `NSWindowDelegate` (resize/close/focus arrive only
-by polling), sublayer append-only (no insert-at-index), no raw-buffer
-`contents` upload (only CGImages produced native-side), no menu API, no
-pasteboard, no drag session, no display-link frame clock, and the
-pump-on-a-timer model leaves AppKit's internal modal loops (live resize,
-menu tracking) starving JS. The full required API is specified in
-§"The bridge: the required API".
-
-## What already carries over
-
-The measured split from [wayland.md](wayland.md) §"What already carries
-over" applies unchanged, because it was measured against the display
-system, not against Wayland specifically: **~16,200 lines of portable
-core** (reconciler, yoga, styles/decorations parsing, palette, a11y
-model, keysyms, compose, text-selection model, anchors) and **~8,700
-lines of `components/` + `frame/` + `refresh/`** carry over as-is. Of
-`nodes.js`'s 11,515 lines, only `WindowNode` + `PopupNode` (~3,100)
-speak X; `BoxNode`, `TextNode`, `ImageNode`, `CanvasNode`,
-`TextInputNode`, `TextAreaNode` and the layout/hit-test machinery never
-name the display system. The honest per-backend surface is the same
-~9–10k-line list wayland.md names — window realize/present, events, DnD,
-clipboard, screens, window state, scale, keyboard state, compositing,
-input time, startup — plus, for macOS, the presenter itself.
-
-What the _consumers_ actually depend on was inventoried for this RFC
-across both sibling repos (`@react-x11/workbench` 0.1.0,
-`@react-x11/components` 0.4.0, cloned and grepped 2026-09-01):
-
-- The workbench is a thin consumer: `<box>`, `<text>`, `<window>`
-  (`title`/`width`/`height`/`onCloseRequest` only), `<textinput>`, seven
-  core components, `react-x11/test`, and
-  `jsxImportSource: "react-x11"`. Nothing X-shaped at all.
-- `@react-x11/components` is the real contract: **all ten subpaths**
-  (`.`, `/host`, `/node`, `/style`, `/keysyms`, `/test`, `/yoga`,
-  `/ntk`, `/jsx-runtime`, `/jsx-dev-runtime`, `/debug`). It subclasses
-  `Node` and overrides `paint(ctx)`/`measureContent`/`default*` in seven
-  registered elements; it uses the ntk `Context2D` dialect **including
-  the extensions** `fillRects`, `drawGlyphs`, `positioned`,
-  `layoutSubtree`, `vw`/`vh`/`em`; it reads X keysyms (`XK_*`) in twenty
-  files; and its tests name backends
-  (`renderX11(..., { backend: 'mock' | 'xserver' | ... })`).
-- Its genuinely X-only reaches are few and localized: offscreen
-  `ntk.Surface` allocation (charts, terminal, flow), `createWindow({id})`
-  for an embedded client's title, the XEmbed `windowId` flow feeding
-  mpv/VLC, `serverTime()`, and the tray host. Those stay X11-only
-  features of those components, not portability obligations.
-
-Two conclusions fall straight out of that inventory. First, **the public
-API does not need a redesign to go native** — the compatibility surface
-is the intrinsics, the components, the style system, the hooks, the
-`Node`/`Context2D`/`registerElement` seam, the keysym vocabulary and the
-test harness, and every one of those is implementable on Cocoa. Second,
-**`XK_*` keysyms are the cross-platform key vocabulary by adoption**, not
-an X leak to be replaced: they are symbolic integers used by every
-consumer, `keysymOf()`/`ctrlChordLetter()` already abstract them, and the
-macOS input layer synthesizes them (Latin-1 keysyms are their code
-points, the rest via the `0x01000000 + UCS` rule plus a ~50-entry `kVK_*`
-table for arrows/function/editing keys). Renaming them would break every
-consumer to remove a prefix.
-
-Desktop integration repeats Wayland's pleasant surprise, further along:
-the appearance ladder **already has a macOS rung** (`appearance.js` reads
-`AppleInterfaceStyle`/accent through a long-lived `osascript` child), and
-so does the file dialog ladder. The native backend upgrades those rungs
-from `osascript` to real API and deletes nothing.
-
-## One renderer, two presenters
-
-The user-facing question first — _conditional per-OS host components
-inside one reconciler, or a completely separate reconciler exposing the
-same public API?_ — because everything else hangs off it.
-
-**A separate reconciler is the wrong split, and the inventory above says
-why.** The public API that must stay identical is not a thin façade: it
-includes the retained `Node` contract itself (subclassed by consumers),
-the style system with its state blocks and transitions, the event
-synthesis rules ("answer the input" — press chains, `:active`
-narrowing, capture/bubble order), focus and tab order, text editing with
-undo/coalescing, selection, scroll semantics, the a11y model, the anchor
-math, and the test harness's behavioral assumptions. A second
-implementation of all of that is a second toolkit wearing the first one's
-types — two copies of every behavioral decision AGENTS.md records, one
-maintainer, and a drift surface the size of the project. The measured
-portable core (~25k lines with components) is precisely the code a
-separate reconciler would fork.
-
-**A pure "conditional host components" split is too shallow**, though: the
-difference between X11 and Core Animation is not _which_ box node to
-instantiate, it is _what happens after commit_ — immediate-mode paint
-versus retained-property sync. The seam has to sit at that boundary, and
-the codebase is already shaped for it in three load-bearing ways:
-
-1. `createInstance` performs **no platform calls** (the render phase is
-   discardable); every real window is created in the commit phase via
-   `realize()`. The host config is already platform-free.
-2. Nodes do not paint themselves spontaneously — they **announce**:
-   `invalidate(layoutChanged, node, reason)` is the one channel through
-   which every change reaches the screen, and `WindowNode.flush()` is the
-   one consumer. The X11 damage/paint pipeline is an _implementation of
-   that channel_, not part of the node model.
-3. Everything a node needs from the platform is already reached through
-   the `app` object — `createWindow`, `fonts.layout`, `clipboard`, the
-   event emitter — and `createRoot({ app })` injects it. The headless
-   mock in `src/testing/mock-app.js` passes the whole suite, which is
-   the existence proof that the contract is closed.
-
-So the proposal is **one renderer, one node model, two presenters**, plus
-per-platform service modules behind the existing hook APIs:
-
-| seam            | X11 implementation (today's code)                              | Cocoa implementation                                          |
-| --------------- | -------------------------------------------------------------- | ------------------------------------------------------------- |
-| **WindowHost**  | `WindowNode.realize()` → ntk `CreateWindow`, WM hints, mapping | `NSWindow` + layer-hosting flipped view; delegates → events   |
-| **Presenter**   | damage rects → paint walk → ntk 2d ctx → XRender               | dirty nodes → per-node visuals → `CATransaction` property set |
-| **TextEngine**  | ntk `FontManager.layout` (fontkit shaping, glyph atlas)        | CoreText (`CTFramesetter`/`CTLine`) behind the same interface |
-| **InputSource** | ntk window events (X11, XI2)                                   | NSEvent pump → the same normalized event shapes               |
-| **FrameClock**  | ntk rAF (Present completions + fence)                          | `CADisplayLink`/`CVDisplayLink`; CA transactions for pacing   |
-| **services**    | screens/scale/appearance/clipboard/DnD/menus/… (X + D-Bus)     | NSScreen/backingScale/NSAppearance/NSPasteboard/NSMenu/…      |
-
-The refactor this requires of the X11 code is bounded and mechanical:
-`WindowNode.flush()`'s paint half and the `_paint*` methods become the
-X11 presenter (moved, not rewritten), and the node model keeps layout,
-absolutize, hit testing, events, focus, selection and props. It lands as
-its own phase with **zero behavior change**, pinned by the existing
-pixel tests, `test/dirty-rect.test.js`, and `npm run bench -- --check` —
-the same discipline the scroll-blit work used. Registered third-party
-elements keep their `paint(ctx)` contract on both presenters (see
-§"Custom drawing on a layer tree").
-
-This split also answers the "complete rewrite vs seams" question with
-numbers: seams cost a ~3–4k-line mechanical extraction inside `nodes.js`
-plus per-backend modules that had to be written under any design; a
-rewrite duplicates ~25k lines of accumulated behavior and every future
-fix twice. And the extraction is not macOS-only spend — the Wayland
-plan's "WindowNode.realize grows a second path" and the presenter split
-are the same seams.
-
-## Two tiers, one architecture — and the reconciler fit
-
-Both integration levels from the exploration brief are real, and the plan
-uses both — but **they are stages of one build, not alternatives**, and
-the design target is the retained tier. The commitment made here, so the
-bring-up stage cannot calcify into the architecture: _Tier S exists to
-validate mechanisms and to serve as the raster fallback inside Tier L;
-every interface is designed for Tier L from day one._
-
-### Tier S — surface presenter (canvas2d, single layer per window)
-
-Implement the `app`/`window`/`ctx` contract (the `mock-app.js` shape)
-over Cocoa: an `NSWindow` whose content is one bitmap-backed layer, a
-canvas2d context over `CGContext`, CoreText behind `app.fonts`, NSEvents
-mapped to the ntk event names. `createRoot({ app: cocoaApp })` then runs
-today's renderer unchanged — damage rects, paint walk, dirty-rect
-machinery and all, painting into the bitmap and committing changed rects
-to the layer (`setNeedsDisplayInRect`-style partial uploads, or an
-IOSurface pair).
-
-Everything here is load-bearing later, which is what justifies building
-it first:
-
-- the **CG-backed 2d context** is Tier L's raster fallback for
-  `<canvas>`, `<svg>` and registered elements (CG is canvas2d's ancestor;
-  the dialect including `fillRects` maps to `CGContextFillRects`
-  directly);
-- the **CoreText TextEngine** is the same object Tier L's text visuals
-  measure and rasterize through;
-- the **window host, event mapping and run-loop work** carry verbatim;
-- the whole thing runs the existing test suite and examples on macOS
-  natively, which is the fastest possible detector for event/text/input
-  contract gaps.
-
-What Tier S cannot do, structurally: make scrolling cheap (the blit
-becomes a `memmove` + upload), or exploit retina (2× is 4× the raster
-and 4× the upload). It is a correct port with X11's cost model on
-hardware that offers a better one. Offloading an animation it can — not
-structurally, but for the few nodes that animate, which get a layer of
-their own above the bitmap (§"Layer promotion" below, issue #483).
-
-**A rounded clip stays off CoreGraphics' path clip.** CG draws through a
-non-rectangular clip by masking everything the drawing covers: a pane-sized
-picture through a `roundRect` clip took 22 ms where the same picture under a
-rectangle took 8. So a box with `overflow` and a `borderRadius` draws its
-children under its rectangle and puts the corner squares they reached back,
-the route X11 has taken since #685 (`src/nodes/roundclip.js`). The bitmap is
-CPU memory, so keeping a corner is a row memcpy out of it
-(`BackendContext2D.readbackSource`, #693), and a graph's zoom inside a
-rounded pane went from 34 to 52 frames a second.
-
-### Tier L — layer presenter (retained, the design target)
-
-The Cocoa presenter consumes the same `invalidate()` stream but keeps a
-**visual** per drawn node — lazily, only for nodes that draw something —
-and on flush syncs dirty nodes into layer properties inside one
-`CATransaction` per frame, actions disabled by default. Layout runs
-exactly as today (yoga, absolutize); frames are written from the yoga
-rects. The commit pipeline becomes:
-
-```
-React commit → applyProps diff → invalidate(node)
-  frame: yoga layout → for dirty nodes: visual.sync(node) → CATransaction commit
-```
-
-No damage rects, no paint walk, no paint cache, no scroll-blit ledger, no
-`_outsideDamage` culling — that machinery is the X11 presenter's private
-business. The style vocabulary maps almost embarrassingly well, which is
-not a coincidence — both vocabularies are children of CSS:
-
-| style prop                              | CALayer mapping                                                                   |
-| --------------------------------------- | --------------------------------------------------------------------------------- |
-| `backgroundColor`                       | `backgroundColor`                                                                 |
-| `borderRadius`                          | `cornerRadius` (+ `cornerCurve: continuous` — a native nicety X11 cannot offer)   |
-| uniform `border*`                       | `borderWidth`/`borderColor`                                                       |
-| per-edge border colors, `borderStyle`   | four edge sublayers, or the raster fallback for that node                         |
-| `backgroundImage: linear-gradient(...)` | `CAGradientLayer` (the parsed spec from `decorations.js` feeds it directly)       |
-| `boxShadow`                             | `shadowColor/Opacity/Radius/Offset` + **`shadowPath`** set from the rounded rect  |
-| `zIndex`                                | `zPosition` (+ sibling order for equal z)                                         |
-| `outline*` (focus ring)                 | one sublayer outside bounds                                                       |
-| `overflow: hidden`/scroll clipping      | `masksToBounds` on the clipping node's layer                                      |
-| scroll offset                           | `bounds.origin` on the clip layer — the whole scroll path                         |
-| `:hover`/`:active`/`:focus` state block | property sets on one layer (exactly the "repaint of one node" they were built as) |
-| `transition: { prop: ms }`              | `CATransaction` duration / `CABasicAnimation` — **runs in the render server**     |
-
-The `shadowPath` row carries a scar worth transferring: issue #413 was a
-blur re-run per composite that cost 700× and showed up in no request
-count. CA has the same trap in the same place — a shadow without
-`shadowPath` makes the render server derive the silhouette per frame —
-and the fix is the same shape: hand it the geometry once. The presenter
-sets `shadowPath` always, from the same resolved rect + radius the
-border uses.
-
-Nodes whose visual exceeds the property vocabulary do not fail — they
-**degrade to raster per node**: the visual allocates a bitmap, replays
-the node's paint through the CG-backed 2d context (translated so
-`this.abs` lands at the layer origin), and sets it as `contents`. That
-one rule carries `<canvas onDraw>`, `<svg>`, all seven of
-`@react-x11/components`' registered elements, per-edge borders and any
-future paint feature ahead of its layer mapping — correctness never
-waits for a mapping, and mappings are pure optimization.
-
-Two structural decisions inside Tier L, called out because they are easy
-to get wrong:
-
-- **Layer per drawing node, not per node.** A layout-only `<box>` (no
-  background, border, shadow, clip, or scroll) materializes no layer;
-  its children parent to the nearest ancestor with one, positioned by
-  the already-absolute rects. A clipping or scrolling node always
-  materializes (it _is_ the mask/viewport). This keeps the layer count
-  proportional to visible painted content — the same quantity the X11
-  path rasterizes — rather than to tree shape, and virtualized lists
-  (`Table`, `monitor`) already bound visible content by construction.
-  Whether collapsing is needed at all is a Phase-3 measurement
-  (`CATransaction` commit cost vs. layer count), and the fallback of
-  "every drawn node gets a layer" is the simpler first cut.
-- **The node tree stays the source of truth for input.** Hit testing,
-  capture/bubble, press chains, focus — all continue to run on node
-  rects exactly as on X11. `CALayer hitTest:` is not used for dispatch.
-  One event model, one set of tests, identical interaction semantics on
-  both backends; the layer tree is write-only presentation.
-
-Text in Tier L is a raster visual by default: the TextEngine's layout
-(same object that measured for yoga) rasterizes into the node's layer
-contents at `contentsScale`, so measurement and pixels cannot disagree.
-`CATextLayer` (attributed strings, WindowServer-side re-raster on scale
-change, animatable `foregroundColor`) is an _optional_ fast path for
-static single-style text, adopted only if profiling says the raster
-visuals' memory or update cost matters — it uses its own framesetter,
-and two framesetters is one framesetter too many for anything
-selection- or caret-bearing.
-
-### Why the retained tier is the design target, in this project's terms
-
-The project grades itself on input-to-photon, then stability, then client
-CPU (AGENTS.md, [wayland.md](wayland.md) goals). Per scenario, against
-Tier S on the same hardware:
-
-- **Hover/press feedback** (`:hover`/`:active` blocks): Tier S repaints
-  the control's rect into the bitmap and uploads; Tier L sets properties
-  on one layer. Both answer on the input's frame; L does it with less
-  work and _keeps doing it_ when the JS thread is busy mid-transition.
-- **Scrolling a 500-row list**: S = memmove + strip repaint + upload per
-  notch (the X11 fast path, minus the server doing the blit for us);
-  L = one `bounds.origin` write. The entire class of scroll-blit gates,
-  ledgers and bail conditions stops existing on this backend.
-- **Transitions** (Switch thumb, hover fades): S = JS frame loop ×
-  raster × upload for the duration; L = one animation handed to the
-  render server, frame-perfect under JS stalls. This is the qualitative
-  gap — no amount of Tier S optimization reaches "smooth while the app
-  thread is blocked".
-- **Window live-resize**: S re-lays-out and re-rasters everything per
-  tick on the modal loop's cadence; L re-lays-out and updates frames —
-  the WindowServer interpolates the rest. (Both need the run-loop work
-  in §"Input and the run loop" to receive resize ticks at all.)
-- **Typing**: equivalent — caret/selection damage is small either way;
-  L still wins on retina by shipping properties instead of pixels.
-
-And one honest cost column: Tier L pays **per-layer memory** for
-rasterized contents (text bitmaps especially — X11's shared glyph atlas
-has no direct equivalent; mitigations if measurement demands them: an
-atlas texture behind `contents`+`contentsRect`, or `CATextLayer`),
-**commit overhead** proportional to layers mutated per transaction (kept
-off the NAPI floor by the batched-ops call in the addon API), and
-**complexity in the visuals** (edge sublayers, gradient layers) that the
-raster fallback bounds.
-
-### Measure first — the gate between the tiers
-
-Per the exploration brief's own instruction: the retained tier is built
-because the model fits, but it is _kept_ because the numbers say so. The
-macOS twin of `scripts/bench` (Phase 1 exit) runs the same scenarios —
-hover storm, wheel scroll on the 500-row list, virtualized re-slice,
-transition storm, typing — and reports, per scenario: wall-clock frame
-time, **input-to-photon** (NSEvent timestamp → the display-link
-timestamp of the frame containing the response; CA has no
-presentation-time protocol, but a display link plus
-`CATransaction.completionBlock` brackets it within a frame), CPU time,
-and RSS. Tier S is the baseline; Tier L must beat it where the model
-says it should (scroll, transitions, resize) and must not regress
-typing or cold mount. If a scenario shows Tier S already saturating the
-display's refresh with headroom on target hardware, that scenario's
-Tier-L machinery (e.g. layer collapsing) is deferred — measured, not
-assumed, in both directions. The numbers land in this document's
-successor the way wayland.md carries its measurements.
+On macOS `createRoot()` renders through **Cocoa** by default: real
+`NSWindow`s, Core Animation compositing, the system menu bar and native
+control bezels, with no X server anywhere. The tree, components, styles and
+hooks are the same; this page is what an app sees differently here, and what
+it does not have yet. The design record — presenters, threads, the bridge
+contract, measurements, the plan — is [design/macos.md](../design/macos.md).
+
+## Choosing the backend
+
+`createRoot({ backend })`:
+
+- `'auto'` (the default) — Cocoa on macOS where the bridge is installed, X11
+  through `$DISPLAY` (XQuartz) where it is not.
+- `'cocoa'` — Cocoa, with the bridge **required**.
+- `'x11'` — X11 through XQuartz, still the way to run X-only features
+  (`<foreign>`, `examples/wm.jsx`) on a Mac.
+
+`REACT_X11_BACKEND=x11` or `=cocoa` overrides both. `createRoot({ app })`
+ignores `backend`: a connection already is one.
+
+The bridge is **[`@windowkit/appkit`](https://www.npmjs.com/package/@windowkit/appkit)**,
+an `optionalDependency` with N-API prebuilds for arm64 and x64, so it works
+under Node and Bun. An install that skips optional dependencies has no
+bridge, and `'auto'` falls back to X11. The range react-x11 asks for has
+everything on this page; where an older bridge lacks a verb, the feature is
+detected and degrades as described below.
+
+## Root options and environment
+
+`createRoot({ cocoa: { … } })`, ignored off macOS and when `app` is passed:
+
+- `presenter` — `'surface'` (the default: one bitmap per window) or
+  `'layers'` (one CALayer per drawn node, opt-in while it is measured).
+  `REACT_X11_COCOA_PRESENTER` says the same.
+- `promote` — [layer promotion](#layer-promotion-the-animated-few-on-their-own-layers-above-the-surface-presenter)
+  of animated boxes; `false` keeps every animation on the frame clock.
+  `REACT_X11_COCOA_PROMOTE=1`/`=0` says the same.
+- `frameInterval` — ms between scheduled frames. By default each window
+  paces itself on its own display (8.3 ms at 120 Hz, 16.7 at 60); a number
+  applies to every window.
+- `pumpInterval` — ms between AppKit event pumps (8) when the app's JS runs
+  on the main thread: the floor under input latency there. A
+  [worker](#js-on-a-worker-a-ui-thread-of-the-bridges-own) has no pump.
+- `resizeWait` — ms AppKit may hold a live-resize tick for the app's frame at
+  the new size, on a worker (50; `0` lets the edge move without waiting).
+- `paneStretch` — when a `<Frame>` pane's last frame is stretched while its
+  next one comes: `'behind'` (the default: once it is later than
+  `resizeWait`), `'never'` or `'always'`. `REACT_X11_COCOA_PANE_STRETCH` says
+  the same.
+- `screenPoll` — ms between re-reads of the screen layout while a
+  `useScreens()` subscriber is mounted (500; `0` for never).
+- `appName` — what the Dock, ⌘-Tab and the app menu print for an unbundled
+  process; a bundle's `Info.plist` wins.
+- `activationPolicy` — `'regular'` (the default: a Dock tile and a ⌘-Tab
+  entry), `'accessory'` (a menu-bar app: windows, no tile) or `'prohibited'`.
+  On a worker, set it [at launch](#js-on-a-worker-a-ui-thread-of-the-bridges-own).
+- `exitOnQuit` — end the process once a quit request (the Dock's Quit, ⌘Q, a
+  logout) has closed the app (`true`); `false` is for an embedder that owns
+  the process's lifetime.
+
+Other variables: `REACT_X11_THREADED=0` (keep the JS on the main thread),
+`APPKIT_ACTIVATION_POLICY` (the policy AppKit launches with),
+`REACT_X11_CALAYERS_PATH` (where the bridge's addon is, for a
+[compiled binary](#running-as-an-app-bundle)), and
+[`REACT_X11_NO_STROKE_CHUNKING=1`](#stroking-a-path-with-many-subpaths) and
+[`REACT_X11_NO_SHADOW_TILES=1`](#a-shadow-from-a-tile).
+
+The `desktop` option defaults to `{ a11y: false, globalMenu: false }` here:
+AT-SPI and the D-Bus menu export have nothing to register against on a Mac.
+The menu bar is [the system's own](#menus-the-global-menu-finally-at-home)
+regardless.
 
 ## Windowing semantics: what maps, what bends, what breaks
 
-| react-x11 today                                    | macOS                                                                                                      | verdict                                                                                                       |
-| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `<window>`, WM-managed                             | `NSWindow` (titled), delegate events for move/resize/close/focus                                           | maps; the app _can_ place itself (unlike Wayland)                                                             |
-| `<window x y>` screen position                     | `setFrameOrigin` (flip Y against the screen frame)                                                         | maps                                                                                                          |
-| auto-sizing (`width: 'auto'`)                      | measure first, then size the window before ordering front — same commit-phase shape as `realize()`         | maps cleanly                                                                                                  |
-| `<popup>` (override-redirect, self-placed)         | borderless non-activating `NSPanel`, `addChildWindow` to the anchor's window, screen-coordinate placement  | maps — `anchor.js` flip/clamp math survives against `NSScreen.visibleFrame`                                   |
-| `<popup grab>` dismissal                           | no pointer grabs; local+global event monitors, or key-window resignation                                   | bends — same UX, different mechanism                                                                          |
-| `decorations: false`                               | `styleMask: [.borderless]` (or `.fullSizeContentView` for CSD-ish looks)                                   | maps                                                                                                          |
-| `states`: maximized/fullscreen/minimized/attention | `zoom:`, `toggleFullScreen:`, `miniaturize:`, `requestUserAttention:`; readback via delegate notifications | maps; `sticky`/`below`/`skip_taskbar`/`shaded` have no equivalent                                             |
-| `alwaysOnTop`                                      | `window.level = .floating`                                                                                 | maps                                                                                                          |
-| `transientFor`                                     | `addChildWindow:` / sheets                                                                                 | maps for the dialog case                                                                                      |
-| `appId`, `onClientMessage`, size-increment hints   | —                                                                                                          | gone; bundle identity lives in Info.plist                                                                     |
-| `transparent`                                      | `isOpaque = false`, clear background — always composited, no compositor probe needed                       | maps _better_; `useSupports('transparency')` is constant-true                                                 |
-| frame clock (Present + fence + estimator)          | `CADisplayLink` (macOS 14+) / `CVDisplayLink`                                                              | simpler; per-window, refresh-rate-aware                                                                       |
-| scale ladder (env → XSETTINGS → Xft → RandR)       | `backingScaleFactor` + `windowDidChangeBackingProperties`                                                  | collapses to one authoritative, live source                                                                   |
-| screens (`useScreens`)                             | `NSScreen.screens`, re-read: the bridge follows the change notification, but no event reaches a client     | maps — asked before a placement and on a clock while watched (#617)                                           |
-| appearance ladder                                  | `NSApp.effectiveAppearance` KVO + `NSColor.controlAccentColor`; accent-change notification                 | the osascript rung already feeds accent + ink into the palette; in-process later                              |
-| clipboard (selections, INCR, targets)              | `NSPasteboard` (+ lazy providers for the ownership model); no PRIMARY selection                            | maps; `transfer.js` MIME plumbing reusable; INCR dies unmourned                                               |
-| DnD (XDND)                                         | `NSDraggingSource`/`NSDraggingDestination` on the hosting view                                             | maps; the `dropAccept`/`onDrag*` prop contract holds                                                          |
-| global menu (D-Bus registrar, in-window fallback)  | `NSApp.mainMenu` — **always present**, delegation never fails                                              | maps _better_; see §Menus                                                                                     |
-| file dialogs (portal → osascript → drawn)          | `NSOpenPanel`/`NSSavePanel` replace the osascript rung                                                     | upgrades                                                                                                      |
-| a11y (AT-SPI over D-Bus)                           | `NSAccessibility` protocol, virtual `NSAccessibilityElement` tree fed from the same `a11y.js` model        | maps; the model carries, the bridge is new (the Chromium/Flutter shape)                                       |
-| idle / keep-awake                                  | `CGEventSourceSecondsSinceLastEventType` / `IOPMAssertion`, `NSProcessInfo` activity                       | idle **shipped**, `ioreg` until the bridge reads it (#938); keep-awake maps                                   |
-| startup notification, `activateWindow`             | `NSApp.activate` + `makeKeyAndOrderFront:`, `NSRunningApplication`; Launch Services owns launch UX         | `activateWindow` **shipped** (`CocoaApp.raiseWindow`); startup dissolves                                      |
-| URI schemes / single instance (`application.js`)   | Apple Events (`kAEGetURL`) + Launch Services registration; single-instance is the platform default         | maps; same hooks (`onAppOpen`/`onAppActivate`), new plumbing                                                  |
-| tray                                               | `NSStatusItem`                                                                                             | **shipped** (`useTray()`); the X11 side has the freedesktop StatusNotifierItem rung (`src/statusnotifier.js`) |
-| `<glarea>` (GLX / direct CGL)                      | **shipped**: `x11-dri`'s CGL context rendering into IOSurfaces on a sublayer (`src/cocoa/glarea.js`)       | bends; ntk's `cgl` direct backend was the prior art                                                           |
-| `<foreign>`, XEmbed `<Frame>`, `examples/wm.jsx`   | —                                                                                                          | **gone by design**                                                                                            |
-| `ssh -X` remoting                                  | —                                                                                                          | X11 backend remains the remote answer                                                                         |
-| keyboard state (Caps Lock before first key)        | `NSEvent.modifierFlags` (static read + `flagsChanged`)                                                     | maps                                                                                                          |
-
-The popup row deserves the same sit-down wayland.md gave it, with the
-opposite conclusion: macOS _keeps_ client-side placement, so `anchor.js`
-stays the single source of truth on this backend — the math that had to
-move into Wayland's positioner stays exactly where it is here, reading
-`NSScreen` geometry instead of Xinerama.
+macOS has no separate window manager, so what one does is where the backends
+part company. The per-prop list is
+[elements.md](elements.md#on-the-cocoa-backend); in short:
+
+- **Maps**: `<window>` is an `NSWindow` that places itself (`x`/`y` work),
+  min/max sizes are its own, and its size is a whole number of points,
+  rounded up. `resizable` and `decorations` are read once, at creation.
+  `fullscreen`, `maximized`, `hidden` and `demands_attention` are the
+  full-screen Space, the zoom, the Dock and the Dock bounce.
+- **Better**: `transparent` and a window's `borderRadius` always work —
+  every window composites, so `useSupports('transparency')` is always true.
+- **Inert**: the `sticky`, `below`, `skip_taskbar` and `shaded` states;
+  `appId`, `windowType`, `gravity` and the increment and aspect hints (bundle
+  identity lives in `Info.plist`); `transientFor`, for now — a managed
+  `<Dialog>` floats on its own window anyway. `onClientMessage` never fires.
+- **`<popup>`** is a borderless panel at the popup level, placed by the same
+  anchor math. `grab` bends: there are no pointer grabs, so a press in
+  another of the app's windows reaches the popup as a press outside it,
+  which dismisses it. `grabKeyboard` makes a key-capable window, as
+  `NSPopover` does, which closes on `onBlur` ([elements.md](elements.md)).
+- **`<glarea>`** is a CGL context rendering into IOSurfaces on a sublayer
+  ([gl.md](gl.md)); **`<Frame>`** works through shared surfaces rather than
+  reparenting ([frame.md](frame.md)).
+- **Screens** (`useScreens`) map, but macOS sends a client no event for a
+  display change, so the layout is re-read on a clock while watched
+  ([system.md](system.md#on-macos-the-layout-is-asked-for-not-announced)).
+  `app.scale` is the screen's `backingScaleFactor`, read once, at startup.
+- **Not yet**: nested `<window>` elements throw.
+- **Gone by design**: `<foreign>` and XEmbed, a window manager
+  (`examples/wm.jsx`), `ssh -X`. A `<foreign>` reports one `onError` and
+  draws an empty box; `useSupports('embedding')` is false.
+
+**Inert means inert, not fatal, and silent**: a prop with no meaning here is
+accepted and does nothing, so the same JSX runs on every backend and shared
+application code stays branch-free.
 
 ## Desktop integrations: what an app does outside its own windows
 
-The handful of things an app says to the desktop rather than draws — a file
-dialog, a permission prompt, a drag to another app, a tray icon, a Dock badge,
-a raise from a launcher. This is the survey of where each stands on the cocoa
-backend, what already works (including the crude `osascript`/shell rungs that
-need no bridge), and what is blocked on a native addition — each gap has a
-`@windowkit/appkit` ticket for the bridge and a react-x11 ticket for the
-consumer, so the work is tracked rather than rediscovered.
-
-| integration                       | today on cocoa                                                                                                                                                                                                                                                                                                                                    | the better way (bridge gap)                         | tickets                                                         |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------- |
-| **file open/save**                | **shipped** — `NSOpenPanel`/`NSSavePanel` as a sheet, the ladder's top rung (`docs/filedialog.md`)                                                                                                                                                                                                                                                | — (bridge 0.5)                                      | react-x11#461 → windowkit/appkit#14 (done)                      |
-| **raise / app switcher**          | **shipped** — `activateWindow()` = `NSApp.activate` + order-front                                                                                                                                                                                                                                                                                 | —                                                   | this PR (`CocoaApp.raiseWindow`)                                |
-| **deep links** (`useAppOpen`)     | **shipped** — Apple Events → `useAppOpen`/`useAppActivate`; Quit → the primary window's close request                                                                                                                                                                                                                                             | — (bridge 0.5)                                      | react-x11#465 → windowkit/appkit#18 (done)                      |
-| **drag & drop** (external)        | **shipped** — `NSDraggingDestination`/`Source` behind the same `dropAccept`/`onDrag*`/`dragData` props                                                                                                                                                                                                                                            | — (bridge 0.5)                                      | react-x11#462 → windowkit/appkit#16 (done)                      |
-| **clipboard**                     | **shipped** — `useClipboard()` and the text controls, over `NSPasteboard.general` as `CLIPBOARD`: every type in `targets()`/`read()` (text by the bridge, the rest by `osascript` until it reads items), `watch()` polling `pasteboardChangeCount()`. `PRIMARY` is X11-only, not a missing rung: selecting copies nothing (`docs/clipboard.md`)   | `pasteboardItems()`, `pasteboardItemData(i, type)`  | react-x11#937 → windowkit/appkit (to file)                      |
-| **system tray**                   | **shipped** — `useTray()` over `NSStatusItem` (the freedesktop half landed too, #353)                                                                                                                                                                                                                                                             | — (bridge 0.5)                                      | react-x11#463 (macOS half of #353) → windowkit/appkit#17 (done) |
-| **Dock badge / attention / menu** | **shipped** — `setBadge`/`useBadge` (LauncherEntry on Linux), `demands_attention` bounces, `useLauncherMenu`                                                                                                                                                                                                                                      | — (bridge 0.5)                                      | react-x11#464 → windowkit/appkit#15 (done)                      |
-| **activation policy / app name**  | **shipped** — `createRoot({ cocoa: { activationPolicy, appName } })`                                                                                                                                                                                                                                                                              | — (bridge 0.5)                                      | react-x11#464 → windowkit/appkit#15 (done)                      |
-| **permissions** (TCC)             | **shipped** — `usePermission()`/`requestPermission()` over the bridge; `openPrivacySettings` on any Mac                                                                                                                                                                                                                                           | — (bridge 0.5); Linux portals are #466's other half | react-x11#466 → windowkit/appkit#19 (done)                      |
-| **notifications**                 | **shipped** — `notify()` over `UNUserNotificationCenter` in a bundle, `osascript` for a bare `node`; `org.freedesktop.Notifications` on Linux                                                                                                                                                                                                     | — (bridge 0.5)                                      | react-x11#469 → windowkit/appkit#26 (done)                      |
-| **calendar** (EventKit)           | **shipped** — `useDesktopCalendarEvents()` over `EKEventStore`, an `osascript` child under XQuartz; Evolution Data Server on Linux                                                                                                                                                                                                                | — (bridge 0.8)                                      | react-x11#504 → windowkit/appkit#39, #40 (done); writes are #41 |
-| **eyedropper** (`useEyedropper`)  | **shipped** — `pickScreenColor()` over `NSColorSampler`, the ladder's top rung (`docs/eyedropper.md`); the system draws the loupe out of process, so no Screen Recording grant of our own. A bridge before 0.9 has no rung at all — `supported` is false, and the X11 rung needs a pointer grab and a root read the cocoa `X` stub has neither of | — (bridge 0.9)                                      | react-x11#517 → windowkit/appkit#46 (done)                      |
-| **idle time** (`useIdle`)         | **shipped** — `app.lastInputMs()`, polled on the adaptive wait the X rung uses: the bridge's `lastInputMs()` where it has one, otherwise `ioreg`'s `HIDIdleTime`, a short-lived child per check, only while a `useIdle()` is mounted                                                                                                              | `lastInputMs()`, a CoreGraphics read                | react-x11#938 → windowkit/appkit (to file)                      |
-
-Two of these have a **freedesktop counterpart worth having in core with no
-bridge at all**, because they are D-Bus like the portal and the global menu
-already are: the Dock badge (`com.canonical.Unity.LauncherEntry`, one signal
-under the app's `.desktop` id) and the permission prompts (the per-device
-portals — `org.freedesktop.portal.Camera`, `.Location`). Both are tracked on
-the react-x11 tickets above so the cross-backend API is designed once.
-
-The pattern for every rung here is `docs/filedialog.md`'s ladder: the desktop's
-own mechanism where there is one, a crude shell-out beneath it, and a typed
-"cannot do this here" at the floor — never a silent no-op.
-
-## Text: the engine contract
-
-Everything the renderer needs from text goes through one object today —
-`app.fonts.layout(spans, base, options)` returning a layout with
-`{width, height, draw(ctx, x, y), indexAt(x, y), caretPosition(index),
-rangeBands(...)}` plus font loading (`openFont`/`loadFont`) and glyph
-queries. That interface _is_ the TextEngine contract; the macOS backend
-implements it over CoreText, the optional `coverage()` (#673) included:
-
-- **Matching**: family list + weight/style/`fontVariationSettings` →
-  `CTFontDescriptor`/`CTFontCreateWithName`, with the CSS generic
-  families mapped to system faces (`sans-serif` → SF via
-  `systemFontOfSize`, which also finally answers the fontconfig-on-macOS
-  wrong-font issue #86 for this backend — the right fix on the native
-  path is not having fontconfig in it at all). `opsz` behaves (SF's
-  optical sizing is CoreText-native). `-apple-system` and
-  `BlinkMacSystemFont` — the system font's names in WebKit and Gecko, and
-  in Blink, from before CSS called it `system-ui` — are `system-ui` here,
-  in any case, so a stack written for the web that leads with them is set
-  in SF rather than in the first fallback that happens to be installed.
-  Only on this backend: they name the Mac's face and nothing on X11.
-- **Sizes reach CoreText as points.** A size the engine is handed is in
-  device pixels, and CoreText reads some of a face's data by point size:
-  San Francisco's optical size and tracking, and the tracking Apple Color
-  Emoji's `trak` table adds below 29pt. Made at the device size, a font on
-  a 2x display was the face as it is set at twice its size — a 13px label
-  8% narrower than AppKit sets it, a 19px emoji 1em wide where it is 23pt
-  at 19pt — while faces with no such data (Helvetica, Menlo, most web
-  fonts) measured the same, which is why it hid. So every font is made at
-  `size / app.scale` points under a matrix of `app.scale` (the bridge's
-  `scale`, windowkit/appkit#106), and CoreText answers in device pixels as
-  before. An emoji's advance is the one number that is not exactly twice
-  its 1x one: CoreText rounds a bitmap glyph's to a whole pixel of the font
-  it is set in, half a point at 2x (test/cocoa-text-scale.test.js). A
-  bridge older than the option ignores it.
-- **Shaping/wrapping/bidi/truncation**: `CTFramesetter` over an
-  attributed string built from the same span list (spans map to
-  attribute ranges — the nested-`<text>` model transfers directly).
-  OpenType features are a property of the font, so a span with
-  `fontVariantNumeric` or `fontFeatureSettings` is set in a font with them
-  applied (`fontApplyFeatures`, one per face and feature set), and
-  `letterSpacing` is the span's `kCTKernAttributeName`, with the optional
-  ligatures turned off as ntk turns them off (issue #588). A bridge older
-  than the verb draws the face unchanged and says so once in development.
-- **Metrics for yoga**: the same framesetter answers `measureContent`,
-  so measure and render cannot disagree. Whole-pixel answers, per the
-  yoga content-floor rules. **A width offer of zero is the min-content
-  question**, not a degenerate layout — it is how yoga measures the floor
-  under `minWidth: 'auto'` — and CoreText cannot be asked it directly: its
-  breaker makes progress whatever width it is given, so a paragraph offered
-  zero (or a pixel) comes back broken _inside_ its words. So the engine
-  breaks the text itself, at the UAX#14 opportunities of the same
-  `linebreak` package ntk wraps with, and has CoreText shape and measure the
-  result — one unbreakable run per line, whose widest is the longest word.
-  Both backends therefore agree on where a line may break and on what a
-  `<text>` in a flex item is allowed to shrink to
-  (`brokenAtEveryOpportunity`, src/cocoa/fonts.js;
-  test/cocoa-text-floor.test.js). **A paragraph that elides is asked a
-  different question**, and the engine answers it here too: it has somewhere
-  to put the text it cannot show, so its floor is the `…` it would end in
-  rather than its longest word. Eliding needs a width, which the zero offer
-  is not, so the cap and the cut are made in the text — the first
-  `maxLines - 1` broken lines and then the mark, in the face of the run the
-  cut fell in — and CoreText is asked for neither
-  (`cappedToEllipsis`). Left to elide unbounded it keeps the line count and
-  puts everything over it back on the last line, which floored every
-  `textOverflow: 'ellipsis'` label at max-content and made it overflow
-  sideways rather than give way.
-- **Carets/hit/selection**: `CTLineGetStringIndexForPosition`,
-  `CTLineGetOffsetForStringIndex`, line origins → `indexAt`,
-  `caretPosition`, `rangeBands` — the `<textinput>`/selection surface,
-  method-for-method. **An empty paragraph is one empty line**, as tall as a
-  line of the face it would have been set in and aligned as one, because
-  that is ntk's answer and every caret is measured from it. CoreText sets
-  no line for no text, so the engine makes that one itself
-  (`blankLine`, test/cocoa-empty-paragraph.test.js). Without it an empty
-  field's caret was its mark padding alone, and an empty `<textarea>`'s was
-  nothing.
-- **Raster**: draw the frame into a bitmap for the node's layer
-  (`contentsScale`-aware); glyph-run-level drawing
-  (`CTFontDrawGlyphs`) backs the `drawGlyphs`/`positioned` context
-  extensions the terminal and code-editor components use.
-- **Coverage**: `coverage({ pad })`, a layout's coverage without a surface,
-  is the bridge's `layoutCoverage` (`@windowkit/appkit` 0.13.0,
-  windowkit/appkit#73). Each glyph's CoreText outline
-  (`CTFontCreatePathForGlyph`) goes where the run put it, unrounded, and the
-  layout is filled once, non-zero, by the signed-area accumulation ntk
-  rasterizes with, so this engine and X11's give the same bytes for the same
-  outlines. It is deliberately not CoreText's glyph rasterizer. With font
-  smoothing off that snaps nothing, but it shrinks a small glyph's counters:
-  Menlo's `b` at 14px comes out 5% heavier than its outline. CoreGraphics'
-  path fill is exact to a percent but costs 160–340 µs a label, several times
-  the draw and readback it replaces; the accumulation costs 23–58 µs. A
-  span's colour plays no part, and Apple Color Emoji's bitmaps come out as
-  their silhouettes. A bridge without the verb answers null.
-
-The glyph-run seams are part of that contract on both backends (issue
-#432, over @windowkit/appkit 0.3's glyph natives — windowkit/appkit#1).
-The face `fonts.match()` returns answers ntk's `glyphIdFor(cp)` (`null`
-when unmapped), `advanceOf(id, size)` and `shape(text, size)` beside
-`metrics(size)` — which reports ntk's `lineGap`/`lineHeight` alongside
-CoreText's `leading` — and the manager answers `fallbackFor(cp, family,
-opts)` off the app's loaded faces and then CoreText's cascade. The
-context answers `drawGlyphs(op, src, positioned)`,
-`createSolidPicture(r, g, b, a)` and `Render.PictOp.{Over, Src}` with
-ntk's exact run contract, grouping the runs by face and size into one
-`CTFontDrawGlyphs` per colour, so a renderer written against ntk's
-context — `<Terminal backend="vt">` — runs unchanged. Three things
-differ from ntk and are stated where they live: `shape()` runs the text
-through the typesetter (`fontShapeText`), and a glyph from a run
-CoreText substituted carries that face as `font`, which `drawGlyphs`
-honours — so an emoji cluster in Menlo comes out as the emoji, where ntk
-shapes `.notdef`; every op draws as Over, which for the opaque inks text
-uses is what Src does too; and the transform scales glyphs as well as
-their origins, because CoreGraphics draws text through the CTM like
-everything else.
-
-The alternative — reusing ntk's fontkit shaping stack on macOS and
-rasterizing through the Wayland Tier-A span compositor — is recorded,
-not chosen: it buys byte-identical metrics across backends (one test
-suite, one wrap behavior) at the cost of client-side font matching
-against the macOS font system (the exact pain #86 documents), no
-system-font niceties, and a hard dependency on the Wayland renderer
-workstream. The seam keeps it swappable if cross-backend metric parity
-turns out to matter more than platform-correct text; the default is the
-platform's own text system, matching how every other ladder in this
-project prefers the platform's own answer.
-
-Grayscale antialiasing (macOS dropped subpixel AA in Mojave) means
-self-rastered text is not visibly second-class — the field's CPU-raster
-toolkits look native on modern macOS.
-
-**IME** is the reason to be on this text stack eventually:
-`NSTextInputClient` on the hosting view, routed to the focused node's
-composition events (`CompositionStart/Update/End` already exist in the
-event vocabulary), gives dead keys, marked text and CJK input the way
-the platform means it — the capability X11 issue #272 wants and cannot
-yet have. Phase 5, but the view is written with the protocol stubs from
-day one.
+Most of these are [filedialog.md](filedialog.md)'s ladder: the platform's
+mechanism, a shell-out beneath it, and a typed "cannot do this here" at the
+floor.
+
+- **File open/save**: `NSOpenPanel`/`NSSavePanel`, a sheet on the window that
+  asked ([filedialog.md](filedialog.md)).
+- **Raise**: `activateWindow()` activates the app and orders the window front.
+- **Deep links, documents, reopen**: Apple Events into
+  `useAppOpen`/`useAppActivate`; Quit is the primary window's close request;
+  single instance is the platform default
+  ([uri-schemes.md](uri-schemes.md#on-macos)).
+- **Drag and drop with other apps**: AppKit's dragging behind the same
+  `dropAccept`/`onDrag*`/`dragData` props
+  ([drag-and-drop.md](drag-and-drop.md#interoperating-with-other-applications)).
+- **Clipboard**: `NSPasteboard.general` as `CLIPBOARD`; `watch()` polls.
+  No `PRIMARY`: selecting copies nothing ([clipboard.md](clipboard.md)).
+- **Tray**: `useTray()` over `NSStatusItem`, icon names as SF Symbols
+  ([desktop.md](desktop.md#the-tray)).
+- **Dock**: `setBadge`/`useBadge`, the `demands_attention` bounce,
+  `useLauncherMenu`; the name and activation policy are the `cocoa` options
+  ([desktop.md](desktop.md#the-launcher-a-badge-attention-and-the-dock-menu)).
+- **Permissions**: `usePermission()`/`requestPermission()` over TCC, and
+  `openPrivacySettings`
+  ([permissions.md](permissions.md#what-each-kind-actually-does-on-macos)).
+- **Notifications**: `notify()` over `UNUserNotificationCenter`, only in a
+  **code-signed app bundle**; `osascript` banners otherwise
+  ([notifications.md](notifications.md)).
+- **Calendar**: `useDesktopCalendarEvents()` over EventKit
+  ([desktop-calendar.md](desktop-calendar.md)).
+- **Eyedropper**: `pickScreenColor()` over `NSColorSampler`; the system draws
+  the loupe, so no Screen Recording grant is needed. A bridge older than 0.9
+  has no rung, and `useEyedropper().supported` is false
+  ([eyedropper.md](eyedropper.md)).
+- **Idle time**: `useIdle()`, from the bridge or `ioreg`
+  ([system.md](system.md#useidle-and-usekeepawake--is-anyone-there)).
+- **Appearance**: dark or light, the accent, and the desktop's whole palette
+  ([appearance.md](appearance.md#the-desktops-palette)).
+- **Keep-awake**: no macOS rung — `useKeepAwake()` holds nothing here.
+- **Accessibility**: none yet ([below](#not-supported-yet)).
+
+## Text
+
+Text goes through CoreText behind the same API: the same `<text>` measures,
+wraps, elides, selects and hit-tests on both backends, with the platform's
+metrics, which differ from X11's. Layout can wrap differently across
+backends; compare structure and behaviour across them, not pixels.
+
+- **Fonts are the system's.** The CSS generic families map to system faces
+  (`sans-serif` is San Francisco), `opsz` is CoreText's own optical sizing,
+  and `-apple-system` and `BlinkMacSystemFont` read as `system-ui`, so a font
+  stack written for the web sets in SF. Labels and emoji measure as AppKit
+  sets them.
+- **OpenType features** (`fontVariantNumeric`, `fontFeatureSettings`) and
+  `letterSpacing` work; `letterSpacing` turns optional ligatures off, as on
+  X11. A bridge too old for one draws the plain face and says so once in
+  development.
+- **Lines break** at the same UAX#14 opportunities as on X11, so a `<text>`
+  in a flex item shrinks to the same min-content width; one that elides
+  (`textOverflow: 'ellipsis'`) floors at its `…`. An empty paragraph is one
+  empty line, so an empty field's caret has a line's height.
+- **Antialiasing is greyscale**, as macOS has drawn it since Mojave.
+- **Glyph-level drawing** (`drawGlyphs`, `positioned`, a face's
+  `glyphIdFor`/`advanceOf`/`shape`/`metrics`, `fallbackFor`) answers ntk's
+  contract, so a renderer written against ntk's context runs unchanged.
+  Three differences: `shape()` substitutes fallback faces, so an emoji in
+  Menlo comes out as the emoji where ntk shapes `.notdef`; every op draws as
+  `Over`; and a transform scales glyphs as well as their origins.
+- **`coverage()`** is the signed-area fill X11 uses, so both give the same
+  bytes for the same outlines; colour emoji come out as silhouettes. A bridge
+  without the verb answers `null`.
+- **No input method yet**: dead keys, Press-and-Hold accents and CJK input
+  wait on `NSTextInputClient` ([events.md](events.md#input-methods) says what
+  a dead key types meanwhile).
 
 ## Input and the run loop
 
-Event mapping is mechanical — the normalized shapes already exist and the
-dispatcher never sees platform structs:
-
-- Mouse/wheel: NSEvent → `{x, y}` flipped to top-left (POC does this),
-  buttons, click counts (`clickCount` → `detail`), `scrollingDeltaX/Y`
-  with `hasPreciseScrollingDeltas` → the `smooth` wheel flag (macOS is
-  the smooth-scroll platform; the wheel pipeline already handles pixel
-  deltas), enter/exit via a tracking area, per-window routing by
-  `windowNumber`.
-- Hover is the active window's. The tracking area is `ActiveAlways`, so
-  motion over a background window arrives, and the event manager drops it
-  there (`app.hoverNeedsActiveWindow`, [events.md](events.md#when-the-response-is-painted)):
-  the platform's convention, which the window server already kept for the
-  cursor — one set by an application that is not the active one is ignored
-  — so a link in a background window lit up under an arrow. A press still
-  acts on the first click (`acceptsFirstMouse`), and the wheel still
-  scrolls.
-- Modifiers: `modifierFlags` → `shiftKey/ctrlKey/altKey/metaKey`
-  (⌘ = meta, ⌥ = alt — the DOM's own macOS convention, which the event
-  API borrowed already). The app says ⌘ is what shortcuts are pressed
-  with (`primaryModifier: 'Super'`), so the text controls answer ⌘Z/⌘C/⌘V
-  and their edit menu prints `⌘C`
-  ([events.md](events.md#primary-modifier)).
-- Keys: `keyCode` (kVK) + `characters`/`charactersIgnoringModifiers` →
-  `keysym` (rule above), `codepoint`, `key`, `repeat`. The Latin-chord
-  rule from `keyboard.js` (shortcuts keep working under a Cyrillic
-  layout) is reimplemented from
-  `charactersByApplyingModifiers:`/the kVK position map — same behavior,
-  simpler source.
-
-**The run loop is the one architectural risk in the whole plan**, so it
-gets the full treatment. The POC's model — Node's loop is master, a
-timer pumps `nextEventMatchingMask:` — works until AppKit runs one of
-its internal modal loops (live window resize/drag, menu tracking,
-drag sessions, panel runModal), which happen _inside_ the pump call: JS
-is then frozen for the duration, timers queue, React cannot commit, and
-only render-server animations keep moving. Three options, in ascending
-order of invasiveness:
-
-1. **Timer pump only** (POC today). Acceptable for the spike; input
-   latency is the timer cadence; modal loops starve the app. Not
-   shippable as the default.
-2. **Timer pump + a libuv drain inside AppKit's loops** — install a
-   `CFRunLoopObserver`/source that runs
-   `uv_run(uv_default_loop(), UV_RUN_NOWAIT)` (plus microtask
-   checkpoint) each cycle of _whatever_ run loop is spinning. AppKit's
-   modal loops then keep Node alive: React commits during live resize,
-   menu items update while a menu is open, timers fire. This is the
-   standard libuv embedding recipe pointed the other way, and it is
-   bounded addon work. The risk to design for is re-entrancy — JS
-   running from inside a native frame that a JS call started — which the
-   addon guards with an in-pump flag (no nested drains) and by keeping
-   drains off the pump's own cycle.
-3. **Full inversion** — `[NSApp run]` owns the process, libuv embedded
-   as a slave (the Electron shape: watch `uv_backend_fd` on a helper
-   thread, wake the main loop, drain there). Most correct, most
-   invasive; not needed until proven needed.
-
-**Decision: build 2, keep 1 as the fallback switch, hold 3 in reserve.**
-Exit criterion for Phase 0: during a live window resize, a React
-state-driven relayout visibly tracks the drag — that single demo proves
-the drain works where it matters most.
-
-**What happened instead.** Option 2 was never built: doing a frame's work
-inside the delegate callbacks (`CocoaApp._afterInput`) met the exit
-criterion without it, and option 1 is what shipped — now the fallback
-(`REACT_X11_THREADED=0`) behind the default below. When the drain was finally
-probed (2026-09-11) its re-entrancy risk turned out to be concrete rather
-than theoretical — a `uv_run` nested under a JS call runs timers and never
-drains the microtasks they queue — and the shape that removes both of option
-1's costs on stock Node and Bun is a fourth one: AppKit keeps the main thread
-in a real `[NSApp run]` and the JS moves to a worker. §"JS on a worker: a UI
-thread of the bridge's own" below.
-
-The frame clock rides the display link: `requestAnimationFrame` callbacks fire
-on link ticks, commits wrap in explicit `CATransaction`s, and the "answer the
-input" early-flush (`flushPendingFrames` on handler unwind) maps to committing
-the transaction before the pump returns to AppKit — same policy, new
-mechanism. What runs in pump mode is the timer pump with a frame interval over
-it (threaded mode, the default, has no pump and gives every frame a timer of
-its own — §"The renderer's half") (`frameInterval`; by default the period of
-the display each window is on, as `listScreens` reports it — 8.3ms on a 120Hz
-panel, 16.7 on a 60Hz monitor — with a frame that falls between two pump ticks
-given a one-shot timer of its own, so the period is the display's whatever the
-pump's cadence — and, since the frame pacer, a frame asked for between two
-ticks armed on the spot rather than looked at by the next tick), discrete
-input and the wheel flushed on the event, and a window that is not on glass
-deferring its frames — see "Measured" below for what each of those was worth.
-
-What the clock cannot know is whether a frame is worth painting. It has no
-fence: the X11 frame waits for the server to consume the last one, and a
-window fed off an input path — a streaming terminal — self-paces to what
-the server can composite; here the "server" is CoreGraphics on the JS
-thread and the frame is due whenever the display is, so the same window
-paints every refresh and the thread paints screens nobody reads. That is
-`frameRate`'s job ([elements.md](elements.md#framerate--pacing-the-frames-under-a-flood),
-[architecture/frame-pacing.md](architecture/frame-pacing.md)): a window
-under `'adaptive'` holds a claim while its recent frames have spent more
-than their share of the thread, priced by what the flush _and the present_
-cost — `CocoaWindow.present` reports the flip back to the node, and the
-damage-sized catch-up copy behind it is paid inside the next frame's flush
-(§"Measured: the swapchain and the WindowServer's hold"). Off by default;
-`cocoa: { frameInterval }` stays the clock's own cap over everything on it.
+- **Pointer**: top-left coordinates, `clickCount` as `detail`, and a
+  trackpad's precise deltas as the wheel's `smooth` flag.
+- **Hover belongs to the active window**: a background window gets no
+  `:hover`, enter, leave or motion until it is active, the platform's
+  convention ([events.md](events.md#when-the-response-is-painted)). A first
+  click on a background window still acts, and the wheel still scrolls it.
+- **Modifiers**: ⌘ is `metaKey`, ⌥ is `altKey`. ⌘ is the app's primary
+  modifier (`app.primaryModifier` is `'Super'`), so the text controls answer
+  ⌘Z/⌘C/⌘V, their edit menu prints ⌘C, and a chord written with `Control`
+  means ⌘ ([events.md](events.md#primary-modifier)).
+- **Keys** arrive as the same `XK_*` keysyms as on X11, and shortcuts keep
+  their Latin letters under a non-Latin layout. The lock state is readable
+  before the first key.
+- **Frames** are paced per window on its own display. A window that is
+  ordered out, miniaturized or entirely covered by another app's window
+  paints nothing — its frames and `requestAnimationFrame` callbacks wait —
+  and gets one catch-up frame when it is back. A window fed off a stream (a
+  terminal under `cat`) paints every refresh unless it sets
+  `frameRate: 'adaptive'`
+  ([elements.md](elements.md#framerate--pacing-the-frames-under-a-flood)).
 
 ## JS on a worker: a UI thread of the bridge's own
 
-The run loop above leaves two costs standing, and the Windows PRD names
-them: input waits for the pump, and a modal loop freezes Node
-([windows.md](windows.md#what-the-cocoa-backend-does-and-what-it-costs)).
-Its answer on Windows is a UI thread of the addon's own — one thread creates
-every window and runs every modal loop, JS stays on Node's thread, and events
-cross through a `napi_threadsafe_function`
-([windows.md](windows.md#three-shapes-on-windows)). Win32 allows that because
-a window belongs to the thread that created it. AppKit does not: an
-`NSWindow` made anywhere but the main thread is an exception that ends the
-process — `createWindow2` called from a worker aborts with _"NSWindow should
-only be instantiated on the main thread!"_
-
-So on macOS the same shape runs with the roles swapped. **The UI thread is
-the process main thread, parked in a real `[NSApp run]` for the life of the
-app, and the renderer — React, layout, painting, CoreText — moves to a
-`worker_threads` Worker.** The rest of the Windows design carries over
-unchanged: the three rules that keep two threads from deadlocking
-([windows.md](windows.md#the-rules-that-keep-it-from-deadlocking)), one
-wake per frame for commands, events in batches, and the bounded resize
-handshake ([windows.md](windows.md#resize-where-the-threads-meet)). The
-bridge's half is filed as
-[windowkit/appkit#49](https://github.com/windowkit/appkit/issues/49),
-with the probe's code.
-
-### Why the JS has to leave the main thread
-
-Options 2 and 3 above keep the JS where it is and run libuv from inside
-AppKit's loops, and both nest: the addon is only ever entered from JS, so a
-`uv_run` it starts from inside `[NSApp run]` runs under the JS call that got
-it there. The probe below pumped the main thread's own loop that way, from a
-common-modes timer: the main thread's `setInterval` callbacks fired, three of
-three, and **none of the microtasks or next-ticks they queued ever ran**.
-Node drains them when the outermost callback scope closes, and a scope opened
-under a JS call is never the outermost — the failure
-[#484](https://github.com/sidorares/react-x11/pull/484) found inside the
-pump, now for every callback. An inversion that does not nest needs whoever
-owns `main()` to own the outer loop, which is why Electron patches libuv and
-NodeGui ships a forked Node; and Bun has no libuv loop to embed at all. On
-stock `node` and `bun`, a worker is the shape that frees the JS.
-
-A worker wakes on the same kind of threadsafe call, and its deliveries are
-outermost: a microtask queued inside one ran 0.01–0.02 ms later (p50), so a
-handler's `setState` commits on the event that caused it.
-
-### Measured: the probe
-
-2026-09-11, Apple M1 Pro, macOS 15.2, Node 26.0.0 and Bun 1.4.0, react-x11
-at e372289. The probe is an addon of its own, about 600 lines, in the shape
-proposed here: a command queue drained by a version-0 `CFRunLoopSource` in
-`kCFRunLoopCommonModes`, events out through one threadsafe call per wake
-with motion folded, a layer-hosting window like the bridge's, and the
-bounded resize wait. Its worker ran a 5 ms timer and posted a layer change
-every 16 ms through every phase.
-
-|                                               | today: the 8 ms pump                        | the probe: JS on a worker                                                |
-| --------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------ |
-| an event reaching JS                          | waits for the next tick, 0–8 ms             | 0.02 ms p50; p95 0.13 ms idle, 1.3–1.8 ms inside a modal loop            |
-| JS through menu tracking                      | frozen — a drag held a 25 ms timer for 31 s | the 5 ms timer's worst gap: 14.0 ms                                      |
-| JS through an `NSAlert`'s `runModal`          | frozen                                      | 9.7 ms                                                                   |
-| JS through a live resize                      | only the delegate callbacks run             | 12.5 ms                                                                  |
-| a layer change posted by JS                   | inline                                      | applied 0.02 ms later, p50, whatever mode the run loop is in             |
-| a frame at the new size, during a live resize | same thread, same call                      | 39 of 39 ticks inside a 50 ms wait; waited 3.1 ms p50 for 3 ms of layout |
-| the main thread busy for 300 ms               | JS frozen                                   | JS timers unaffected, worst gap 6.1 ms                                   |
-| JS busy for 200 ms                            | every window frozen                         | windows live; the 10 events JS missed arrive as one batch                |
-
-Layer changes landed inside the menu's `NSEventTrackingRunLoopMode` (72 of
-them) and the alert's `NSModalPanelRunLoopMode` (75), which is what a
-source in the common modes buys. The shipped bridge, loaded in a worker,
-answered the rest of the design's questions: all 182 verbs load, CoreGraphics
-drawing with readback and CoreText work from the worker, `createWindow2`
-aborts, and `measureControl` with `drawControlIntoSurface` draws correct
-pixels and then segfaults the process at exit — bezels stay on the UI
-thread.
-
-What the probe did not show: a hardware live resize (it posts mouse events
-into the same tracking loop), a real drag session (a real `beginDrag` holds
-the pointer for about 30 seconds), or anything on glass, which this
-machine's session cannot capture.
-
-### Who owns what
-
-| thread                    | owns                                                                                                                                                                                                                                                                                                   | reaches the other by                                                                            |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
-| the main thread — UI      | `NSApplication` and its delegate; every `NSWindow`, view and panel and their delegates; the menu bar, the Dock, status items; the cursor; the pasteboard; drag sessions, file panels, the colour sampler; control bezels; the `CATransaction` that applies each frame's layer changes; the resize wait | batched events through one threadsafe function per environment; state it publishes under a lock |
-| the worker — the renderer | React, layout, the node tree; CoreGraphics into IOSurface-backed surfaces; CoreText and fonts; `<glarea>`'s CGL context                                                                                                                                                                                | commands queued to the UI thread, one wake per frame                                            |
-
-Pixels stay on the worker, and they are most of a frame. What crosses is
-the frame's layer changes, as one batch the UI thread applies in one
-transaction — one commit, so the frame and a resized window's geometry
-can land together, which a commit of the worker's own could not promise.
-EventKit, notifications, permissions and the colour sampler already answer
-through threadsafe functions from queues of their own and follow whichever
-environment calls them.
-
-### The bridge's half
-
-[windowkit/appkit#49](https://github.com/windowkit/appkit/issues/49)
-is the proposal, in five parts:
-
-- **The threading core**
-  ([#50](https://github.com/windowkit/appkit/issues/50)):
-  `runMain()`, the command queue, events built as plain records on the UI
-  thread and made into JS values on the worker, published state, exit
-  through `runMain`'s return value, signals forwarded. Pump mode stays, and
-  one verb body serves both: parsed on the calling thread, run inline on the
-  main thread and queued from any other.
-- **The AppKit verbs**
-  ([#51](https://github.com/windowkit/appkit/issues/51)):
-  of 182, the surfaces, drawing, layouts and fonts stay on the calling
-  thread untouched; the rest become commands, handles allocated at the call,
-  published reads, or answers that arrive later.
-- **Frames across the boundary**
-  ([#52](https://github.com/windowkit/appkit/issues/52)):
-  one batch of layer changes per frame, and IOSurface buffers that change
-  hands by event, because the flip now happens when the UI thread applies
-  the batch rather than when JS asks for it.
-- **The live-resize handshake**
-  ([#53](https://github.com/windowkit/appkit/issues/53)).
-- **Control bezels on the UI thread**
-  ([#54](https://github.com/windowkit/appkit/issues/54)),
-  answered asynchronously with `BezelStore`'s cache in front.
-
-The bridge is closer to this than its synchronous API suggests. Everything
-AppKit asks it synchronously is already answered from state the renderer set
-earlier — the drop response, the drag source's masks, the Dock menu,
-`windowShouldClose:` (always no, with a close request to JS) and
-`applicationShouldTerminate:` (always cancel, with a quit request) — which
-is rule two of the Windows design, followed before it was written down.
-
-### The renderer's half
-
-Threaded mode is the default on macOS: `node app.js` and `bun app.jsx` run
-the app on a worker, with nothing in the app or on the command line asking
-for it, and so does `tsx app.jsx` on Node 24 and later. On Node 20 and 22
-an app started under an ES module loader, tsx or any other `--import` or
-`--loader`, keeps the main thread and the pump (below). It needs a bridge
-with `runMain()`, @windowkit/appkit 0.10. What it costs at startup, how to
-skip it, and what moves on which Node, is in
+AppKit owns the process main thread and runs its menus, drags, live resizes
+and modal panels there. So on macOS react-x11 **moves the app's JS onto a
+`worker_threads` Worker** by default, and the main thread sits in a real
+`[NSApp run]`: the JS keeps running through every menu and resize, and input
+reaches it as it happens rather than at the next pump. It needs a bridge with
+`runMain()` (`@windowkit/appkit` 0.10).
+
+`node app.js` and `bun app.jsx` move with nothing asked for, and so does
+`tsx app.jsx` on Node 24 and later. The launcher moves the app before its
+entry is loaded at all, which is cheaper:
+
+```sh
+node --import react-x11/cocoa-main app.js
+bun --preload react-x11/cocoa-main app.jsx
+```
+
+The app **stays on the main thread**, with the pump, off macOS; with
+`REACT_X11_THREADED=0` or `REACT_X11_BACKEND=x11`; in a REPL or under `-e`;
+in a single executable (a Node SEA, `bun build --compile`); in a `<Frame>`
+pane; under a test runner; when react-x11 is imported after the app started
+running (an `import()` the entry awaits, or one from a timer); and on Node 20
+and 22 under an ES module loader (`--import`, `--loader`, tsx). There a menu,
+a drag, a live resize or a modal panel stops the JS while it is open. The
+startup cost of each route and the matrix by Node version are in
 [packaging.md](packaging.md#on-macos-the-app-moves-onto-a-worker).
 
-- **The move** (`src/cocoa/relaunch.js`, reached from `src/bootstrap.js`,
-  the first import of `src/index.js`). An entry's imports finish before its
-  body runs, so when react-x11 is evaluated on the main thread the app has
-  not run a line. It starts a Worker on that same entry, with the node
-  flags the process started with and a shared environment, and parks the
-  main thread in `Atomics.wait` — no AppKit yet — until the worker says
-  what it needs. The flags are inherited, not handed over as `execArgv`: a
-  Worker refuses a list holding one V8 or process-wide flag, such as
-  `--expose-gc`, and those hold for every thread already. The worker runs
-  a few lines of react-x11's own before the entry (`WORKER_START`), so
-  that however early it stops, it can say so. Node starts it on them, as
-  `eval` code that then runs the entry the way Node runs a worker's file:
-  `process.argv[1]` set to it, and `Module.runMain`, which runs the
-  `--import` loaders first and makes the entry the main module,
-  `require.main` and `import.meta.main` as they were. An `import()` of the
-  entry does neither (measured, Node 20–26). Bun's eval worker loses both
-  an entry's failure and `require.main`, so there the entry stays the
-  worker's own and the lines go in as its `preload`. The
-  first cocoa `createRoot` asks for AppKit (`requestAppKit`), and the main
-  thread launches it and enters `runMain()`; an app that never makes one,
-  an X11 app on XQuartz or a script, never launches AppKit and never gets a
-  Dock tile. It is synchronous throughout, `process.exit` being the main
-  thread's only way out, because a top-level await would cost the CommonJS
-  builds and `require()` of the package. It declines, and the app keeps the
-  pump, off macOS; with `REACT_X11_THREADED=0` or `REACT_X11_BACKEND=x11`;
-  for a REPL or `-e`; in a single executable, whose entry is not a file a
-  worker can load; in a `<Frame>` pane, which has no AppKit to keep and
-  talks to its host over the fork's IPC channel, the main thread's — a
-  worker has no `process.send` ([frame.md](frame.md)); under a test
-  runner; when react-x11 is imported after the app started running; and on
-  Node 20 and 22, under an ES module loader. Node tells the late import by
-  what evaluates it. It starts an app from two modules of its own,
-  `node:internal/main/run_main_module` and `node:internal/modules/run_main`:
-  a CommonJS entry's first run and a `--require` preload evaluate under
-  them, and an ES module entry's graph, an `--import` preload's too, under
-  an async function there, which V8 keeps on the stack as an async frame.
-  An `import()` is evaluated by a job of its own, whose stack ends in the
-  module loader, or in the app's code that awaits it. So react-x11 reads
-  its own stack, async frames and all, as it is evaluated (measured, Node
-  20.20 to 26.0, nested and behind a top-level await, under tsx,
-  `--experimental-loader`, source maps and a stack trace limit of 0). The
-  public signal, `performance.nodeTiming.loopStart`, -1 until the event
-  loop turns, was the one before, and it is wrong both ways: Node 20 and 22
-  turn the loop while they load an ES module entry, so no ES module entry
-  moved there, and 24 and later evaluate an `import()` the entry makes
-  before the loop turns, so an app that awaited one moved and ran its entry
-  twice.
-  The loader rule is tsx's: it keeps its hooks to the main thread on Node 20
-  and 22, and a worker without them stops on the first `.jsx` or `.ts` file
-  it loads (measured, 20.20 and 22.16). No loader can be asked before the
-  move, so there any `--import` or `--loader`, on the command line or in
-  `NODE_OPTIONS`, keeps the app where it is, and the launcher moves one
-  whose loader follows.
-  Bun has neither to read: it reports no loop, and leaves no frame below a
-  module it evaluates. The entry's record in its module cache, which it
-  went by before, was wrong both ways: Bun marks a CommonJS module loaded
-  before its body runs, so `bun app.cjs` never moved, and an ES module has
-  no record until it is evaluated, so an entry that ran a line and then
-  awaited its `import()` of react-x11 moved and ran that line again on the
-  worker. It reads three things instead (measured, Bun 1.4). `bun:main`,
-  the module Bun writes to run the entry from, is in `require.cache` once
-  the entry has finished, top-level awaits and all, so an import after
-  that is late. Code below react-x11 on the stack loaded it synchronously,
-  as Bun's loader leaves no frame below an ES module's imports: a CommonJS
-  entry is on its first run while its own wrapper is the outermost frame,
-  and a CommonJS module an ES module entry imports is part of the entry's
-  graph. And an ES module's body runs only once every module it imports
-  statically has been evaluated: while one of the entry's is not in
-  `require.cache` — read with Bun's own scanner and resolver — react-x11 is
-  part of its graph, and once all are, the entry's body has started and
-  the `import()` is its own.
-- **`react-x11/cocoa-main`** (`src/cocoa/main.js`) is the same move asked
-  for by name — `node --import react-x11/cocoa-main app.js`,
-  `bun --preload react-x11/cocoa-main app.jsx` — before the entry is loaded
-  at all, which spares the main thread loading the entry's imports for
-  nothing, and without the checks — all but one: in a `<Frame>` pane,
-  which gets this `--import` whenever its host was started under it, it
-  does nothing, as it does off macOS and inside a Worker the app starts.
-- **The worker's side** (`bootstrapWorker`), set up by the same import on
-  the worker, which recognises the shared state in its `workerData`; the
-  pieces are `src/cocoa/threaded.js`'s. Stdout, stderr and the console
-  write straight to fds 1 and 2: a Worker's own forward through its
-  parent's loop, which is parked, and Bun's console bypasses
-  `process.stdout` altogether. The new console keeps what the runtime put
-  on the one it replaces and a `Console` lacks — the inspector's
-  `timeStamp`, `profile`, `profileEnd`, `context` and `createTask`, and
-  `console.Console` — because code that loaded first has already looked:
-  React's development reconciler checks `console.timeStamp` once, as it
-  loads, and calls it on every render after, so a script that imported
-  `react-x11/test` ahead of `react-x11` threw on its first render.
-  `process.exit` asks the main thread first
-  (`requestExit`) and then ends the worker, which is also how Node's own
-  handling of an uncaught error reaches it, with code 1; `exit()` on the UI
-  thread, the probe's first try, raced static destructors. From its first
-  line, before any of this (`WORKER_START`), the worker says it is done
-  after the app's last exit listener — kept last, since Node runs a
-  worker's exit listeners through `process.emit` and Bun calls them
-  directly (measured) — and the main thread ends the process on that, so
-  an app's exit handlers finish as they would in a process of its own. It
-  prints its own uncaught error, because the parked main thread never runs
-  its loop again to hear the worker's `'error'`. Both used to wait for this
-  set-up, and a worker that stopped before its import of react-x11 had run
-  there did neither: the process waited for ever, with nothing printed.
-  Such an error now comes with a word on why, since the main thread had
-  run the same code without a complaint (§"What changes for an app"). A
-  `signal` event is re-emitted on the worker's `process`, and one nobody
-  listens for exits 128 + n. The first cocoa root waits for `runMain`
-  before it builds the app: until the run starts the bridge has published
-  nothing, and an app that asked `listScreens()` then got `[]` and took
-  scale 1 on a 2x panel (measured). What the app imports before react-x11
-  runs before this set-up, so a module that logs as it loads belongs after
-  it.
-- **One channel** (`openThreadedChannel`). The bridge takes one `connect`
-  per environment, so the bootstrap opens it before the entry runs and
-  fans the batches out — signals to itself, the rest to `CocoaApp`. What a
-  subscriber throws leaves the delivery once every subscriber has had the
-  batch, and the bridge makes it the worker's uncaught exception. Before
-  0.10 it was swallowed: an exception out of a threadsafe function's
-  callback is, under Node's default policy, a warning — the app went on
-  with its window up and the error gone (measured, and fixed in the bridge
-  as windowkit/appkit#65).
-- **`CocoaApp`** (`src/cocoa/app.js`) is fed by the batches
-  (`_routeBatch`): each event is routed as the pump routes it, what the
-  inputs owe — React's half, the paint, the present (`_afterInput`) — is
-  paid once per batch, and then comes the frame tick the pump did. No
-  interval and no `pump2`; every frame gets a timer of its own, and
-  `_routeGeometry`'s coalesced second flush is the pump's alone. The display link ticking from the UI thread through the same
-  channel, the Windows PRD's frame thread
-  ([windows.md](windows.md#the-frame-clock)), is still to come.
-- **Windows are keyed by the handle.** `createWindow2` answers a handle at
-  the call; `windowNumber` and the published frame arrive with
-  `window-created`, and every window event names the handle.
-- **The fence.** A flip is a command the UI thread applies later, so the
-  buffer it takes off glass is still on glass when the call returns.
-  `CocoaWindow.frameInFlight()` — the X11 contract's fence, which the pump
-  never needed, and whose `frameHeld()` half is what the frame clock asks
-  (`CocoaApp._tickFrames`) — holds the window's next frame until `surface-released`
-  names that buffer, and no frame draws into that buffer before then, one
-  that did not wait included. A new size is never in flight: it paints
-  into a new chain that nothing shows. A release that never comes lets the
-  frames go after 100 ms, and not the buffer. And the release is the flip
-  applied, not the WindowServer letting go of the buffer: that is
-  `surfaceIsInUse`'s to say, and a frame asks it of every buffer it might
-  take (§"Measured: the swapchain and the WindowServer's hold").
-- **The resize handshake.** Each flip is a recorded frame committed with
-  the size it was painted at, in AppKit's own points, and each window asks
-  AppKit to wait for it for `cocoa: { resizeWait }` ms — 50 by default, 0
-  for none. The layer presenter's frame commits its size too. A `<Frame>`
-  pane is held to the same budget the other way round: while its frames of
-  a new size come within it, its layer shows the last one at its size,
-  cropped where the layer shrank and its last column and row carried over
-  where it grew (`contentsRect`, `contentsCenter`), rather than stretching
-  it, and past it, stretches it across and still not down
-  (docs/frame.md §"Sizing, stacking, input").
-- **The screen layout is pulled.** `listScreens()` is always current — the
-  bridge republishes its copy on
-  `NSApplicationDidChangeScreenParametersNotification`, and in pump mode
-  asks AppKit live — but nothing tells the app, so `CocoaApp` asks:
-  `refreshScreens()` re-reads it, compares, and publishes a desk that moved
-  into `src/screens.js`. It runs before a placement reads the layout
-  (`availableArea`), when a window reports that it moved — at most once a
-  second, since a drag reports every frame — and on a clock while a
-  `useScreens()` subscriber is mounted, `cocoa: { screenPoll }` ms apart
-  (500 by default, 0 for none). An app that never watches the layout keeps
-  no clock. What the read does **not** re-derive is `app.scale`: every rect
-  this backend speaks in is points times that factor, and moving it under
-  the windows, the events and the surfaces that already exist in that space
-  is a different change from re-reading a layout.
-- **A live resize is what AppKit brackets**: `liveResizing` is set between
-  the bridge's `window-live-resize` begin and end (windowkit/appkit#63), in
-  both modes. AppKit's tracking loop reports a resize per pointer move and
-  nothing when the drag stops, so the pump used to read the end as "a pump
-  tick ran", and a worker, which no AppKit loop holds, has nothing like
-  that to read; a drag that pauses now stays a drag, and the catch-up frame
-  runs on the tick after the release.
-- **Answers that come later.** `clipboard.read()` and `targets()`;
-  `CocoaWindow.snapshot()`, a promise now on both threads; the drop's
-  payload, read from the event's `items`; and bezels. `BezelStore.prefetch`
-  asks for every kind's metrics beside the rest of startup — 41–49 ms cold,
-  where the yoga load beside it takes 15–50 — so layout reads them
-  synchronously as before. A bezel not drawn yet is null: its canvas draws
-  the one it had and repaints when the new one lands, and a bezel drawn at
-  rest brings its pressed twin, so a press never waits for one.
-- **Tests.** The 52 `test/cocoa-*.test.js` files drive fake bridges that
-  answer synchronously and keep passing on the pump;
-  `test/cocoa-threaded.test.js` drives the same app over a fake in a
-  worker's shapes, `test/cocoa-relaunch.test.js` pins when the move
-  happens, under Bun too where `bun` is on PATH, and the worker's side of
-  the hand-off, and
-  `test/cocoa-threaded-launch.test.js` runs real apps with the real bridge
-  — moved by the import, by the launcher, kept on the pump, and one that
-  never makes a root (it skips without a bridge that has `runMain`).
-  The contract the renderer needs is the X11 one, asynchronous from the
-  start, which [windows.md](windows.md#the-rules-that-keep-it-from-deadlocking)
-  makes the same point about.
-
-Measured 2026-09-11, M1 Pro, Node 26.0.0 and Bun 1.4.0, the bridge built
-from its main branch at 0b17653: `createRoot` took 92 ms on the worker and
-102 ms with the pump, for one window; the launch test's three cases —
-the entry on a worker with its window made and painted, `process.exit(7)`,
-and an uncaught error printed with exit 1 — pass under both runtimes; and
-`examples/app.jsx` ran under the launcher with nothing on stderr. On the
-published 0.10.0, spawn to the first painted window of a one-window app,
-median of seven: Node 471 ms on the pump, 544 ms moved by the import,
-462 ms moved by the launcher; Bun 408, 446 and 385 ms; memory 170, 219 and
-186 MB under Node, 150, 182 and 159 MB under Bun. `examples/raster-gate.jsx`,
-started with no flag under Bun and under `node --import tsx`, kept
-animating through a live resize at 48–62 fps.
-
-The activation policy is the launch's: the launcher has launched AppKit
-before the app's code runs, so `cocoa: { activationPolicy }` can only
-switch it afterwards, when a Regular launch has already shown its Dock
-tile. The bridge reads `APPKIT_ACTIVATION_POLICY` as it launches
-(windowkit/appkit#67) — `APPKIT_ACTIVATION_POLICY=accessory node --import
-react-x11/cocoa-main app.js` for a menu-bar app, or `LSUIElement` in a
-bundle's `Info.plist` — and an app whose option disagrees with how it
-launched is told so, naming the variable.
-
-What it does not do yet, each noted where it lives:
-
-- A drop's binary types, an image, are offered and read as nothing: the
-  event carries the text and URL forms, and a worker cannot read the drag
-  pasteboard inside the callback.
-- The layer presenter's colour transitions start from the declared value,
-  since `presentationValue` answers later on a worker.
-- A transparent window's shadow is recomputed a frame interval after a
-  flip, rather than once the flip has committed.
-- `process.stdin` still forwards through the parked main thread.
-- A worker that cannot load the entry stops the app, where the main thread
-  could have run it with the pump. Under a loader that keeps its hooks to
-  the main thread — tsx before 4.21.1 on Node 24 and later (measured, 4.20.6
-  on 24.12 and 26.0), or tsx on 20 and 22 under the launcher — the app
-  moves and stops as it starts, on `ERR_UNKNOWN_FILE_EXTENSION`. A load
-  failure has run nothing of the app's on the worker, so the main thread
-  could carry on in its place, if `WORKER_START` told such a failure from
-  the rest.
-- Under Bun, react-x11 required from a callback before the entry has
-  finished reads as the entry's first run, and the app moves and runs that
-  code again on the worker: from a nextTick or a microtask a CommonJS
-  entry queues in its own file, or from a timer while an ES module entry
-  waits on a top-level await. Bun runs a CommonJS entry's nextTicks and
-  microtasks before it evaluates `bun:main`, and its stack does not tell a
-  callback's frame from a module's own. A callback that ends by returning
-  its `require()`, in strict code, leaves no frame at all — JavaScriptCore
-  makes that a tail call — and reads as late.
+**A menu-bar app sets its policy at launch.** On a worker AppKit is up before
+the app's code runs, so `cocoa: { activationPolicy }` can only switch it
+afterwards, when a Regular launch has already shown a Dock tile. Launch with
+the variable, or put `LSUIElement` in the bundle's `Info.plist`; an app whose
+option disagrees with its launch is told so in development.
+
+```sh
+APPKIT_ACTIVATION_POLICY=accessory node --import react-x11/cocoa-main app.js
+```
 
 ### What changes for an app
 
-- About **16 MB** of RSS for the worker's isolate (a bare `node` at 46.5 MB,
-  62.5 MB with one idle worker) and **26–31 ms** before the worker runs its
-  first line.
-- The idle app stops waking 125 times a second: the pump is an 8 ms
-  interval whether anything happens or not.
+- About **16 MB** of RSS for the worker's isolate, and **26–31 ms** before
+  the worker runs its first line.
+- The idle app stops waking 125 times a second: the pump is an 8 ms interval
+  whether anything happens or not.
 - Inside a Worker, `process.chdir()` throws, `process.on('SIGINT')` is never
-  called (the launcher forwards signals), `process.env` is a copy unless it
-  is shared, and `process.stdin` forwards through the main thread the way
-  stdout does.
-- What the entry imports ahead of react-x11 runs twice: on the main thread,
-  then again on the worker. A call only a main thread may make —
-  `process.chdir()`, `process.umask(mask)` — goes through the first time
-  and throws the second, and the app stops with that error and a word on
-  why. Make it on the main thread only (`isMainThread`, from
+  called (the launcher forwards signals: a signal is re-emitted on the
+  worker's `process`, and one nobody listens for exits with 128 + n),
+  `process.env` is a copy unless it is shared, and `process.stdin` forwards
+  through the main thread the way stdout does.
+- **What the entry imports ahead of react-x11 runs twice**: on the main
+  thread, then on the worker. A module that does work as it loads — opens a
+  port, writes a file, logs — does it twice. A call only a main thread may
+  make — `process.chdir()`, `process.umask(mask)` — goes through the first
+  time and throws the second, and the app stops with that error and a word
+  on why. Make it on the main thread only (`isMainThread`, from
   `node:worker_threads`): what it changes is the process's, so the worker
   starts with it. One made after the import runs on the worker alone and
-  throws there; `REACT_X11_THREADED=0` keeps the whole app on the main
-  thread.
+  throws there. Import react-x11 first in the entry, or set
+  `REACT_X11_THREADED=0` to keep the whole app on the main thread.
+- `process.exit()` and an uncaught error end the app as they would a process
+  of its own: exit handlers run, and the error is printed with exit code 1.
 - `--inspect` attaches to the main thread; the app is the worker target
   beside it.
-- Packaging: a single-executable build has to carry the worker's entry
-  beside the main one ([packaging.md](packaging.md)), and
-  `bun build --compile` has to be given it as an entry point.
-
-### Not probed yet
-
-- A hardware live resize, a real drag session, and pixels on glass.
-- `<glarea>`'s `x11-dri` CGL context inside a worker.
-- `react-x11/refresh`'s module hooks inside a worker.
-- The swapchain on glass. No frame writes into a buffer the WindowServer
-  holds, measured at the moment of every write (§"Measured: the swapchain
-  and the WindowServer's hold"), and the scroll blit moves its band as the
-  frame takes its buffer, or in one already caught up; but a torn frame has
-  not been looked for on screen, before the change or after it, and a
-  capture cannot see one.
-- IME and NSAccessibility, neither built yet: both are questions AppKit asks
-  the view synchronously, and both take the answer the Windows design gives
-  them — the caret rect and a copy of the accessibility tree, pushed ahead
-  to the UI thread.
-
-### The order
-
-The bridge's core and every verb have landed (windowkit/appkit#50–#54), and
-so have a batch-fed `CocoaApp` and the move that makes threaded mode the
-default on macOS. Pump mode stays, unchanged, as the off switch
-(`REACT_X11_THREADED=0`) and wherever the move declines — a single
-executable first among them. Still to take under threaded mode: an
-input-to-photon measurement and the resize cell of the Cocoa bench, which
-runs its columns on the pump — perceived latency is the metric this
-project grades on, and latency is what the change is for.
+- A single executable does not move, and runs on the pump
+  ([packaging.md](packaging.md)).
+
+Not done yet on a worker:
+
+- A dropped image, or any binary type, reads as nothing: the drop carries its
+  text and URL forms.
+- The layer presenter's colour transitions start from the declared value.
+- A transparent window's shadow is recomputed a frame interval after a flip,
+  not once the flip has committed.
+- A worker that cannot load the entry stops the app: under tsx before 4.21.1
+  on Node 24 and later, or tsx on Node 20 and 22 under the launcher, it stops
+  as it starts on `ERR_UNKNOWN_FILE_EXTENSION`. Update tsx, or set
+  `REACT_X11_THREADED=0`.
+- Under Bun, react-x11 required from a callback before the entry has
+  finished — a `nextTick` or microtask a CommonJS entry queues, a timer while
+  an ES module entry awaits at top level — reads as the entry's first run,
+  and that code runs again on the worker.
+- Not yet tried on the worker: `<glarea>`'s GL context and
+  `react-x11/refresh`'s module hooks.
 
 ## Native controls
 
-House rule applied: **default native, seam out.** On the Cocoa backend
-core controls render with AppKit's own pixels; interaction, focus,
-keyboard and a11y semantics stay the shared implementation (the
-"answer-the-input" press model is behavior this project considers part
-of its identity, and AppKit's own controls would take it over
-wholesale — different focus ring timing, different keyboard rules,
-different event routing — which is why real `NSView` controls embedded
-in the layer tree are _not_ the mechanism).
-
-The mechanism is the POC's proven one: **offscreen NSCell/control
-rendering into cached images** (the WebKit/Gecko technique), keyed
-`(kind, size, state, appearance, accent)`, nine-slice-stretched via
-`contentsCenter` where the bezel allows, set as the control node's layer
-contents. Push buttons (including the accent-filled default button),
-checkbox, radio, popup, slider knob/track, switch — all render today in
-both appearances with pressed/on states.
-
-Wiring, shaped as theme policy rather than per-widget forks:
-
-- `ThemeProvider` grows `controls: 'auto' | 'native' | 'drawn'`. The
-  default, `'auto'`, takes bezels wherever the backend has them — the
-  Cocoa backend, and win32 while the desktop is light (`win32/bezels.js`
-  says why) — and the drawn controls everywhere else, X11 included.
-  `'native'` asks for them outright; on a backend without them it warns
-  once and draws, because an error would make the same app code illegal
-  on X11, which is the opposite of what a cross-backend widget set is
-  for. `'drawn'` is this library's rendering on every backend.
-  Per-instance escape hatch: `native={false}` on a control for the odd
-  custom-branded button. A drawn control on macOS keeps today's themed
-  rendering, so custom-designed apps lose nothing.
-- Components keep their exact public contracts (`checked`/`onChange`,
-  the `changeEvent` shape, `useControl` states) and swap only the
-  _bezel_: where the drawn variant renders well/track/thumb boxes, the
-  native variant renders a bezel-image node sized by the cell's natural
-  metrics. Hover/press/focus continue to drive it — pressed bezels are
-  re-keyed images, and the press state still lands on the press frame.
-- A native control is **two boxes**: the footprint the caller's `style`
-  sizes, and the control itself — bezel, title and press wash — at AppKit's
-  metrics, centred in it. One box could not be both, because a cell's title
-  is _placed_ against the bezel's bottom edge rather than centred in the
-  box, and a `height`, a `flexGrow` or a parent's align-stretch moved the
-  box without moving the bezel the system draws at one size: the label
-  ended up below the control it names (#510). The role, the handlers, the
-  focus ring and the ref stay on the control, so the slack around it is
-  slack — a press there does nothing, as it does in AppKit.
-- A `<Button>` label **wraps** when its row is too narrow for it, as a drawn
-  one does, and the control grows by the lines it gained — so a push button
-  is AppKit's height only while its title is one line. A push bezel is one
-  height (asked for a taller frame, AppKit draws its own 22pt centred in
-  it), so a box taller than that is drawn as `NSBezelStyleFlexiblePush`:
-  the same button stretched to its frame, which AppKit gives a title that
-  wraps and WebKit and Gecko draw a tall push button with. At one line the
-  two are the same pixels, except the default button's accent, which is
-  flat in the flexible bezel where the push has a sheen. A bridge that
-  predates the kind keeps the push and says so once, in development
-  (`src/cocoa/bezels.js`, "Taller than one line"). Pinning the title to one
-  line's height put its first line above the bezel instead.
-- The palette gains a macOS system theme whose tokens read semantic
-  `NSColor`s (accent, text, separators) so _drawn_ content — cards,
-  tables, custom widgets — sits harmoniously beside native bezels, and
-  the desktop accent reaches `theme.accent` on this backend through the
-  same explicit adoption rule as on Linux.
-- Text controls stay drawn everywhere for now: `<textinput>`'s editing
-  model (undo, selection, caret cadence from desktop settings) is deep
-  shared behavior, and a native `NSTextField` would fork it. The native
-  win for text is IME (§Text), not the bezel.
-- `NSSwitch`'s knob animation: the native bezel pair + the existing
-  `transition` on the thumb reproduces it; if fidelity disappoints, the
-  switch is the one control worth revisiting as a real view. Menus and
-  popover _panels_ are never bezel-rastered — their vibrancy needs
-  private API; they go native for real (§Menus) or stay drawn.
-
-`useSupports('nativeControls')` reports the capability so component code
-and apps can branch the way `'shaders'` consumers already do.
+`Button`, `Checkbox`, `Radio`, `Switch`, `Slider` and `Select` wear
+**AppKit's own bezels** here by default; interaction, focus, keyboard and
+accessibility stay the shared implementation. A bezel is an image drawn
+through the ordinary paint path, not an embedded `NSView`
+([components.md](components.md#native-bezels)).
+
+- `ThemeProvider`'s `controls`: `'auto'` (the default) takes bezels wherever
+  the backend has them — Cocoa, and win32 while the desktop is light — and
+  draws elsewhere; `'native'` asks outright, and on a backend without them
+  warns once and draws; `'drawn'` is this library's rendering everywhere.
+  `native={false}` on one control is the escape hatch.
+- `useSupports('nativeControls')` says whether the backend has them.
+- A native control is **two boxes**: the footprint `style` sizes, and the
+  control at AppKit's metrics, centred in it. Role, handlers, focus ring and
+  ref are on the control, so a press in the slack around it does nothing.
+- A `<Button>` label **wraps** when its row is too narrow, and the control
+  grows with it; past one line it is AppKit's flexible push button, whose
+  default-button accent is flat. A bridge too old for that bezel keeps the
+  push and says so once in development.
+- Text controls stay drawn: a native `NSTextField` would fork the shared
+  editing model.
+- Drawn content sits beside the bezels through the desktop's palette
+  ([appearance.md](appearance.md#the-desktops-palette)).
 
 ## Menus: the global menu, finally at home
 
-**A popup on this backend is sized as an NSMenu.** Where the backend
-renders native controls, `<ContextMenu>`, a `<MenuBar>`'s dropdowns and a
-`<Select>`'s list take NSMenu's geometry rather than the palette's — 22pt
-rows, 5pt of padding, 11pt separators, the 13pt menu font at regular
-weight, a 5pt highlight radius — read off `NSMenu.size` (`NATIVE_MENU` in
-`components/native.js`). The drawn menu's 30pt rows of 14px medium text
-read as another toolkit's beside the menus the system's own controls open.
-The menu bar itself keeps the drawn metrics: a bar is not an NSMenu.
-
-**A `<Select>`'s list is the NSMenu itself** where the bridge has
-`popUpMenu` (@windowkit/appkit 0.20): `CocoaApp.popUpMenu` drops it from the
-trigger through an `NSPopUpButtonCell` nobody draws, as a browser drops a
-`<select>`'s, and a pane asks its host to (`pane-menu`). The drawn list
-stays for a drawn select that does not ask for it (`nativeMenu`) and for an
-older bridge.
-
-The Linux global menu was built for exactly this moment: the item
-vocabulary is data (dbusmenu's), `MenuBar` draws the same array it
-exports, and the pure `snapshot`/`diffSnapshots`/`IdAllocator` machinery
-in `dbusmenu.js` produces stable ids and structural-vs-property diffs
-with no D-Bus in sight. The macOS adapter consumes precisely that:
-
-- `snapshot(menus)` → build/patch an `NSMenu` tree; `IdAllocator` ids
-  key an `NSMenuItem` cache across re-renders; `diffSnapshots` decides
-  patch-in-place (title/enabled/state) vs. rebuild (structure).
-  `itemProperties()` is the one function swapped — dbusmenu props out,
-  `{title, enabled, hidden, state, keyEquivalent(+mask), submenu}` in.
-- Item activation carries the id back; `itemFor(id).onSelect` fires —
-  the same contract the registrar path has.
-- `useGlobalMenu` on this backend **always delegates** — the fallback
-  drawn bar (`if (delegated) return null` in `MenuBar`) simply never
-  renders, and `onGlobalMenuChange(true)` reports it. No registrar
-  probing, no liveness rules: the menu bar is a platform constant.
-- macOS requires the standard skeleton — the application menu
-  (About/Preferences/Hide/Quit), Edit, Window — which the adapter
-  synthesizes around the app's menus by default (the main customer
-  ships a Mac-correct menu bar with zero configuration), with the
-  app-menu items reachable as props for the apps that name their own
-  (`about`, `preferences` handlers). `editmenu.js`'s item set feeds the
-  standard Edit menu so text controls get theirs.
-- **Accelerators invert.** On X11 the app window matches chords itself;
-  in `NSMenu` the key equivalent belongs to the item. The adapter maps
-  chords → `keyEquivalent` + modifier mask, reading `Control` as ⌘: a
-  cross-platform chord is written in the _primary_ modifier, and
-  `[['Control','S']]` taken literally would demand ⌃S on a Mac. No
-  `Primary` token was needed for that — `Control` already is one — and the
-  window's own matching reads it the same way (`app.primaryModifier`,
-  `matchesShortcut(ev, shortcut, { primary })`), so `useAccelerator` and a
-  drawn row answer and print ⌘ too. A delegated bar's bindings are **not**
-  disarmed wholesale, as first planned: the menu bar answers only the
-  chords it can spell, and F5, `plus` or a second alternative would have
-  gone dead. Instead `useMenuAccelerators` _reserves_ exactly the ones it
-  does answer (`answersShortcut`, cocoa/globalmenu.js), so no binding in
-  the window takes them — the bridge shows JS every key before
-  `[NSApp sendEvent:]`, and an item answered by both would run twice
-  ([events.md](events.md#the-macos-menu-bar)).
-- `ContextMenu` defaults to a native `NSMenu` popup on this backend
-  (same adapter, `popUpMenuPositioningItem:`), with the drawn popup as
-  the seam (`native={false}`) — the drawn one exists, works, and some
-  apps will want visual consistency with custom themes. Note the native
-  menu runs a tracking loop: run-loop option 2 is what keeps React
-  alive while it is open (menu-item enablement updating live is the
-  test).
+**The menu bar is the system's, always.** A window's `menus` go to the macOS
+menu bar as soon as they are installed, the drawn bar never renders, and
+`onGlobalMenuChange(true)` reports it ([globalmenu.md](globalmenu.md)). Item
+icon names are SF Symbols.
+
+- An **application menu** goes in front of the app's, carrying Quit (⌘Q).
+  Quit is a quit request: the primary window's close request, which
+  `onCloseRequest` can intercept, then, with `exitOnQuit`, the end of the
+  process. Nothing else is synthesized — no About, Hide, Edit or Window
+  menu — so an app that wants them names them in `menus`.
+- **Accelerators**: `Control` in a chord is ⌘, so `[['Control', 'S']]` is ⌘S;
+  there is no separate `Primary` token. The menu bar answers the chords it
+  can spell — one chord, one character key — and reserves them so no window
+  binding fires them twice; the rest (F5, `plus`, a second alternative) are
+  matched by the window ([events.md](events.md#the-macos-menu-bar)).
+- Where native controls render, `<ContextMenu>`, a `<MenuBar>`'s dropdowns
+  and a `<Select>`'s drawn list are **sized as NSMenu is**: 22pt rows, 5pt
+  padding, 11pt separators, the 13pt menu font.
+- **A `<Select>`'s list is the real NSMenu**, dropped from the trigger as a
+  browser drops a `<select>`'s; `nativeMenu` chooses
+  ([components.md](components.md)).
+- The Dock menu and a tray item's menu take the same item vocabulary
+  ([desktop.md](desktop.md)).
 
 ## Custom drawing on a layer tree
 
-The escape hatches all reduce to one rule stated in Tier L: **a node
-whose content is painted code gets a raster visual** — a bitmap-backed
-layer, the CG canvas2d context translated to its box, redraw on the
-node's own damage claims, `contentsScale` from the window. A claim that
-names the node re-rasters that node; a bare rect — an element's
-`invalidate(false, rect)` for the box a dragged item moved through, the
-region `scrollContents` shifts, the strip an animation ticks in —
-repaints every raster visual whose ink it touches, the same
-conservative answer the damage model gives a rect on X11 — and only that
-part of each: the raster keeps its bitmap as the visual's composition
-cache, the pass clears and clips to the claim, and `paintDamage()` names
-it, so an element culls a drag step or an animation tick the way it does
-on X11 instead of replaying its whole scene into a clip.
-
-- `<canvas onDraw>`: `paintContent` runs against the CG ctx; a new
-  `onDraw` closure invalidates the node (existing rule); `putImageData`
-  keeps its absolute-coordinates contract via the same `info.x/y`.
-- `cacheKey`/`mono`: the pattern transfers — keyed bitmaps shared
-  across canvases; `mono` renders an alpha-only mask once per
-  (name, size) and tints per ink via `CGContextClipToMask` + fill, so
-  the a8-coverage economics survive (ink stays out of the raster key).
-- `registerElement` + `Node.paint(ctx)` subclasses (all seven components
-  elements): work unchanged through the raster visual. An element that
-  overrides `paint` — `super.paint(ctx)` for the box, then its scene —
-  has its content nowhere but in that override, so the raster replays
-  the override itself, with the child walk held back (the children have
-  visuals of their own). The `Context2D` dialect the consumers exercise
-  — including `fillRects`, `drawGlyphs`, `positioned`, `layoutSubtree`,
-  `vw/vh/em` — is part of the ctx contract on both backends.
-- `ntk.Surface` offscreen allocation (charts, terminal, flow): the Cocoa
-  app object supplies one. `app.createSurface(options)` answers ntk's
-  `Surface` contract over a CG bitmap (`src/cocoa/surface.js`, issue
-  #433), and `react-x11/ntk`'s `Surface` asks the app it is handed before
-  falling through to ntk's pixmap, so a component allocates its buffer
-  the same way on both backends. `getContext('2d')` is the CG context,
-  `copyWithin` is one in-place copy of the surviving band (the bridge's
-  `scrollSurface`, ntk#252's exact contract, clamp for clamp), and
-  `ctx.drawImage(surface, …)` is one `CGContextDrawImage`. Sized in
-  device pixels like the window's backing store. Two things differ from
-  ntk and are stated where they live: a bitmap has one graphics state,
-  so a surface has one context for its life (`destroy()` on it is a
-  no-op) and `render()` brackets its callback in save/restore from the
-  identity; and `format: 'a8'` throws — the coverage surfaces the paint
-  cache and the shadows use stay on their X path until a consumer needs
-  them here. The subpath's other drawing-adjacent names
-  (`cssColorStraight`, `decodeImage`, `Image`) are pure JS already, and an
-  `Image` is a `drawImage` source here as well: its straight RGBA goes into
-  a CG bitmap once per `Image` (the bridge's `ctxPutImageData`
-  premultiplies) and composites like a surface, scaling included. The
-  X-only names stay X-only — `Picture`, and with it `<image picture>` and
-  `<image drawable>`, draw nothing here and warn once in development. An element that composites such a surface
-  over its box on **every** frame — a terminal, a chart on a socket — pays
-  that composite and the window swapchain's catch-up copy behind it to move
-  pixels it already has; making the element's surface its own layer instead,
-  the way `<glarea>` and layer promotion already do, is designed in
-  [architecture/element-layer-contents.md](architecture/element-layer-contents.md)
-  (#499) and not built.
-- `<svg>`: the declarative vocabulary (`SvgChildNode`) is portable; the
-  rasterizer behind it renders through the same CG ctx.
-- A future, deliberate seam — not built until a consumer needs it:
-  `registerElement({ visual })`, letting an element supply a
-  layer-aware visual instead of raster (a chart that wants its series
-  as shape layers, say). The raster default means nobody _has_ to.
+`<canvas onDraw>`, `<svg>` and a registered element's `paint(ctx)` run
+unchanged, through a CoreGraphics context that speaks the whole dialect:
+canvas2d plus `fillRects`, `drawGlyphs`, `positioned`, `layoutSubtree` and
+`vw`/`vh`/`em`.
+
+**Offscreen surfaces.** `react-x11/ntk`'s `Surface` is a CoreGraphics bitmap
+here, in device pixels. Unlike ntk:
+
+- A surface has **one context for its life**: `getContext('2d')` answers the
+  same object every time, its `destroy()` is a no-op, and `render()` brackets
+  its callback in `save`/`restore` from the identity.
+- `format: 'a8'` **throws**: allocate `argb32` and tint through
+  `fillStyle`/`globalAlpha`.
+- `Picture`, `<image picture>` and `<image drawable>` are X server
+  resources: they draw nothing here and warn once in development. An `Image`
+  works.
+
+**Context properties** that differ or matter here:
+
+- **`globalCompositeOperation`** is canvas's whole set, including blend
+  modes (`multiply` and the rest) that X11 lacks. An op applies inside what
+  the draw covers, as on X11 and unlike a browser's `copy`. A bridge without
+  the verb refuses all but `source-over`: assign, then read it back. A
+  `drawGlyphs` call's `op` is ignored.
+- **`'copy'` plus `drawImage(surface, x, y)`** at the surface's own size, a
+  whole-pixel translate, no alpha, no shadow and at most a rectangular clip
+  is a row memcpy, not a blend — the cheap way to present a surface every
+  frame (a 125×45 terminal grid in 0.42 ms rather than 1.37). Anything else
+  is drawn, with the same result.
+- **`globalAlpha`** below 1 on a surface draw is cheap where
+  `ctx.fadesSurfacesCheaply` is true.
+- **`imageSmoothingEnabled`/`imageSmoothingQuality`** are honoured; a context
+  starts at `'medium'`, not canvas's `'low'`. `'low'` makes a surface drawn
+  tile by tile through a matrix far cheaper (784 tiles: 200 ms → 27 ms).
+- **`filter`** applies the colour functions (`grayscale()`, `sepia()`,
+  `saturate()`, `hue-rotate()`, `invert()`, `brightness()`, `contrast()`),
+  `opacity()`, and `blur()` on drawn images only; `drop-shadow()` and `url()`
+  do not stick. Read `filter` back to know.
+- **`clip(rule)`** honours `'evenodd'`; **`roundRect`** takes canvas's radii,
+  `{ x, y }` corners included; **`createPattern`** is not supported.
+
+An element can hand parts of its drawing to the render server as `sprites()`
+([extending.md](extending.md#parts-of-your-drawing-on-layers-of-their-own)).
+One that composites its own surface over its box every frame — a terminal, a
+chart on a socket — pays that composite and a copy behind it; a layer of the
+element's own is [designed, not built](../design/architecture/element-layer-contents.md).
 
 ### Stroking a path with many subpaths
 
-`CGContextStrokePath` is **quadratic in the number of subpaths** in the
-path it is handed. Measured on this machine — closed 13-vertex rings
-scattered over a 1024×1024 surface, a 2px line, one `ctx.stroke()`:
-
-| rings | vertices | one stroke | chunked (what ships) |
-| ----: | -------: | ---------: | -------------------: |
-|   500 |    6,500 |      20 ms |                14 ms |
-| 1,000 |   13,000 |      59 ms |                29 ms |
-| 2,000 |   26,000 |     208 ms |                56 ms |
-| 4,000 |   52,000 |     986 ms |               113 ms |
-
-The subpath count is the driver, not the vertex count: one 26,000-vertex
-subpath strokes in 4ms where two thousand 13-vertex ones take 208. It was
-found rasterizing vector map tiles — a `buildings` layer is one feature of
-a couple of thousand building outlines, accumulated into one path
-(react-x11 issue #456).
-
-So `CocoaContext2D.stroke` splits such a path into several
-`CGContextStrokePath` calls, cut at subpath boundaries — a chunk closes at
-the first `moveTo` past 512 points or 128 subpaths, which is within 5% of
-the best chunk for every shape swept. **The backend picks the size, not the
-caller**, because the right size is a fact about CoreGraphics that no
-caller can know, and because the X11 context wants the exact opposite: there
-a stroke is an a8 coverage mask over the path's bounding box uploaded with
-one `PutImage`, so a bigger path is _fewer_ uploads over the same pixels,
-and batching for one backend pessimizes the other.
-
-Two things are deliberately left whole, both because splitting them would
-be a loss:
-
-- **A hairline** — a device-space width of 1 or less, so `lineWidth` times
-  the CTM's scale. Below that width CoreGraphics strokes through a path
-  that is already linear in the subpath count (the 2,000-ring path above
-  costs 7ms at 1px, whole), and splitting it is a **2× regression**: the
-  per-call setup with nothing to win back.
-- **Anything that composites** — a translucent `strokeStyle`, a
-  `globalAlpha` below 1, a live shadow. Each chunk paints separately, so a
-  pixel that two subpaths' strokes each half cover is inked twice at half
-  coverage rather than once at full, and reads a little lighter. That is
-  the one visible difference chunking can make, and it is confined to the
-  seams where subpaths overlap under an opaque ink, where blending the same
-  colour twice changes only the antialiased fringe. `ctx.strokeChunking =
-false` turns the split off for a caller that needs those seams exact, and
-  `REACT_X11_NO_STROKE_CHUNKING=1` for a whole process.
-
-`fill` is not chunked and cannot be: the winding rule is a property of the
-path as a whole, so a hole in a shape stops being a hole once its ring is
-in a different call.
-
-The path is recorded in JS alongside the native one so a chunk can be
-re-issued — a flat number array, reused across paths. It costs an ordinary
-paint nothing measurable (20,000 rounded-rect fill+strokes: 601ms before,
-597ms after; 20,000 twelve-segment polylines: 113ms before, 116ms after),
-and the record is what puts the whole path back if a `fill`, a `clip` or
-more path building follows a stroke that consumed it. `test/cocoa-stroke-chunking.test.js`.
-
-### Compositing a surface at a translate
-
-An element that owns a surface presents it every frame: the terminal's
-grid, a retained scene, anything that rasters once and shows the result
-many times. `ctx.drawImage(surface, x, y)` is how it says so, and on this
-backend that was `CGBitmapContextCreateImage` of the whole source plus
-`CGContextDrawImage` — a CGImage built and a blend run, every frame, for
-pixels that were only ever going to be copied. In
-sidorares/react-x11-components#69 §6's profile it is 1.7ms of a 6ms
-`<Terminal backend="vt">` frame, the second-largest line after the cell
-background fills.
-
-The context takes canvas's own way of saying "do not blend, replace" —
-
-```js
-ctx.globalCompositeOperation = 'copy';
-ctx.drawImage(surface, x, y);
-```
+CoreGraphics strokes in time quadratic in a path's subpaths, so the context
+splits a large stroke at subpath boundaries: a path of 4,000 rings strokes
+in 113 ms rather than 986. Left whole: a hairline (1 device pixel or less)
+and anything that composites — a translucent `strokeStyle`, `globalAlpha`
+below 1, a shadow. The one visible difference: where two subpaths' strokes
+overlap, the antialiased fringe reads a little lighter.
+`ctx.strokeChunking = false` turns it off for one context,
+`REACT_X11_NO_STROKE_CHUNKING=1` for the process. `fill` is never split.
 
-— and, where that is all it is, sends the composite as a row memcpy
-(`blitSurface`) instead. `scripts/cocoa-composite-probe.mjs` prices the
-two routes against the real bridge; on an M1 Pro, 200 composites a cell:
-
-| source          | destination       | CGImage draw |  memcpy |
-| --------------- | ----------------- | -----------: | ------: |
-| 125×45 grid @2x | the whole surface |       1.37ms |  0.42ms |
-| 125×45 grid @2x | a third of it     |       0.36ms |  0.14ms |
-| 125×45 grid @2x | one row's damage  |      0.033ms | 0.012ms |
-| 80×24 grid @2x  | the whole surface |       0.35ms |  0.18ms |
-
-`globalCompositeOperation` itself is `ctxSetBlendMode`, and the vocabulary
-is the **bridge's** rather than a table kept on this side: the names are
-canvas's own, and the verb answers whether the mode is now the one asked
-for. So this backend never goes stale against a bridge that grows an op,
-and never claims one it would not draw. 0.7.0 knows the whole canvas set
-— the Porter-Duff ops ntk maps to XRender's, plus the separable and
-non-separable blend modes CoreGraphics has and XRender does not, which a
-caller reaching for `multiply` should know are macOS-only until ntk grows
-them. Two things about it are worth knowing. A bridge without the verb —
-anything before 0.7.0 — **refuses** everything but `source-over` rather
-than accepting it and drawing something else, so the detection a caller
-writes is canvas's own: assign, then read the property back. An op
-applies inside what the draw covers rather than across the whole surface —
-a browser's `copy` clears everything the drawing missed, where
-`kCGBlendModeCopy` and XRender's `Src` both leave it alone, so the two
-backends agree with each other and differ from a browser together. And the
-`op` argument a `drawGlyphs` call carries is still ignored; text composites
-through the context's mode like everything else.
-
-The blit is an optimization and never a difference, so every way the
-memcpy would not be exactly what the draw produces turns it off and the
-draw happens: an op other than `copy`, a transform that is not a
-whole-pixel translate, a `globalAlpha` below 1, a live shadow, a
-destination size that differs from the source's, a fractional source
-rect, and a surface composited into itself.
-
-The clip is the interesting one. A memcpy cannot see a CGContext's clip,
-and a paint pass is clipped to its damage rect — so the context tracks
-the clip **as a rect** beside the CTM it already tracked, and hands it to
-the verb. It tracks only what it can state exactly: a single `rect` path
-under an axis-aligned transform landing on whole pixels. A rounded
-corner, an arc, a polygon, two rects, a half-pixel edge or a rotation all
-resolve to "there is a clip and I cannot name it", which turns the blit
-off until a `restore()` pops back past it. The clips a paint pass
-actually sets — the damage rect, a square-cornered `overflow` — are the
-ones it recognises.
-
-`test/cocoa-composite.test.js` pins both halves: the decisions over a
-fake bridge — including a bridge with neither verb and one whose
-vocabulary is smaller, which is what the feature detection is for — in
-CI, and, where the real bridge loads, that the blit and the draw are
-pixel-identical.
-
-### Compositing a surface under an alpha
-
-CoreGraphics draws an image under an alpha below 1 at some fifteen times
-what the same draw costs at 1, and composites a transparency layer the
-same way. Neither the flip nor the interpolation is the cost, and nor is
-the colour space, which is sRGB at both ends. So a group faded on a
-surface of its own — `<box opacity>` (`NodePaint._paintGroup`), CSS
-`opacity` in `@react-x11/components`' `<Html>` — cost more than drawing
-each thing in it faded, which is the wrong answer wherever they overlap
-(#810). A standalone benchmark of the bridge's own surfaces, a 556×300
-card on an M1 Pro:
-
-| drawn as                                  |   ms |
-| ----------------------------------------- | ---: |
-| the card, each thing at alpha .6          | 0.63 |
-| its surface at alpha 1                    | 0.09 |
-| its surface at alpha .6, the CGImage draw | 1.24 |
-| a transparency layer at alpha .6          | 1.30 |
-| its pixels scaled by .6, then drawn at 1  | 0.25 |
-
-The bridge's `ctxDrawSurfaceFaded` (`@windowkit/appkit` 0.18.0) is the last row:
-`ctxDrawSurface` with the alpha passed again, since CoreGraphics keeps no
-getter for the one `ctxSetGlobalAlpha` set, which scales the source rect's
-premultiplied pixels into a bitmap of their own and draws that at 1. The
-colours are the same within a unit a channel. The context sends a draw
-there when its `globalAlpha` is below 1, the bridge has the verb and no
-shadow would ink — a shadow is drawn from the image and the alpha
-together — and says so as `fadesSurfacesCheaply`, beside `scalesText`, for
-an element choosing between fading a group and fading each thing. The
-bridge itself draws what is not that shape — a rect off the pixel grid, an
-IOSurface source, a surface onto itself — through the CGImage under the
-alpha, as before, and so does a bridge without the verb.
-`test/cocoa-composite.test.js` pins the decisions over a fake bridge, and,
-where the real bridge has the verb, that its colours are the draw's.
-
-### Drawing a surface through a matrix
-
-Every context the bridge makes resamples an image at
-`kCGInterpolationMedium`, and at medium CoreGraphics resamples the whole
-source for a draw through a matrix, whatever the clip. A surface drawn a
-tile at a time — a box in perspective, each tile under its own clip and the
-matrix of the plane over it, as `<Html>` draws one — so costs each tile all
-of the surface: 784 tiles of a 1400×1120 surface took 200ms on an M1 Pro,
-and 27ms at `kCGInterpolationLow`, which is bilinear, what a layer in
-perspective is drawn with. Keeping the CGImage the draw makes of the
-surface between draws changed nothing.
-
-The context takes canvas's own properties for it —
-
-```js
-ctx.save();
-ctx.imageSmoothingQuality = 'low';
-// …the tiles…
-ctx.restore();
-```
+### A shadow from a tile
 
-— `imageSmoothingEnabled`, false for the nearest pixel, and
-`imageSmoothingQuality`, `'low'`, `'medium'` or `'high'`, over
-`ctxSetImageSmoothing` (@windowkit/appkit 0.23.0, windowkit/appkit#109).
-Both are state `save` and `restore` keep. A context starts at `'medium'`,
-where the bridge's contexts were always made, and not at canvas's `'low'`:
-an image drawn small keeps the quality it was drawn at. A bridge without
-the verb keeps both where they start, so a caller knows whether an
-assignment took by reading it back, as with `globalCompositeOperation`.
-
-### A filter's colour functions
-
-`filter`, canvas's again, is a CSS filter list the context applies to what
-it draws after it, and `save` and `restore` keep it:
-
-```js
-ctx.save();
-ctx.filter = 'grayscale(1)';
-ctx.drawImage(surface, x, y); // grey
-ctx.restore();
-```
+On macOS and Windows the context draws the shadow of a rect, a `roundRect`,
+a `fillRect` or an inset frame of two from a **tile** made once and
+stretched, shared by every card with the same shadow — a page header's inset
+shadow went from 130–380 ms to 4 ms.
 
-The context applies the colour functions — `grayscale()`, `sepia()`,
-`saturate()`, `hue-rotate()`, `invert()`, `brightness()`, `contrast()` —
-and `opacity()` (`src/backend/filter.js`). Each of them leaves alpha as it
-is, so it is a linear map of premultiplied colour, and drawing a shape in
-the colour it makes of a fill's is drawing the shape and filtering it: a
-fill, a stroke, a gradient's stops, a glyph run's ink and a symbol are
-filtered so, at no cost. An image, a surface and a text layout that
-carries colours of its own are filtered by their pixels — read with
-`ctxGetImageData`, run through the matrices, put on a bitmap of their own
-and drawn — which is a pass over the pixels on the JavaScript thread for
-every draw. A shadow is cast after the filter, in its own colour, and
-faded with what `opacity()` fades.
-
-`blur()` sticks too, and is applied to what is drawn as an image — a
-`drawImage` of an image or a surface, which is what a renderer
-composites a layer of its own with — and not to a fill, a stroke or
-text, which are drawn sharp in the colours the rest of the list makes.
-Its standard deviation is in the units the destination is given in, and
-two `blur()`s are one. The source is read as far round as the blur
-reaches, three deviations, scaled down by the bridge's resampling until
-the deviation is two pixels, blurred there and run through the colour
-functions, and drawn back up, smoothed: a Gaussian is smooth to the
-scale it was taken at, which is how Skia blurs a large radius, and a
-glass card's 64-pixel blur at 2x is a pass over a few thousand pixels.
-Past the source is nothing, which the blur fades into, as canvas has it.
-
-`drop-shadow()` and a `url()` reach past what is drawn, which this does
-not apply, so a list with one in it does not stick; nor does any on a
-bridge without the pixel verbs. As with the other properties here, a
-caller knows by reading `filter` back. `<Html>` draws a CSS `filter`'s
-colour functions so where it sticks, and from a read back where it does
-not — X11, whose server runs no colour matrix and answers a read a round
-trip later.
-
-### A clip's fill rule
-
-`clip()`, `clip(rule)`, `clip(path)` and `clip(path, rule)` are canvas's,
-and the rule reaches `ctxClip` as the flag `ctxFill` takes:
-`CGContextEOClip` for `'evenodd'` (@windowkit/appkit 0.24.0,
-windowkit/appkit#111), and a winding geometry or an alternate one on
-Windows (@windowkit/win32 0.0.7, windowkit/win32#12). ntk's SvgView cuts an
-element to its `<clipPath>` with the shape's `clip-rule`, and a ring cut by
-nonzero is the square around it. The rect the context keeps for
-`blitSurface`'s memcpy does not depend on the rule: one rect is one
-subpath wound once, which both rules cut alike.
+- A tiled shadow is the canvas spec's gaussian (σ half the blur, three σ
+  wide), as Chrome and X11 draw it. Other shapes, rotations and composite
+  ops get CoreGraphics' own, which is a little narrower.
+- `<box boxShadow>` draws on macOS and Windows.
 
-### A shadow from a tile
+`REACT_X11_NO_SHADOW_TILES=1`, or `ctx._shadowTiles = false` on one context,
+puts every shadow back on CoreGraphics.
+
+## Animations and transforms
+
+`transition` and `animation` styles work as everywhere. Where a layer can
+express the property — a plain `<box>`'s `backgroundColor`, `borderColor`,
+`borderWidth`, `borderRadius` and `opacity` — the **render server runs the
+animation**: no JS frames, and it keeps moving while the JS thread is blocked
+(`examples/animation.jsx` blocks it for two seconds). Everything else — text
+colour, layout properties, a node that paints as a raster — runs on the frame
+clock exactly as on X11.
+
+- **Timing** matches the frame clock's easings.
+- **Interruption**: a length retargets smoothly from where it is; a colour
+  restarts from the value on screen.
+- **Not offloaded**: `boxShadow`. `transform` is not a style property on any
+  backend yet.
 
-CoreGraphics blurs a shadow on every fill that has one set, and what it
-costs is the shape's area times the blur's width: a page header's
-`box-shadow: inset 0 0 100px`, repainted by each strip a scroll exposed, was
-130 to 380 ms at 2x, and a card's 200px hover shadow 110 ms — every frame
-the header or the card was in view. Direct2D does not draw a live shadow at
-all; the Windows bridge records one and draws nothing.
-
-So the context (`src/backend/context2d.js`, both bridges) recognises the
-shapes a box shadow is made of — a `fill` of a path that is one `rect` or
-one `roundRect`, or two of them one inside the other filled `'evenodd'`,
-which is the frame an inset shadow is cast around, and a `fillRect` — and
-draws their shadow from a **tile**. The shadow of a rounded rect is the
-same all along its straight edges, so it is made once, for a copy of the
-shape shortened to three pixels of straight edge on each axis that has
-room, and drawn as up to nine pieces: the corners as they are, the
-straight pixel stretched between them. The tile is named by its corners,
-blur, hole and colour — not by where the shape is or what part of it a
-paint reaches — so every card with one shadow shares a tile, and a strip a
-scroll exposes draws a strip of it. ntk plans the tile and makes its
-pixels (`ntk/shadow-tiles`, the same code X11's shadows come from): the
-shape's coverage and a gaussian of σ `shadowBlur / 2`, made smaller for a
-wide blur and scaled up as it is drawn. The header's inset shadow is 4 ms
-where CoreGraphics took 130 to 380, and the tiled shadow is within six
-levels of 8-bit alpha of the exact one (`test/backend-shadow-tiles.test.js`,
-over the real bridge where it loads). What a tile cannot draw — a path of
-anything else, a transform that rotates, a composite other than
-`source-over` — is the bridge's, as before.
-
-Two things follow that are visible:
-
-- **A shadow a tile draws is the canvas spec's gaussian**, σ half the
-  blur, three σ wide — the one Chrome and X11 draw. CoreGraphics' own blur
-  is a little narrower, about 0.45 of the blur and cut off at the blur, and
-  it is still what a shape a tile does not draw gets.
-- **`<box boxShadow>` draws on macOS and Windows.** It was baked on an X
-  server and drew nothing without one. Without one it is the context's own
-  shadow now, which is to say a tile.
-
-`REACT_X11_NO_SHADOW_TILES=1`, or `ctx._shadowTiles = false` on one
-context, puts every shadow back on the bridge, for measuring the two
-against each other.
-
-A `roundRect` takes its radii as canvas has them: a number, a
-`{ x, y }` point for an elliptical corner, or a list of one to four of
-either, scaled down together where two corners on a side would meet. It
-took numbers alone, clamped each on its own, and drew a `{ x, y }` corner
-square. Circular corners go to the bridge as `ctxRoundRect`; elliptical
-ones as `ctxRoundRectXY` where it has one — and as op 9 in the one-call
-`ctxPath` stream — and as curves where it does not, so an older bridge
-draws them too.
-
-## Animations and transforms: the API the model unlocks
-
-The existing declarative vocabulary is the seam: `transition:` and
-`animation:` in styles. On X11 they run on the frame clock (JS
-interpolation, repaint per frame — including the premultiplied-lerp
-rule), and so do they on the surface presenter. **The layer presenter
-hands them to the render server** where the node's own layer expresses
-the property — a plain `<box>`'s `backgroundColor`, `borderColor`,
-`borderWidth` and `borderRadius` — and schedules no frames for them: the
-style goes to its target, which is the layer's model value, and the frame
-that sends it attaches an explicit animation carrying the pixels there
-(`CocoaLayerPresenter.animate`, `@windowkit/appkit` >= 0.5). A loop is one
-repeating animation and costs no JS frames at all. Everything else — a
-colour on text, a layout property, any node that paints as a raster — stays
-on the frame clock, byte-identical to before; the presenter can only decline,
-never break. **The surface presenter takes the same animations** by
-promoting the node to a layer of its own for as long as it animates —
-the next section — so `examples/animation.jsx` is the demonstration on
-either: its frame counter reads 0 while the plain-box loops keep going,
-and they keep going through a deliberate two second block of the JS
-thread.
-
-The three semantics [the design](architecture/animation.md) said to pin:
-
-- **Timing parity** is control points, not names. `transition`'s ease-out
-  is cubic-bezier(0.33, 1, 0.68, 1) to within 0.003 and the loop easings
-  map the same way (`EASING_CONTROL_POINTS`, styles.js), where CA's named
-  `easeOut` is a different curve — test/style.test.js pins both facts.
-- **Interruption**: a length retargets _additively_ — the model goes to the
-  new target and a delta animation `(old − new) → 0` joins the one still
-  running — so a change of mind mid-flight is continuous with nothing read
-  back; a colour cannot be additive and restarts from the presentation
-  value the bridge reports.
-- **Completion** is the bridge's `animation-end` event, so the node model
-  drops the entry when the render server says so, not when a timer guesses.
-
-Not offloaded yet, in the order they would pay: transforms (they do not
-exist as a style property — the design's §3.4) and `boxShadow`'s
-components. `opacity` (#601, offloaded in #818) and, for a node no pointer
-lands on, an out-of-flow node's insets as `position` have since joined the
-list above (`ANIMATED_KEY_PATHS`, `INSET_KEY_PATHS`, src/cocoa/presenter.js).
-
-Two style capabilities currently rejected everywhere become cheap on
-layers and are proposed as **capability-gated additions** rather than
-macOS-only forks, keeping one style vocabulary:
-
-- **`opacity`** — free on a layer (`opacity`); on X11 implementable as
-  group-raster through an ntk `Surface` at composite time (bounded,
-  cacheable). Ship on both, the X11 cost documented. _Shipped that way
-  (#601): a style property on every backend, a group faded as one._
-- **`transform`** (2D: translate/scale/rotate) — free on a layer;
-  XRender pictures do transform, so a bounded X11 story exists for
-  leaf-ish content even if the general case (transformed subtrees with
-  events) is deferred. Proposed staged: layer backend first behind
-  `useSupports('transforms')` + an `@supports` style block, X11 catch-up
-  or documented divergence decided by real demand.
-
-Both wait until the presenter exists; they are listed because "hardware
-composited layers with animation and transformations" is half the reason
-to build Tier L, and the API shape (style props + capability gates)
-should be agreed before someone builds a macOS-only thing.
+On the default presenter the offload is
+[layer promotion](#layer-promotion-the-animated-few-on-their-own-layers-above-the-surface-presenter).
+`cocoa: { presenter: 'layers' }` gives every drawn node a CALayer instead; it
+is opt-in while it is measured, and a pan there re-rasters the whole scene.
 
 ## Layer promotion: the animated few on their own layers above the surface presenter
 
-The presenter choice above is all-or-nothing, and for the shape of app
-that most wants the retained tier — a large scene with one or two
-animated elements in it — neither answer was right. `surface` could not
-offload an animation at all: every transition frame was a JS repaint plus
-an upload, and a stalled JS thread stopped the animation dead. `layers`
-offloaded it and paid for the whole rest of the scene: a pan is a
-whole-scene re-raster (`scrollRegion` is nulled in layers mode), and every
-raster visual carries its own bitmap. The hybrid is what browsers call
-**layer promotion**, and it is the surface presenter's default (issue
-#483): keep the bitmap for the scene, and give the handful of nodes that
-actually animate a CALayer of their own above it. `src/cocoa/promotion.js`
-is the whole of it.
-
-**Why it was cheap here.** The mechanism already shipped, for `<glarea>`.
-The surface presenter's pixels are the window root layer's `contents`,
-and a layer's contents draw _below_ its sublayers — so a promoted sublayer
-composites over the bitmap for free, and there was no compositing to
-write. The hole in the 2D raster was already an idiom (`GlAreaNode.paint`
-is empty): a promoted node is skipped by the paint walk (`Node._promoted`),
-so the walk paints what is behind it and nothing else. The animation
-seam was already presenter-agnostic — `animateNode` / `cancelNodeAnimation`
-are feature-detected on the window, and `_offloadDeclined` hands a
-property back to the frame clock whenever a presenter cannot take it — and
-the bookkeeping of what the render server runs was one class
-(`LayerAnimations`, presenter.js) once it was lifted out of the layer
-presenter; the two differ only in which node has a layer.
-
-**What a promoted node is.** A property box — its background, border and
-radius as properties of its layer, the same `propBoxProps` the layer
-presenter sends, which is exactly the vocabulary the render server
-animates. Its children, if it has any, ride the layer as one raster
-sublayer painted by the node's own `_paintChildren` walk (a `Visual` and a
-`RasterState` from the layer presenter, used standalone), repainted for the
-claims that reach into it and for a change in where the children sit —
-the hover card in `examples/animation.jsx` promotes with its two captions.
-Its `opacity` is the layer's as well, and the layer is then the group CSS
-asks for: Core Animation draws a layer under an opacity below 1 with its
-sublayers and fades them as one (`allowsGroupOpacity`, YES by default on
-macOS), which is what `NodePaint._paintGroup` draws on the bitmap — read
-back as 1 off a promoted layer's presentation layer, and a half-faded card
-over a red child snapshotted with no blue in the red. A promoted node
-inside a promoted node leaves a hole in its parent's raster and sits on a
-layer of its own above it, and coming off its layer it is painted into
-that raster again in the same frame (#817: what gives it back — the grace
-running out, a fade above it — claims its own layer or nothing, so no
-claim would have); every promoted layer is flat on the window root,
-ordered by paint order. Hit testing never moves: the node tree stays the
-source of truth for input on every presenter, so promotion changes pixels
-and nothing else.
-
-**The policy** is not inferred from the scene, and there is no style prop
-to get wrong: a node is promoted because it has a transition or a loop on
-a property a layer can express — a plain `<box>`'s `backgroundColor`,
-`borderColor`, `borderWidth`, `borderRadius`, `opacity` — for as long as
-it has one and a second after, and returns to the bitmap then. A loop on
-an inset of a box out of the flow is one as well, where no pointer lands
-on the box (`position: 'absolute'`, `pointerEvents: 'none'`): it moves
-that box and nothing else, so it is the layer's position, an offset added
-to where the layout rests the box, and a percentage is a share of the
-parent's padding box, run again where it has got to when the parent's size
-changes (`LayerAnimations.follow`). The pointer is the condition because
-input is hit against the layout's rect, which holds still while the layer
-moves. `<ProgressBar indeterminate>`'s block is one: a bar cost a layout
-pass and a frame at the display's rate, 16% of a core on an M1 Pro at
-75 Hz, and costs nothing now. The second is
-`IDLE_GRACE_MS`: a hover card fades in and, a moment later, out; a palette
-step ends one transition and starts the next; a toast pulses again.
-Demoting on the last frame of each cost a layer and a repaint of the hole
-per round trip — the first run of the bench made 96 layers for 48 cards —
-and a second is longer than any such gap. Nothing can promote two hundred
-nodes by mistake, and there is nothing to document on a backend that may
-decline it.
-
-**The hard part is z-order.** A promoted layer sits above _all_ the 2D
-content, so promotion is only correct where nothing paints over the node.
-Browsers answer the general case with overlap testing that cascades
-promotions upward through the stacking context — precisely the machinery
-worth not having. The cheap rule instead: a node is promoted only when
-nothing painted after it in the walk reaches into its bounds — no later
-sibling at any level (a later subtree counts where it puts ink, so a
-layout-only container laid over the node is no overlap, and a later
-subtree that is itself promoted is on a layer above and does not count),
-no ancestor's border ring or focus ring (both are painted after the
-children), and no ancestor that fades, because the layer would not fade
-with it: a box inside a faded box stays in the
-group's pixels, on the clock, where a layer on the root was drawn at full
-strength until #817. A clipping ancestor cuts the layer to its box: the
-layer goes in a box of the clip's size that masks to it, the way an
-element's part is cut (below), so a row half scrolled out of its list is
-promoted, and one none of which shows is kept on a layer that shows
-nothing. The innermost clip with round corners that does not hold the node
-gives the box its corners, and a square clip that cuts that one again is a
-box around the box, as for a part. All of it is answered from
-`paintOrder()` and the cached paint reach, and the same test runs again
-every frame, later-painted nodes first, so a node that becomes
-overlapped, hidden, clipped round, faded around or non-plain (a `:hover`
-that adds a shadow) returns to the bitmap in the frame that finds it, the
-animation handed back to the clock. Overlays, toasts, drag ghosts,
-spinners, floating cards and the rows of a list pass by construction.
-Declining is always safe — the frame
-clock runs the animation exactly as it does with promotion off — and a
-refusal is remembered until the next layout, so the same scene does not
-cost a frame's decline per retarget.
-
-**A scrollbar's thumb goes above the rows it is drawn over.** The bars
-are painted after a pane's children, over them, and the thumb is a bar's
-only ink — its track is not drawn. So a row under the thumb is no reason
-to refuse the row: the thumb goes on a layer of its own instead, a colour
-and a radius as core paints it, ordered after everything inside the pane
-and before whatever is painted after it, and the bitmap stops painting it
-(`Scrollable._paintScrollbars`). That is only where nothing painted after
-the pane reaches anywhere the thumb can go, nothing above the pane fades
-and every clip above it holds the track whole — `_clear` asked of the
-pane at its tracks — and the thumb is back in the bitmap in the frame no
-layer is under it any more. Without it every row of a list was under the
-track, and a list of pulsing rows was the clock's at the display's rate.
-
-**Not while the pane scrolls.** A node inside a pane that scrolled in the
-last 250 ms gets no layer, keeps none and is offered none (`_scrolling`):
-its layer would move every frame the pane is painted anyway, and the
-pane's blit carries it in the bitmap. The window marks the panes a frame
-scrolls (`_pendingScrolls`), and promotion notes them before anything
-else, since a wheel steps a pane 60 times a second against a display's 75
-or 120 and the frames between its steps are still the scroll. A refusal
-for it is not remembered for the layout, as the others are, since a
-scroll ends without laying anything out. The case is a list whose rows
-fade on hover: a wheel brings row after row under the pointer, and each
-kept a layer for the grace, was asked every frame whether it might stay
-and had its raster synced as the pane moved it. On components' 100,000-row
-`<Table>` that cost a wheel 29% more of every frame than painting the
-fades in the bitmap did, 57% of a core to 66%. A loop on a row comes off
-with the rest, carries on on the clock where it had got to, and is offered
-again a quarter of a second after the pane stops. So a pane that code
-scrolls every frame, a ticker or a smooth scroll of its own, keeps
-everything in it on the clock for as long as it moves: its layers would
-have moved every frame too.
-
-**A loop the clock runs is offered again.** Nothing about a loop ever asks
-twice — a transition ends and the next one is offered afresh, but a loop
-turned down at its start would run on the clock, a frame every refresh,
-for as long as it runs. So after each frame's layout the window offers
-every loop the clock runs to the presenter again, at most every 250 ms and
-only where the scene would take it now (`wouldTake`): a fading ancestor
-arrived at 1, a sibling moved away. It comes over
-where it is in its cycle — the render server's animation starts that far
-in — and a loop given back carries on from where the render server had
-it, so a spinner that changes hands does not jump either way.
-
-**The frame.** `WindowNode.flush()` gives the presenter its word in after
-layout and before the damage is taken (`window.prepareFrame`, feature-
-detected like `presentFrame`): whatever it moves onto or off a layer
-claims the bitmap under it in that same frame, so a node is never painted
-at its target before a declined animation restarts from its start, and a
-demoted node is back in the bitmap in the frame its layer goes. A
-promoted node's own claims — a retarget, a hover flip, a caption changing
-inside it — are answered on the layer and cost the bitmap nothing: the
-`noteInvalidate` channel the layer presenter listens on answers `true`,
-`WindowNode.invalidate` records a frame with nothing in it for the bitmap,
-and the frame runs the presenter's half and paints no pixel (`hovertree`
-below: 0kpx a frame). The scroll blit's safety gate skips a promoted node
-for the same reason — its pixels are not in the bitmap the band is cut
-from — which is what makes a pan under a pulsing toast a blit
-(`pananim`), on a backend where the toast's per-frame claim used to poison
-every notch.
-
-**What to expect, and how to stop it.** An animation on a plain box
-costs one frame to start and, a second after the last one ends, one to
-come back, and the render server draws every frame between — through a
-busy JS thread, at the display's rate — while the bitmap keeps the frame
-for everything else, the scroll blit included. What it costs is a CALayer
-and, for a node with children, a bitmap the size of their reach, for as
-long as the node animates and the second after. A fade is one of them: a
-200×120 card with an `opacity` loop over a child painted 120 frames in two
-seconds on the clock, and paints none on its layer.
-`createRoot({ cocoa: { promote: false } })` or `REACT_X11_COCOA_PROMOTE=0`
-keeps every animation on the frame clock, which is what the presenter
-bench's `surface` column measures; `true` / `=1` turns it on regardless
-of the bridge. `test/cocoa-promotion.test.js` pins the contract over the
-fake bridge; `test/animation-example.test.js` walks the example through
-it.
-
-**An element's parts** (#819). A registered element whose content is its
-own `paint` has no plain box to promote, so it offers the parts of its
-drawing it would like lifted — `sprites()`, asked every frame like
-`opaqueRect()` ([extending.md](extending.md#parts-of-your-drawing-on-layers-of-their-own)).
-Each lifted part is a layer of its own on the window root, in the same
-paint order as the promoted nodes (`src/cocoa/sprites.js`): its content a
-raster painted once by the part's own `paint`, its opacity and its
-transform — a matrix, which the bridge takes from `@windowkit/appkit` 0.19,
-or a matrix3d for a part turned out of the plane, which Core Animation draws
-in its perspective on the GPU — properties of the layer, and its animations
-keyframes the render server runs. The rules are the ones above, asked of the element at everywhere the
-part can be over its animations, with the element's own fade added to its
-ancestors': the element vouches for its inside, and leaves a hole where a
-lifted part is from the frame `spritesLifted` tells it so. A part given back
-is the element's to draw again in that same frame, with the bitmap under it
-claimed. A registered element offering a card with an opacity loop, a turn
-sampled into 61 matrices, or a static half-faded quarter turn painted no
-window frame and no paint of the element in two seconds on this machine,
-with the render server's values moving under it. A part may name another
-as its `parent`: its layer is then a sublayer of the parent's, placed from
-the corner of the parent's raster, which the presenter paints again
-without it — handing the parent's `paint` the keys lifted inside it —
-whenever that set changes. It is asked about nothing at the window's
-level, since the parent was, and only kept to the parent's raster.
-
-**One thing it found, and the bridge it needs.** A promoted node is the
-same node drawn two ways in turn, and the two had to agree to the pixel
-or every hover would flash. They did not: a layer's `backgroundColor` went
-through `@windowkit/appkit`'s `CGColorCreateGenericRGB` while its surfaces
-are sRGB, so `#dbe7f4` rastered as (219, 231, 244) and composited as
-(228, 236, 245) — paler, on every layer the layer presenter ever set, and
-a colour animation there landed on a model value that did not match its
-own `to`. [windowkit/appkit#33](https://github.com/windowkit/appkit/pull/33)
-makes every colour crossing the bridge sRGB and adds `colorSpace()` to
-say so, and shipped as `@windowkit/appkit` 0.5.1, the range this package
-asks for; against it the same card differs by at most six units of one
-channel, in the antialiasing. Promotion is on by default **only where the
-bridge answers `'sRGB'`** — on 0.5.0 it stays off unless asked for — so
-nobody gets the flash for free, and the bridge upgrade is what turned it
-on.
-
-**And one a wide-gamut display found** (#820). The surface presenter shows
-the window through an IOSurface, and that IOSurface named no colour space.
-Core Animation shows such a surface as the display's own numbers, and
-colour-matches everything that does name one: a promoted layer's `CGImage`,
-its `backgroundColor`. So on a display whose profile is not sRGB — a
-MacBook's built-in panel, a monitor carrying its own EDID profile — the
-window was more saturated than its CSS colours, and a promoted node changed
-colour on its way onto its layer and again on its way back: `#3b82f6` read
-(59, 130, 246) in the bitmap and (78, 128, 238) on its layer on the
-built-in panel. `@windowkit/appkit` 0.19.0 and every release after it,
-which this package asks for, name every IOSurface they make sRGB, and
-`setLayerContentsIOSurface` names one that names nothing, which covers a
-`<glarea>`'s x11-dri frames too (windowkit/appkit#98, #99). On it the
-bitmap, a promoted layer, a `<Frame>` pane and a `<glarea>` read the same
-numbers on all three displays measured. Three consequences:
-
-- **Every window on such a display is colour-managed now**, as Safari and
-  Chrome manage a page, and looks less saturated than it did before 0.19.0:
-  correct, and visibly different.
-- **Opaque colours agree to the pixel; translucent ones do not quite.**
-  Core Animation blends a layer in the display's space, where the bitmap
-  blends in sRGB before it is matched, so `rgba(255, 0, 0, 0.5)` over white
-  reads (239, 134, 131) in the bitmap and (245, 153, 145) on a layer.
-  Neither the bridge nor core can name that space away, and it matters most
-  for a node given back while it rests at a partial opacity.
-- **`window.snapshot()` reads the display's numbers for the bitmap**, as it
-  already did for a layer, and the PNG carries the display's profile: red
-  is (234, 51, 35) on the built-in panel. A script that compares raw
-  snapshot numbers with CSS colours sees the shift.
-
-**Measured**, 2026-09-06, this machine (a 120Hz panel; the window on a
-60Hz monitor where it says 59fps), 4s per cell, `npm run bench:presenters
--- --scenario=anim,animtree,hovertree,pananim,scroll,tree`; `surface` is
-promotion off, `promoted` on. Frames are what the JS side painted;
-`ticks` are the scenario's own changes (a palette step every 15, a hover
-flip or a wheel notch every one).
-
-| scenario    | column   | frames / ticks | flush avg / p95 | damage a frame     | cpu  | what it says                                       |
-| ----------- | -------- | -------------- | --------------- | ------------------ | ---- | -------------------------------------------------- |
-| `anim`      | surface  | 455 / 235      | 2.17 / 2.51ms   | 2170kpx            | 46%  | every frame of every fade, all 48 cards            |
-|             | promoted | 16 / 241       | 2.80 / 6.92ms   | 136kpx             | 17%  | one frame a palette step; 48 layers, made once     |
-|             | layers   | 16 / 241       | 2.21 / 3.26ms   | —                  | 17%  |                                                    |
-| `animtree`  | surface  | 208 / 120      | 14.58 / 16.97ms | 2031kpx            | 108% | cannot keep up: the fades repaint the grid         |
-|             | promoted | 243 / 243      | 0.91 / 1.87ms   | 13kpx              | 54%  | the grid's one cell a tick; the fades cost nothing |
-|             | layers   | 244 / 244      | 2.75 / 3.75ms   | —                  | 67%  | a visual per node of the grid                      |
-| `hovertree` | surface  | 476 / 242      | 0.28 / 0.38ms   | 43kpx              | 14%  | input→flush p50 2.80ms                             |
-|             | promoted | 242 / 242      | 0.31 / 0.39ms   | 0kpx               | 11%  | p50 2.86ms; the bitmap paints nothing              |
-|             | layers   | 241 / 241      | 1.38 / 1.65ms   | —                  | 22%  | p50 2.75ms                                         |
-| `pananim`   | surface  | 702 / 243      | 0.65 / 1.82ms   | 817kpx, 31% full   | 24%  | the toast's claim poisons every notch's blit       |
-|             | promoted | 219 / 242      | 1.57 / 2.01ms   | 525kpx, 0% full    | 22%  | the blit, exactly `scroll`'s                       |
-|             | layers   | 220 / 243      | 1.89 / 2.28ms   | 2520kpx, 100% full | 17%  | a whole-scene re-raster a notch                    |
-| `scroll`    | promoted | 220 / 243      | 1.45 / 1.86ms   | 525kpx             | 20%  | as surface: 1.49 / 2.01ms, 525kpx, 21%             |
-| `tree`      | promoted | 243 / 243      | 0.47 / 0.65ms   | 4kpx               | 49%  | as surface: 0.42 / 0.57ms, 4kpx, 47%               |
-
-So both halves at once: the animation's frames match `layers`, the flush
-and the scroll match `surface`, and `animtree` and `pananim` beat both.
-The 54% left in `animtree` is the React commit of a 3,700-node tree per
-tick, which `tree` prices at 47% with no animation at all. The gate keeps
-it: `scripts/bench/presenters-gate.json`'s `promoted` rules judge the
-promoted column on frames per tick, full frames and damage share, next to
-the surface column's own.
+The default presenter keeps one bitmap per window and gives the few nodes
+that animate a CALayer of their own above it while they do. Hit testing never
+moves: promotion changes pixels and nothing else. With no prop to set, a node
+is promoted when it is
+
+- a plain `<box>` with a transition or a loop on `backgroundColor`,
+  `borderColor`, `borderWidth`, `borderRadius` or `opacity` — for as long as
+  it has one and a second after; or
+- a box out of the flow that no pointer lands on (`position: 'absolute'`,
+  `pointerEvents: 'none'`) with a loop on an inset, which moves it and
+  nothing else — `<ProgressBar indeterminate>`'s block costs no frames;
+- and **only where nothing paints over it**: no later sibling's ink in its
+  bounds, no ancestor's border or focus ring, no ancestor that fades. A
+  clipping ancestor, round corners included, clips the layer. A node in a
+  pane that scrolled in the last 250 ms waits until the pane stops.
+
+A node that stops qualifying returns to the bitmap in the frame that finds
+it, and its animation carries on on the frame clock from where it was. A
+scrollbar thumb over promoted rows goes on a layer of its own.
+
+It costs a frame to start, one to come back a second after the last
+animation ends, and meanwhile a CALayer, plus for a node with children a
+bitmap the size of their reach. `cocoa: { promote: false }` or
+`REACT_X11_COCOA_PROMOTE=0` keeps every animation on the frame clock; `true`
+or `=1` forces it on whatever the bridge (it is on by default where the
+bridge reports sRGB colours, 0.5.1 and later).
+
+**On a wide-gamut display** (a MacBook's built-in panel, a monitor with its
+own profile) every window is colour-managed, as a browser manages a page, so
+it looks less saturated than an unmanaged one. Opaque colours agree to the
+pixel between bitmap and layer; translucent ones differ slightly, because
+Core Animation blends in the display's space. `window.snapshot()` reads the
+display's numbers and carries its profile, so a script comparing raw
+snapshot pixels with CSS colours sees a shift.
+
+Design notes and measurements:
+[design/macos.md](../design/macos.md#layer-promotion-the-animated-few-on-their-own-layers-above-the-surface-presenter).
 
 ### Video on a layer
 
-A `<video frames>` ([elements.md](elements.md#video)) is the first part
-whose layer shows a **source** rather than a raster: its sprite's
-`contents` is the sink, and `src/cocoa/video.js` puts every pushed frame
-into a video surface — an IOSurface the render server scans out as it is,
-NV12 for a YCbCr sink, BGRA for a BGRA one (`createVideoSurface`,
-windowkit/appkit#103) — and repoints the layer inside the `push`. The
-window paints nothing for it: on the real bridge, threaded, sixty pushes
-of a 320x180 NV12 sink cost the window one frame, the one that lifted it.
-The surfaces are a ring of up to four, written only when
-`videoSurfaceIsInUse` says the render server has let one go.
-
-Declined — a box painted over it, a fade, a rounded clip — the element
-draws the newest frame into a surface of its own through
-`writeVideoSurface`, which converts a YCbCr frame in the colours the layer
-shows it in. Both are the colours `AVPlayerLayer` shows the frame in: a
-surface with CoreVideo's tags alone is linearised with the exact 709 curve,
-where the player, VideoToolbox and Core Image use Apple's 1.961 gamma, so
-the bridge names each surface's colour space from its tags and converts
-through VideoToolbox. Read back through `snapshotWindow`, the same frame
-lifted, drawn and played differs by at most two levels a channel. A
-bridge without the verbs lifts nothing, and the frame is converted in
-JavaScript instead (`app.videoFormats()` then says `BGRA` first).
-
-A `<video src>` is the second source: an `AVPlayer` over the file or URL
-(`createPlayer`, `src/cocoa/player.js`) is the
-part's `contents`, and lifted, its own `AVPlayerLayer` goes inside the part's
-layer and fills it — AVFoundation puts every frame on the screen, and on the
-real bridge a playing 30fps clip cost the window no frames at all. Declined,
-the element asks `playerCopyFrame` for the frame showing every display frame
-while it plays, which answers only when there is a new one, so a covered
-30fps clip is thirty frames a second of the window's, each bounded to the
-picture, in the colours the player's layer shows. Over a bridge without the
-verbs `createPlayer` is absent from the app, `useSupports('mediaPlayback')`
-is false, and `src` refuses as it does on X11. A `<Frame>` pane runs no
-AppKit, so nothing there would ever hear a player's events: its host plays
-its videos for it and sends the frames down (docs/frame.md, "A pane's
-videos").
-docs/architecture/video.md is the design record.
+A [`<video>`](elements.md#video) goes on a layer of its own under the same
+rule: nothing painted over it, no fade, no rounded clip that cannot hold it.
+
+- **`<video frames>`**: lifted, each pushed frame goes straight to a surface
+  the render server shows, at no cost to the window; declined, the element
+  draws the newest frame into the window. The colours are `AVPlayerLayer`'s.
+  Over a bridge without the video-surface verbs the frame is converted in
+  JavaScript, and `app.videoFormats()` lists `BGRA` first.
+- **`<video src>`** plays through `AVPlayer`: lifted, its player layer shows
+  every frame at no cost to the window; covered, each new frame is copied
+  into the window. Over a bridge without the player verbs
+  `useSupports('mediaPlayback')` is false and `src` refuses, as on X11. In a
+  `<Frame>` pane the host plays the video and sends the frames down.
 
 ## Running as an app bundle
 
-A react-x11 process is a `node` (or `bun`) process, and AppKit names, icons
-and identifies an app by the **bundle its executable lives in**: run from the
-shell, the menu bar says "node", the Dock shows the generic icon, and the
-defaults domain — where AppKit remembers window frames and whether a tab
-bar is showing — is `node`'s or `bun`'s, shared with every other script
-that runtime ever ran. `examples/form/` is the example of the fix:
+AppKit names, icons and identifies an app by the **bundle its executable
+lives in**. Run from the shell, the menu bar says "node", the Dock shows the
+generic icon, the defaults domain (window frames, the tab bar) is shared with
+every script that runtime ever ran, and the notification centre refuses the
+app. `cocoa: { appName }` fixes the name alone; a bundle fixes all of it.
+`examples/form/` is the example:
 
-```
+```sh
 npm run examples:form:app   # builds examples/form/build/Guestbook.app and opens it
 ```
 
-[`make-app.sh`](../examples/form/make-app.sh) copies `Info.plist`, renders
-`icon.svg` into an `.icns` with the system's own tools (Quick Look, `sips`,
-`iconutil`), and makes the executable with `bun build --compile`: one Mach-O
-with bun's runtime, the example and react-x11 inside it, at
-`Contents/MacOS/Guestbook`. AppKit takes an app's main bundle from the
-running executable's path, so a real binary there is the whole trick — no
-launcher, nothing to find at launch time.
-
-What a compiled binary cannot contain is the Cocoa bridge's native addon,
-which the backend loads with `require` from a file. The bundle carries it
-as `Contents/Resources/calayers.node`, and the compile entry,
-[`main.js`](../examples/form/main.js), names it through the backend's
-`REACT_X11_CALAYERS_PATH` seam — relative to `process.execPath`, so the
-bundle can be moved — before importing the example. `Info.plist` carries
-the name, the identifier (`com.example.guestbook`), the icon,
-`NSHighResolutionCapable` (without it AppKit renders at 1×) and
-`LSEnvironment` naming the Cocoa backend. Launch Services then reports the
-process as the app:
-
-```
-$ lsappinfo info -only name,bundleid,bundlepath "$(lsappinfo find pid=<pid>)"
-"LSDisplayName"="Guestbook"
-"CFBundleIdentifier"="com.example.guestbook"
+[`make-app.sh`](../examples/form/make-app.sh) makes the executable with
+`bun build --compile` at `Contents/MacOS/Guestbook`: AppKit takes the main
+bundle from the running executable's path, so it must be a real binary, not
+a script.
+
+- **The bridge's addon cannot be compiled in.** The bundle carries it as
+  `Contents/Resources/calayers.node`, and the entry,
+  [`main.js`](../examples/form/main.js), points `REACT_X11_CALAYERS_PATH` at
+  it relative to `process.execPath` before importing the app, so the bundle
+  can be moved.
+- **`Info.plist`** carries the name, the identifier, the icon,
+  `NSHighResolutionCapable` (without it AppKit renders at 1×) and
+  `LSEnvironment` naming the Cocoa backend. `lsappinfo` then reports the
+  process under the app's name and identifier.
+
+**The tab bar under bun.** Unbundled, a `bun` app's windows live in the
+`bun` defaults domain, and once anything turns the tab bar on there (View →
+Show Tab Bar, a stray shortcut) every window the bridge opens wears a 28pt
+tab bar and every popup lands that much off. Clear it, or run as a bundle:
+
+```sh
+defaults delete bun "NSWindowTabbingShoudShowTabBarKey-NSWindow-CALBackendDelegate-(null)-VT-FS"
 ```
 
-(A script can be a bundle's executable too, and there is a way to make
-AppKit take the bundle rather than the interpreter as the main one —
-`#!/usr/bin/env -S CFProcessPath=<this file> bun` sets CoreFoundation's
-process path before the interpreter starts — but the compiled binary needs
-no such trick, and nothing installed on the machine at launch time.)
-
 ### Distributing the bundle
 
-What `make-app.sh` builds is a developer's bundle: it runs where it was
-built, and nowhere else without three more steps.
-
-- **Signing.** The binary is unsigned. Gatekeeper lets an unsigned app run
-  from a build directory, but not one that arrived in a download (the
-  quarantine attribute) — for that it wants a Developer ID signature with
-  the hardened runtime, then notarization. Sign **inside-out, and not
-  with `--deep`**: Apple DTS says not to use it ("Signing a Mac Product
-  For Distribution" and "Creating distribution-signed code for Mac",
-  forums threads 128166 and 701514) and to sign nested code first, with
-  entitlements on the main executable only. So: the addon in `Resources`,
-  without entitlements, then the app with them:
-
-  ```sh
-  ID="Developer ID Application: NAME (TEAMID)"
-  codesign --force --timestamp --sign "$ID" Guestbook.app/Contents/Resources/calayers.node
-  codesign --force --timestamp --options runtime --entitlements bun.plist \
-    --sign "$ID" Guestbook.app
-  ditto -c -k --keepParent Guestbook.app Guestbook.zip
-  xcrun notarytool submit Guestbook.zip --keychain-profile notary --wait
-  xcrun stapler staple Guestbook.app
-  ```
-
-  `bun.plist` is the five entitlements from Bun's "Code signing on macOS"
-  (`allow-jit`, `allow-unsigned-executable-memory`,
-  `disable-executable-page-protection`, `allow-dyld-environment-variables`,
-  `disable-library-validation`). For a copy handed to a colleague, the
-  same two `codesign` lines with `--sign -` and
-  `xattr -dr com.apple.quarantine` on the receiving end are the short
-  path. The machine this was written on has no signing identity: the
-  ad-hoc steps were run, the Developer ID ones are Apple's documentation —
-  [packaging.md](packaging.md#developer-id-or-the-app-store) keeps the
-  line between the two.
-
-- **The Mac App Store is a different bundle.** The store requires App
-  Sandbox, and a `bun build --compile` binary does not start under it.
-  Measured 2026-09-08 (macOS 15.2, bun 1.4.0): this bundle re-signed with
-  only `com.apple.security.app-sandbox` dies every time — `SIGTRAP` in
-  `_libsecinit_appsandbox` for the bare binary, `SIGABRT` in HIServices'
-  `_RegisterApplication` inside the bundle, after the kernel logs
-  `Sandbox: Guestbook deny(1) mach-lookup com.apple.coreservices.launchservicesd`
-  (oven-sh/bun#15661, open). The same example as a node single executable
-  (`node --build-sea`, node 26) in this bundle's shape — same plist, same
-  `calayers.node` in `Resources` — runs sandboxed, launched by `open`,
-  registered with Launch Services, in its own container, with no sandbox
-  denial logged. So a store build is packaging.md's tier 3 inside its
-  tier 5, signed with "Apple Distribution", packaged with `productbuild`
-  and uploaded with Transporter; the recipe, the two esbuild defines the
-  form example needs today, and what was and was not run are in
-  [packaging.md](packaging.md#developer-id-or-the-app-store). Bun stays
-  fine for Developer ID, which needs no sandbox.
-- **Architecture.** `bun build --compile` targets one CPU and the bridge's
-  prebuilds are one per CPU; the script builds for the machine it runs on.
-  A universal bundle is two builds and `lipo` — for the executable and for
-  `calayers.node` alike.
-- **Paths.** The compiled binary is self-contained, and `main.js` finds the
-  addon relative to `process.execPath`, so the bundle can be moved, zipped
-  and dragged into `/Applications`. Nothing in it refers to the repo.
-- **Size.** About 70MB, nearly all of it bun's runtime; the example and
-  react-x11 are a few hundred kilobytes of it. The node SEA of the same
-  example, the store shape, is 142MB.
-
-**The tab bar under bun.** Without a bundle, a window opened by `bun` is in
-the `bun` defaults domain, and once anything has turned on the tab bar for
-one of our windows there — View → Show Tab Bar, or a stray shortcut — AppKit
-persists it as
-`NSWindowTabbingShoudShowTabBarKey-NSWindow-CALBackendDelegate-(null)-VT-FS`
-and every window the bridge opens from then on wears a 28pt tab bar. It also
-shifts the content view down by that much, which the bridge's
-`getWindowFrame` does not report (windowkit/appkit#12), so every popup lands
-a bar's height off. Clear it with
-
-```
-defaults delete bun "NSWindowTabbingShoudShowTabBarKey-NSWindow-CALBackendDelegate-(null)-VT-FS"
-```
-
-or run the app as a bundle, whose own domain has never seen the key. The
-durable fix is the bridge's: `tabbingMode = NSWindowTabbingModeDisallowed`
-on every window it opens.
-
-## Public API: what changes
-
-Measured against both consumers, the surface holds; the deltas are
-additive or mechanical:
-
-1. **Backend selection.** `createRoot()` gains
-   `backend: 'x11' | 'cocoa' | 'auto'` (default `'auto'`: Cocoa on
-   darwin when the bridge is installed, else X11 via `$DISPLAY`;
-   `REACT_X11_BACKEND` overrides for A/B). Backend-specific options
-   stay flat but documented per backend (`display`/`stream`/`glxVisual`/
-   `glPolicy` are X11's; an unknown-to-this-backend option throws with
-   the usual corrective error). `createRoot({ app })` keeps working and
-   is how tests inject mocks of either flavor. _As built, the set is
-   `'x11' | 'cocoa' | 'wayland' | 'win32' | 'auto'`: `'auto'` takes
-   win32 on Windows the way it takes Cocoa on darwin, and never chooses
-   Wayland (`resolveBackend`, src/Reconciler.js)._
-2. **Capabilities.** `useSupports` grows `'nativeControls'`,
-   `'embedding'` (false here), `'globalMenu'`, `'transforms'` (when built)
-   beside `'transparency'` and `'shaders'`; same store-and-settle semantics.
-3. **Inert props policy** (wayland.md open question 1, now decided the
-   way it leaned): same JSX everywhere; a prop with no meaning on this
-   backend (`appId`, `xi2`, `onClientMessage`, X-only states) is
-   inert with a one-time dev-mode note naming the backend — not a
-   throw, so shared app code stays branch-free.
-4. **Keysyms are the key vocabulary**, formally: documented as
-   react-x11's own symbolic key codes (X heritage acknowledged), with
-   the Cocoa input layer synthesizing them. No consumer changes.
-5. **Chord grammar** gains `Primary` (§Menus). Existing tokens keep
-   their literal meanings.
-6. **Test harness**: `renderX11(..., { backend })` namespace gains
-   `'cocoa'` (real, windowed) and `'cocoa-mock'` (headless presenter
-   recorder); existing names untouched. `toPNG`/`pixelAt` on Cocoa read
-   the window snapshot. Pixel _hashes_ are per-backend by construction
-   (CoreText raster ≠ ntk raster); cross-backend assertions compare
-   structure and behavior, not bytes.
-7. **Packaging.** The bridge publishes as its own package — a
-   freestanding, toolkit-agnostic Cocoa bridge (its README already
-   documents the host-config mapping for any reconciler), `os:
-["darwin"]`, prebuilds for arm64/x64, N-API (which keeps the Bun
-   door open; verify in Phase 1). react-x11 references it as an
-   `optionalDependency` exactly as it does `dbus-native`: absent on
-   Linux installs, absent even on macOS if the user skips optional
-   deps — and `backend: 'auto'` then falls back to X11 with a
-   diagnostic. The Cocoa backend code itself lives in-repo
-   (`src/cocoa/…`), not a separate package: one repo, one test suite,
-   one release train, the same reasoning wayland.md's open question 2
-   leaned to.
-8. **The name.** Nothing in this design _requires_ renaming `react-x11`,
-   and both consumers import it by that name today. But this RFC is the
-   moment the name becomes descriptive of one backend out of three
-   planned, and pre-release is the last cheap moment to change it. The
-   options are (a) keep it (Electron ships Chromium nobody renamed;
-   the name becomes heritage), or (b) rename once, now, to something
-   backend-neutral, with `react-x11` republished as an alias or left as
-   the X11-flavored entry. **This document deliberately does not decide
-   it** — it is a taste call for the maintainer — but it does say:
-   decide before the Cocoa backend ships, because every README, example
-   and import written after that multiplies the cost, and do not ship a
-   compatibility alias _afterward_ (AGENTS.md's own shim rule).
-
-## The bridge: the required API
-
-The contract that was published against, grouped, with the POC's coverage
-marked at the time (✅ had it, 🆕 was the work). Mechanism only; policy
-stays in the renderer. `@windowkit/appkit` has since grown past this list —
-its own README is the current reference; this is the shape it was asked
-for.
-
-**App & run loop.** `initApp()`; `pump()` ✅; run-loop drain hook
-(option 2: install/remove the libuv drain, with the re-entrancy guard)
-🆕; display link per window (`onFrame(cb)` with timestamps, start/stop)
-🆕; activation policy + `activate()`, app/dock name 🆕; termination and
-`applicationShouldTerminate` routing 🆕; open-URL/open-file Apple Event
-callbacks (for `onAppOpen`) 🆕.
-
-**Windows.** create ✅ with style options (titled/borderless/panel,
-non-activating, level, opaque/clear) 🆕partial; close ✅; title, frame
-get/set in top-left global coords 🆕 (size ✅); min/max size, aspect 🆕;
-zoom/miniaturize/fullscreen + state readback 🆕; `addChildWindow` 🆕;
-delegate events — resized (live-resize ticks included), moved,
-close-requested, key/main changed, backing-scale changed, screen
-changed, miniaturized 🆕; `scale` ✅; snapshot ✅; per-window event
-routing (window id on every event) 🆕; `requestUserAttention`,
-`orderFront/out` 🆕.
-
-**Layers.** create Layer/Text/Gradient/Shape ✅; `set(props)` for
-frame/bounds/position/anchor, backgroundColor, cornerRadius (+
-`cornerCurve`, `maskedCorners`), border, shadow (+ **`shadowPath`** 🆕),
-opacity, zPosition, transform, `masksToBounds`, mask, `contentsScale`,
-`contentsCenter`/`contentsRect`/`contentsGravity` 🆕partial;
-`addSublayer` ✅ + **`insertSublayer(at/below/above)`** 🆕; remove ✅;
-`bounds.origin` scroll offset (covered by `set`) ✅; **raw-buffer
-contents upload** (premultiplied BGRA/RGBA + stride → layer contents,
-ideally IOSurface-backed for no-copy) 🆕; image contents ✅; **batched
-ops** — one call applying a serialized list of (layer, props) mutations
-inside one transaction, so a big commit is one NAPI crossing 🆕;
-transactions ✅ (`begin/commit`, duration, timing, `disableActions`,
-completion callback 🆕); explicit animations ✅ (+ removal ✅,
-`animationDidStop` callback 🆕).
-
-**Drawing (raster fallback).** A CG bitmap surface object: create at
-size×scale ✅, a canvas2d-compatible verb set over it ✅ (native-side,
-one call per verb — CG covers the standard set; `fillRects` →
-`CGContextFillRects` ✅; `drawGlyphs` → `CTFontDrawGlyphs` ✅), read and
-write pixels ✅, hand to a layer as contents without a copy ✅
-(`createSurfaceIOSurface` + `setLayerContentsIOSurface`), draw one
-surface into another ✅ (`ctxDrawSurface`), shift a band in place ✅
-(`scrollSurface`), copy rects between same-size surfaces ✅
-(`copySurfaceRegion`), the blend mode a `globalCompositeOperation` sets ✅
-(`ctxSetBlendMode`, 0.7.0) and a row memcpy between surfaces of any two
-sizes ✅ (`blitSurface`, 0.7.0 — issue #498; the context feature-detects
-both, so an older bridge draws every composite as a CGImage under
-source-over), and the resampling an `imageSmoothingQuality` sets ✅
-(`ctxSetImageSmoothing`, 0.23.0), and a radial gradient ✅
-(`ctxFillRadialGradient`, 0.28.0). Still 🆕: a pattern fill (`createPattern`,
-which `<Flow>`'s grid tiles ask for), and an explicit
-free (a surface goes with its handle's finalizer). The alternative — rasterize JS-side and use the raw-buffer
-upload — stays open; the API supports both so the choice can be
-measured.
-
-**Text.** measure ✅ → full layout object 🆕: build from span list
-(attributed string), report lines/runs/origins, `indexAt`,
-`caretOffset`, range rects, truncation/`maxLines`, draw-to-bitmap ✅ and
-draw-into-surface 🆕, glyph-run access for `drawGlyphs` ✅
-(`fontGlyphForCodepoint`, `fontGlyphAdvances`, `fontFallbackFor`,
-`ctxDrawGlyphs` in 0.2.0, `fontShapeText` and `fontWithSize` in 0.3.0 —
-windowkit/appkit#1);
-font matching by family list/weight/style/variations → descriptor, and
-loading app-supplied font files (`loadFont`) 🆕; `hasGlyph` ✅.
-
-**Controls.** `controls.render` ✅ (push/default/checkbox/radio/popup/
-slider/switch, states, sizes, appearance) — add: focus-ring state,
-progress bars (bar/spinner), disclosure, natural-metrics query,
-nine-slice insets per kind 🆕; `controls.isDark` ✅ → replaced by
-appearance API below.
-
-**Menus.** Build/patch NSMenu trees from an item list (title, enabled,
-hidden, state/mixed, keyEquivalent+mask, separator, submenu, image?);
-stable item handles for in-place patching; set as main menu; standard
-app/Edit/Window skeleton helpers; context popup at screen point;
-`onAction(id)`; `menuWillOpen` hook 🆕 (all new).
-
-**Pasteboard.** read/write types (string, RTF?, file URLs, custom UTIs
-mapped from MIME), change count polling, lazy provider callback 🆕.
-
-**Drag & drop.** Begin drag session (image, items); destination
-registration on the view with enter/over/exit/drop callbacks carrying
-position + types 🆕.
-
-**Screens & appearance.** `NSScreen` list (frame, visibleFrame, scale,
-id) + change notification; `effectiveAppearance` (dark/light, high
-contrast, reduce motion, accent + change notifications) 🆕
-(replaces `appearanceIsDark` ✅).
-
-**Cursors & misc.** Standard cursor set + hide/show (`setCursor`
-parity) 🆕; `NSStatusItem` (tray; later) 🆕; open/save panels (later)
-🆕; a11y virtual element tree (later, its own design) 🆕.
-
-**Testing hooks.** `postMouseEvent` ✅ extended with modifiers, wheel,
-key events 🆕; window snapshot ✅; a headless mode statement (CI:
-windowed Aqua sessions on macOS runners are expected to work — verify
-in Phase 1; the mock presenter keeps unit tests off the GUI entirely).
-
-## The split: what the bridge owns, what the renderer owns
-
-Written 2026-09-03 against react-x11 2.4.0 and `@windowkit/appkit`
-0.3.0, when the question came up in the concrete form "if the bridge
-grew a full canvas2d API, could it replace ntk on this backend
-outright?" — with the retained tier's need to reach layers, and two
-more backends on the horizon (Wayland at the canvas2d level, Windows
-with primitives not yet chosen), to be held in the same design. The
-answer is a division of labour, and it is mostly the one the code
-already has.
-
-**What is where today.** The bridge exports 36 `ctx*` verbs over an
-opaque surface handle, 8 surface operations (create, IOSurface-backed
-create and lookup, lock/unlock, size, copy rects between two surfaces,
-scroll within one, hand to a layer), the CoreText natives, the layer
-and transaction natives, windows, pasteboard, menu, controls, screens
-and events — one N-API crossing per verb, no state, no policy. On top
-of it `src/cocoa/` is ~4,500 lines: the canvas-shaped context (the
-JS-visible state and the ntk dialect over the verbs), the text engine,
-the layer presenter, the window with its IOSurface swapchain, the app.
-What the cocoa path reaches ntk for is pure JS — colour parsing, the
-shadow math, `SvgView`'s traversal, the image decoders, fontkit metrics
-behind `openFont` — and no X object is constructed. So "replace ntk"
-is already true in substance: on macOS ntk is a utility library and
-the X implementation of the drawing dialect. The one ntk object a
-consumer still handed the backend was `Surface`, and the fix for that
-is dispatch (issue #433, `react-x11/ntk` asking the app), not a port.
-
-**The dialect is the floor contract, and it lives here.** Every backend
-implements canvas2d plus the ntk extensions — `fillRects`, `drawGlyphs`
-with its run contract, `positioned`, Path2D as an argument to
-fill/stroke/clip, the callback-shaped `getImageData`, `Render.PictOp`
-numbering. That is react-x11's policy: it is what `src/nodes/` and every
-registered element paint against, X11 answers it through ntk's XRender
-encoder, Cocoa through `CocoaContext2D` over CG verbs, Wayland will
-through the `'2d-sw'` rasterizer [wayland.md](wayland.md) builds on
-X11 first. The JS class stays in this repository rather than moving
-into the bridge for three reasons. It is the dialect, and a dialect
-defined in three repositories drifts three ways — every context fix
-would become a floor bump, the way #434 cost a `^0.3.0` floor and a
-lock regeneration for two natives. A wrapper that forwards to a **verb
-table** is reusable by any addon that speaks the same verbs, so a
-Windows addon over a Direct2D render target plugs in with no wrapper
-changes at all, where a class inside `@windowkit/appkit` could never be
-reused by Windows or Wayland. And the fake-bridge tests already pin it
-here. The bridge's contribution is exactly the verb table — mechanism —
-and that table is the native-addon contract to standardise:
-`createSurface`/`surfaceSize`/`scrollSurface`/`copySurfaceRegion`/
-`ctxDrawSurface`/`ctxGetImageData`/`ctxPutImageData` and the `ctx*`
-verbs over an opaque handle. Cocoa's is `@windowkit/appkit`'s export
-list as it stands.
-
-**Layers are a ceiling, behind the seam that exists.** The bridge
-speaks two vocabularies, raster (surfaces, verbs, text) and retained
-(layers, transactions, shape and gradient layers, contents), and the
-renderer chooses per window; the node model never learns which. The
-retained presenter needs the raster vocabulary too — its Raster visual
-replays a node's paint into a bitmap and hands the bitmap to a layer —
-so canvas2d is what every backend must provide and layers are what a
-backend may add, behind `noteInvalidate`, `presentFrame` and a null
-`scrollRegion`: three feature-detected hooks, the X11 path
-byte-identical. That is the whole integration surface, and it should
-stay that size. The presenter does not move into the bridge (it
-consumes the node model, which is policy), and there is no third,
-hybrid mode: a node is either properties on a layer or a raster on
-one, decided per node per frame.
-
-**The channel is already node-granular.** `invalidate(layoutChanged,
-node | null, reason)` reaches the presenter as `noteInvalidate(damage,
-layoutChanged, reason)` — which node, what kind — and the X11 painter
-is the one reducing it to rects. The layer presenter today collapses a
-structural `null` into a walk of the whole tree, which is the measured
-~40 ms per frame at ~1,500 nodes (the presenter bench's largest open
-number). That is a presenter-internal fix — dirty-subtree pruning off
-yoga's per-node layout flags and the `_reflowed` set, the same signals
-the X11 path uses to keep layout dirt local — not a new channel. The
-`reason` vocabulary already separates `'scroll'`, which is the
-`bounds.origin` case.
-
-**What is genuinely shared across the coming backends** is the
-client-owned bitmap with buffered presentation. The window's swapchain
-(`_ensureSurface`/`_takeBack`/`present`/`scrollRegion`/`noteFrameDamage`)
-is written over six primitives — create, lock/unlock, copy region between
-two surfaces, scroll within one, present, and whether the compositor still
-holds a buffer — and a Wayland `wl_buffer` pool, where the compositor
-holds a buffer until `release`, is the same shape (catch-up copy or
-buffer-age damage, [wayland.md](wayland.md)); so is a Windows swap chain
-or DIB pair. The offscreen `Surface` is the same family: written over
-`createSurface`, `surfaceSize`, `scrollSurface` and `ctxDrawSurface` plus
-the wrapper, behind the app seam (`app.createSurface(options)`), so a
-Wayland app implements the seam over a CPU bitmap with its `'2d-sw'`
-context and `copyWithin` is the memmove `scrollSurface` already is. Per
-backend, then: Wayland's context is the JS rasterizer, so the dialect
-holds by construction, and with no retained tier (`wl_subsurface` is too
-coarse) `presentFrame` is absent and the X11 paint path runs verbatim over
-the swapchain; Windows' two candidate primitive sets are exactly the two
-vocabularies — a Direct2D target for the verb table, DirectComposition
-visuals for a presenter — so it starts at the floor with the wrapper and
-the swapchain reused and adds a composition presenter later behind the
-same seam. [windows.md](windows.md) is that backend's PRD.
-
-**In order, with the priority stated:** the existing two backends, X11
-and Cocoa, become stable and performant before a third is started, so
-the steps that serve them come first. (1) This section: the verb table
-and the surface operations are the native-addon contract. (2) Issue
-#433: `CocoaSurface` over that contract, the `createSurface` seam,
-dispatch in `react-x11/ntk` — landed with this text. (3) The
-presenter's dirty-subtree pruning, ahead of anything below because it
-is the open number on a shipped backend. (4) Moving the context
-wrapper and the swapchain under `src/backend/` with neutral names — when
-a second native backend or Wayland actually starts, and not before: a
-half-renamed tree is worse than either name. (5) Bridge growth stays
-verb-shaped — a pattern fill for `<Flow>`'s grid tiles, a blend op for
-`PictOp.Src` — and never a JS canvas class.
-
-_As built: Wayland did not take the `'2d-sw'` route. Its context is a GLES
-rasterizer of its own (`src/wayland/context2d.js`, wayland.md's Tier D),
-which draws the dialect rather than forwarding it. Step (4) was taken for
-the context alone when the Windows backend started — `src/backend/context2d.js`
-drives both bridges' verb tables — and the swapchain stayed in `src/cocoa/`._
-
-## Measured: the frame clock and the large tree
-
-Written 2026-09-03 against react-x11 2.5.0 and `@windowkit/appkit` 0.3.0,
-on an M1 Pro at 2x, from the stress scenarios `npm run bench:presenters`
-grew for it — "state update → pixels" and "interaction → pixels" inside a
-tree the size of an application screen (`--cells`, 1,200 labelled boxes:
-3,662 nodes) — and the surface presenter, which is the default. The
-numbers travel as well as any timing does; the ratios are the findings.
-
-**What a frame cost, and what it costs now** (median flush unless said
-otherwise; `cpu` is the process as a share of one core, driver ticks at
-62.5Hz):
-
-| scenario                                  | before                     | after                      |
-| ----------------------------------------- | -------------------------- | -------------------------- |
-| `tree` — one memoized cell per tick       | 1.25ms                     | 0.35ms                     |
-| `tiny` — one of 5,000 cells (14k nodes)   | 7.2ms p95                  | 1.2ms p95                  |
-| `multi` — 12 scattered cells per tick     | 11.9ms, 1,470kpx repainted | 2.8ms, 264kpx              |
-| `press` — down/up, input → flush          | 4.3ms p50 / 10.2 p95       | 2.6ms p50 / 8.7 p95        |
-| `scroll` — wheel notch, input → flush     | 15.2ms p50                 | 1.9ms p50                  |
-| `resize` — a live tick, 40-tick drag      | 71ms, 2 full frames each   | 28ms, 1 frame + 1 catch-up |
-| `occluded` — hidden window, cell per tick | 207 frames, 50% cpu        | 0 frames                   |
-| `layout` — every cell reflows per tick    | 44ms (18fps)               | 44ms — see below           |
-
-Five changes, each fenced by a test:
-
-- **The paint reach is cached** (`Node._paintBoundsCache`, src/nodes/invalidate.js). A
-  bounded frame asked every subtree on the way to its rect whether it
-  reached in, and each answer walked the subtree: a one-cell repaint cost
-  the whole tree, linearly. The union is now kept until something that
-  moves it announces itself — layout, a child list change, a style swap, a
-  state flip, `invalidate` — with `REACT_X11_NO_BOUNDS_CACHE=1` as first
-  aid. Shared with X11, and the protocol bench is unchanged by it:
-  `test/paint-reach.test.js`.
-- **The damage rect cap is the backend's** (`window.damageRectCap`). Four
-  rects is what a pass costs the X server; a Cocoa pass is one CoreGraphics
-  clip and a culled walk, so its window keeps sixteen — twelve components
-  ticking at once paint their twelve rects instead of the box around them.
-- **A resize tick is one frame** (`CocoaWindow._freshSurface`,
-  `_routeGeometry`). Replacing the backing surface used to queue a second
-  full frame behind the one already painting it, and the React-half flush
-  was queued per event — and inside AppKit's resize loop no microtask runs
-  until the drag ends, so a forty-tick drag ran eighty full frames on the
-  mouse release: the freeze after a resize. A fresh surface now asks for a
-  frame only when the flush that found it was bounded, and holds the
-  present until that frame lands; the release owes at most one flush.
-  `test/cocoa-frames.test.js`.
-- **A live resize defers the content floors** (`_deferContentFloors`,
-  src/nodes/window/size.js). The floors (#249) were three extra layout passes and their
-  walks — 21 of the 44ms a relayout cost on this tree, before they were
-  measured incrementally (§"Measured: incremental floors") — and a drag
-  calls the frame from inside every pointer move. A live tick lays out against
-  the floors it has (exact along the main axis, a frame stale for wrapped
-  text across it) and the first frame tick after the release measures once
-  and lays out again: answer the input, then catch up. Only under
-  `liveResizing`, which the Cocoa window holds between AppKit's begin and
-  end of the drag (`window-live-resize`); an X window never sets it. A content change mid-drag takes
-  the measured path.
-- **A window nobody can see owes nothing** (`CocoaWindow._visible`): frames
-  for a window that is ordered out or miniaturized wait in the queue and
-  its present waits with them; one catch-up frame when it is back. (A
-  window entirely behind another application's window joined that rule in
-  the pass after this one — see below.) The frame gate also moved from
-  "one interval since the last frame" to
-  "the first pump tick at or after it", which took a 16/24/16/24ms cadence
-  to a steady 16 (52 → 56fps against the 62.5Hz driver), and the wheel is
-  answered on the event like a press — AppKit already delivers scroll
-  events at the display's rate, so that is once per refresh by
-  construction. (Mostly: a trackpad lands two in one tick often enough
-  that the window now gates it — see "The wheel is gated to the display too" below.)
-
-The structural half of these numbers is a gate now:
-`npm run bench:presenters -- --check` judges full-window frames, the share
-of the window a cell repaints, frames per resize tick and frames for a
-hidden window against `scripts/bench/presenters-gate.json`, and
-`npm run bench:touched` runs it — with the X11 gates — only for a change
-that reaches a hot path. CI's `bench-cocoa` job does the same on a macOS
-runner.
-
-**What was left, in order of what it cost** — the list that became #442,
-and the pass below.
-
-## Measured: after the frame-clock pass
-
-Written 2026-09-03 against react-x11 2.5.0 and `@windowkit/appkit` 0.4.0
-(windowkit/appkit#10, which shipped the bridge half of #442: `releaseSurface`,
-every surface's bytes accounted to V8, `fps` on `listScreens`, and
-`window-occlusion` events), same machine, same bench, the surface presenter.
-Four of the six items are closed by it; the two that remain are the
-renderer's own and are listed at the end.
-
-| what                                                          | before                  | after                 |
-| ------------------------------------------------------------- | ----------------------- | --------------------- |
-| a 40-tick resize burst, no yield between ticks — rss during   | +572 to +655MB          | +12 to +14MB          |
-| `anim` on the 120Hz panel                                     | 55.7fps, 32% cpu (16ms) | 113.5fps, 49% (8.3ms) |
-| `hover` on the 120Hz panel, input → flush p50 / p95           | 7.2ms / 16.8            | 3.1 / 9.2             |
-| `icons` — 300 mono icons re-tinted per tick, flush avg / p95  | 2.98ms / 3.35, 72% cpu  | 2.07 / 2.42, 67%      |
-| `covered` — the big tree behind another window, cell per tick | a frame per tick        | 0 frames              |
-
-- **The retired pair is released on the flip** (`CocoaWindow._releaseBacking`,
-  `releaseSurface`). A resize tick allocates two window-sized IOSurfaces and
-  used to leave the two it replaced to their handles' finalizers — which run
-  on the event loop, and inside AppKit's resize loop the event loop does not
-  run, so a drag held every pair it ever made until the release. The bridge's
-  accounting alone (`napi_adjust_external_memory`) makes the collection
-  prompt once the loop is back; the explicit free is what bounds the peak
-  while it is not, which is the number in the table. The row is a script
-  driving forty `setWindowFrame`s synchronously, the way the modal loop
-  delivers them; the bench's `resize` cell yields between ticks and its rss
-  column is collection noise either way now. `CocoaSurface.destroy()` and
-  the layer presenter's rasters release the same way, and a bridge without
-  the verb gets the drop it always had. `test/cocoa-frames.test.js`,
-  `test/cocoa-surface.test.js`.
-- **Each window paces itself on its own display** (`CocoaApp.frameIntervalFor`,
-  `_frameDue`). The default interval is `1000 / fps` of the screen under the
-  window's centre, re-read when it moves; `createRoot({ cocoa: { frameInterval
-} })` still overrides it for every window. The frame queue keeps a clock per
-  window, so a window on the 120Hz panel paints every refresh while one on a
-  60Hz monitor paints every other pump tick. What it is worth is the `anim`
-  and `hover` rows: twice the frames for half again the CPU, and input →
-  flush halved, on the panel that can show it. One honest limit at the
-  time: the 8ms pump quantized the cadence, so a 75Hz monitor (13.3ms)
-  painted at 62.5fps — the gate was the interval less half a pump, and
-  9.3ms fell on the 16ms tick. The pass below gives such a frame a timer
-  of its own.
-- **A window entirely behind another application's window owes nothing**
-  (`CocoaApp._routeOcclusion`, `CocoaWindow._visible`). AppKit's
-  `windowDidChangeOcclusionState` arrives as `window-occlusion`; off, the
-  window's frames wait in the queue and its present with them, exactly as an
-  ordered-out window's do; on, the next pump tick runs one catch-up frame.
-  `map()` resets the flag, since a show is a claim to be on glass and AppKit
-  corrects it a pump later. The bench's new `covered` scenario opens a window
-  of our own over the tree and is in the gate at zero frames. What is not
-  free while covered is the React commit itself: the scenario's 41% CPU is
-  `root.render` of a 3,662-node tree per tick, and no frame clock can take
-  that.
-- **The paint cache is on** (`paintCacheFor` accepts an app with
-  `createSurface`; `PaintCache.coverage`). Entries are `CocoaSurface`s
-  through `react-x11/ntk`'s `Surface`, composited with one `ctxDrawSurface`.
-  This backend has no coverage surface, so a mono drawing is cached as
-  argb32 with its colour in the key — `paintCached(ctx, box, ink)` now says
-  which colour to paint in — one entry per colour rather than one for all of
-  them, still one render per colour instead of one per cell per frame. A
-  blurred shadow, whose blur is a pass over the mask, stays live. The `icons`
-  row is the gain, and the larger cost left in that scenario is the React
-  re-render of 300 unmemoized components. `test/cocoa-paint-cache.test.js`.
-- **A pane's frame gate is real** (`CocoaPaneWindow.frameInFlight`). The
-  early flush a discrete input gets (`flushPendingFrames`, src/frames.js) is
-  safe because it is gated on the last frame having landed — that gate is
-  what folds a burst into one paced frame — and the pane window answered it
-  with a constant `false`. So every message the host had queued while the
-  pane was busy painting got a full frame of its own: a forty-tick resize of
-  `examples/frame.jsx`'s pane, whose frame costs 250–320ms, stepped through
-  42 presents at 42 intermediate sizes and reached the final one twelve
-  seconds after the drag had ended, each step the previous IOSurface
-  stretched to the layer's new frame. A pane hears nothing back from the
-  host, so a present now counts as in flight for one frame interval; the
-  same burst is one frame at the size it ended on, plus the one the first
-  message was answered with. `test/cocoa-frames.test.js`. Since #870 the
-  host answers each present, and the gate is that answer as well
-  (§"Measured: a pane's presents, answered").
-- **The wheel is gated to the display too** (`CocoaApp._routeWheel`,
-  `CocoaWindow._flippedRecently`). The wheel's early flush painted and
-  flipped for every scroll event, and a trackpad lands two in one pump
-  tick often, so the second frame was drawn into the buffer the first
-  flip had taken off glass microseconds before — while the WindowServer
-  could still be compositing from it. A scroll's frame blits before it
-  repaints what the shift got wrong, and a composite caught between the
-  two shows the blit alone: a held `position: 'sticky'` header dragged up
-  a pixel for a frame, or the rows under it painted over it and then
-  corrected. Everything else in a scrolling pane moves anyway, which is
-  why this hid until something was meant to hold still. Now the first
-  event of a burst is answered on the spot and the rest fold into the
-  next paced frame, and a frame that answered the wheel restarts the
-  window's clock, so the pump does not flip again a few milliseconds
-  after it. Only the wheel: a resize paints into a pair it has just made,
-  and gating its ticks cost the live resize a frame after the drag
-  (`resize` in the presenter gate caught it). `test/cocoa-frames.test.js`.
-- **A `<glarea>`'s frame and its overlay go out together**
-  (`CocoaWindow.surfaceFrameOwed`, `CocoaApp._tickFrames`). Two things
-  let the overlay a surface's children are painted on reach the screen
-  ahead of the GL frame it was painted for, while #641 had ordered the
-  two within a tick. An input answered at once, a press, a key or a wheel
-  notch, flushed the window inside its dispatch, overlay and all, and left
-  the GL frame the same input asked for on the clock, a refresh or more
-  later. And inside a tick the two were still two commits: the overlay is
-  flipped in a transaction of its own in the window's flush, the GL frame
-  after its draw, and a frame that rebuilt its scene put 10–16ms between
-  them. `<Flow>` over 400 widget bodies (react-x11-components'
-  `flow-stress` example) showed it: the first notch of a zoom took the
-  bodies and their cards off the overlay 20–25ms before the GL frame that
-  drew the cards in their place, and for that long the graph showed its
-  edges with nothing under them.
-  Now a window whose surface has a frame queued is left to the clock by the
-  early flush, and a tick runs such a window's frame and its surfaces'
-  inside one transaction, committed with the window's size, so every layer
-  the two changed lands in one commit. What an input gives up is the head
-  start of its 2D half on such a window; its GL half never had one.
-  `test/cocoa-glarea.test.js`.
-
-**What was left, in order of what it cost** — the three items of #445,
-measured in the pass below: a full relayout of a large tree (44ms at 3,600
-nodes, half of it the content floors measured from scratch), nothing drawn
-at a level of detail, and the pump quantizing the frame period.
-
-## Measured: incremental floors, the strip, the frame timer
-
-Written 2026-09-03 against the pass above (react-x11 2.5.0, `@windowkit/appkit`
-0.4.0), same machine, same bench, the surface presenter — the three items
-#445 ranked, in its order.
-
-| what                                                                 | before          | after           |
-| -------------------------------------------------------------------- | --------------- | --------------- |
-| `layout` — 3,662 nodes, the container's padding toggling: fps, flush | 18.4fps, 43.8ms | 34.4fps, 19.9ms |
-| `tiny` — 14,452 nodes, 5px labels: the frame the grid reflows on     | 320ms           | 175ms           |
-| `anim` on a 75Hz monitor                                             | 56.3fps         | 70.4fps         |
-| `anim` on the 120Hz panel                                            | 108–113fps      | 108.6fps        |
-
-- **The floors are measured incrementally** (`collectFloorStale`,
-  `probeHeightFloors`, `contentSpan`, src/nodes/window/floors.js). Every node keeps the
-  extent it was last measured at — what it needs from the box around it,
-  on each axis — and a measurement re-reads only the nodes whose subtree
-  changed, taking the rest at the number they carry. Which subtrees
-  changed is yoga's own record: a style setter, a child that came or went
-  and a text that asked to be re-measured all mark their node and every
-  node above it dirty, and the walk goes down that path and no other. So
-  a padding change on a container measures the container and nothing
-  below it, a row that mounts measures itself alone, and a colour change
-  measures nothing. The passes are paid for only where a floor is going
-  to be written from what they find: the width pass runs when content
-  changed under a node on a row's main axis, and the heights are settled
-  the other way round — the real layout runs first, a walk over the nodes
-  it moved asks each leaf, in JavaScript and out of its own layout cache,
-  whether its height at its new width is the height it had, and only if
-  one says otherwise (or content changed under a node a height floor is
-  written on) do the two height passes run and the layout again. On the
-  `layout` cell that is one pass over yoga where it was four, and a walk
-  over two nodes where it was four walks over 3,600: the floors went from
-  22ms of the frame to 6, of which 4 is the one yoga pass. What is left
-  of that frame is paint — 1,200 rounded fills and 1,200 `CTLineDraw`s,
-  about 15ms — and React's own commit. `test/content-floors.test.js`
-  counts the nodes each kind of change measures and the passes it runs.
-- **Text below a legible size is a strip** (`TextNode._paintsStrip`).
-  Under six logical pixels a label is a smudge of its ink, and a
-  rectangle per line over the band the letters sit in, in that ink at the
-  coverage small text has, is the same smudge for one fill instead of a
-  glyph run. Logical pixels, because what is legible is a physical
-  question: a 5px label is the same size on a 2x panel as on a 1x
-  monitor. `createRoot({ textStripBelow })` moves the line and `0` keeps
-  glyphs at every size (`REACT_X11_TEXT_STRIP_BELOW` for a process that
-  cannot reach `createRoot`); the layout is untouched either way — the
-  strip is as wide as the line the shaping settled. What it is worth is honest: on CoreGraphics a `CTLineDraw` of a three-glyph label costs about what a fill does, so the `tiny` cell on the surface presenter is unchanged by it (48–49fps either way) — its reflow frame is the 5,000 rounded cell fills, not the labels; on X11 the strip takes the cell's flush p95 from 86ms to 12ms, the glyph path's periodic expensive frames gone.
-  `test/text-strip.test.js`.
-- **A frame due between two pump ticks gets a timer of its own**
-  (`CocoaApp._armFrameTimer`, `_frameDue`). The gate is now a millisecond
-  under the interval — a timer's drift, no more — and a frame the next
-  tick would be late for is run by a one-shot at the moment it is due,
-  which runs the frame queue and presents; a present commits its own
-  transaction, so nothing waits for the pump. The clock is kept on the
-  display's period rather than on the moment a frame happened to run, so
-  a tick that took a frame a little early or a timer that fired a little
-  late moves nothing. The 75Hz row is what it is worth; the 120Hz panel,
-  whose period the 8ms pump already fit, is unchanged. What the pump
-  alone still does is poll AppKit's events, which `pumpInterval` stays
-  the cadence of; the display link (§"Input and the run loop") would take
-  input latency under it. `test/cocoa-frames.test.js`.
-
-**What is left, in order of what it costs:** the paint of a large tree —
-the fills and the line draws, which only not repainting can take away: a
-paint cache over the cells that did not change, or the layers presenter —
-then yoga's own pass at about a millisecond per thousand nodes, and React's
-commit of a tree that re-renders unmemoized.
-
-## Measured: the flood, under the frame pacer
-
-Written 2026-09-07 against react-x11 2.8.3 and `@windowkit/appkit` 0.6.0,
-same machine, the surface presenter, `npm run bench:presenters --
---scenario=stream --columns=surface`: a window-sized element repainting its
-whole box on every claim, claimed every 2ms by a timer standing in for a
-producer — the shape of a terminal under `cat`. The rows are `--frame-rate`
-([elements.md](elements.md#framerate--pacing-the-frames-under-a-flood)).
-
-| `--frame-rate` |   fps | paint share of wall | cpu | producer: claims/s |
-| -------------- | ----: | ------------------: | --: | -----------------: |
-| `display`      | 120.0 |                 58% | 72% |                244 |
-| `adaptive`     |  36.1 |                 21% | 27% |                529 |
-| `30`           |  29.7 |                 19% | 24% |                539 |
-| `throughput`   |   8.8 |                  9% | 13% |                592 |
-
-The default paints every refresh and starves its producer of half its
-ticks; `'adaptive'` holds paint at the budget and gives the producer all of
-them. The design and the rest of the numbers are in
-[architecture/frame-pacing.md](architecture/frame-pacing.md). Two things
-here are the backend's own: `CocoaWindow.present` reports the flip and its
-catch-up copy to the node, so the frame is priced by what the thread
-spent and not just by the flush; and `CocoaApp._requestFrame` arms the
-frame timer for a request that arrives between two pump ticks, so a held
-claim lands at its wait rather than at its wait rounded up to the pump.
-The structural gate is unchanged: every rule holds at the default, which
-is what every scenario but `stream` runs at.
-
-## Measured: the swapchain and the WindowServer's hold
-
-Written 2026-09-17 against react-x11 2.15.3 and `@windowkit/appkit` 0.11.0,
-the M1 Pro's 120Hz panel, for #602: a menu-bar popover flickered while its
-spectrum animated. The scene is that popover's shape — a borderless,
-transparent 320×440pt window with eight bars on `height` loops, which
-repaint the whole window every frame (#603) — and every write into an
-IOSurface (a copy, a clear, a fill, a glyph run) is checked with
-`surfaceIsInUse` at the moment it lands. Three runs of 4s per row,
-alternating the old swapchain and this one on a loaded machine; clicking is
-a press and a release every 100ms through `postMouseEvent`, each answered on
-the event.
-
-| mode               | catch-up copies into a held buffer | first draws of a frame into a held buffer |
-| ------------------ | ---------------------------------- | ----------------------------------------- |
-| pump               | 1,439 of 1,440 → 0 of 1,426        | 569 of 1,440 → 0 of 1,426                 |
-| pump, clicking     | 1,671 of 1,680 → 0 of 1,680        | 543 of 1,680 → 0 of 1,680                 |
-| threaded           | 1,236 of 1,387 → 0 of 1,381        | 833 of 1,387 → 0 of 1,381                 |
-| threaded, clicking | 1,314 of 1,590 → 0 of 1,571        | 660 of 1,591 → 0 of 1,571                 |
-
-Counting every write, not only the first of a frame: 148,839 of 386,377
-landed in a held buffer before, and 0 of 383,938 after.
-
-- **A frame takes its buffer at its first draw** (`CocoaWindow._takeBack`).
-  The catch-up copy used to follow the flip: in pump mode microseconds
-  after it, into the buffer the flip had just taken off glass, and on a
-  worker after `surface-released`, which says the flip was applied and not
-  that the WindowServer let go. Now nothing is chosen at the flip. The next
-  frame's first draw takes, of the buffers not on glass, one that
-  `surfaceIsInUse` answers free — on a worker, one whose release has come
-  as well — and of those the one on glass most recently, which missed the
-  fewest frames.
-- **Each buffer keeps what it missed.** A present adds its damage to every
-  buffer it did not show, so a buffer that comes back several frames
-  behind is caught up with all of them; past 64 rects, whole.
-- **The chain grows to four buffers, on demand.** The WindowServer let go
-  of a buffer a median of about 9ms after a flip replaced it, and under
-  40ms at the 99th percentile. So at 120Hz the buffer a flip replaced is
-  often still held when the next frame draws, and the one before it
-  rarely: an animation mostly needs three. An input answered on the spot
-  between two of its frames puts two flips inside one refresh, and a
-  loaded machine holds buffers longer; four covered every run above. With
-  every buffer held and the chain full, the frame takes the one off glass
-  longest — the one write left that can land in a held buffer.
-- **…and gives them back.** A second after a window's last frame, a chain
-  that grew keeps two buffers: the one on glass and the one on glass
-  before it. A still window holds the backing store it always did, and its
-  next frame takes the kept buffer without making one.
-- **A new chain starts with one buffer.** A live-resize tick paints its size
-  once and the next tick makes a chain of its own, so a tick now allocates
-  one window-sized IOSurface instead of two, and no full copy follows its
-  flip: the bench's `resize` cell made 41 surfaces for its 40 ticks where it
-  made 80, and uploaded 61kpx a frame where it copied 2,611.
-- **Not done: pacing the input.** #602 also suggested gating every input's
-  early present the way the wheel's is gated (`_flippedRecently`), which
-  keeps a burst to one flip per refresh and the chain to three. It would
-  also move the answer to a press on an animating window to the next paced
-  frame, up to a refresh later. The fourth buffer spends memory instead of
-  latency, and only while a window animates and takes input at once.
-
-`test/cocoa-frames.test.js`, `test/cocoa-threaded.test.js` and
-`test/cocoa-scroll-blit.test.js` hold the rules, the last in pixels. What
-is not measured is a torn frame on glass, before or after: `snapshotWindow`
-renders the window from the buffer just flipped in, not the one being
-written, and cannot see this race either way.
-
-## Measured: a scroll's band, copied once
-
-Written 2026-09-25 against react-x11 2.22.6 and `@windowkit/appkit` 0.13.0,
-the M1 Pro at scale 2. A scroll blit's frame used to write its band twice.
-The frame's first draw took a buffer and caught it up to the frame on glass,
-and the catch-up owed the band, because the frame before had blitted it too.
-Then `scrollSurface` moved the band inside that buffer. Now a scroll that is
-its frame's first draw takes its buffer with the band already moved:
-`blitSurface` copies it across from the frame on glass at the shift, and
-the catch-up copies everything else (`CocoaWindow._takeBack`). Every pixel
-ends where the two passes left it, the strips the shift exposes included, so
-the frame repaints what it did. A scroll later in a frame, a chain of one, a
-buffer that owes nothing or a bridge without `blitSurface` moves the band in
-place, as before.
-
-The time spent in the bridge's copies, in each probe of the components
-sweep (`scripts/bench/sweep/` in react-x11-components), the median of three
-runs alternating the two:
-
-| scroll                              | copies per frame | the window's flush, p50 |
-| ----------------------------------- | ---------------- | ----------------------- |
-| `<CodeEditor>`, 50,000 lines, wheel | 2.09 → 1.61ms    | 4.00 → 3.72ms           |
-| `<Markdown>`, 600 KB, wheel         | 1.44 → 1.01ms    | 6.02 → 5.55ms           |
-| `<Table>`, 100,000 rows, wheel      | 1.15 → 0.99ms    | 2.66 → 2.68ms           |
-| `<Flow>`, a pan of the cards scene  | 1.36 → 0.80ms    | —                       |
-
-`scripts/cocoa-blit-probe.mjs` counts the frames that take the band across
-(`across`): 499 of its 500 on the real bridge, with the two windows'
-pictures identical on every frame.
-
-**A copy measured in a loop is not the copy a frame makes.** A 15 MB copy
-between two IOSurfaces takes 0.34 ms back to back on this machine, 45 GB/s.
-One copy every 16 ms, with the thread asleep in between, takes 1.8 ms at
-the median and 4 ms at the 90th percentile. The band copies above run at
-that rate: about 8.5 GB/s. It is not the surface: plain `malloc`ed memory
-slows down the same way, and a buffer the WindowServer is showing copies at
-full speed in a loop. It is not the thread's QoS class either:
-user-interactive, default and utility all measure alike. Splitting the rows over two to eight GCD threads makes the
-loop twice as fast and the paced copy no faster. So the time is in the
-memory system waking up, not in the core doing the copy. What a frame can
-do about it is copy fewer bytes, and a benchmark of a copy has to leave the
-thread idle between copies, the way a frame clock does.
-
-## Measured: a paragraph laid out again
-
-Written 2026-09-25 against react-x11 2.22.6 and `@windowkit/appkit` 0.13.0
-with windowkit/appkit#75, which 0.14.0 released, on the M1 Pro at scale 2. A
-window resize lays every paragraph of a document out at the new width, and
-`createLayout` was most of that frame. Timed inside the verb over the reflow
-of a 600 KB document, it went to four places:
-
-| part of `createLayout`                   | `<Markdown>` | `<Html>` |
-| ---------------------------------------- | ------------ | -------- |
-| the attributed string from the spans     | 30%          | 27%      |
-| `CTTypesetterCreateWithAttributedString` | 37%          | 40%      |
-| breaking lines, the `CTLine`s and runs   | 16%          | 16%      |
-| the result's objects, one a line and run | 17%          | 17%      |
-
-The first two are the text becoming glyphs, and they are the same at every
-width. So the engine keeps a paragraph's typesetter
-(`CocoaFontManager._keptTypesetter`), found by everything shaping reads — the
-spans' text, faces, colours, features and spacing, and the direction — and a
-layout of the same paragraph at another width, alignment, line height or
-line cap is broken from it (appkit's `typesetter`). A min-content
-measurement lays out other text, the paragraph broken at every opportunity,
-and keeps its own. The geometry comes back packed, two `Float64Array`s
-rather than an object per line and run (`unpackLines`). The kept
-typesetters hold at most a megabyte of text, about 25 MB of CoreText's, and
-the paragraph laid out least recently is let go past it
-(`releaseTypesetter`); a font the app loads lets them all go. A bridge from
-before the verbs, appkit 0.13 and earlier, is asked the old way.
-
-Separately, a layout's code point to code unit table
-(`codeUnitOffsets`) is null for text with no surrogate pair, which is
-nearly all text: it was a walk of every character of a document at every
-width.
-
-| 600 KB document, `docsweep.tsx` | reflow step, p50 | first paint    |
-| ------------------------------- | ---------------- | -------------- |
-| `<Markdown>`                    | 335 → 228 ms     | 1255 → 1174 ms |
-| `<Html>`                        | 574 → 273 ms     | 549 → 526 ms   |
-
-First paint moves too, because a paragraph's max-content measurement and
-its wrapped layout are now one shaping. `test/cocoa-kept-typesetters.test.js`
-holds the keys, the eviction and the unpacking over a fake bridge, and,
-where the bridge keeps typesetters, that every layout made from one is the
-layout made from the spans.
-
-## Measured: a pane's presents, answered
-
-Written 2026-10-04 against react-x11 2.40.0 with #870 and #875 and
-`@windowkit/appkit` 0.25.0, on the M1 Pro's 120Hz panel at scale 2, with the
-browser example in `@react-x11/components` on a Wikipedia article. A preload
-logged, in the pane, the first write into each ring buffer after a present —
-the seq the buffer was last presented under, the newest `pane-shown` heard,
-and `surfaceIsInUse` — and in the host every lookup, so each write could be
-held against the moment the host looked its buffer up. The scenarios: the
-window dragged 4 px every 16 ms; and the pane scrolling itself a notch every
-8 ms, or every 4 for a burst — input the host's thread has no part in, as
-momentum or a page's own animation is — with the host idle, or busy 60 ms in
-every 150. Two runs of each, master and branch interleaved.
-
-| per 3 s of scrolling                                       | before       | after       |
-| ---------------------------------------------------------- | ------------ | ----------- |
-| busy host: frames drawn into a buffer it looked up after   | 93–98 of 376 | 0           |
-| busy host: frames drawn into the buffer on the layer       | 19           | 0           |
-| any host: frames drawn into a buffer the WindowServer read | 155–177      | 0–2         |
-| busy host: input to the host's lookup, p50 / p99           | 7.9 / 64 ms  | 8.5 / 64 ms |
-| idle host: presents a second, input to present p50         | 119, 5.9 ms  | 119, 6.6 ms |
-| burst: presents a second, input to present p50             | 118, 6.0 ms  | 118, 6.6 ms |
-
-Three findings decided the design (`CocoaPaneWindow.frameHeld`, `_takeBack`,
-`frameInFlight`):
-
-- **The host two presents behind is ordinary.** A host busy with its own
-  frame stops answering, and triple buffering assumed it never would: the
-  pane drew into the buffer on the layer, or into one a present still in
-  the channel named, which the host then showed half drawn. A frame now
-  takes a buffer only once the host has answered a present after the last
-  one that named it, and waits on the clock for the answer when there is
-  none, 250 ms at most.
-- **An answer is a lookup, not a frame on glass.** The buffer the layer let
-  go of stays in use for 8 ms after the pane hears the answer at the median,
-  13–22 at the 90th percentile; and a host back from a stall answers a run
-  of presents at once while its UI thread commits later. Taken on the answer
-  alone, the frame after each stall drew into the buffer the screen still
-  showed, 18–23 frames of 285. So a frame takes a buffer the WindowServer
-  has let go of as well, asked every millisecond for a frame interval at
-  most. The catch-up copy moved from the present to the frame's first draw
-  for the same reason — at the present the buffer two behind was still read
-  in nearly half the frames of a scroll — and that is the 0.6 ms the table
-  shows: the copy is on the input's path now. Doing it at the present when a
-  free buffer is already there is the obvious follow-up.
-- **The input gate keeps its frame interval.** Gating on the answer alone
-  answered an input 4 ms sooner at the median, and drew a frame per input
-  past the display's rate: 245 a second at 250 inputs a second, 355 at 1000,
-  the pane busy 58% of the time against 33%, and the frames that outran the
-  WindowServer drew into buffers it still read. Nothing the pane can ask
-  says when a frame is on glass — a buffer reads in use from the host's
-  lookup, not from the refresh — and a gate on the clock's own grid in
-  place of the interval held every input to the paced frame just the same.
-
-A drag is faster for the second: master copied the whole frame into the
-next buffer at every present, and the next frame of a drag is a new size on
-a new ring, so the copy was thrown away every time — 126 copies in 126
-presents, against 55 in 174 now. Frames during the drag, the mean of six
-interleaved pairs: 52 a second before, 59 after.
-`test/cocoa-frames.test.js` holds each rule over the fake bridge, and each
-fails its own test when taken out.
+`make-app.sh` builds a developer's bundle, which runs where it was built;
+[packaging.md](packaging.md#tier-5--a-macos-app) has the recipes. What
+differs on macOS:
+
+- **Signing.** A downloaded app needs a Developer ID signature with the
+  hardened runtime, then notarization. Sign inside-out, not with `--deep`:
+  `calayers.node` first, without entitlements, then the app with Bun's five
+  entitlements ([packaging.md](packaging.md#developer-id-or-the-app-store)).
+  For a colleague, ad-hoc signing (`--sign -`) and
+  `xattr -dr com.apple.quarantine` on their end are the short path.
+- **The Mac App Store** requires App Sandbox, under which a
+  `bun build --compile` binary does not start. A Node single executable in
+  the same bundle shape does, so that is the store build; Bun is fine for
+  Developer ID.
+- **Architecture.** A compiled binary and the bridge's prebuild are each for
+  one CPU; a universal bundle is two builds and `lipo`, for the executable
+  and `calayers.node` alike.
+- **Size.** About 70 MB with bun, nearly all of it the runtime; 142 MB as a
+  Node single executable.
 
 ## Testing
 
-The strategy mirrors the X11 suite's shape rather than its mechanism:
-
-- **Unit tier, headless, any OS**: `backend: 'cocoa-mock'` — the Cocoa
-  presenter running against a recorded layer-op sink and a metrics-only
-  TextEngine stub (the `mock-app.js` precedent). Asserts _which layer
-  mutations a commit produces_ — the retained twin of the dirty-rect
-  tests — plus all the shared behavioral tests, which run on the node
-  model and don't care about the presenter.
-- **Integration tier, macOS**: real windows on a runner's Aqua session;
-  pixels via window snapshot; input via the posted-event path (the
-  harness's `fireEvent` transport). Per-backend pixel baselines; the
-  scenario-level structural assertions (find-by-color, behavior) shared.
-- **The bench twin** (§Measure first) is part of the definition of done
-  for the presenter, not an afterthought — the scroll and transition
-  scenarios are the reason Tier L exists, so they are what fences it.
-
-### The swapchain, in pixels
-
-Counting bridge calls is the right shape for a frame clock and the wrong
-one for a fast path whose only observable is the picture. The scroll blit
-is the case: `scrollRegion` shifts a band inside the **back** buffer, the
-frame repaints only the strips the shift exposed, and what carries the
-band into the other buffers is the catch-up copy over the rects
-`noteFrameDamage` collected, when a frame takes one of them. A catch-up
-covering the wrong rects leaves a buffer one shift stale, and a pan then
-smears — a staircase of duplicated content at increasing offsets, which is
-what issue #458 reports.
-
-Two harnesses answer it, and they answer the same question:
-
-- `test/cocoa-scroll-blit.test.js` runs in CI on any OS. Its bridge holds
-  real rasters — a byte per pixel, `ScrollSurface`, `CopySurfaceRegion` and
-  `BlitSurface` written out with the natives' own clamping — and the proof
-  obligation is
-  one line: render the same pane into two windows, delete `scrollRegion`
-  on the second (which is how the scroll blit feature-detects a backend without
-  the fast path), and the buffer handed to the layer must hold the picture
-  the repaint painted. Then the frames a pan meets: bursts coalesced into
-  one frame, a frame painted but not presented, a present held or
-  occluded, a resize mid-gesture, fuzzers over all of it — and a third
-  window whose buffers the WindowServer holds for up to two frames after
-  each flip (#602), so that a buffer comes back several frames behind,
-  where no write may land in a held buffer or in the one on glass. The
-  heaviest of those run twice: the band taken across with the buffer, and
-  a bridge without `blitSurface`, moving it in place.
-- `scripts/cocoa-blit-probe.mjs` is the same comparison over the real
-  bridge — CoreGraphics contexts, IOSurfaces, an actual swapchain — for
-  when the question is whether the bridge does what the model says. Not
-  part of the suite (it needs macOS); run it when the swapchain or the
-  bridge's surface verbs change. It runs in pump mode: its frames are
-  driven synchronously, and a worker's would wait on releases the loop
-  never yields for.
-
-Both also count the blits, because two windows that both repainted agree
-about everything and prove nothing.
-
-## The plan
-
-Each phase has an exit that makes the next safe to start; the first two
-run against today's renderer with no core changes.
-
-- **Phase 0 — the bridge contract.** Close the POC gaps
-  that block everything else: event modifiers + per-window routing +
-  wheel/key posting, window delegates, `insertSublayer`, raw-buffer/
-  IOSurface contents, batched ops, display link, run-loop drain
-  (option 2), and the menu API skeleton. Publish 0.2.0 with prebuilds.
-  _Exit: a demo app live-resizes with JS-driven relayout tracking the
-  drag, and a native menu's items enable/disable from JS while open._
-- **Phase 1 — the surface backend (Tier S).** `src/cocoa/app.js`
-  implementing the ntk app/window/ctx/fonts contract; CoreText
-  TextEngine v1; event mapping; `createRoot({ backend })` selection;
-  `cocoa-mock` harness backend. Run the examples; port the test suite
-  where the mock reaches. Build the bench twin and record Tier-S
-  baselines, including input-to-photon. _Exit: `examples:widgets`,
-  `tasks`, `form` fully interactive natively; suite green on
-  cocoa-mock; baselines recorded._
-- **Phase 2 — the presenter seam (X11-neutral refactor).** Extract
-  paint/damage/flush into the X11 presenter behind the
-  invalidate/flush contract; nodes keep model+events+layout. **Zero
-  behavior change**, pinned by pixel gates, dirty-rect tests and
-  `bench --check` on X11. _Exit: X11 suite and bench byte- and
-  number-identical; the presenter interface documented in
-  docs/extending.md terms._
-- **Phase 3 — the layer presenter (Tier L core).** Visuals for
-  box/text/image/canvas + raster fallback; clipping and scrolling via
-  layer properties; popups as panels; `CATransaction` per commit.
-  Measure against Tier-S baselines; apply the §Measure-first gates
-  (layer-collapse and text-atlas work only where numbers demand).
-  _Exit: the bench twin shows Tier L beating Tier S on scroll and
-  transition scenarios and regressing none; examples run on layers;
-  Tier S demoted to fallback/A-B switch._
-- **Phase 4 — the platform (macOS services).** NSMenu global menu +
-  `Primary` chords; native appearance/screens/scale/window-state;
-  pasteboard clipboard; native control bezels behind
-  `controls: 'native'`; native file dialogs; `useSupports` additions.
-  _Exit: `examples:menu` is the system menu bar; `widgets` renders
-  native bezels; appearance flips live without osascript._
-- **Phase 5 — the deep integrations.** DnD; NSAccessibility bridge over
-  the a11y model; IME via NSTextInputClient; transitions offloaded to
-  CA (+ `opacity`, then `transform`, capability-gated); `<glarea>` over
-  CAOpenGLLayer/ntk-cgl; tray via NSStatusItem; app lifecycle
-  (open-URL → `onAppOpen`). Each is its own bounded design against a
-  by-then-stable presenter. _Exit: per-feature; the a11y bridge's is
-  VoiceOver reading the widgets example the way Orca reads it today._
-
-## Open questions
-
-1. **The name** (§Public API #8) — decide before Phase 4 ships anything
-   user-visible.
-2. **Layer granularity numbers** — layer-per-drawn-node is the bet;
-   collapse thresholds and the text-atlas question are Phase-3
-   measurements, and the §Measure-first gates decide them.
-3. **Run-loop option 3** — is the drain (option 2) enough for menu
-   tracking + live resize + drag sessions in practice, or does a real
-   inversion become necessary? Phase 0/1 experience answers it.
-   Answered 2026-09-11, and neither: a nested drain never drains
-   microtasks, and an inversion needs whoever owns `main()`. The answer is
-   JS on a worker with AppKit parked on the main thread — §"JS on a worker:
-   a UI thread of the bridge's own", with the bridge's half filed as
-   [windowkit/appkit#49](https://github.com/windowkit/appkit/issues/49).
-4. **Transition semantics under CA** — retarget/interrupt parity with
-   the JS loop needs a written spec before Phase 5 flips the default.
-5. **Cross-backend text metrics** — accepted divergence (per-backend
-   pixel baselines) vs. the shared-shaping option if component layout
-   portability bites in practice.
-6. **Bun on the Cocoa backend** — N-API under Bun is expected to work;
-   verify early (Phase 1) since single-file packaging is a stated goal.
-   Answered in two halves: `make-app.sh` is that single file and it runs,
-   and it cannot be the App Store one — a bun binary does not start under
-   App Sandbox (§Distributing the bundle), so that build is node's SEA.
-7. **`@react-x11/components` on Cocoa** — the seven registered elements
-   should light up via the raster path untouched; the X-only corners
-   (tray-host, embed, media-player embedding, `serverTime`) need
-   per-module capability statements rather than silent absence.
-
-## References
-
-- [wayland.md](wayland.md) — the sibling RFC; shared inventory and the
-  opposite rendering inversion.
-- [remote.md](remote.md), [embedding.md](embedding.md),
-  [globalmenu.md](globalmenu.md), [appearance.md](appearance.md),
-  [filedialog.md](filedialog.md), [accessibility.md](accessibility.md),
-  [events.md](events.md), [styling.md](styling.md),
-  [extending.md](extending.md), [testing.md](testing.md) — the
-  per-feature contracts this plan maps onto Cocoa.
-- Apple: Core Animation Programming Guide; `CATransaction`,
-  `CALayer.shadowPath`, `contentsCenter`, `NSTextInputClient`,
-  `NSAccessibilityElement`, `NSDraggingSession`, `NSPasteboard`,
-  `CADisplayLink` (macOS 14+).
-- libuv — "Embedding libuv in other event loops" (the run-loop drain's
-  recipe, pointed at AppKit).
-- Distribution: Apple, "App Sandbox" (the store requirement) and "Porting
-  just-in-time compilers to Apple silicon" (`allow-jit` matters only under
-  the hardened runtime); Apple DTS on the forums, "Signing a Mac Product
-  For Distribution" (thread 128166) and "Creating distribution-signed code
-  for Mac" (701514) — inside-out signing, no `--deep`; Bun, "Code signing
-  on macOS" in the executables guide; Node, `tools/osx-entitlements.plist`;
-  oven-sh/bun#15661 for bun under App Sandbox.
-- WebKit/Gecko form-control rendering via offscreen `NSCell` drawing —
-  the native-bezel technique the POC reproduces.
-- [`@windowkit/appkit`](https://www.npmjs.com/package/@windowkit/appkit) —
-  the bridge this document specified, as published. §"The bridge: the
-  required API" was its 0.2.0 contract.
+`react-x11/test` drives the **X11 backend on every platform, macOS
+included**; there is no `'cocoa'` backend for `renderX11()`. Test the tree,
+queries and behaviour there, which are shared. Pixels are per-backend
+(CoreText is not ntk's rasterizer), so native bezels, the `NSMenu` and
+pasteboard flavours are checked by running on a Mac
+([testing.md](testing.md)). A window's `snapshot()` resolves to its
+composited pixels, in the display's colour profile.
+
+## Not supported yet
+
+- **VoiceOver**: no `NSAccessibility` bridge, and AT-SPI is off here, so a
+  Cocoa app is not reachable by assistive technology yet. Write roles and
+  labels anyway; the bridge will read them ([accessibility.md](accessibility.md)).
+- **Input methods**: no `NSTextInputClient` — no marked text, Press-and-Hold
+  accents or CJK input ([events.md](events.md#input-methods)).
+- **Nested `<window>` elements** throw; a `<glarea>` is the only child
+  surface.
+- **`Surface` `format: 'a8'`** throws — allocate `argb32` and tint through
+  `fillStyle`/`globalAlpha`.
+- **`createPattern`**, and the X-only `Picture`, `<image picture>` and
+  `<image drawable>`.
+- **The eyedropper over a bridge older than 0.9**: `useEyedropper().supported`
+  is false — leave the eyedropper button undrawn.
+- **`useKeepAwake()`**: no macOS rung.
+- **`transform`** as a style property (on any backend).
+- **`transientFor`** and the `sticky`, `below`, `skip_taskbar` and `shaded`
+  states: inert.
+- **A `'cocoa'` backend for `react-x11/test`.**
+- **Dropped images** while the app runs on a worker.
+- **Never, by design**: `<foreign>` and XEmbed, a window manager
+  (`examples/wm.jsx`), remoting over `ssh -X` — run the X11 backend through
+  XQuartz for those.