react-x11 2.51.0 → 2.52.0

package/docs/remote.md

@@ -0,0 +1,223 @@
+# Remote display
+
+This is the case the architecture is categorically better at, and the one
+nothing else on the page has told you about.
+
+A react-x11 app **draws over the wire**. It does not render pixels and ship
+them; it sends X11 drawing requests — rectangles, glyph runs, composites —
+and the X server on the far end turns them into pixels. So "running the app
+somewhere else" is not a feature bolted on top. It is what the protocol is,
+and the program does not know the difference.
+
+```sh
+ssh -X buildbox
+npm start          # the window opens on your desktop
+```
+
+Nothing in the app changes. No VNC, no browser, no streaming daemon, no port
+to forward, no second copy of the UI.
+
+**This is the X11 backend**, and it is the reason X11 stays the flagship
+target rather than becoming the legacy one: the Cocoa, win32 and Wayland
+backends have no wire at all, so nothing on this page applies to them. That
+matters in one specific case — **an app running on a Mac or on Windows and
+drawing somewhere else**. `$DISPLAY` in the environment does not choose the
+backend there; `backend: 'auto'` sees darwin and picks Cocoa, or win32 and
+picks the win32 backend, and the window opens on the local machine. Say
+which you want:
+
+```sh
+REACT_X11_BACKEND=x11 DISPLAY=thin-client:0 npm start
+```
+
+`createRoot({ display: … })` or `createRoot({ stream: … })` also settle it —
+naming an X endpoint in code _is_ choosing X11, because an ignored
+connection option would be worse than either answer. An app running on Linux
+and drawing to a Mac's XQuartz is not affected: both ends are X11 already.
+
+## What it costs, measured
+
+The honest comparison is with pixel streaming (VNC, RDP, a
+`--remote-debugging` browser), because that is what people reach for
+instead. The trade is bytes-per-frame against round-trips-per-interaction.
+
+From `scripts/bench/baseline.json`, which measures against node-x11's
+in-process server — so these are exact protocol costs, not estimates:
+
+| scenario                           | requests | bytes out | replies | stalls |
+| ---------------------------------- | -------- | --------- | ------- | ------ |
+| mount: a window, 40 boxes + labels | 110      | 4.2 kB    | 32      | 0      |
+| 50 filled rounded boxes            | 122      | 6.6 kB    | 7       | 0      |
+| a paragraph of text                | 39       | 6.0 kB    | 7       | 0      |
+| 10 wheel notches over 500 rows     | 224      | 11.2 kB   | 22      | 4      |
+| 5 drag steps of a card of widgets  | 72       | 4.3 kB    | 11      | 0      |
+
+**A whole window appears for about four kilobytes.** A single 1280×800 frame
+of VNC, even well compressed, is tens to hundreds of kilobytes, and it is
+sent again every time anything moves. Scrolling a 500-row table ten notches
+costs 11 kB here because only the damaged strip is redrawn (the
+[scroll-blit path](../AGENTS.md), issue #138); the same scroll under pixel
+streaming is ten full frames. Dragging a card with a background of its own
+is the same trade: each step copies the card where it went and draws the
+strip it uncovered, so its widgets are not drawn again
+([extending.md](extending.md#an-element-that-covers-its-box), issue #681) —
+the five steps in the table would be 24 kB drawn.
+
+What react-x11 pays instead is **latency sensitivity**. Bandwidth is not the
+scarce resource on a link like this — round trips are. A request that waits
+for a reply stalls the pipeline for a full RTT, so on a 60 ms link every
+reply is 60 ms of nothing.
+
+The last two columns are how that is watched, and the difference between
+them is the whole point. `replies` counts requests that carry an answer;
+`stalls` counts the ones whose reply arrived with **nothing pipelined behind
+them** — the request was the last thing sent, so the connection really did
+sit idle for a round trip. A pipelined reply costs a reply and no time: the
+mount's 32 are almost all `InternAtom`, fired off together while the window
+is built, and it stalls on none of them. (The bench's own `settle()` fences
+are a fixed floor in that column, so read growth rather than the absolute
+number.)
+
+So the rule — "avoid round trips", rule 4 in
+[AGENTS.md](../AGENTS.md#protocol-efficiency) — is really "avoid _blocking_
+round trips", which is why atoms, geometry and glyph pages are cached rather
+than re-asked, and why `stalls` is the column to watch on a slow link.
+`npm run bench -- --hotspots` attributes them, request by request.
+
+Rules of thumb, from the shape of the protocol rather than from a benchmark
+we have not run:
+
+- **Under ~20 ms RTT** (a LAN, a nearby VPS): indistinguishable from local.
+- **20–80 ms** (a continent away): typing and scrolling stay responsive;
+  window mapping and font setup have a visible beat.
+- **Above ~150 ms** or on a lossy link: X11's chattiness starts to show, and
+  a pixel-streaming protocol designed for high latency will feel better.
+  This is not a react-x11 limitation, it is X11's, and it is the honest place
+  to say so.
+
+`unverified:` those bands are reasoning from the request/reply counts above,
+not measurements over a shaped link. Measuring them properly means `tc
+netem` between two hosts; if you do it, the numbers belong in this table.
+
+## `ssh -X` and `ssh -Y`
+
+`-X` runs your app as an **untrusted** X client. `-Y` runs it trusted, which
+turns the restrictions off. They are not "the one that works" and "the one
+that does not":
+
+|                                    | `-X` (untrusted) | `-Y` (trusted) |
+| ---------------------------------- | ---------------- | -------------- |
+| read other windows' pixels         | no               | yes            |
+| grab the keyboard, record input    | no               | yes            |
+| take the clipboard from other apps | restricted       | yes            |
+| your app's own windows             | fine             | fine           |
+
+**Prefer `-X`.** react-x11 should work under it — it draws into windows it
+created, which is what untrusted mode is for. If something does not, that is
+a bug worth filing rather than a reason to reach for `-Y`. Most toolkits'
+documentation says "use `-Y` if `-X` misbehaves"; that advice hands every
+program on the remote host the ability to read your screen and log your
+keystrokes.
+
+### The failure that looks like a crash
+
+An untrusted `-X` cookie **expires**. OpenSSH's `ForwardX11Timeout` defaults
+to 20 minutes; after that the connection is refused and your app dies
+mid-session with a connection reset — no warning, no message that mentions
+X11, and it happens long enough after startup that nobody connects the two.
+
+```sh
+# in ~/.ssh/config
+Host buildbox
+  ForwardX11 yes
+  ForwardX11Trusted no
+  ForwardX11Timeout 8h        # or 0 for no expiry
+```
+
+If a long-running app dies after roughly twenty minutes and
+`onDisconnect(reason)` reports `'error'`, this is the first thing to check.
+react-x11 tells you it happened, and nothing more —
+[a reconnect is not a reconnect](README.md):
+every window id, pixmap, glyph set and font died with the connection.
+
+## `DISPLAY=host:0` — and why not
+
+The other way to reach a remote display is to point `DISPLAY` straight at it
+and open port 6000. Do not:
+
+- The connection is **plaintext**. Every keystroke, every glyph you draw and
+  the authentication cookie itself cross the network in the clear.
+- Making it work usually means `xhost +`, which turns off access control for
+  _everyone_, or `xhost +host`, which trusts every user on that host.
+- Most X servers ship with TCP listening disabled now, so it takes
+  deliberate work to open the hole.
+
+`ssh -X` gives you the same thing, encrypted, authenticated per-session, and
+with no listening port. Use it. If you genuinely need a raw display
+connection — a lab network, a kiosk — carry the cookie explicitly with
+`xauth` and never with `xhost` (see [security.md](security.md)).
+
+## The other X servers
+
+"An X server" is broader than "a Linux desktop":
+
+| where                         | what runs                                                                                                                                    |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| Linux desktop                 | X.Org, or **Xwayland** — see below                                                                                                           |
+| macOS                         | [XQuartz](https://www.xquartz.org). `ssh -X` from Terminal starts it for you                                                                 |
+| Windows                       | VcXsrv, Xming, or an X server inside WSLg                                                                                                    |
+| headless CI                   | `Xvfb :99 -screen 0 1280x800x24`                                                                                                             |
+| a disposable screen           | `Xephyr :10 -screen 1200x800` — a window on your desktop that _is_ a display. What the [window-manager example](../examples/README.md) needs |
+| a session you can reattach to | `Xvnc` / TigerVNC, or **Xpra**, which is X11-native and can detach and reattach a running app                                                |
+| no display at all             | node-x11's in-process server — [testing.md](testing.md)                                                                                      |
+
+**Xwayland: yes.** On a Wayland desktop, X11 clients run under Xwayland, and
+react-x11 is an ordinary X11 client there. Everything in this documentation
+applies. Some window-manager interactions are thinner (Xwayland brokers what
+the compositor is willing to expose), and `WM_TRANSIENT_FOR` and the
+`_NET_WM_STATE` work are among the things that survive the trip — see
+[elements.md](elements.md#transientfor--a-window-that-belongs-to-another).
+
+**Native Wayland: not remotely**, and the reason is not effort. Wayland has
+no drawing protocol. A Wayland client allocates a buffer, renders pixels into
+it _itself_, and hands the compositor a handle — there is nothing to send over
+a wire, and no server-side rendering to ask for. The entire premise of this
+page, that drawing crosses the connection, does not exist there. The Wayland
+backend (`backend: 'wayland'`, [wayland-backend.md](wayland-backend.md)) is
+therefore a different program under the same API — it rasterizes locally —
+which is why it is opt-in only and never what `'auto'` picks: on Linux the
+default stays X11, and with it everything on this page.
+
+**XQuartz notes**, since it is the most common macOS path:
+
+- The window manager is quartz-wm, which has the thinnest EWMH support in
+  the stack. It does not advertise `_NET_WM_STATE_ABOVE`, so `alwaysOnTop`
+  falls back to Apple-WM window levels ([elements.md](elements.md)).
+- Put `/opt/X11/bin` first on `PATH`. Font family resolution shells out to
+  `fc-match`, and Homebrew's fontconfig — which is usually found first —
+  ships no macOS system-font aliases, so `sans-serif` resolves to a CJK
+  face. Issue [#86](https://github.com/sidorares/react-x11/issues/86).
+
+## Making it feel better
+
+Everything the renderer does to be cheap locally pays double here, because
+each saved request is a saved trip across the link:
+
+- Keep repaints **bounded**. `REACT_X11_DEBUG_PAINT=full` warns, with a
+  reason and a stack, on any silent full-window repaint —
+  [debugging.md](debugging.md). A full repaint is the difference between
+  4 kB and 40 on every frame.
+- `REACT_X11_TRACE=summary` prints the request and byte counts for a live
+  app, so you can see what a given interaction actually costs on the wire
+  before blaming the link.
+- `ssh -C` compresses. X11 traffic is highly compressible — repeated
+  drawing requests, text, glyph data — and on a slow link it is usually
+  worth it.
+- Prefer one long-lived connection to many short ones: connection setup is
+  several round trips of its own, plus the font and atom warm-up.
+- **Drags across applications are round-trip heavy**, because finding the
+  foreign window under the pointer means asking the server, per pointer
+  position. Dragging _within_ the app costs nothing extra — it never
+  touches the wire — and a drop target that answers with `e.freeze()` stops
+  the source asking while the pointer stays inside it. See
+  [drag-and-drop.md](drag-and-drop.md).

package/docs/scale.md

@@ -0,0 +1,339 @@
+# Display scale
+
+Every length in react-x11 is a **logical pixel**: a unit sized so that
+`fontSize: 14` is comfortably readable at the distance the display is
+actually viewed from. On the panels of the last decade one logical pixel is
+two device pixels — or 1.5, or 1.25 — and the renderer multiplies exactly
+once, on the way to the server. An app says nothing and gets a UI the same
+physical size on a 2013 monitor and a retina laptop.
+
+```jsx
+const root = await createRoot();               // scale: 'auto' is the default
+const root = await createRoot({ scale: 2 });   // pin it
+REACT_X11_SCALE=1.5 node app.js                // the user outranks everybody
+```
+
+```jsx
+import { useScale } from 'react-x11';
+const scale = useScale(); // 1, 2, 1.5... static for the life of the root
+```
+
+## What is logical and what is device
+
+**Logical — everything application code touches:**
+
+- every style length (`width`, `padding`, `fontSize`, `borderRadius`, the
+  lengths inside `boxShadow` and gradient stops, `hitSlop`…)
+- window geometry props (`width`, `height`, `x`, `y`, `minWidth`…) and the
+  `onResize` payload
+- event coordinates: `ev.x`/`ev.y`/`ev.localX`/`ev.localY`, wheel
+  `deltaX`/`deltaY`, drag `screenX`/`screenY`
+- `getClientRects()`, `measure()`, `useScreens()` rects,
+  `anchorRect`/`centerRect`/`anchorArea`
+- the scroll surface: `scrollTo()`/`scrollBy()` arguments, `onScroll` and
+  `onViewport` payloads
+- the theme: `DefaultTheme.fontSize` is 14 and stays 14
+
+**Device — the renderer's internals and the deliberate escape hatches:**
+
+- `node.abs`, yoga's computed layout, everything painted
+- `node.scrollX`/`scrollY`/`contentWidth`/`contentHeight` read directly off
+  a ref (positions in the rendered surface; use the `onScroll` payload for
+  logical math)
+- `<canvas onDraw>`: the browser's own canvas contract — the box arrives in
+  device pixels and the payload carries `scale`, so detail is drawn on the
+  real grid. Deliberately **not** a `ctx.scale()`: ntk positions glyphs
+  through the transform but sizes them from the font, so a scaled transform
+  would move an app's `fillText` without growing it — and it would knock
+  every fill off ntk's server-side fast paths besides.
+- a registered element's `paint()` and `hitTest()` (see
+  [extending.md](extending.md)): `this.style` and `this.abs` arrive already
+  device, and so are `paintDamage()`, the rects handed to `invalidate` and
+  `scrollContents` and the rects of an a11y scene; synthetic events are
+  logical, and `this.scale` is on every node for the constants that never
+  pass through a style and the event coordinate on its way to `abs`.
+
+Fonts are the point of the whole exercise: a `fontSize: 14` at scale 2 is
+shaped, measured and rasterized at 28px. Text on a retina panel is _sharper_,
+not bigger-blurrier — the same reason every native toolkit renders this way
+instead of transform-scaling a 1x picture.
+
+"Logical" is per node rather than per window as soon as a `scale` prop is in
+the tree: everything in the first list is divided by the scale of the node
+it is about, which is the display's until an enclosing `scale` says
+otherwise. See "A subtree of its own" below.
+
+## How `'auto'` decides
+
+X11 never grew a scale protocol, so the answer is scattered across four
+generations of convention. The ladder consults each rung only when the ones
+above said nothing, ordered by "who is closest to a human having decided":
+
+1. **Environment** — `REACT_X11_SCALE` (ours, wins over everything including
+   an explicit `scale:` number — it is the accessibility escape hatch), then
+   `GDK_SCALE`, then `QT_SCALE_FACTOR`. The user already told their other
+   toolkits; an app of ours on the same desktop should agree.
+2. **XSETTINGS** — `Gdk/WindowScalingFactor` when it is 2+, then `Xft/DPI`
+   (in 1024ths of a dpi on the wire; a daemon writing plain dpi is read
+   right too). This is what the desktop's own settings dialog writes and
+   what every GTK app on the screen is already obeying.
+3. **`RESOURCE_MANAGER`** — `Xft.dpi`, the `xrdb` convention winit,
+   Chromium and every terminal emulator read.
+4. **RandR millimetres** — the panel's physical size against its pixel
+   size, run per output, under mutter's viewing-distance model: the DPI
+   that counts as "1x" is 135 under a 20″ diagonal (a panel in your lap at
+   ~50cm) and 110 over it (across a desk). Snapped to quarter steps in
+   [1, 3]. For calibration: a 27″ 2560×1440 desk monitor computes 109dpi →
+   1x; a 27″ 4K computes 163dpi → 1.5x; a 16″ MacBook panel computes
+   255dpi → 2x, matching macOS.
+5. **The resolution class** — when the millimetres are absent or caught
+   lying, the pixel grid itself is the last signal: nothing ships as a 1x
+   panel with a grid ≥3000 wide or taller than 1600 on its short side, so
+   those are called 2x and everything else 1x. That takes in the 2560×1664
+   and 2880×1800 lids, and a VM window over any retina panel (a UTM window
+   on a 14″ MacBook is 2488×1668). Only the confident call is made without
+   physical data — 2560×1440 and 2560×1600 stay 1x on purpose, because
+   they are the commonest 1x desk monitors there are and only millimetres
+   could tell them from a 13″ retina lid.
+6. **1.**
+
+Two readings deserve their asterisks. **96 is not an answer**: `Xft.dpi: 96`
+and `Gdk/WindowScalingFactor: 1` are what daemons publish when nobody ever
+opened the dialog (xfsettingsd writes both unconditionally), so they fall
+through to the hardware instead of pinning an unconfigured 4K laptop to
+microscopic. And **millimetres are audited before they are believed**
+(`classifyMm`): zeroes, aspect-ratios-as-sizes (16×9 "millimetres"),
+physical/pixel aspect disagreement, and — the one that motivated all of
+this — virtual machines, detected by EDID vendor and model (`RHT` / "QEMU
+Monitor", VMware, VirtualBox, Parallels, Hyper-V) and by connector name
+(`Virtual-*`, `qxl`, …). `XWAYLAND*` outputs skip the hardware rung too:
+the compositor owns scaling there and publishes its decision through rung
+2, in both of its Xwayland modes.
+
+### Servers that are not describing hardware
+
+Rungs 4–5 read a panel, so they are skipped where the connection has no
+panel to describe. Two cases, both of them servers people really run:
+
+- **XQuartz**, detected by the `Apple-WM` extension. macOS composes the
+  desktop in _points_ and hands X the point space, already normalised for
+  density: a 16″ retina lid arrives as 1728×1080, a 1x monitor beside it as
+  2560×1403, and the window server scales what it is given onto whichever
+  panel the window lands on. Inferring a factor here doubles a size macOS
+  is about to double again, so the ladder answers 1x with the source
+  `xquartz` — the same exemption `XWAYLAND` gets, for the same reason.
+- **A single synthetic output covering every monitor.** XQuartz, Xvfb,
+  x11vnc and TigerVNC, Xephyr and pre-RandR drivers answer the output walk
+  with one output — usually named `default`, always without millimetres —
+  whose CRTC is the _union_ of the desktop. Two 2560×1440 monitors union to
+  5120×1440, which rung 5 reads as a retina panel; the machine this was
+  found on unioned a retina lid and two 1x monitors into 5120×2520 and drew
+  every widget at double size. Xinerama reports those heads separately, so
+  more heads than outputs retires rung 5 (`isUnionOutput`). Rung 4 survives
+  it — credible millimetres describe real glass however the pixels were
+  divided up, which is what an `xrandr --setmonitor` split of one ultrawide
+  is.
+
+Both guards sit _below_ the configured rungs: `REACT_X11_SCALE`,
+`GDK_SCALE` and a desktop's own XSETTINGS still win, because a person who
+typed a factor outranks the platform.
+
+### The machine this was built against
+
+A 16″ MacBook panel handed 1:1 to a UTM Linux guest (XFCE, X11) defeats
+rungs 1–4 simultaneously, which is why the ladder has five:
+
+```
+core screen      3456×2168 px, "914×573mm"   → synthesized to exactly 96dpi
+XSETTINGS        Gdk/WindowScalingFactor 1, Xft/DPI 98304 (= 96·1024)
+RESOURCE_MANAGER Xft.dpi: 96                 → the never-configured default
+RandR            Virtual-1 "870×550mm"       → a 40″ panel that is 16″
+EDID             vendor RHT, model "QEMU Monitor"  → the lie, signed
+verdict          2x via the resolution class → correct
+```
+
+Every millimetre in that transcript is invented — QEMU fabricates a size
+that makes the maths land on ~100dpi — and every configured source is an
+untouched default. Run `node scripts/scale-probe.mjs` against any display
+to see the same table for it, or `REACT_X11_DEBUG_SCALE=1` in an app to
+watch the ladder resolve.
+
+## On Wayland
+
+A compositor has a scale protocol, and its answer is the display scale:
+fractional-scale-v1 where it is offered (1.25, 1.5…), else
+`wl_surface.preferred_buffer_scale`, else the integer `wl_output.scale` of
+the output a window is on. Buffers are drawn at that density, so text is
+as sharp at 1.5 as at 2. Two things still outrank it, as on X11:
+
+- **`REACT_X11_SCALE`, then `createRoot({ scale })`** pin the factor,
+  absolutely: device (buffer) pixels per logical pixel. On a compositor at
+  1x, `REACT_X11_SCALE=2` is a window twice the size drawn at full
+  resolution, not a small one stretched.
+- **The resolution class, when the compositor says 1.** A VM window over a
+  retina panel is the case: QEMU's EDID describes the guest's screen as a
+  ~100dpi monitor, mutter believes it and runs at 100%, and every app laid
+  out at the compositor's word comes up half the size it is on the host.
+  When every output is at 1x and the largest has no credible millimetres
+  (`classifyMm`) but a retina-class grid, the layout is 2x — what the X11
+  ladder answers for the same screen through Xwayland. A compositor that
+  scales any output has decided for itself (133% on that same VM is
+  someone's choice), and credible millimetres were the compositor's own
+  evidence, so both keep their answer.
+
+The frame a window draws for itself follows the compositor, not the
+layout: it is drawn at the desktop's scale, beside every other window's.
+`REACT_X11_DEBUG_SCALE=1` prints which of these answered.
+
+## Several monitors
+
+Rungs 4–5 are computed for every connected output, because a desktop with a
+retina lid and an office monitor genuinely has two answers. The **root's**
+scale — the one layout and paint use — is the primary output's (the largest,
+where nothing is flagged primary), matching what GNOME does on X11: one
+scale for the session, chosen for the display you called primary.
+
+The per-output answers ride on `useScreens()` — every entry carries its own
+`scale` — so an app that places windows can do better, and a window can be
+pinned with `createRoot({ scale })` per root. What this deliberately does
+not do is re-scale a window as it is dragged between mismatched monitors:
+X11 has one coordinate space and no per-window scale protocol, so that move
+is a resize the window manager fights mid-drag; Qt is the one toolkit that
+tries it, and "chosen at creation, static after" is the behaviour of
+everything else on this window system.
+
+Static-at-startup is the other honest limitation: a mid-session change of
+`Xft.dpi` or a monitor swap does not re-scale running windows. Rare enough
+that GTK3 apps mostly share it; restart the app.
+
+## A subtree of its own
+
+The display scale is one number for the whole window. `scale` on an element
+is a second factor for one **subtree** of it:
+
+```jsx
+<box scale={zoom} style={{ width: w / zoom, height: h / zoom }}>
+  <NodeBody /> // written in plain logical pixels, unaware of the zoom
+</box>
+```
+
+The semantics are CSS's `zoom`, not a transform:
+
+- A node's **effective scale** is its parent's times its own `scale` prop,
+  so nested props multiply and the display scale is the floor they multiply.
+  `node.scale` is that number, and every path that already asked for it —
+  `scaleResolvedStyle` at the end of the style funnel, the caret and
+  scrollbar constants, shadows and gradients, a registered element's own
+  `paint()` — follows with no second mechanism.
+- **The node's own style scales too.** `scale={2}` on a box with
+  `padding: 8` gets 16 device pixels of padding, not 8 with bigger children
+  inside it. That is what makes the caller's job the one-liner above: divide
+  the size you want the box to occupy by the zoom, and write everything
+  inside it at 1x.
+- **Text is shaped at the size it is drawn at.** A `fontSize: 14` inside
+  `scale={2}` is shaped, measured and rasterized at 28 — the same thing the
+  display scale does, for the same reason. A zoomed-in graph is not a
+  stretched screenshot of a zoomed-out one.
+- **Yoga lays out the scaled numbers** like any others, so a zoomed subtree
+  wraps, flexes and measures its content floors at the size it is drawn.
+
+What it is for: an element that owns a viewport — a graph pane, a canvas, a
+map — and mounts application content inside it. The pane draws its own
+world, and the React subtree beside it has to follow the same zoom;
+`ctx.scale()` cannot do that here (see "Why multiply values instead of
+transforming the context" below) and a layer transform on the Cocoa
+presenter would draw a zoomed body whose hit testing still lived at the
+unzoomed rects.
+
+### What a boundary costs
+
+**Events are in the target's unit.** `ev.x`, `ev.y`, `localX`/`localY` and
+`getClientRects()` on a node inside a zoomed subtree are all divided by
+_that node's_ scale, so they agree with each other and with the styles it
+was written in — a handler inside the subtree needs to know nothing. The
+trade-off is CSS `zoom`'s: a handler on an **unzoomed ancestor** reads a
+coordinate in the zoomed descendant's unit, because the target is what
+decides. When a pane needs its own coordinates for a hit that landed inside
+the content it hosts, `ev.nativeEvent` is the way back — device pixels of
+the window, which `/ node.scale` converts to whichever unit is wanted.
+`screenX`/`screenY` are unaffected: they are desktop coordinates, and the
+desktop has one scale.
+
+A wheel notch scrolls `48` of the target's logical pixels, so content under
+the pointer travels the distance the zoom says it should.
+
+**A real X window is its own root.** `<window>` and `<popup>` take no
+`scale` prop and ignore an enclosing one: their geometry is the server's, a
+window manager sees no zoom, and a menu opened from a zoomed card should
+come up at the size the rest of the app's menus are. `<glarea>` and
+`<foreign>` do inherit — their boxes are laid out by the parent like any
+other child's.
+
+**Quantise a gesture-driven zoom.** Every distinct factor is a distinct
+font size to shape and cache, so a wheel handler feeding the raw accumulator
+into `scale` makes a new set of glyphs per frame. Round to a step — 5%, or
+a ladder of preset zooms — and the cache does its job.
+
+## Prior art, and where this sits
+
+| Toolkit                          | X11 sources, in order                                                                                     | Notes                                                                                                             |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| GTK 3/4                          | `GDK_SCALE` env; XSETTINGS `Gdk/WindowScalingFactor`                                                      | integer only; fonts via `Xft/DPI`                                                                                 |
+| Qt 5/6                           | `QT_SCALE_FACTOR`, `QT_SCREEN_SCALE_FACTORS`; per-screen logical DPI (`Xft.dpi`), physical DPI from RandR | the only per-screen attempt on X11                                                                                |
+| winit                            | `WINIT_X11_SCALE_FACTOR`; `Xft.dpi`; RandR mm                                                             | mm path famously burned by 1×1mm and VM EDIDs ([winit#1983](https://github.com/rust-windowing/winit/issues/1983)) |
+| Chromium/Electron                | `Xft.dpi` via XSETTINGS then xrdb; `GDK_SCALE`                                                            | never trusts RandR mm                                                                                             |
+| SDL 2/3                          | `Xft.dpi` only                                                                                            | 1x on every unconfigured desktop                                                                                  |
+| mutter (the config UI's default) | per-monitor mm under the 135/110-dpi viewing-distance model                                               | the model rung 4 adopts, constants and all                                                                        |
+
+The composition is the contribution: desktop configuration first (rungs
+1–3, which is where Chromium/SDL stop — correct on configured desktops,
+tiny on unconfigured HiDPI ones), mutter's perceptual model where the
+hardware is honest (which is where winit's mm math stops — right until an
+EDID lies), and the resolution class where it is not (which nobody else
+has, and which is the only rung that survives a VM).
+
+## Design notes
+
+**Why multiply values instead of transforming the context.** Two hard
+reasons, both ntk's. Its 2d context batches solid fills into server-side
+`Render.FillRectangles` and takes similar fast paths for strokes, rounded
+rects and glyph runs — all gated on an identity transform, so a frame-wide
+`ctx.scale(2,2)` would rasterize every box in the UI as polygons. And its
+text model sizes glyphs from the font while only _positioning_ them through
+the transform, so scaled-transform text comes out moved but not grown.
+Multiplying at the style funnel instead means paint code, damage rects, the
+scroll blit and the paint cache all keep working in integer device pixels
+with the transforms they always had. (`paintcache.js` even guards against
+the other choice: a non-identity CTM disables it entirely.)
+
+**Where the multiply lives.** One place for styles —
+`scaleResolvedStyle()`, at the end of the style funnel in `_syncStyle`, so
+state blocks, size queries and the flex shorthand all still think in the
+logical pixels the app wrote. One place for the theme's font size — the
+root branch of `inheritedTextStyle`, because descendants inherit an
+already-resolved size and any second multiply would compound. One place for
+window geometry (`scaleWindowGeometry`), one per string-parsed decoration
+(`shadowSpecs`/`gradientSpec`, whose parses are memoized on the raw string
+so the scale rides into the memo key), and division at each app-facing
+egress (`SyntheticEvent`, `getClientRects`, `onScroll`, `useScreens`…).
+`yoga` needs no `pointScaleFactor` games: layout runs directly in device
+pixels and its ordinary whole-pixel rounding is what keeps a 1-logical-px
+border crisp at 1.5x.
+
+**Fractional scales** work end to end (`1.25`, `1.5`, quarter steps from
+the ladder), with the usual X11 caveat: a 1-logical-px hairline at 1.25x is
+1 or 2 device pixels depending on where it lands. Integer scales have no
+such seams.
+
+**What tests see.** The headless harnesses resolve to exactly 1 — a mock
+app has no display to ask — so every geometry assertion in the suite means
+its numbers literally. `createRoot({ app, scale: 2 })` opts a test in, and
+so does `renderX11(element, { scale: 2 })` from `react-x11/test`;
+`test/scale-render.test.js` is the boundary contract pinned as tests.
+`setScaleForTests()` (from `src/scale.js`) pins a factor without a
+connection.
+
+**Known costs.** The paint cache's per-item budget is device pixels, so at
+2x a widget occupies 4× the budget it did — icons and checkboxes still fit
+comfortably. Damage rects, protocol traffic and backing stores scale the
+same way any HiDPI surface does.