react-x11 2.51.0 → 2.52.0

package/docs/gl.md

@@ -0,0 +1,170 @@
+# 3D: `<glarea>` and the three ways underneath it
+
+react-x11 gives you a **GL surface in the layout** and nothing above it. A
+scene graph — meshes, materials, lights, post-processing — is
+[`@react-x11/components/three`](ecosystem.md), which brings its own
+reconciler and renders through the surface described here.
+
+```jsx
+<glarea
+  style={{ flexGrow: 1 }}
+  clearColor="#0b1021"
+  frameLoop="always"
+  onCreated={(gl) => gl.Enable(gl.DEPTH_TEST)}
+  onDraw={(gl, { width, height }) => {
+    /* one frame */
+  }}
+/>
+```
+
+`examples/viewer3d.jsx` is the worked example: a model viewer that orbits,
+and the display-list discipline the indirect backend demands.
+
+## The three ways
+
+`<glarea>` and `onDraw` are the same everywhere. What is underneath is not:
+these are different APIs, not three spellings of one, and which one a
+connection has decides what `onDraw` can do.
+
+|                | **direct** (X11)                                                                                                                                                                                                       | **indirect** (X11)                                                 | **Cocoa**                                                                                    |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| how it draws   | OpenGL ES 2 on the GPU, in two flavors: on Linux frames reach the server as dma-buf descriptors over DRI3 + Present, and on macOS/XQuartz the server exports the window's surface over Apple-DRI and CGL draws into it | GL commands encoded into the X connection                          | CGL — OpenGL 4.1 core on Metal — into IOSurface-backed framebuffers, presented as a sublayer |
+| shaders        | **yes**, GLSL ES 1.00                                                                                                                                                                                                  | none; the protocol encodes no shader objects                       | **yes**                                                                                      |
+| render targets | **yes** — framebuffer objects                                                                                                                                                                                          | none; the protocol encodes no framebuffer objects                  | **yes** — it draws into one                                                                  |
+| geometry       | vertex buffers on the GPU                                                                                                                                                                                              | immediate mode compiled into display lists                         | vertex buffers on the GPU                                                                    |
+| lighting       | per fragment                                                                                                                                                                                                           | per vertex                                                         | per fragment                                                                                 |
+| cost per frame | one Present request                                                                                                                                                                                                    | matrices, material state and one `CallList` per mesh               | a swap between two targets; the WindowServer composites                                      |
+| where it runs  | a local connection, plus ntk's optional `x11-dri` addon: a Linux server with DRI3, or macOS/XQuartz with Apple-DRI (ntk 8.4.0)                                                                                         | any server that allows indirect contexts, including over a network | any Mac, on the Cocoa backend — it needs the same optional `x11-dri` addon and nothing else  |
+
+The Cocoa column is the X11 direct path with the X-specific half swapped
+out: the same `x11-dri` CGL context and the same WebGL-shaped `gl` table,
+but instead of attaching to a surface an X server exported, frames render
+into IOSurfaces and present by handing the surface's id to the area's own
+`CALayer`. `glPolicy: 'indirect'` is the one setting that is an error there
+and says so — GLX is a protocol, and there is no server to speak it to.
+
+The two other backends have no column because they hand `onDraw` the same
+direct API the Cocoa one does, and report `gl.backend === 'direct'` too. On
+**win32** a `<glarea>` is a WGL core context drawing into a Direct3D texture
+that is copied into a composition swap chain under the window's own visual
+([windows-gl.md](windows-gl.md)), so it composites with the window's alpha
+where an X11 surface does not. On **Wayland** it is not a surface of its own
+at all: it is a rectangle of the window's backing target, drawn by the
+window's own GLES context between the tree's 2D paint and its children's
+panes (`src/wayland/glarea.js`).
+
+On X11 the default is indirect, because it is what react-x11 has always
+used. Turn the other on per app:
+
+```jsx
+const root = await createRoot({ glPolicy: 'auto' });
+```
+
+`'auto'` uses direct where it is available and indirect otherwise, which is
+usually what you want: most modern desktops **refuse** indirect GLX — Xorg
+1.17 and later, and Xwayland, ship with it off — and those are exactly the
+machines where direct works. `'direct'` and `'off'` are the strict forms, and
+`'indirect'` is the default. One run can be switched without touching code:
+
+```sh
+NTK_GL_POLICY=direct npm start
+```
+
+Which flavor a connection got is `app.glCapabilities().flavor` — `'dri3'` or
+`'appledri'`. Both spell the context the same way, so nothing above the
+policy has to branch on it; it is worth reading when a machine that should
+have direct does not.
+
+Everything about how the backend is chosen and why it might be unavailable —
+the `GLError` codes, `app.glCapabilities()`, the addon — is ntk's, and is
+documented in [ntk's context-gles.md](https://github.com/sidorares/ntk/blob/master/docs/context-gles.md).
+
+`npm run labs:direct-gl` is the shader path on a real display, and reports
+both the flavor and which backend actually drew.
+
+## Raw GL through `onDraw`
+
+`onDraw(gl, { width, height, node })` hands you the context itself, and
+there are two spellings of GL to write against — camelCase ES 2 against
+PascalCase OpenGL 1.x. Nothing translates between them. Branch on
+`gl.backend`, which is `'direct'` or `'indirect'`; the Cocoa path reports
+`'direct'`, because that is the API it hands you:
+
+```jsx
+<glarea
+  onDraw={(gl) => {
+    if (gl.backend === 'direct') gl.clear(gl.COLOR_BUFFER_BIT);
+    else gl.Clear(gl.COLOR_BUFFER_BIT);
+  }}
+/>
+```
+
+Code written against one spelling will not run on the other, which is why
+the default X11 policy does not switch under an app that never asked for it
+— and why `examples/viewer3d.jsx` reports which one it got rather than
+pretending it can draw on both. It also means a scene written for the direct
+API runs unchanged on the Cocoa backend, and one written for indirect GLX
+does not run there at all.
+
+**On the indirect backend, geometry belongs in a display list.** Every
+immediate-mode vertex is a command on the wire, so a mesh re-sent per frame
+costs kilobytes per frame while a compiled list costs one `CallList`. Names
+are yours to choose — `GenLists` is a round trip, and this is the backend
+where round trips are the thing to avoid.
+
+## Input
+
+The pointer over a surface is the tree's, on every backend: `onMouseDown`,
+`onMouseMove`, `onMouseUp`, `onClick`, `onWheel` and the rest fire at the
+`<glarea>` — or at a child drawn over it (below) — and bubble, with
+`ev.localX`/`localY` measured from the target's corner, which is what a
+scene picks with. Nothing needs to listen on the surface's own window, and
+nothing should: on X11 a listener there takes the event away from the tree
+([elements.md](elements.md#glarea) says why).
+
+## 2D over the surface
+
+A `<glarea>`'s children are drawn above it — a legend, a toolbar, a label
+over the scene — laid out in its box and hit before it. They are ordinary
+elements. Core paints them on panes stacked over the surface, from the
+window's own frame. On the Cocoa backend Core Animation composites the
+panes with the GL frame, translucency and all. On X11 a pane is an opaque
+child window, so what a child leaves unpainted shows the surface's
+`clearColor` ([elements.md](elements.md#glarea) has the table).
+`useSupports('glOverlay')` asks whether a connection draws them;
+`examples/labs/gl-overlay.jsx` runs one on both backends.
+
+The answer is no on XQuartz. The macOS window server composites every GL
+surface there above everything the X server draws, so nothing can be drawn
+over one. The children are laid out and not drawn, and a development build
+warns once. On macOS the Cocoa backend is the one that composites a HUD
+over GL.
+
+So a HUD is not GL's business: its text is set by the app's own text
+engine, its controls take their own input, and nothing is rasterized into a
+texture.
+
+## When there is no surface at all
+
+`onError(err)` fires when no GL context could be made: no GLX, indirect
+disabled, no matching visual. `err.code` is one of ntk's `GLXError` values,
+`GLX_INDIRECT_DISABLED` being the usual one. Without a handler the failure is
+a console warning and the element draws nothing, which looks like a bug in
+your scene rather than a fact about the machine — so handle it and say what
+the reader can do.
+
+## Testing
+
+A GL app is tested on **what it emits**, not on pixels — which is also the
+only option, because GL renders where `GetImage` cannot read it (see
+[glx.md](glx.md)):
+
+- `test/glarea.test.js` drives node-x11's in-process X server with its GLX
+  emulator registered, so a frame's GL calls land on a `RecordingBackend`.
+  No display, no GPU, no addon.
+- `test/viewer3d.test.js` does the same for the example, and says in its
+  header which claim that harness cannot see and where it is measured
+  instead.
+
+See also [glx.md](glx.md) for the indirect backend's design, and what its
+transport can never do.

package/docs/globalmenu.md

@@ -0,0 +1,278 @@
+# The global menu
+
+Some desktops put an application's menu bar in their own panel rather than in
+its window — Unity's design, still shipped by KDE Plasma's Application Menu
+widget, by `vala-panel-appmenu`, and by several GNOME extensions. On one of
+those, an app that draws its own menu bar is drawing a second one.
+
+react-x11 notices and hands the menu over. There is **nothing to configure and
+nothing to call**:
+
+```jsx
+import { MenuBar } from 'react-x11';
+
+<MenuBar
+  menus={[
+    {
+      label: 'File',
+      items: [
+        { label: 'New', shortcut: [['Control', 'N']], onSelect: newFile },
+        { type: 'separator' },
+        { label: 'Save As…', enabled: false },
+      ],
+    },
+  ]}
+/>;
+```
+
+That is the whole of it, and it is the same line every time. Where the
+platform has somewhere to put a menu, `MenuBar` renders nothing and the
+platform shows this one; where it does not, `MenuBar` draws the bar itself,
+exactly as before.
+
+| where the menu goes                                    | when                                                                                  |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| **the macOS menu bar**, at the top of the screen       | the Cocoa backend, always                                                             |
+| **the desktop's panel**, over `com.canonical.dbusmenu` | a panel is running one of the applets above                                           |
+| **the window**, drawn by `MenuBar`                     | everything else — a stock GNOME session, XQuartz, an ssh session, a bare `startx`, CI |
+
+The rest of this page is about the middle row, which is the one with a
+protocol in it. The macOS row is
+[macos.md §Menus](macos.md#menus-the-global-menu-finally-at-home): the
+adapter is `src/cocoa/globalmenu.js`, it consumes the same `menus` array
+through the same snapshot machinery, and because a menu bar is a platform
+constant rather than a service that may or may not be running, it takes the
+menu the moment it is installed — the drawn fallback never renders there.
+
+## The item vocabulary is the protocol's
+
+`menus` is a plain data prop rather than JSX children, and its item shape is
+`com.canonical.dbusmenu`'s. That is what makes the rest work: **the identical
+array serialises**, so there is one authoring model rather than a drawn one and
+an exported one that drift apart.
+
+| property                   | meaning                                                     |
+| -------------------------- | ----------------------------------------------------------- |
+| `label`                    | the row's text                                              |
+| `type`                     | `'separator'` draws a rule; absent means an ordinary row    |
+| `items`                    | a submenu                                                   |
+| `enabled`                  | defaults to `true`; `false` dims the row and makes it inert |
+| `visible`                  | defaults to `true`; `false` removes it                      |
+| `shortcut`                 | `[['Control', 'S']]` — drawn, exported **and bound**        |
+| `toggleType`/`toggleState` | `'checkmark'` or `'radio'`, and `0` / `1` / `-1`            |
+| `iconName`                 | an icon-theme name, for the panel's menu                    |
+| `iconData`                 | raw PNG bytes, for an icon that is not in a theme           |
+| `disposition`              | `'normal'`, `'informative'`, `'warning'`, `'alert'`         |
+| `onSelect(item)`           | runs whichever menu the click came from                     |
+| `key`                      | identity, when the label is not stable                      |
+
+`toggleState` has **three** values, not two: `-1` is _indeterminate_ — a "Bold"
+that is on for part of the selection — and it draws as a dash rather than as
+unchecked, because "off" is a different claim from "it depends".
+
+`icon` is the one thing that does not cross the bus. It is a react-x11 drawing
+callback ([components.md](components.md#menubar--contextmenu)) and the desktop
+cannot call a function, so an item that wants an icon in both menus carries
+`icon` for ours and `iconName` for the panel's.
+
+### Shortcuts are a list, not a string
+
+```js
+shortcut: [['Control', 'S']];
+```
+
+The outer array is a list of _alternatives_; each inner one is modifier tokens
+(`Control`, `Alt`, `Shift`, `Super`) ending in the key. Only the first is
+drawn — a row has one shortcut column.
+
+**On macOS, `Control` means ⌘.** A cross-platform app writes its shortcuts
+in the primary modifier, and the Mac's primary modifier is Command, not its
+own ⌃ — so `[['Control', 'S']]` becomes ⌘S in the menu bar, which is what a
+Mac user expects Save to be. `Super` maps there too; `Shift` and `Alt` are
+themselves. A chord the `NSMenu` spelling cannot express is simply not
+printed beside the item — the binding still fires, because the app's own
+window answers it (below). The text controls' own chords follow the same rule
+there, and so does the edit menu that prints them
+([events.md](events.md#primary-modifier)), and so do the window's own
+bindings: `useAccelerator`, and a drawn `MenuBar` or `ContextMenu`, which
+prints `⌘S` beside the row ([events.md](events.md#the-chord)).
+
+The key is named the way GDK names it, so `plus` rather than `+` and `Prior`
+rather than `PgUp`, because that is what a panel's importer parses. Menus print
+the friendly form: `[['Control', 'plus']]` draws as `Ctrl++`.
+
+**It is a binding**, and the app writes it once. A mounted `MenuBar` answers
+its own items' chords: Ctrl+S fires the item's `onSelect` without the menu
+being opened, gated by that item's own `enabled` and `visible`
+([events.md](events.md#accelerators)).
+
+That matters most in exactly this case. When the panel draws the menu, the
+**panel is not going to deliver the key** — it has no idea the window's
+keyboard is where the user is — so the app's own window still has to, and
+`MenuBar` keeps its bindings when it stops drawing. `accelerators={false}`
+turns them off for an application with a dispatcher of its own.
+
+The macOS menu bar is the one delegate that **does** deliver keys: it runs an
+item on the ⌘ chord it installed as its key equivalent, and it does that after
+the window has already seen the key. So there `MenuBar` reserves those chords
+— no binding in the window answers them, its own included, and the item runs
+once — and keeps answering the rest, the chords no `NSMenu` key equivalent can
+spell ([events.md](events.md#the-macos-menu-bar)).
+
+## What happens on the wire
+
+The D-Bus path, in enough detail to recognise it in `dbus-monitor` and to
+know what to look at when a menu does not appear. None of this applies on
+the Cocoa backend, where there is no wire and no registrar — installing an
+`NSMenu` is the whole of it.
+
+1. **Detection.** Does something own `com.canonical.AppMenu.Registrar` right
+   now? Only ownership counts — see the trap below.
+2. **Export.** The menu is served at `/com/react_x11/menus/<xid>` on the
+   process's existing bus connection ([dbus.md](dbus.md)), so the desktop sees
+   one application rather than several.
+3. **Registration.** `RegisterWindow(xid, path)`. The service name is inferred
+   from the sender, so only the path is supplied.
+4. **The KDE properties**, in addition: `_KDE_NET_WM_APPMENU_SERVICE_NAME` and
+   `_KDE_NET_WM_APPMENU_OBJECT_PATH`, written as `STRING`/format 8. Plasma
+   reads these off the window instead of asking a registrar, and runs a
+   registrar _as well_ — which of the two a given version prefers is not
+   something to bet a menu on.
+5. **Only then** does `MenuBar` stop drawing. `RegisterWindow` returning is the
+   evidence; a registrar that refuses the call leaves the menu where the user
+   can still reach it.
+
+It is followed for the life of the window, not sampled once: `NameOwnerChanged`
+moves the menu into the panel when one starts and back into the window when one
+exits, with no re-render on the app's part.
+
+### The trap: activatable is not running
+
+Ubuntu ships `com.canonical.AppMenu.Registrar` as a D-Bus **activatable**
+service, so the name resolves even with no panel installed. This is the exact
+opposite of the rule `hasService()` follows for portals, and getting it wrong
+is silent and total — an app with no menu anywhere.
+
+A registrar is not the feature; it is a directory the panel reads. Nothing
+starts one except a panel starting up. So react-x11 asks `ListNames` for a live
+owner, and every call it then makes carries D-Bus's `NO_AUTO_START` flag —
+without which the tidy-up `UnregisterWindow` sent after a panel dies would
+_launch a fresh registrar_, which would own the name with nothing drawing the
+menus it collects.
+
+## Seeing it work, without a desktop that has one
+
+`com.canonical.dbusmenu` has no reference client you can install on its own —
+the consumers are panel applets welded into Plasma, into `vala-panel`, or into
+a GNOME extension. So there is one in this repo:
+
+```bash
+npm run globalmenu:host
+```
+
+It owns the registrar name — it _is_ the panel — and prints every menu handed
+to it. In another terminal:
+
+```bash
+npm run examples:menu
+```
+
+The window's own menu bar disappears, which is the feature, and the menu
+appears in the host. Type an item's id and press Enter to activate it; the
+example's own state changes, and the property update comes back the other way.
+Ctrl-C the host and the bar returns to the window.
+
+On a machine that really does have a panel, `npm run globalmenu:host -- --watch`
+attaches to the live registrar rather than competing for the name.
+
+## Turning it off
+
+```jsx
+<MenuBar menus={menus} globalMenu={false} />
+```
+
+```bash
+REACT_X11_NO_GLOBAL_MENU=1
+```
+
+```jsx
+await createRoot({ desktop: { globalMenu: false } });
+```
+
+The prop is for one bar. The other two are process-wide: the environment
+variable needs no application change, which is what a user working around a
+panel that renders something badly actually has, and the `createRoot` option
+is the one an embedder can reach without also setting it for every child
+process it spawns — see [desktop.md](desktop.md#turning-the-desktop-off),
+where `desktop: false` turns this off along with the other two integrations
+that talk to the session bus.
+
+## Drawing your own bar
+
+`MenuBar` does all of this itself. A component that draws its own can have the
+same behaviour:
+
+```jsx
+import { useGlobalMenu } from 'react-x11';
+
+function Bar({ menus }) {
+  const exported = useGlobalMenu(menus, { onSelect });
+  if (exported) return null; // the panel has it
+  return; /* … your bar … */
+}
+```
+
+## Known limits, so they are not rediscovered as bugs
+
+- **Stock GNOME has no global menu bar at all**, so nothing owns the registrar
+  name and the in-window bar stays. That is correct rather than broken. The
+  extensions that add one do own it, and then this works.
+- **`ContextMenu` is not exported**, and should not be. The registrar's unit is
+  a window's menu _bar_; a right-click menu belongs where the pointer is.
+- **One menu per window.** The registrar's entry, the object path and the KDE
+  properties all belong to the window, so a second `MenuBar` in a window that
+  already has one stays drawn in the window until the first unmounts or turns
+  `globalMenu` off, and only then takes the panel. A bar remounted with a new
+  `key`, or switched off and on again, waits the same way for the one it
+  replaces to finish leaving, which takes a round trip or two.
+- **`AboutToShow` cannot be answered honestly.** dbusmenu wants a synchronous
+  "do you need to rebuild this submenu", and a React `setState` has not
+  rendered by the time the reply must go out. react-x11 answers `false`, runs
+  `onAboutToShow`, and emits `LayoutUpdated` when the new items actually
+  serialise — shells listen for that unconditionally, so a lazily-built submenu
+  fills in one round trip later than a synchronous toolkit manages. Answering
+  `true` instead would be worse: the shell would immediately fetch a subtree
+  that has not been built and cache the old one.
+- **`org.gtk.Menus`/`org.gtk.Actions` is deliberately not exported.** Handling
+  both serialisations is right for a panel and wrong for an app — traffic flows
+  _towards_ dbusmenu, not away from it. Plasma ships `gmenu-dbusmenu-proxy` to
+  convert GTK's menus into dbusmenu, and the GNOME extensions that render
+  third-party menus consume dbusmenu. A second exporter would be roughly double
+  the work for no consumer the first does not already reach.
+- **No bus is a first-class configuration.** Everything here degrades to
+  "draw the bar" without logging: no `dbus-native` (Node 20), no
+  `$DBUS_SESSION_BUS_ADDRESS`, a connection that fails. See
+  [dbus.md](dbus.md).
+
+## Performance, and the one thing worth knowing
+
+A menu is re-serialised whenever the `menus` array changes identity, which for
+an app that builds it inline is every render. That part is cheap. What is not
+cheap is the signal it produces, and the difference is the reason this feature
+has a diff at all:
+
+- ids and children identical, only properties differ → `ItemsPropertiesUpdated`,
+  **revision unchanged**;
+- structure changed → `revision++` and `LayoutUpdated(revision, parent)`, with
+  `parent` the nearest common ancestor of what changed rather than `0`.
+
+Plasma re-fetches a whole subtree on `LayoutUpdated` and only patches on
+`ItemsPropertiesUpdated`. A menu whose one check mark flipped must therefore
+not bump the revision — which is exactly what a naive
+`setState` → `LayoutUpdated(++rev, 0)` does on every keystroke, and it turns one
+property write into a re-walk of every menu in the application.
+
+Item ids are keyed on the path of `key ?? label` down the tree — the same
+identity `MenuBar` already uses for its React keys — so they survive a
+re-render, and they are never reused, because a shell has properties cached
+against them.

package/docs/glx.md

@@ -0,0 +1,137 @@
+# 3D over indirect GLX
+
+How a 3D scene works over this transport, and what the transport can never
+do. `<glarea>` and the three ways underneath it are [gl.md](gl.md); the
+scene graph that rides on this one is
+[`@react-x11/components/three`](ecosystem.md). This page is the design
+underneath both, kept because the constraints explain most of the API's
+shape — and because they are permanent: they are properties of a wire
+protocol frozen in the 1990s, not of any implementation.
+
+On X11 `<glarea>` is a real X child window on a GLX visual, and under the
+default `glPolicy` everything drawn into it travels as **indirect GLX**: the
+GL protocol encoded into the same X connection as everything else. No direct
+rendering, no native bindings, no GPU driver bindings — the same pure-JS
+story as the rest of the stack. (The direct path, which does take a native
+addon, is [gl.md](gl.md)'s.)
+
+The cost of that reach is a **fixed-function OpenGL 1.x pipeline**, and that
+single fact decides the rest.
+
+## What the protocol encodes
+
+node-x11's `glxrender.js` encodes 70 GL commands:
+
+| available      |                                                                                                                                                         |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| immediate mode | `Begin`/`End`, `Vertex3f`, `Normal3f`, `Color3f/4f`, `TexCoord2f`                                                                                       |
+| matrices       | `MatrixMode`, `LoadIdentity`, `LoadMatrixf`, `MultMatrixf`, `Push/PopMatrix`, `Translatef`, `Rotatef`, `Scalef`, `Frustum`, `Ortho`                     |
+| lighting       | `Lightfv`, `LightModelf`, `Materialfv`, `Materialf`, `ColorMaterial`, `ShadeModel`                                                                      |
+| texturing      | `TexImage2D`, `BindTexture`, `TexParameter*`, `TexEnv*`, `TexGen*`                                                                                      |
+| state          | `Enable`/`Disable`, `Clear*`, `DepthFunc`, `DepthMask`, `BlendFunc`, `AlphaFunc`, `CullFace`, `FrontFace`, `PolygonMode`, `Viewport`, `Scissor`, `Fog*` |
+| display lists  | `CallList`, `ListBase` (+ `NewList`/`EndList`/`DeleteLists` in `glx.js`)                                                                                |
+
+There are **no GLSL shaders, no VBOs, no vertex arrays** (`DrawArrays` and
+`VertexPointer` are not encoded), **no framebuffer objects and no
+instancing**. `ProgramString`/`BindProgram` expose ARB _assembly_ programs,
+which are out of scope.
+
+That rules out, permanently and by protocol: shader materials and
+post-processing. Both are implemented on the direct backend, and asking for
+one here throws an error naming the reason rather than rendering something
+that only looks right — the scene graph keeps the list, as `DIRECT_ONLY_KINDS`.
+(`<instancedMesh>` works on both, but as a loop over transforms rather than
+as hardware instancing, which GLX also encodes no way to ask for.)
+
+## Why display lists are mandatory
+
+With no vertex arrays, geometry can only be sent as immediate-mode commands.
+A 1 000-triangle mesh is ~3 000 `Vertex3f` + 3 000 `Normal3f` commands —
+about **96 KB per frame** if re-sent every frame, or 5.7 MB/s at 60fps for
+one modest mesh.
+
+So each geometry is compiled into a **server-side display list** once, and a
+frame sends only matrices, material state and one `CallList` per mesh. A
+static scene costs O(meshes) requests per frame instead of O(vertices).
+
+This is the AGENTS.md "Protocol efficiency" rule set applied literally — use
+server-side primitives, batch, never re-send what the server already has —
+and because it is a protocol property rather than an intention, the scene
+graph's own tests assert it on the encoded command stream: a 6 000-vertex
+sphere compiles once, and the steady-state frame is under 30 GL commands
+with no vertices in it.
+
+The cache is keyed by geometry identity. A geometry prop change recompiles
+that one list; a transform or material change is per-frame state only, so the
+same list is shared by meshes that differ in material.
+
+## The shape of the tree
+
+```
+<glarea> host element  ->  real X child window with a
+                                            GLX visual + its own colormap
+                     |
+                GLContext (ntk)   MakeCurrent -> context tag
+                     |
+              Scene node tree (parallel to the drawn-node tree)
+                     |
+     commit: compile dirty geometries -> display lists
+     frame:  Clear -> camera matrices -> per mesh: PushMatrix,
+             MultMatrixf, material state, CallList, PopMatrix -> SwapBuffers
+```
+
+`<glarea>` is one of the four elements that legitimately need an X window of
+their own — with `<window>`, `<popup>` and `<foreign>` (NEXT_STEPS §4): GLX needs its own visual and cannot share the
+XRender pipeline the 2D elements draw through.
+
+A scene tree over this surface is **separate from the drawn-node tree** — no
+yoga, no hit testing against the 2D tree, no painting into the parent's 2d
+context. To layout, `<glarea>` is a leaf sized by ordinary layout props.
+
+## The scene graph moved
+
+The r3f-shaped names this page used to map — `<mesh>`, the geometries, the
+materials, the lights, the camera prop — belong to
+[`@react-x11/components/three`](ecosystem.md) now, together with the display-
+list cache described above: it keeps its own reconciler and its own indirect
+renderer, built on exactly the constraints this page documents. What stays
+here is the transport, which is what those constraints come from.
+
+## Testing
+
+The primary tests are **hermetic and assert the encoded GLX command
+stream**, not pixels: that a geometry compiles to one display list, that a
+frame emits matrices plus `CallList` rather than thousands of `Vertex3f`,
+and that a transform change re-sends no geometry. That is the property that
+actually matters, and checking it needs no GL at all. Core's half is
+`test/glarea.test.js` and `test/viewer3d.test.js`; the scene graph tests its
+own in its own repo.
+
+Pixels are the awkward part. On XQuartz, GL renders into a Metal surface the
+compositor owns rather than into the X drawable, so `GetImage` reads back
+white and a 3D screenshot has to be captured by hand from
+a scene on a real server with indirect GLX — which is why
+`npm run screenshots` skips it. The documentation site's playground is the
+exception that renders GL headlessly: node-x11's browser GLX emulator
+replays the same protocol onto WebGL2.
+
+## Open questions
+
+- Is there a depth-buffer-capable visual reachable via `GetVisualConfigs` on
+  both XQuartz and Xvfb/llvmpipe?
+- Can a `<glarea>` be composited with 2D content drawn over it, or does the
+  GL child window always sit on top? Answered: the GL window is always on
+  top of the parent's drawing, so the surface's own children are drawn on
+  windows of their own stacked above it — opaque ones, one per region they
+  reach, since a child window cannot be translucent without a compositor
+  (`src/gloverlay.js`, [elements.md](elements.md#glarea)). Except on
+  XQuartz, where the window server composites the surface above every X
+  window, those included, and the children are not drawn at all.
+
+## Scope discipline
+
+Indirect GLX is a 1990s fixed-function pipeline reached over a network
+protocol. The value is _reach_ — 3D in a pure-JS X11 client with no native
+dependencies — not performance or fidelity. A plausible-looking API that
+quietly fails on anything modern would be worse than a small one with honest
+edges, which is why unsupported r3f names throw with the reason.