react-x11 2.51.0 → 2.52.0

package/docs/wayland.md

@@ -0,0 +1,545 @@
+# A native Wayland backend
+
+**Status: research RFC, since built.** The backend it plans landed in #548
+as `src/wayland/`, opt-in; [wayland-backend.md](wayland-backend.md) is the
+record of what was built, and where the two disagree that one ran. The RFC
+below was written before any code, 2026-08, against react-x11 2.2.1,
+ntk 8.7.0, node-x11 4.1.0, x11-dri 0.6.0; the line counts and library
+versions below are measurements from that date, not estimates. Two upstream
+issues were filed from this research
+([x11-dri#19](https://github.com/sidorares/node-x11-dri/issues/19),
+[x11-dri#20](https://github.com/sidorares/node-x11-dri/issues/20)) and one
+upstream capability landed just before it
+([node-x11#290](https://github.com/sidorares/node-x11/pull/290)).
+
+## What this is, and is not
+
+This is a plan for a **second backend, not a migration**. X11 stays a
+first-class target: the remote case ([remote.md](remote.md)) is the
+flagship reason this project exists, old X11-only systems stay supported,
+and nothing below proposes touching how the X11 path works. The question
+this document answers is what it would take to run the same React tree
+natively on a Wayland compositor — no Xwayland in the picture — on the
+systems where that is the better experience.
+
+The goals that shape every choice here are the project's standing ones:
+
+- **a small, portable codebase** — no compiled dependencies where possible;
+  a native module is admissible where a runtime leaves no other way to
+  reach a required OS facility, or where a hot path is significantly faster
+  compiled and the pure path remains as fallback;
+- **the whole range of desktop UI** — full applications, small utilities,
+  tray tools, panels and desktop-integration services, window managers;
+- **the best experience available per system** — perceived performance
+  first (input-to-photon), then stability, then client CPU and memory.
+
+One goal meets a hard wall immediately and it is better to say so up top:
+**a window manager cannot be a Wayland client.** Compositing, stacking and
+input routing are the compositor's own body, not a role a client can take.
+`examples/wm.jsx` and the window-management half of the API remain X11-only
+under this plan; the shell-adjacent use cases that _can_ be served
+client-side (panels, docks, launchers, lock screens, tray tools) map to
+their own protocols and are covered below. Being the compositor — a
+react-x11 embedded in a wlroots- or Smithay-class host — is a different
+project and out of scope here.
+
+## What Wayland actually changes
+
+Wayland's wire protocol is a **control plane**. Objects, requests, events;
+interfaces defined in XML; two 32-bit words of header and 32-bit-aligned
+arguments in host byte order
+([the spec](https://wayland.freedesktop.org/docs/book/Protocol.html), and
+[wayland-book.com](https://wayland-book.com/) as the readable tour). What it
+does not carry — ever, not just at setup — is drawing. There is no
+`PolyFillRectangle`, no RENDER `Composite`, no `PutImage`. A client hands
+the compositor **finished pixels** by reference: a `wl_buffer` naming
+either shared memory (`wl_shm`) or a GPU buffer
+([linux-dmabuf](https://wayland.app/protocols/linux-dmabuf-v1)), attached
+to a surface, damaged, committed. Surface state is double-buffered and
+atomic — everything set since the last `commit` applies in one step.
+
+That deletes the premise of ntk's rendering layer. It is tempting to read
+this codebase as "canvas-like drawing code that happens to target X11", and
+most planning mistakes would start there. ntk's 2d context is an **XRender
+encoder**: fills are server-side trapezoids or rectangles, gradients are
+`CreateLinearGradient` objects, text is `CompositeGlyphs` against a
+server-resident glyph cache, `drawImage` is a `Composite`, and a `Surface`
+is a pixmap+picture pair. The server rasterizes and composites; the client
+describes. On Wayland the client rasterizes and composites, full stop —
+which is why the largest workstream below is a renderer, not a protocol.
+
+The other structural inversion: on X11 the client asks and the server
+answers (`GetGeometry`, `QueryPointer`, properties); requests take effect
+as issued. On Wayland the client **requests and the compositor decides**,
+answering with `configure` events the client must ack. A window does not
+know its own screen position, cannot place itself in globals, and cannot
+read other windows. Several react-x11 features live or die on that line —
+the inventory is below.
+
+Two things get simpler, and they are not small:
+
+- **Frame pacing.** ntk earns its frame clock the hard way — Present
+  completions, a fence fallback, a quantile estimator over completion
+  history to guess the refresh rate. Wayland hands the same thing over
+  directly: `wl_surface.frame` callbacks say "now is a good time to draw",
+  and [presentation-time](https://wayland.app/protocols/presentation-time)
+  reports when a committed frame actually reached the screen, with clock
+  id, refresh interval and flags. For a project whose stated first goal is
+  input-to-photon, this is the first target where **photon time is
+  observable**, not inferred.
+- **Scale.** The four-generation ladder in [scale.md](scale.md) —
+  environment, XSETTINGS, `Xft.dpi`, RandR-millimetre audit — collapses to
+  `wl_output.scale` plus
+  [fractional-scale-v1](https://wayland.app/protocols/fractional-scale-v1)
+  with [viewporter](https://wayland.app/protocols/viewporter): authoritative,
+  per-output, and live.
+
+## What already carries over
+
+Measured against 2.2.1 (`src/`, excluding `.d.ts`):
+
+| slice                                                                                                                                                         | lines   | Wayland fate                              |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------- |
+| portable core — reconciler, yoga, styles/decorations parsing, palette, a11y tree + AT-SPI, keysym tables, compose, text selection model, D-Bus stack, anchors | ~16,200 | unchanged                                 |
+| `components/` + `frame/` + `refresh/`                                                                                                                         | ~8,700  | unchanged (`<Frame>`'s host seam changes) |
+| X-touching modules                                                                                                                                            | ~23,400 | see below                                 |
+
+The 23,400 overstates the rewrite. `nodes.js` is 11,515 lines of which only
+`WindowNode` + `PopupNode` (~3,100) speak X — `BoxNode`, `TextNode`,
+`ImageNode`, `CanvasNode`, `TextInputNode` and the layout/paint/hit-test
+machinery drive a 2d context and never name the display system. The honest
+rewrite surface is **~9–10k lines**: window realize/present, `events.js`,
+`dnd.js`, `clipboard.js`, `screens.js`, `windowstate.js`, `scale.js`,
+`keyboardstate.js`, `compositing.js`, `inputtime.js`, `startup.js`.
+
+On the ntk side the split is starker. The portable half of a renderer
+**already exists** there, built for the local-raster path and for glyphs:
+
+- `rasterize.js` — analytic coverage accumulation (the font-rs algorithm),
+  outlines/polygons in, A8 out;
+- `path.js` — Path2D, flattening, stroking, transforms;
+- `shadow.js` — `blurCoverage`, separable gaussian, baked once;
+- `text/` — fontkit faces, shaping, bidi, line breaking, layout — the
+  entire text stack short of the final composite;
+- `fontconfig.js`, `imagedata.js` (premultiply/unpremultiply, pixel
+  layouts), `color.js`, `region.js`.
+
+What does not exist is the piece XRender was doing: the **span
+compositor** — A8 coverage × paint source → premultiplied ARGB with
+Porter-Duff, clipping, gradient evaluation, transformed image sampling —
+and a client-side **glyph atlas** where the server-side `GlyphSet` used to
+be. That is the gap, whatever tier below fills it.
+
+Desktop integration is the pleasant surprise: it was built D-Bus- and
+portal-first, X as a fallback rung ([dbus.md](dbus.md),
+[filedialog.md](filedialog.md), [appearance.md](appearance.md),
+[eyedropper.md](eyedropper.md), [globalmenu.md](globalmenu.md), AT-SPI in
+[accessibility.md](accessibility.md)). On Wayland those modules mostly
+_lose a rung_ rather than gain one. The X-only integration channels
+(`xsettings.js`, startup-notification's X path, the eyedropper's crosshair
+grab) simply end at the ladder's portal rung.
+
+## The transport: file descriptors, both ways
+
+Everything in Wayland that moves bulk data moves a descriptor: the
+compositor sends every client its keymap **as an fd**; `wl_shm` pools go
+over as fds; clipboard and drag-and-drop hand the receiving side a pipe fd
+and stream content through it. Descriptors ride SCM_RIGHTS ancillary data,
+matched to `fd`-typed arguments **by order, not by message** — the spec is
+blunt that "any byte of the stream, even the message header, may carry the
+ancillary data". A transport that cannot receive descriptors is not a
+limited Wayland client; it is not a Wayland client.
+
+Where the runtimes stand:
+
+| runtime    | send fds                                                     | receive fds                                                         | verdict                       |
+| ---------- | ------------------------------------------------------------ | ------------------------------------------------------------------- | ----------------------------- |
+| Node       | yes — node-x11's `fdpass.js` via `process.binding` internals | **no** — an arriving fd on a libuv-read socket aborts the process   | needs a small native module   |
+| Bun        | yes — `bun:ffi` → `sendmsg(2)` (node-x11 4.1.0)              | **yes** — `bun:ffi` → `recvmsg(2)` + a poll thread (node-x11 4.1.0) | works today, pure JS + dlopen |
+| Node+addon | yes                                                          | yes — an addon owning the socket end to end (~200 lines of C)       | the eventual portable answer  |
+
+Node upstream is not coming:
+[nodejs/node#53391](https://github.com/nodejs/node/issues/53391) — filed
+specifically for Wayland — is closed "not planned". Bun landed in
+[node-x11#290](https://github.com/sidorares/node-x11/pull/290)
+(`lib/fdpass-bun.js`, 884 lines): `dlopen` of libc, no compiler and no
+headers, two transports. The default keeps Bun's own socket and adds
+`sendFds()`; `receiveFds: true` owns the descriptor end to end — `recvmsg`
+on the main thread, readiness from a worker blocked in `poll(2)` — because
+Bun's reader silently drops ancillary data it did not ask for. Three
+properties make it a Wayland transport with zero changes: it connects to
+**any** unix path, it is `net.Socket`-shaped with real backpressure, and
+its ownership contract (sent fds consumed; received fds owned by the caller
+once taken) is the one Wayland's object model wants.
+
+**Decision: prototype on Bun.** It is the only runtime where the whole
+stack stays JS-plus-dlopen today. The Node fallback is not abandoned — it
+is a bounded ~200-line native module that owns one socket, and `x11-dri`
+already exists as a home for exactly this kind of gap-filler — but it is
+not on the critical path, and building Bun-first keeps the prototype free
+of a compile step. This matches the portability goal's own exception
+clause: a compiled module is admissible where the runtime leaves no other
+option, and on Node it does.
+
+## The protocol layer: mostly already written
+
+Prior art, surveyed 2026-08:
+
+- **[node-wayland-client](https://github.com/sdumetz/node-wayland-client)**
+  (npm `wayland-client` 3.0.0, Apache-2.0, active — last commit 2026-06).
+  Pure TS, zero runtime dependencies; parses `wayland.xml` (or precompiled
+  JSON) and generates typed proxies. The core is **~1,270 lines** —
+  `display.ts` 382, `interface.ts` 257, `args.ts` 231 — with ~2,350 lines
+  of tests. The socket is injected through the constructor, the `fd`
+  argument type is already encoded in all three codec paths, and the one
+  missing piece is a single guard: a request whose signature contains an
+  `fd` throws `"sending ancillary data not supported"`. The README asks
+  for exactly the contribution this project would make.
+- **[westfield](https://github.com/udevbe/westfield)** /
+  [Greenfield](https://github.com/udevbe/greenfield) — a full Wayland
+  **server** in TypeScript for a browser-hosted compositor. Wrong
+  direction, but proof the wire level is comfortable in JS, and its XML
+  codegen is worth reading.
+- Everything else (2013-era `node-wayland` bindings to libwayland) is dead.
+
+So the layer is either **adopt `wayland-client` and contribute the fd
+path** (a few hundred lines against node-x11's Bun transport), or write an
+in-house equivalent in node-x11's idiom (~1.5–2.5k lines plus codegen).
+Adopt-first is the default; the fork-shaped risk — the project is one
+person's — is mitigated by its size: this is a library we could absorb,
+not a dependency we would be stuck on. Either way the per-protocol cost
+after that is ~zero, because every interface is generated from XML.
+_As built: adopted, and forked as
+[`@windowkit/wayland`](https://github.com/windowkit/wayland) —
+`wayland-client` 3.0.0 plus descriptor passing both ways, a synchronous `$`
+request path and callback payloads, offered back upstream._
+
+The shopping list, mapped to what each protocol replaces here:
+
+| protocol                                                                   | stands in for                                                     |
+| -------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| core (`wl_compositor`, `wl_shm`, `wl_seat`, `wl_output`, `wl_data_device`) | connection, buffers, input, screens, clipboard/DnD                |
+| [xdg-shell](https://wayland.app/protocols/xdg-shell)                       | `WM_*`/EWMH window lifecycle, `<popup>` placement                 |
+| xdg-decoration (+ kde-server-decoration)                                   | asking for server-side decorations (often refused)                |
+| [linux-dmabuf](https://wayland.app/protocols/linux-dmabuf-v1)              | the GPU tier's buffer handoff                                     |
+| fractional-scale-v1 + viewporter                                           | the whole of `scale.js`'s ladder                                  |
+| [presentation-time](https://wayland.app/protocols/presentation-time)       | Present completions; adds real photon timestamps                  |
+| cursor-shape-v1                                                            | server-side cursor names                                          |
+| primary-selection                                                          | the PRIMARY half of [clipboard.md](clipboard.md)                  |
+| xdg-activation                                                             | `_NET_ACTIVE_WINDOW` + startup notification's focus half          |
+| [layer-shell](https://wayland.app/protocols/wlr-layer-shell-unstable-v1)   | `_NET_WM_STRUT_PARTIAL` — panels/docks (wlroots + KDE; not GNOME) |
+| ext-session-lock, ext-idle-notify                                          | lock screens; `useIdle()`                                         |
+| text-input-v3                                                              | the input-method story `compose.js` approximates                  |
+
+## Rendering: the tiers
+
+First, what the field does — because "software rendering on Wayland" is
+sometimes assumed to be a second-class citizen, and it is not:
+
+| toolkit                  | rasterizer                                                                                                                    | handoff    |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| QtWidgets                | CPU raster engine                                                                                                             | `wl_shm`   |
+| GTK4                     | GSK — cairo (CPU), GL, Vulkan; [Vulkan default on Wayland since 4.16](https://blog.gtk.org/2024/01/28/new-renderers-for-gtk/) | either     |
+| foot, most wlroots tools | pixman (CPU)                                                                                                                  | `wl_shm`   |
+| Firefox                  | WebRender (GPU), software WebRender fallback                                                                                  | dmabuf/shm |
+
+CPU-to-shm is mainstream, and the one systemic cost it had — the
+compositor's copy to GPU-visible memory — was addressed on the compositor
+side in 2026:
+[KWin 6.7 imports page-aligned shm buffers as udmabufs](https://zamundaaa.github.io/wayland/2026/05/06/making-wl-shm-fast.html)
+and samples them directly, taking KWin from 80–90% of a core to ~20% while
+a CPU-rendered app scrolls. The client's whole obligation is page-aligned
+pool allocations and GPU-friendly strides (~256-byte multiples; ≈1.6%
+padding at 4K). Any pool we write complies from day one.
+
+Also load-bearing for everything below: `wl_shm` +
+`wl_surface.damage_buffer` preserves ntk's **dirty-rectangle model
+verbatim** — paint the damaged rects into the mapped buffer, report
+exactly those rects, commit. The entire performance architecture
+(`MAX_DIRTY_RECTS`, scroll blits as `memmove`, the paint cache) transfers
+without redesign. A GPU swapchain does _not_ preserve it — buffers rotate,
+so damage must be tracked per buffer age or the frame fully redrawn — which
+is half the argument for the tier ordering below.
+
+### Tier A — our own span compositor, pure JS
+
+Extend what ntk already has (coverage rasterizer, paths, shadows, text
+shaping) with the missing span compositor and a client glyph atlas, and
+register it as a sibling 2d context. The seam already exists and is the
+whole reason this is tractable: every context registers in
+`Drawable.renderingContextFactory` (`'2d'`, `'x11'`, `'opengl'`, `'gles'`,
+`'cgl'` today), and `src/nodes/` asks for a context by name and never looks
+behind it.
+
+- **Portability: perfect.** JS + typed arrays; runs everywhere including
+  the in-process test server.
+- **Performance: the open question, but a bounded one.** A widget UI
+  repaints small dirty regions; the analytic rasterizer measures ~25µs for
+  a 20px icon; glyphs come out of an atlas as `memcpy`+blend. The risk is
+  large-area work — full-window gradients, big images under transform —
+  where JS with no SIMD pays. Mitigations exist per-hot-path (see tiers
+  below); the floor is validated by every pixman-based tool on the desktop.
+- **Why it is first anyway:** it can be built and shipped **on the X11
+  backend first** as `getContext('2d-sw')`, diffed against XRender output
+  with the existing pixel-hash gates and benches — a reference
+  implementation and a working test harness on day one, no Wayland in the
+  loop. It also answers standing X11 wants: rendering where RENDER is poor
+  or absent, and one day feeding DRI3/Present directly.
+
+### Tier B — a Wasm rasterizer
+
+[CanvasKit](https://skia.org/docs/user/modules/canvaskit/) (Skia compiled
+to Wasm, full `CanvasRenderingContext2D`) or
+[tiny-skia](https://github.com/linebender/tiny-skia) behind a thin binding.
+No native toolchain — Wasm loads everywhere — so this **respects the
+portability rule** while buying SIMD and two decades of Skia's raster
+tuning.
+
+The catch is not speed but scope: adopting Skia's canvas means adopting
+Skia's text, fonts and geometry, displacing ntk's own text stack — the
+part of this codebase most worth keeping. The honest use of this tier is
+narrower: **a span-filling kernel behind Tier A's API** (tiny-skia fits;
+CanvasKit does not slice that thin), swapped in per-context where
+profiling says the JS compositor is the bottleneck. Same API, same tests,
+a hot-path exception exactly as the goals allow.
+
+### Tier C — a native 2d library
+
+[skia-canvas](https://github.com/samizdatco/skia-canvas) ships prebuilt
+Skia with GPU raster and the canvas API; published comparisons put
+CanvasKit ~25× behind it on some workloads (numbers to re-measure on ours,
+not to inherit). This is the "just works, fastest today" tier and a
+legitimate prototyping shortcut — the RFC's own preference for a compile
+step over a blocked prototype applies. It is not the destination: a
+multi-megabyte native dependency for every app contradicts the packaging
+story, and its GPU path duplicates Tier D with less control. If used, it
+hides behind the same `renderingContextFactory` name so nothing above the
+seam knows.
+
+### Tier D — our own accelerated 2d over x11-dri
+
+The addon misnamed by history: `x11-dri`'s `Gpu` is **GBM + EGL + GLES on
+a DRM render node and never touches X**. Its swapchain output is already
+the exact shape the Wayland GPU path consumes —
+`surface.swap()` → `{ fd, stride, offset, modifier }` →
+`zwp_linux_dmabuf_v1.create_params.add(...)` → `wl_buffer` — and dmabuf
+import is fd-**send** only, which even plain Node can do. A
+NanoVG-shaped renderer (stencil-then-cover fills, glyphs and gradients as
+textures) over the existing `dri.gl` binding gives GPU 2d with the text
+stack still ours.
+
+Filed from this research, both small and both blocking this tier:
+
+- [x11-dri#19](https://github.com/sidorares/node-x11-dri/issues/19) — the
+  EGL config never asks for stencil bits, while the binding exports the
+  full stencil API against it. Stencil-then-cover needs `stencilSize`.
+- [x11-dri#20](https://github.com/sidorares/node-x11-dri/issues/20) — no
+  in-place resize (a drag-resize rebuilds the swapchain per frame), and
+  GEM handle reuse across recreation makes the documented `key`-cache
+  pattern silently unsafe. Wants `resize()` + a `generation` counter.
+
+Costs to keep in view: per-buffer damage tracking replaces the shm model's
+free dirty rects; a render-node requirement (fall back to Tier A where
+there is none — same seam); and it is a compiled dependency, prebuilt for
+common platforms, `dlopen`-degrading elsewhere — inside the goals'
+exception, but an exception.
+
+**Recommendation:** A first, validated on X11 before Wayland exists; D as
+the performance tier sharing all the Wayland plumbing; B as a swappable
+kernel inside A if profiling demands it; C at most as a prototype-phase
+crutch. All four sit behind one context name, chosen by policy the way the
+GL backends already are.
+
+## Windowing semantics: what maps, what bends, what breaks
+
+| react-x11 today                                                        | Wayland                                                                                                          | verdict                                                                          |
+| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `<window>`, WM-managed                                                 | `xdg_toplevel`; states arrive in `configure` and are acked, not set                                              | maps — state model inverts to request/answer                                     |
+| `<popup>` (override-redirect, self-placed)                             | `xdg_popup` + `xdg_positioner`: anchor rect, gravity, constraint adjustment; compositor places and dismisses     | maps _better_ — but only for anchored popups                                     |
+| `<popup x y>` at screen coordinates                                    | —                                                                                                                | **gone**; no client knows screen coordinates                                     |
+| `anchorRect` flip/clamp in `realize()`                                 | the same policy, expressed as positioner flags, executed compositor-side                                         | our one-source-of-truth design survives; the math moves                          |
+| decorations (WM frames; `_MOTIF_WM_HINTS`)                             | client-side by default; xdg-decoration is advisory and GNOME declines server-side                                | **new work**: draw and hit-test our own titlebar/borders/resize edges            |
+| `windowstate.js` (`_NET_WM_STATE` set)                                 | `set_maximized`/`set_fullscreen`/`set_minimized` + configure states; attention via xdg-activation                | maps; `_NET_WM_DESKTOP`, `ABOVE`, user-time have no equivalents                  |
+| struts (panels reserving edges)                                        | layer-shell — wlroots and KDE, **not GNOME**                                                                     | maps with a hole                                                                 |
+| frame clock (Present + fence + refresh estimator)                      | `wl_surface.frame` + presentation-time                                                                           | simpler and more honest; photon time becomes measurable                          |
+| `keyboardstate.js` (XKB over the wire)                                 | keymap arrives as an fd; interpret with libxkbcommon (`bun:ffi`, ~300 lines) — do not hand-write a keymap parser | maps; `keyboard.js`'s Latin-accelerator resolution survives unchanged above it   |
+| clipboard/DnD (selections, INCR, XDND)                                 | `wl_data_device`: offers are pipe fds, content streams                                                           | maps; the INCR machinery dies unmourned; MIME plumbing in `transfer.js` reusable |
+| `<foreign>` / `<Frame>` (XEmbed,[embedding.md](embedding.md))          | `wl_subsurface` is same-client; xdg-foreign is parenting, not embedding                                          | **gone by design**; `<Frame>` becomes a parented toplevel or an in-process pane  |
+| `examples/wm.jsx`, window lists, global grabs, `GetImage` screen reads | compositor-private                                                                                               | **gone by design**; portals cover capture with consent                           |
+| eyedropper X rung                                                      | portal `PickColor` rung already first                                                                            | loses the fallback rung only                                                     |
+| `ssh -X` remoting ([remote.md](remote.md))                             | no network transparency; [waypipe](https://gitlab.freedesktop.org/mstoeckl/waypipe) proxies fds over ssh         | X11 backend remains the remote answer                                            |
+| tray                                                                   | StatusNotifierItem was always D-Bus                                                                              | unchanged                                                                        |
+
+The one to sit with is the popup row: `anchor.js` exists because a
+`<popup>` must place itself with no round trip available, flipping and
+clamping against screen geometry the client had to learn. Wayland's
+positioner is that exact policy as protocol — a cleaner home for the
+intent, and the end of the screen-coordinate escape hatch in the same
+stroke. The API consequence (some props meaning nothing on one backend) is
+an open question below, not something to paper over.
+
+## Testing
+
+The X11 suite's superpower is `x11/lib/xserver` — a 3,828-line pure-JS X
+server, in-process, no display. The Wayland twin is **smaller**, because
+the hard part of that server is the drawing protocol and Wayland has none:
+a mock compositor implements the registry, surface/buffer lifecycle,
+`configure` handshakes and seat event injection — and every committed
+buffer is **plain memory the test can read**. Pixel assertions stop being
+`GetImage` round trips and become array reads; `fireEvent` maps to
+injecting seat events; the harness stays "real protocol, zero display",
+which is the property worth preserving.
+
+## The plan
+
+Each phase has an exit that makes the next one safe to start.
+
+- **Phase 0 — the spike (days).** Bun + `wayland-client` + node-x11's fd
+  transport: bind globals, memfd a page-aligned pool, put a solid-colour
+  `xdg_toplevel` on a real compositor, and receive the keymap fd. _Exit:
+  fd receive proven end-to-end; adopt-vs-write settled for the protocol
+  layer._
+- **Phase 1 — software 2d, on X11 (the long pole, start immediately).**
+  The span compositor + glyph atlas as `'2d-sw'` behind the factory seam;
+  diffed against XRender via the pixel-hash gates; benched against the
+  scenarios in `scripts/bench`. _Exit: visual parity on the gates;
+  interactive scenarios within an agreed factor of XRender locally._
+- **Phase 2 — surface + shell.** `WaylandWindow` beside ntk's `Window`
+  (frame clock, damage, backing pool); `WindowNode.realize()` grows a
+  second path; configure/ack, CSD drawing, `xdg_popup` placement. _Exit:
+  the examples that need no embedding run natively._
+- **Phase 3 — input and integration.** Seat events into the synthetic
+  event system; xkbcommon keymaps; clipboard/DnD over pipes; scale,
+  outputs, activation; the portal-first modules verified with their X
+  rungs dark. _Exit: the component test suite green on the mock
+  compositor._
+- **Phase 4 — the accelerated tier.** The GLES renderer over x11-dri
+  (after [#19](https://github.com/sidorares/node-x11-dri/issues/19)/
+  [#20](https://github.com/sidorares/node-x11-dri/issues/20)), dmabuf
+  handoff, buffer-age damage. _Exit: chosen scenarios beat Tier A on a
+  render-node machine; automatic fallback proven._
+- **Phase 5 — the payoff.** presentation-time-driven latency measurement;
+  input-to-photon on the dashboard; scheduling tuned against real photon
+  timestamps. _Exit: the number the project optimizes for, finally
+  measured rather than modeled._
+
+## Needs validation
+
+What the backend does today was built and checked on one machine — a
+virtual GNOME/mutter desktop on virgl, one virtual monitor, a mouse and a
+keyboard — and some of it was built to the specification because this
+machine cannot exercise it. Each item names the check that would close it;
+[wayland-backend.md](wayland-backend.md) has the design behind each.
+
+- **Monitors.** Two outputs, one at 200% and one at 100%: `useScreens()`
+  lists both in left-to-right order with per-screen `scale`; the first
+  window lays out at the densest output's scale (`app.scale` is seeded
+  before any window); dragging a window between heads changes `win.output`
+  and its `available` rect once. Plug and unplug an output while running:
+  one re-render per event. GNOME at 150%: `screens[0].scale === 1.5` with
+  no 2→1.5 correction visible on the first frame. A compositor without
+  fractional-scale-v1 and `wl_surface` v6 (older wlroots, Weston): the
+  buffer scale follows the output's integer scale on `enter`.
+- **Touch.** A touchscreen, `examples/widgets.jsx`: a tap clicks, a finger
+  drags a slider live, a second finger clicks nothing; a finger on the
+  titlebar moves the window and on a corner resizes it (the touch `down`
+  serial is what `xdg_toplevel.move` gets); `onMouseDown`'s
+  `nativeEvent.pointerType === 'touch'`.
+- **Tablet.** A pen: hovering shows the arrow (I-beam over text), the tip
+  clicks and drags, the side button is button 3, `nativeEvent.pressure`
+  varies, and pulling the pen away mid-press releases the control. Pads
+  (rings, strips) are accepted and ignored by design.
+- **Input methods.** An IBus engine installed (`ibus-anthy`, `ibus-libpinyin`;
+  `gsettings set org.gnome.desktop.input-sources sources
+"[('xkb','us'),('ibus','anthy')]"`, restored afterwards), `examples/form/index.jsx`
+  under `REACT_X11_WAYLAND_TRACE=1`: typing `nihongo` shows an underlined
+  preedit, Space a segment underline, Enter the committed text and one
+  `onChange`; `Ctrl+Shift+U e9 Space` exercises the same path without an
+  engine. Only the protocol half — `enter`, `enable`, `done`, `leave` —
+  could be seen here; the compositor never composed, because nothing here
+  types.
+- **Drag and drop.** A real pointer, two react-x11 processes
+  (`examples/dnd-source.jsx`, `examples/dnd-target.jsx`) and a GNOME app:
+  a file from Files onto the target, text from the source into Text Editor,
+  and a drag between the two windows of one process (`e.source ===
+'internal'`, items by reference) and of two.
+- **Other compositors.** Server-side decorations, layer-shell and
+  wlr-screencopy were validated on this machine under **sway 1.10.1** and
+  **labwc 0.8.3** (nested and headless, screenshots by grim; `capture()`
+  agreed with grim on every pixel, and the eyedropper picked the exact box
+  colour). Still to see: `ext-image-copy-capture` (written to the spec; no
+  compositor here has it — sway 1.11 / wlroots 0.19 will), KDE Plasma
+  (xdg-decoration and its own capture portal), and a dock on a compositor
+  with two outputs (`layerShell.output`).
+- **The GPU path on real hardware.** `test/wayland/context2d-gpu.test.js`
+  reads antialiased fills and stencil clips back from a render node; it
+  has run on virgl only. Intel, AMD and NVIDIA (Mesa and proprietary) each
+  want one run — the stencil arithmetic is the kind of thing a driver
+  disagrees about. And the frame-time number: `Surface.swap()` costs
+  24.5 ms here, of which ~10 ms is virgl's host round trip on `glFinish`
+  and none is the protocol layer; only bare metal says what Tier D costs.
+- **Multisampling** is designed and not built (GLES 3.0 cannot blit into a
+  multisampled framebuffer, so the target's partial repaints would become
+  textured draws); `MAX_SAMPLES` is 1 here. It needs a machine that reports
+  4 or more.
+- ~~**Bun after an `npm install`.**~~ Closed: node-x11 ships the EINTR fix
+  for `fdpass-bun.js` since x11 4.2.1
+  ([sidorares/node-x11#297](https://github.com/sidorares/node-x11/pull/297)),
+  and the lockfile resolves 4.2.3, so a fresh install no longer closes every
+  Bun example's connection ~0.3 s in.
+
+## Open questions
+
+1. **API surface.** Is the Wayland backend API-compatible-minus-features
+   (same JSX, some props inert, `<foreign>` absent) or a declared subset?
+   Current lean: same JSX, loud dev-mode warnings on inert props, feature
+   detection à la `app.capabilities`. _As built: same JSX; the X-only
+   methods are absent rather than stubbed, so the tree's own probes
+   (`wnd.setProperty?.()`, `useSupports('embedding')`) answer for it._
+2. **Where the code lives.** ntk grows `WaylandWindow` beside `Window`
+   behind the same `App`/`Drawable` contracts vs. a sibling package.
+   Current lean: inside ntk — the factory seam and the portable raster
+   half are already there. _As built: `src/wayland/` in this repository,
+   behind the same app/window contract the cocoa backend keeps; ntk is
+   still the long-term home._
+3. **Runtime floor.** Bun-only until when? Current lean: prototype through
+   Phase 2 on Bun alone; decide on the Node addon when someone needs it,
+   not before. _As built: Node works through x11-dri's `UnixSocket`
+   (uv_poll, fd passing); Bun through node-x11's `bun:ffi` transport. The
+   protocol layer stayed pure JS, having been measured not to be the
+   cost._
+4. **x11-dri's name.** Its GBM/EGL core is display-server-neutral and this
+   plan leans on it twice (GPU tier, and possibly the Node fd/xkb shims).
+   Splitting a `dri-core` out is upstream's call; noted here so the
+   dependency direction is explicit.
+5. **libxkbcommon.** `dlopen` it (compiled, but universally present on
+   Wayland systems) vs. a pure-JS keymap interpreter. Current lean:
+   dlopen — a keymap parser is the kind of code this project writes well,
+   but not before a working backend exists. _As built: the pure-JS parser
+   (`xkb.js`), against the compositor's own keymap text; no libxkbcommon._
+
+## References
+
+- [The Wayland Book](https://wayland-book.com/) — the tour worth reading
+  end to end.
+- [Protocol and model of operation](https://wayland.freedesktop.org/docs/book/Protocol.html) —
+  the wire format, normatively.
+- [wayland.app](https://wayland.app/protocols/) — every protocol, browsable;
+  start with [xdg-shell](https://wayland.app/protocols/xdg-shell).
+- [wayland.xml](https://gitlab.freedesktop.org/wayland/wayland/-/blob/main/protocol/wayland.xml)
+  and [wayland-protocols](https://gitlab.freedesktop.org/wayland/wayland-protocols) —
+  the codegen inputs.
+- [Making wl_shm fast](https://zamundaaa.github.io/wayland/2026/05/06/making-wl-shm-fast.html) —
+  the page-alignment contract this plan adopts.
+- [node-wayland-client](https://github.com/sdumetz/node-wayland-client),
+  [westfield](https://github.com/udevbe/westfield) — prior art.
+- [node-x11#290](https://github.com/sidorares/node-x11/pull/290),
+  [nodejs/node#53391](https://github.com/nodejs/node/issues/53391) — the
+  fd story.
+- [x11-dri#19](https://github.com/sidorares/node-x11-dri/issues/19),
+  [x11-dri#20](https://github.com/sidorares/node-x11-dri/issues/20) — filed
+  from this research.
+- [NanoVG](https://github.com/memononen/nanovg) — the GPU-2d shape Tier D
+  follows; [CanvasKit](https://skia.org/docs/user/modules/canvaskit/),
+  [tiny-skia](https://github.com/linebender/tiny-skia),
+  [skia-canvas](https://github.com/samizdatco/skia-canvas) — Tiers B/C.