react-x11 2.52.0 → 2.53.0

package/docs/gl.md

@@ -26,35 +26,27 @@ and the display-list discipline the indirect backend demands.
 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:
+|                | **direct** (X11)                                                                                                               | **indirect** (X11)                                                 | **Cocoa**                                                                                   |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
+| how it draws   | OpenGL ES 2 on the GPU (DRI3 + Present on Linux, Apple-DRI on macOS/XQuartz)                                                   | GL 1.x commands encoded into the X connection                      | CGL — OpenGL 4.1 core on Metal — presented as a sublayer                                    |
+| shaders        | **yes**, GLSL ES 1.00                                                                                                          | none                                                               | **yes**                                                                                     |
+| render targets | **yes** — framebuffer objects                                                                                                  | none                                                               | **yes**                                                                                     |
+| geometry       | vertex buffers on the GPU                                                                                                      | immediate mode compiled into display lists                         | vertex buffers on the GPU                                                                   |
+| lighting       | per fragment                                                                                                                   | per vertex                                                         | per fragment                                                                                |
+| 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 hands `onDraw` the same WebGL-shaped `gl` table as X11
+direct. `glPolicy: 'indirect'` is an error there, and says so: there is no X
+server to speak GLX to.
+
+**win32** and **Wayland** have no column because they hand `onDraw` the same
+direct API and report `gl.backend === 'direct'` too. On win32 a `<glarea>` is
+a WGL context composited under the window's own visual, so it composites with
+the window's alpha where an X11 surface does not. On Wayland it is drawn into
+the window's own backing target, between the tree's 2D paint and its
+children's panes, rather than being a surface of its own.
+
+On X11 the default is indirect. Turn direct on per app:
 
 ```jsx
 const root = await createRoot({ glPolicy: 'auto' });
@@ -100,17 +92,36 @@ PascalCase OpenGL 1.x. Nothing translates between them. Branch on
 ```
 
 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.
+the default X11 policy does not switch under an app that never asked for it.
+A scene written for the direct API runs unchanged on the Cocoa backend; 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.
+costs kilobytes per frame (about 96 KB for a 1 000-triangle mesh) 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.
+
+### What indirect GLX encodes
+
+Indirect GLX is a fixed-function OpenGL 1.x pipeline, and these are the
+commands it can carry:
+
+| 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`                                                                                               |
+
+There are **no GLSL shaders, no VBOs, no vertex arrays** (`DrawArrays` and
+`VertexPointer` are not encoded), **no framebuffer objects and no
+instancing**, and ARB assembly programs are not supported. These are limits
+of the protocol, not of an implementation: shader materials and
+post-processing need the direct backend.
 
 ## Input
 
@@ -126,23 +137,17 @@ nothing should: on X11 a listener there takes the event away from the tree
 
 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).
+elements. On the Cocoa backend they composite with the GL frame,
+translucency and all. On X11 each is drawn on an opaque pane over the
+surface, 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.
+The answer is no on XQuartz: the macOS window server composites every GL
+surface there above everything the X server draws. 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.
 
 ## When there is no surface at all
 
@@ -155,16 +160,14 @@ 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 a GL app on **what it emits**, not on pixels: GL renders where `GetImage`
+cannot read it (on XQuartz a capture reads back white), so a screenshot of a
+window with a `<glarea>` has a hole where the scene is. On the direct
+backend, `gl.readPixels` inside `onDraw` is the only way to see the frame.
 
-- `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.
+This repo's `test/glarea.test.js` shows the pattern: 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.
 
-See also [glx.md](glx.md) for the indirect backend's design, and what its
-transport can never do.
+Design notes: [design/gl.md](../design/gl.md), and the indirect backend's
+design in [design/glx.md](../design/glx.md).

package/docs/globalmenu.md

@@ -25,10 +25,8 @@ import { MenuBar } from 'react-x11';
 />;
 ```
 
-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 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.
 
 | where the menu goes                                    | when                                                                                  |
 | ------------------------------------------------------ | ------------------------------------------------------------------------------------- |
@@ -36,20 +34,23 @@ exactly as before.
 | **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.
+On macOS the menu bar takes the menu as soon as `MenuBar` mounts and the drawn
+fallback never renders; see
+[macos.md §Menus](macos.md#menus-the-global-menu-finally-at-home).
+
+On Linux the panel row is decided live. The menu leaves the window only once a
+**running** owner of `com.canonical.AppMenu.Registrar` has accepted it (a
+registrar that is merely D-Bus-activatable, as Ubuntu ships it, does not
+count), and it moves into the panel when one starts and back into the window
+when one exits, with no re-render on the app's part. KDE's
+`_KDE_NET_WM_APPMENU_*` window properties are written as well. Design notes:
+[design/globalmenu.md](../design/globalmenu.md).
 
 ## 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.
+`com.canonical.dbusmenu`'s: **the identical array serialises**, so the drawn
+menu and the exported one cannot drift apart.
 
 | property                   | meaning                                                     |
 | -------------------------- | ----------------------------------------------------------- |
@@ -67,13 +68,16 @@ an exported one that drift apart.
 | `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".
+that is on for part of the selection — and draws as a dash rather than as
+unchecked.
+
+`icon` is the one thing that does not cross the bus: it is a react-x11 drawing
+callback ([components.md](components.md#menubar--contextmenu)), so an item that
+wants an icon in both menus carries `icon` for ours and `iconName` for the
+panel's.
 
-`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.
+Building `menus` inline on every render is fine: only what changed is sent to
+the panel, and item identity (the path of `key ?? label`) survives re-renders.
 
 ### Shortcuts are a list, not a string
 
@@ -85,17 +89,14 @@ 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)).
+**On macOS, `Control` means ⌘** — the primary modifier — so `[['Control', 'S']]`
+becomes ⌘S in the menu bar. `Super` maps there too; `Shift` and `Alt` are
+themselves. A chord the `NSMenu` spelling cannot express is not printed beside
+the item, but the binding still fires (the app's window answers it, below).
+The text controls' chords, the edit menu that prints them
+([events.md](events.md#primary-modifier)) and the window's own bindings
+(`useAccelerator`, a drawn `MenuBar` or `ContextMenu`, which prints `⌘S` beside
+the row — [events.md](events.md#the-chord)) follow the same rule.
 
 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
@@ -106,84 +107,35 @@ 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
+When the panel draws the menu, the **panel does not deliver the key**, so
 `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.
+item on the ⌘ chord installed as its key equivalent, after the window has 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 chords no `NSMenu` key equivalent can spell
+([events.md](events.md#the-macos-menu-bar)).
 
 ## 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:
+In a checkout of this repo, a stand-in panel prints every menu handed to it:
 
 ```bash
 npm run globalmenu:host
 ```
 
-It owns the registrar name — it _is_ the panel — and prints every menu handed
-to it. In another terminal:
+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.
+The window's own menu bar disappears and the menu appears in the host. Type an
+item's id and press Enter to activate it; Ctrl-C the host and the bar returns
+to the window. On a machine with a real panel,
+`npm run globalmenu:host -- --watch` attaches to the live registrar instead.
 
 ## Turning it off
 
@@ -200,12 +152,11 @@ 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.
+variable needs no application change (for a user working around a panel that
+renders something badly), and the `createRoot` option is the one an embedder
+can set without it leaking to child processes — see
+[desktop.md](desktop.md#turning-the-desktop-off), where `desktop: false` turns
+this off along with the other session-bus integrations.
 
 ## Drawing your own bar
 
@@ -224,55 +175,21 @@ function Bar({ menus }) {
 
 ## 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.
+- **Stock GNOME has no global menu bar at all**, so the in-window bar stays.
+  The extensions that add one work.
+- **`ContextMenu` is not exported** — a right-click menu belongs where the
+  pointer is.
+- **One menu per window.** 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 (a round trip or two).
+- **A lazily-built submenu fills in one round trip late.** `onAboutToShow`
+  runs when the panel opens the submenu, and the new items reach the panel
+  once they have rendered.
+- **`org.gtk.Menus`/`org.gtk.Actions` is not exported**; Plasma and the GNOME
+  extensions consume dbusmenu.
 - **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.