react-x11 2.52.0 → 2.54.0

package/docs/components.md

@@ -11,31 +11,25 @@ wins by position rather than by clobbering a computed value:
 ```
 
 Props that a component consumes itself are never style — `ProgressBar`'s
-`color`, `Dialog`'s `width`/`height` (a dialog is a real popup window, and
-those are its window's size), `ContextMenu`'s `fontSize` (it measures labels
-with it). Everything else is forwarded to the host box. See
-[styling.md](styling.md).
+`color`, `Dialog`'s `width`/`height` (its window's size), `ContextMenu`'s
+`fontSize` (it measures labels with it). Everything else is forwarded to the
+host box. See [styling.md](styling.md).
 
-Widget components are plain React built on the host elements — no
-reconciler support involved. They live in the package root export.
-
-All of them are screen-reader ready: roles, names, states and AT-driven
-control come built in, and an `aria-label` (or a label child) is the only
-thing a widget can need from you — [accessibility.md](accessibility.md)
-lists what each one announces.
+The widgets are plain React over the host elements, exported from the package
+root. All are screen-reader ready: roles, names, states and AT-driven control
+are built in, and an `aria-label` (or a label child) is the only thing a
+widget can need from you — [accessibility.md](accessibility.md) lists what
+each one announces.
 
 ## Theming
 
 **Widgets follow the desktop with nothing declared** — dark on a dark desktop,
-light on a light one, the same way a GTK or Qt app does. See
-[system appearance](appearance.md) for how that is worked out and how to pin
-or override it.
+light on a light one. See [system appearance](appearance.md) for how that is
+worked out and how to pin or override it.
 
 `<ThemeProvider value={palette}>` gives every widget beneath it a palette,
-layered over the scheme in force — so a partial one names what your app
-changes and everything else keeps following. It carries **shape as well as
-colour** — corner radius, border weight, text size and the padding inside a
-control are most of what separates one platform's controls from another's:
+layered over the scheme in force, so a partial one names only what your app
+changes. It carries **shape as well as colour**:
 
 | token                                                           |                                      |
 | --------------------------------------------------------------- | ------------------------------------ |
@@ -55,37 +49,24 @@ control are most of what separates one platform's controls from another's:
 
 ### The ground and what is on it
 
-`background` is what the **window** is — the fill under everything, painted
-by the window itself. `surface` is what is raised off it: a control's fill, a
-card, the sheet a menu or a dialog is drawn on. The light palette makes them
-the same colour, because a white app on a white ground is what it has always
-been; the dark one lifts `surface` a step, because a card at the ground's own
-colour is a card you cannot see.
-
-A palette that has one ground says so by naming one: **`surface` follows
-`background` unless you name it**, so a theme that only recolours the app
-keeps working and only a design that really raises its cards has a second
-token to fill in.
+`background` is the **window**, the fill under everything. `surface` is what
+is raised off it: a control's fill, a card, the sheet of a menu or dialog.
+The light palette makes them the same colour; the dark one lifts `surface` a
+step. **`surface` follows `background` unless you name it**, so only a design
+that really raises its cards has a second token to fill in.
+`surfaceHover` and `surfaceActive` are that surface's interaction steps.
 
 ```jsx
 <ThemeProvider value={{ background: '#f6f8fa', surface: '#ffffff' }}>
 ```
 
-`surfaceHover` and `surfaceActive` are that surface's own interaction steps,
-which is what they have always been — before there was a `surface` to be the
-steps of.
-
 ### What the app says with colour
 
-`danger`, `success`, `warning` and `info` are the four things a screen has to
-be able to say: this failed, this worked, look at this, here is a note. They
-are what an alert, a badge, a validation message and a toast are coloured
-from, and having them as tokens is what keeps a hard-coded `#e74c3c` — which
-is a bruise on a dark desktop — out of application code.
-
-Each works as **ink as well as fill**: every one clears 4.5:1 against its own
-palette's ground, so the message under a field and the badge beside it are one
-token.
+`danger`, `success`, `warning` and `info` — failed, worked, look at this, a
+note — colour alerts, badges, validation messages and toasts, and keep a
+hard-coded `#e74c3c` (a bruise on a dark desktop) out of app code. Each
+clears 4.5:1 against its palette's ground, so it works as **ink as well as
+fill**:
 
 ```jsx
 <text style={{ color: '$danger' }}>Password too short</text>
@@ -94,8 +75,7 @@ token.
 </box>
 ```
 
-For the tinted panel an alert usually wants — a wash of the colour rather
-than the colour — tint the fill and leave the ink alone:
+For a tinted panel, tint the fill and leave the ink alone:
 
 ```jsx
 import { tint } from 'react-x11/style';
@@ -104,59 +84,39 @@ import { tint } from 'react-x11/style';
 </box>;
 ```
 
-Only `danger` has `…Hover` and `…Active`, because a destructive button is the
-only status fill anyone presses; the other three are things the app says, not
-things the user clicks.
-
-The `…Text` four are the letters on a status fill, and **a palette almost
-never sets them**: each is derived from the fill it goes on, as the more
-legible of that palette's own `text` and `background`. So a theme whose
-`warning` is a yellow gets dark letters on it without having thought about
-it — and the same rule fixes `accentText`, which used to be inherited as
-white onto accents that could not carry white.
-
-`fontFamily` and `fontSize` are the type this app sets, and text that names
-neither **takes them** — a `<text>`, a `<textinput>`, a widget's own label. So
-`<ThemeProvider value={{ fontFamily: 'Inter', fontSize: 16 }}>` is where an app
-says what it is set in, once, rather than on every label, and a `Select`'s rows
-grow with it because a row is its label with even space all round. A `fontSize`
-or `fontFamily` in a style still wins, the way a style property always wins
-over what a node inherits.
-
-The widgets that take a size of their own keep taking it: `MenuBar` and
-`ContextMenu` have a `fontSize` prop because they measure their labels before
-they have anywhere to measure them in, and `Table` has `rowHeight` because
-every row has to be the same height for it to skip the ones off screen.
-
-Both are CSS-style family lists — `'"JetBrains Mono", monospace'` names a
-preference and a fallback.
-
-`monoFamily` is the second face, and nothing unstyled reads it: it is there so
-that every code surface in an app — a listing, a log pane, a hex dump, all
-written by different components — can say `fontFamily: '$monoFamily'` and be
-set from one place.
+Only `danger` has `…Hover` and `…Active` — the only status fill anyone
+presses. The `…Text` four (and `accentText`) are derived from their fill as
+the more legible of the palette's `text` and `background`, so a palette
+almost never sets them: a yellow `warning` gets dark letters unasked.
+
+`fontFamily` and `fontSize` are the app's type, and text that names neither
+**takes them** — a `<text>`, a `<textinput>`, a widget's label — so
+`<ThemeProvider value={{ fontFamily: 'Inter', fontSize: 16 }}>` sets it once,
+and a `Select`'s rows grow with it. A style's `fontSize`/`fontFamily` still
+wins. Both are CSS-style family lists (`'"JetBrains Mono", monospace'`).
+`MenuBar` and `ContextMenu` keep a `fontSize` prop (they measure labels
+before they have a window to measure in), and `Table` keeps `rowHeight`
+(every row must be the same height to skip the ones off screen).
+
+`monoFamily` is read by nothing unstyled: it is there so every code surface
+in an app can say `fontFamily: '$monoFamily'` and be set from one place.
 
 ### Which way it reads
 
-`direction` is `'ltr'` or `'rtl'`, and it is **seeded from the locale**: an
-app started under an RTL locale is mirrored without being configured, the
-way a GTK or Qt one is. Set it here to mirror a whole UI from one place:
+`direction` (`'ltr'` or `'rtl'`) is **seeded from the locale**, so an app
+started under an RTL locale is mirrored unconfigured. Set it here to mirror a
+whole UI:
 
 ```jsx
 <ThemeProvider value={{ direction: settings.rtl ? 'rtl' : 'ltr' }}>
 ```
 
-The provider plants the matching `direction` style property in the node tree
-as it goes, so the **boxes** and the **widgets** mirror together. That is
-why this is the way to do it rather than a bare `<box style={{ direction:
-'rtl' }}>`: yoga mirrors boxes on its own, but which way an arrow key steps,
-which way a chevron points and which side a submenu opens on are widget
-decisions, read through `useDirection()`. Under a bare style property the
-layout mirrors and those do not.
-
-Most of the set needs no help — `Button`, `Checkbox`, `Radio`, `Switch` and
-`ProgressBar` are rows and flex ratios, and come out mirrored on their own.
-The rest each have one thing yoga could not answer:
+The provider plants the `direction` style property in the node tree, so
+boxes **and** widgets mirror together. A bare
+`<box style={{ direction: 'rtl' }}>` mirrors only the layout, not the widget
+decisions read through `useDirection()` — which way an arrow key steps, a
+chevron points or a submenu opens. `Button`, `Checkbox`, `Radio`, `Switch` and
+`ProgressBar` need nothing more; the rest mirror one thing each:
 
 | widget                    | what mirrors                                        |
 | ------------------------- | --------------------------------------------------- |
@@ -164,67 +124,44 @@ The rest each have one thing yoga could not answer:
 | `Tabs`                    | Left/Right walk the strip the way it is drawn       |
 | `Table`                   | column resizing, the sort mark, the header's scroll |
 | `SplitPane`               | which pane is first, the drag and its arrows        |
-| `MenuBar` / `ContextMenu` | submenus open to the start side, and their arrows   |
+| `MenuBar` / `ContextMenu` | submenus open leftwards, and their arrows           |
 | `Select`, `PasswordInput` | the field's own insets follow the text              |
 
-`<textinput>` and `<textarea>` mirror on the inside too — the value, the
-placeholder and the caret are against the direction's start edge, and the
-value is shaped at the box's base level rather than at its own first strong
-character ([styling.md](styling.md#inside-an-editable-field)). What stays
-put: Left/Right and Home/End step through the string rather than across the
-screen.
+`<textinput>` and `<textarea>` mirror inside too: value, placeholder and caret
+sit against the start edge, and the value is shaped at the box's base level
+([styling.md](styling.md#inside-an-editable-field)); Left/Right and Home/End
+still step through the string, not across the screen. The style property and
+logical edges: [styling.md](styling.md#direction-and-the-logical-edges).
 
-See [styling.md](styling.md#direction-and-the-logical-edges) for the style
-property and the logical edges.
+### Size and shape
 
-`paddingY` is the space **you can see** — above the capitals and below the
-baseline — not the space plus whatever the font's ascent left over: every
-widget label is trimmed to its letters
+`paddingY` is the space **you can see**, above the capitals and below the
+baseline: every widget label is trimmed to its letters
 ([styling.md](styling.md#measuring-text-to-its-letters)), so a control is its
-label band plus this twice. That makes it a larger number than the same look
-would need in CSS, and it makes it mean the same thing in every typeface.
-Rows on a popup follow the same rule — a menu row and a `Select` option are
-their label with `padding` all round, so the space above a row's text is the
-space beside it. So does `<textinput>`, which is what keeps a field the same
-height as the `Button` and the `Select` next to it on a form; give it
-`paddingY` and the three agree by construction
-([styling.md](styling.md#measuring-text-to-its-letters)).
-
-The `…Active` four are the colour a control takes **while it is held**, and
-a palette almost never sets them: each is derived from the step the palette's
-own hover already makes — `accent` → `accentHover` → one more of the same —
-so it darkens a light theme and lightens a dark one. Set one explicitly and
-it wins. See [The press state](#the-press-state) for why every control has
-one.
-
-The `radius…` three that name a popup are derived too, and from the **text
-size** rather than from `radius`: a menu is a sheet laid over the window
-where a button is a control cut into it, and half the body size is the
-number desktops land near — 7px at a 14px body. The other two step in from
-there, because a rounded thing inside a rounded thing needs the tighter
-curve: `radiusPopupItem` is the highlight on a menu row, `radiusTooltip` the
-tooltip bubble. A palette that moves `fontSize` and names none of them gets
-all three in proportion; naming one pins it.
-
-`radiusPopupItem` is a **ceiling**, not the radius a row gets. A rounded rect
-inside a rounded rect only reads as one shape when the two curves share a
-centre, which happens exactly when the inner radius is the outer one less the
-gap between them — so a row's corner is `radiusPopup` minus the sheet's
-hairline border minus the inset the row is padded in by, and the token caps
-it. A theme that wants rounder highlights rounds the sheet they sit on: that
-is the only change that can round both and keep them concentric.
-
-They are only ever _seen_ where the display composites — a popup gives up
-its corners by not painting them, and with nothing blending them those
-pixels are black rather than the desktop, so the widgets ask the window
-(`'@supports transparency'`, [styling.md](styling.md)) and stay square
-where the answer is no.
-
-There are two consumers of a palette, and one provider feeds both. Widgets
-read it as React context through `useTheme()`; a `$token` in a style
-resolves against the nearest `theme` **prop** in the node tree, which knows
-nothing about React ([styling.md](styling.md#theme-tokens)). `ThemeProvider`
-puts the merged palette on the context _and_ plants it in the tree, so
+label band plus `paddingY` twice — a larger number than CSS would need, and
+the same in every typeface. Menu rows, `Select` options and `<textinput>`
+follow the rule, so a field, a `Button` and a `Select` on one row match in
+height.
+
+The `…Active` four are the colour **while held**, derived one step past the
+hover (`accent` → `accentHover` → `accentActive`), so a palette rarely sets
+them; one that is set wins. See [The press state](#the-press-state).
+
+The popup radii follow the **text size**, not `radius`: `radiusPopup` is half
+the body size (7px at 14px), and `radiusPopupItem` (a menu row's highlight)
+and `radiusTooltip` (the bubble) step in from it. Naming one pins it.
+`radiusPopupItem` is a **ceiling**: a row's corner is `radiusPopup` less the
+sheet's border and the row's inset, so the curves stay concentric — round the
+sheet to round the highlights. Rounded corners only show where the display
+composites (`'@supports transparency'`, [styling.md](styling.md)); elsewhere
+the widgets stay square.
+
+### `ThemeProvider` and `useTheme()`
+
+Widgets read the palette as React context through `useTheme()`; a `$token` in
+a style resolves against the nearest `theme` **prop** in the node tree
+([styling.md](styling.md#theme-tokens)). `ThemeProvider` feeds both, so this
+paints the palette, and an inner provider merges over an outer one:
 
 ```jsx
 <ThemeProvider value={dark}>
@@ -232,11 +169,10 @@ puts the merged palette on the context _and_ plants it in the tree, so
 </ThemeProvider>
 ```
 
-paints the palette rather than nothing. Nesting works the same either way:
-an inner provider merges over the outer, as an inner `theme` prop does.
-
-`useTheme()` returns the palette in force — complete, whatever the provider
-above set — and is the same object token resolution sees:
+`useTheme()` returns the complete palette in force — the object token
+resolution sees. It indexes like a bag of tokens: `theme[name]` needs no cast;
+named tokens keep their types, anything else is `unknown`. What a provider
+_accepts_ stays closed (`Partial<Theme>`), so a palette typo is caught.
 
 ```jsx
 function Panel() {
@@ -245,20 +181,10 @@ function Panel() {
 }
 ```
 
-It is a bag of tokens, and indexes like one: a component that resolves a name
-it was handed rather than one it wrote — a code block reading its own colour
-map, a renderer resolving `$token` itself — writes `theme[name]` with no cast.
-The named tokens keep their types, anything else is `unknown` and narrows.
-What a provider _accepts_ stays closed (`Partial<Theme>`), because a typo in a
-palette has nowhere else to be caught.
-
-Where the palette reaches the tree depends on where the provider is written.
-
-**Above the windows**, at the root of the tree, it draws nothing, and every
-window under it takes the palette — its background and the type every
-unstyled `<text>` falls back to as well as the `$token`s inside. Whatever
-shape the windows arrive in: a component that renders one, a window that is
-closed for now, several at once, a provider nested in another.
+**Above the windows**, at the root of the tree, a provider draws nothing and
+every window under it takes the palette — background, the fallback type of
+unstyled `<text>`, the `$token`s — however the windows arrive (a component
+that renders one, a closed window, several, a nested provider):
 
 ```jsx
 root.render(
@@ -268,26 +194,20 @@ root.render(
 );
 ```
 
-**Inside a window** it is a `<box>`, styled `{ flexGrow: 1 }` so an app-level
-provider fills its parent; pass `style` to change that
-(`style={{ flexGrow: 0 }}` around a single control). A window nests only in a
-window, so a nested `<window>` under a provider written directly inside a
-window is handed on to that window, and takes the palette with it. Further
-down — a provider inside a `<box>` — there is no window to hand it to, and the
-error says to move the provider.
-
-Widgets plant the merged palette on their own root node too, so a `$token`
-in a style you pass one resolves even with no provider anywhere.
+**Inside a window** it is a `<box>` styled `{ flexGrow: 1 }`; pass `style` to
+change that (`{ flexGrow: 0 }` around a single control). A nested `<window>`
+under a provider written directly in a window takes the palette with it; a
+provider deeper inside a `<box>` has no window to hand it to, and the error
+says to move it. Widgets plant the palette on their own root node too, so a
+`$token` in a style you pass one resolves with no provider at all.
 
-`examples/themes.js` has three worked palettes — GitHub, macOS and Windows,
-each in light and dark — and `npm run examples:theming` switches between
-them at runtime.
+`examples/themes.js` has GitHub, macOS and Windows palettes in light and dark;
+`npm run examples:theming` switches between them.
 
 ## System icons
 
-The glyphs the widgets here are drawn with, exported so an application and a
-third-party widget can use the same ones — a toolbar you write and a `Select`
-you did not should not disagree about which way a chevron points.
+The glyphs the widgets are drawn with, exported so your toolbar and a
+`Select` agree about which way a chevron points.
 
 ```jsx
 import { Icon } from 'react-x11';
@@ -312,45 +232,28 @@ import { Icon } from 'react-x11';
 Everything else goes to the host `<canvas>`, so a clickable one is
 `<Icon name="close" onClick={…} focusable />`.
 
-**`size` is the mark, not a grid it sits in.** This is the one place the set
-departs from how lucide and its descendants are drawn: theirs put about 14px
-of ink in a 24px box, so you reach for `size={20}` next to 14px text. Here
-the ink runs corner to corner, so `size` is what you actually see and the
-number to pick is the number you want — the `Select` chevron is
-`capBand(fontSize)` because it should be as wide as the capitals beside it.
-
-A chevron is the one glyph whose two axes differ: the arms are at 45°, so it
-is as long as `size` along the way it points across and half that the other
-way. `<Icon name="chevronDown" size={10} />` is 10 wide and 5 tall; the same
-size of `chevronRight` is 5 wide and 10 tall.
+**`size` is the mark**, ink corner to corner — not a 24px grid with 14px of
+ink in it as in lucide-style sets — so pick the size you want to see. A
+chevron is the one glyph whose axes differ (45° arms):
+`<Icon name="chevronDown" size={10} />` is 10 wide and 5 tall, and
+`chevronRight` at the same size is 5 wide and 10 tall.
 
 ### Affordances, not nouns
 
-The set holds glyphs that say something about **the control**: there is more
-here, this one is chosen, this closes, this is hidden. It holds no nouns —
-no folder, no document, no save, no printer. Those belong to an icon theme
-(lucide, an XDG icon theme, your own art), they are unbounded in number, and
-a widget set that starts shipping them has taken on a design system.
-
-That is also the answer to "why is X missing": if X names a thing rather
-than an action the control affords, it is not going to be here. Bringing
-your own set is expected and supported — a `<svg>` or a `<canvas>` goes
-anywhere an `<Icon>` does, and `ContextMenu`'s `icon` takes either. The
-platform's own set is there too:
-[`<image src={{ symbol }}>`](elements.md#src-symbol---the-platforms-own-icons)
-draws an SF Symbol on macOS and an icon from the desktop's icon theme
-elsewhere, in the text colour.
-
-The **drawings are not themable** for the same reason: the geometry is the
-widget set's vocabulary, and an application that wants a different chevron
-wants an icon library. Colour and size are yours; the shape is not.
+The set holds glyphs about **the control** — more here, chosen, close,
+hidden — and no nouns (folder, document, printer). Bring your own icon set:
+a `<svg>` or `<canvas>` goes anywhere an `<Icon>` does, and `ContextMenu`'s
+`icon` takes either. The platform's own set is
+[`<image src={{ symbol }}>`](elements.md#src-symbol---the-platforms-own-icons):
+an SF Symbol on macOS, the desktop's icon theme elsewhere, in the text colour.
+The drawings are not themable: colour and size are yours, the shape is not.
 
 ### Colour inherits; size does not
 
-`color` travels down the tree
-([styling.md](styling.md#inheritance-the-ink-the-face-and-the-size)), so an
-icon takes the ink of whatever it is written inside and needs nothing said
-at the call site:
+`color` inherits ([styling.md](styling.md#inheritance-the-ink-the-face-and-the-size)),
+so an icon takes the ink it is written inside, hover included; the `color`
+prop is for ink the surrounding text does not have (a destructive mark, a
+check on an accent fill):
 
 ```jsx
 <box style={{ color: theme.textMuted, ':hover': { color: theme.accent } }}>
@@ -359,39 +262,18 @@ at the call site:
 </box>
 ```
 
-That covers the hover case too. `:hover` marks the row, `color` is
-inherited, and the label and the icon both follow — which is why
-`ContextMenu`'s submenu chevron carries no colour of its own any more. The `color` prop is for saying something the surrounding text does
-not: a destructive action's mark, or a check drawn on an accent fill.
-
-**`size` does not inherit, and is deliberately not `fontSize`.** A glyph is
-a drawing rather than a letter — no baseline to sit on, no ascent to be
-measured against — so it takes its default from the palette's `fontSize` and
-stays put when a label beside it shrinks. Pass `size` for the one icon that
-has to be bigger.
+**`size` does not inherit, and is not `fontSize`**: it defaults from the
+palette's `fontSize` and stays put when a label beside it shrinks. Pass
+`size` for the one icon that must be bigger.
 
 ### What it costs to draw one
 
-Each glyph is a drawing over `<canvas mono>`
-([elements.md](elements.md#canvas)), which is a promise that everything it
-paints is one colour it did not choose — so one drawing serves every state a
-control puts it in, and the paint cache can keep one rendered copy of
-`chevronDown` at 12px for every chevron on the screen at once.
-
-The entry is **coverage**, so the colour is applied at composite time and
-stays out of the key: one rendered copy of `chevronDown` at 12px serves the
-resting row, the highlighted row, the disabled one and both colour schemes —
-the trick the glyph cache runs on text, and the one `<svg>` gets for a
-`fill="currentColor"` document. The size cannot leave the key, since a
-coverage surface is pixels at a fixed size, so one icon at two sizes is two
-entries.
-
-The drawings are module-level, so re-rendering a list invalidates none of
-its icons: `<canvas>` compares `onDraw` by identity, and a fresh closure per
-render is a repaint per glyph.
-
-`icons` is the map of raw drawings, for a widget that wants the glyph
-without the component:
+Each glyph is a module-level drawing over `<canvas mono>`
+([elements.md](elements.md#canvas)), cached as coverage and coloured at
+composite time, so one copy per glyph and size serves every colour and state.
+`icons` is the map of raw drawings, for a widget that wants the glyph without
+the component; keep `onDraw` identity-stable as these are, or every render
+repaints:
 
 ```jsx
 import { icons } from 'react-x11';
@@ -404,28 +286,21 @@ import { icons } from 'react-x11';
 />;
 ```
 
-They are **decoration by default** — `aria-hidden`, because the meaning is
-already on the control, in its `role` and its `aria-expanded`. Name one
+Icons are **`aria-hidden` by default** — the meaning is on the control's
+`role` and `aria-expanded`. Name one
 (`aria-hidden={false} aria-label="Close"`) only when the icon _is_ the
-control and nothing else says so.
+control.
 
 ## Basic controls
 
-`Button`, `Checkbox`, `Radio`/`RadioGroup`, `Switch` and `ProgressBar` share
-one piece of plumbing, `useControl(disabled, onActivate)`: it makes the
-control focusable, activates it on click — and so on Space and Enter, which
-are a click on anything with an `onClick` unless Ctrl, Alt or Super make
-them a shortcut's ([events.md](events.md#space-and-enter-are-a-click)), the
-widgets having no key mapping of their own any more — sets the pointer cursor,
-and expresses hover, press and focus
-feedback as `:hover`/`:active`/`:focus` style blocks rather than React state
-— so moving the pointer over a control repaints one node instead of
-rendering.
-
-`Button`, `Checkbox`, `Switch` and `ProgressBar` take `style`, merged after
-their own so an override wins by position, and forward any remaining props
-to the host box. `Radio` is the exception: it takes only the props listed
-below, and the group around it carries the layout.
+`Button`, `Checkbox`, `Radio`/`RadioGroup`, `Switch` and `ProgressBar` are
+focusable, activate on click — and so on Space and Enter, unless Ctrl, Alt or
+Super make it a shortcut ([events.md](events.md#space-and-enter-are-a-click))
+— set the pointer cursor, and draw hover, press and focus as
+`:hover`/`:active`/`:focus` style blocks, so hovering repaints one node
+rather than rendering. All but `Radio` take `style` (merged after their own)
+and forward other props to the host box; `Radio` takes only its listed props,
+and its group carries the layout.
 
 ```jsx
 import { Button, Checkbox, RadioGroup, Radio, Switch, ProgressBar } from 'react-x11';
@@ -444,93 +319,59 @@ import { Button, Checkbox, RadioGroup, Radio, Switch, ProgressBar } from 'react-
 ```
 
 Label text is the children (or a `label` prop); a bare string is wrapped in
-a `<text>` for you, so `<Button>Save</Button>` needs no `<text>`.
+a `<text>` for you. All five are demoed in `examples/widgets.jsx`.
 
 ### Native bezels
 
-On a backend that renders the platform's own control bezels — today the
-**Cocoa** backend, never X11 — `Button`, `Checkbox`, `Radio`, `Switch`,
-`Slider` and `Select` wear AppKit's pixels by default, while interaction,
-focus, keyboard and accessibility stay this library's shared implementation.
-The mechanism is a bezel _image_ drawn through the ordinary paint path, not
-an embedded `NSView`: the press model and the event routing are behaviour
-this project considers part of its identity, and a real `NSControl` would
-take them over wholesale. [macos.md](macos.md#native-controls) is the
-design record.
-
-**Default native, seam out**, at three levels:
+On the **Cocoa** backend (never X11) `Button`, `Checkbox`, `Radio`, `Switch`,
+`Slider` and `Select` wear AppKit's bezels by default; on **win32** all but
+`Switch` wear the system's own while the desktop is light, and are drawn in
+dark mode. Interaction, focus, keyboard and accessibility stay this
+library's. Opt out at three levels:
 
 ```jsx
+// the app's identity
 <ThemeProvider value={{ controls: 'drawn' }}>
-  {' '}
-  {/* the app's identity   */}
-  <Button native={false}>Brand</Button> {/* one control          */}
+  {/* one control */}
+  <Button native={false}>Brand</Button>
 </ThemeProvider>;
 
 const canGoNative = useSupports('nativeControls'); // what the backend has
 ```
 
-`controls` is `'auto'` (bezels where the backend has them), `'native'` (ask
-for them, and hear about it in development where there are none) or
-`'drawn'` (this library's rendering everywhere). It lives in the theme
-rather than in `style` because whether an app looks native is an
-app-identity decision, not a per-node one. `native={false}` is the escape
-hatch for the one custom-branded control — and a control naming its own
-colours in `style` should also say it, because a bezel the system draws
-ignores them.
-
-Under a native bezel, `style` sizes the box the control _sits in_ rather
-than the control itself. A `<Button>` or a `<Select>` keeps AppKit's own
-height and is centred in whatever footprint the layout gives it, so
-`style={{ height: 44 }}`, a `height: '100%'` in a taller parent, a
-`flexGrow: 1` or a taller neighbour in a stretching row leave a 22pt
-control in a 44pt slot instead of stretching a bezel the system draws at
-one size. The slack around it is not part of the control: a press up there
-does nothing, as it does in AppKit. Drawn controls stretch as they always
-have — their chrome is drawn to the box and their label is centred in it,
-so a stretched drawn control is merely roomy.
-
-The one thing that makes a native button taller is its own label. Squeezed
-narrower than its label, a `<Button>` wraps it at its words — native or
-drawn — and grows by the lines it gained, which on macOS is drawn with
-AppKit's flexible-height push bezel, the one it has for a title that wraps.
-A row that should never wrap its buttons wants `flexWrap: 'wrap'` on the
-row instead, so the buttons move to a second row rather than their labels
-to a second line.
+`controls` (a theme token, since looking native is an app-wide decision) is
+`'auto'` (bezels where the backend has them), `'native'` (ask, and hear about
+it in development where there are none) or `'drawn'`. Give `native={false}`
+to a control that names its own colours in `style` — a system bezel ignores
+them.
+
+Under a native bezel, `style` sizes the slot the control _sits in_: a
+`<Button>` or `<Select>` keeps AppKit's height, centred, so
+`height: 44`, `height: '100%'`, `flexGrow: 1` or a taller neighbour in a
+stretching row leave a 22pt control in a 44pt slot, and a press in the slack
+does nothing. Drawn controls stretch to the box. A `<Button>` squeezed
+narrower than its label wraps it at its words and grows by the lines —
+native or drawn (on macOS with AppKit's flexible-height bezel); give the row
+`flexWrap: 'wrap'` to move buttons to a second row instead. Design notes:
+[macos.md](macos.md#native-controls).
 
 ### The press state
 
-Every control here activates on the **release** — that is what a click is.
-So every one of them also has a distinct look while it is being _held_,
-because otherwise a click a user takes half a second over is half a second
-of a control that has visibly not heard them, and the change, when it comes,
-reads as the machine being slow rather than the hand being unhurried.
-
-Four states, all different: resting, hovered, held, and hovered again on the
-release. The held one is drawn on the press **even though the press itself
-does nothing** — it acknowledges the input, it does not promise the outcome.
-A press dragged off the control drops it, and picking the control back up
-restores it, so the way it looks always agrees with whether releasing there
-would activate anything.
-
-Nothing is needed to get this: it is what the widgets do. Writing a control
-of your own, `:active` is the state block for it —
-[styling.md](styling.md#inline-pseudo-states) — and the palette's
-`accentActive`/`surfaceActive`/`textMutedActive`/`dangerActive` are the
-colours.
+Every control activates on the **release**, and looks distinct while
+**held** — on the press, though the press does nothing yet — so a slow click
+is visibly heard. Four states: resting, hovered, held, hovered again on
+release. Dragging off the control drops the held look and coming back
+restores it, so the look always says whether releasing there would activate.
+For a control of your own, `:active`
+([styling.md](styling.md#inline-pseudo-states)) is the state block and
+`accentActive`/`surfaceActive`/`textMutedActive`/`dangerActive` the colours.
 
 ### The change event, and `name`
 
 Every value control — `Checkbox`, `Switch`, `RadioGroup`, `Select`,
-`Slider` — calls `onChange(ev)` with a change event, the **same signature**
+`Slider` — calls `onChange(ev)` with the **same change event**
 `<textinput>` and `<textarea>` use
-([elements.md](elements.md#the-change-event)). The new value is `ev.value`:
-
-```jsx
-<Checkbox checked={agreed} onChange={(ev) => setAgreed(ev.value)}>
-  I agree
-</Checkbox>
-```
+([elements.md](elements.md#the-change-event)); the new value is `ev.value`:
 
 ```js
 { type: 'change',
@@ -539,29 +380,22 @@ Every value control — `Checkbox`, `Switch`, `RadioGroup`, `Select`,
   name: 'agree', value: true }
 ```
 
-One signature is the point. It is what lets a form library's handler be
-passed straight to any control in the library, with no per-widget adapter:
+So a form library's handler goes straight onto any control:
 
 ```jsx
 <textinput name="host" value={f.values.host} onChange={f.handleChange} />
 <Checkbox  name="agree" checked={f.values.agree} onChange={f.handleChange} />
 ```
 
-`target` is a plain descriptor rather than a node, and that is the one place
-this differs from the host elements: a widget is several nodes with no single
-element holding its value, so there is nothing honest to point at. Its shape
-is what formik's `handleChange` and react-hook-form's event reader
-destructure — `target.type` is how they tell a checkbox from a text field,
-which is why it is set even though nothing in react-x11 reads it. There is no
-`preventDefault`: the value has already changed by the time the handler runs.
-
-**The line is `name`.** A widget that takes one is a form field and reports
-an event. `Tabs`, `Table` and the menus are not form fields — you would never
-register a tab strip with formik — and keep their plain callbacks (`Tabs`
-calls `onChange(id)`).
+`target` is a plain descriptor, not a node (a widget has no single node
+holding its value), shaped as formik's `handleChange` and react-hook-form
+read it — `target.type` tells a checkbox from a text field. There is no
+`preventDefault`: the value has already changed.
 
-`name` is otherwise inert; it exists so a form library has somewhere to put
-one. See [docs/ecosystem/forms.md](ecosystem/forms.md).
+**The line is `name`**: a widget that takes one is a form field and reports
+an event. `Tabs`, `Table` and the menus are not, and keep plain callbacks
+(`Tabs` calls `onChange(id)`). `name` is otherwise inert. See
+[docs/ecosystem/forms.md](ecosystem/forms.md).
 
 ### `Button`
 
@@ -574,31 +408,18 @@ one. See [docs/ecosystem/forms.md](ecosystem/forms.md).
 | `primary`            | speaks in the accent: the fill when solid, the ink and border otherwise |
 | `disabled`           | inert, dimmed, not focusable                                            |
 
-Chrome and colour are two axes, and they compose. `variant` is how much box
-the button carries — `solid` a fill, `outline` a border on nothing, `ghost`
-neither, for the affordance that sits inside other content (a `✕` on a chip,
-a delete on a form row) and must not add a box to the row it lives in.
-`primary` is whose colours it speaks in. So a dialog footer is an `outline`
-beside a `primary` solid, and a toolbar's loudest icon is
-`primary variant="ghost"` — every combination keeps the widget states, which
-is the point of not hand-drawing the chrome-less ones. All variants keep the
-border _width_, so a mixed row lines up to the pixel.
-
-`size="small"` halves the control padding — the toolbar and inline-row
-metric. It is derived from the palette, so a theme that moves `paddingY`
-moves both sizes together, which a hand-made `style={{ height: 22 }}` would
-not.
-
-A label with less room than it needs wraps at its words, the lines centred
-under one another, and the button grows to hold them — a row too narrow
-for its buttons squeezes each to its longest word first, as it would any
-paragraph ([Native bezels](#native-bezels) has what that does to a native
-button).
-
-An **element** child inherits the resolved label colour — the ink is set on
-the button's box and `color` inherits ([styling.md](styling.md)) — so an
-icon+label button is correct by construction in every state, disabled
-included, with nothing passed to the icon:
+`variant` and `primary` compose: `solid` is a fill, `outline` a border,
+`ghost` neither (for a `✕` on a chip, or a delete inside a form row); a
+dialog footer is `outline` beside `primary`, a toolbar's loudest icon
+`primary variant="ghost"`. Every variant keeps the widget states and the
+border _width_, so a mixed row lines up. `size="small"` halves the control
+padding and follows the palette's `paddingY`, which a hand-set `height`
+would not.
+
+A label with too little room wraps at its words, centred, and the button
+grows — a too-narrow row squeezes each button to its longest word first. An
+**element** child inherits the label's colour in every state, disabled
+included:
 
 ```jsx
 <Button primary disabled={busy} onPress={run}>
@@ -623,23 +444,18 @@ included, with nothing passed to the icon:
 
 ### `Radio` / `RadioGroup`
 
-`RadioGroup` takes `value`, `onChange(ev)`, `name`, `style` and any
-box props; each `Radio` takes the `value` it selects, plus `children`/`label`
-and `disabled` — and nothing else, so per-radio styling goes on the group. A
-`Radio` outside a `RadioGroup` throws rather than silently doing nothing.
-`name` lives on the group the way it does in HTML: the group is the field.
-
-Arrow keys move the selection through the group in **mount order**,
-wrapping — Up/Left back, Down/Right forward — which is how a native radio
-group behaves; click or Space selects the focused one.
+`RadioGroup` takes `value`, `onChange(ev)`, `name`, `style` and any box
+props; each `Radio` takes only its `value`, `children`/`label` and
+`disabled`, so per-radio styling goes on the group. A `Radio` outside a
+`RadioGroup` throws. Arrow keys move the selection in **mount order**,
+wrapping (Up/Left back, Down/Right forward); click or Space selects the
+focused one.
 
 ### `Switch`
 
-`checked`, `onChange(ev)`, `name` and `disabled`, the same semantics
-as `Checkbox` in a sliding pill. The thumb is absolutely positioned and
-animates on `left` (`transition: { left: 120 }`) because `justifyContent`
-would flip between the ends with nothing in between to animate — the worked
-example in [styling.md](styling.md#transitions).
+`checked`, `onChange(ev)`, `name` and `disabled`, as `Checkbox`, in a
+sliding pill (the thumb's `left` transition is the worked example in
+[styling.md](styling.md#transitions)).
 
 ### `ProgressBar`
 
@@ -658,29 +474,17 @@ Determinate with a `value`, indeterminate without one.
 <ProgressBar indeterminate style={{ width: 200 }} />
 ```
 
-The determinate fill is expressed as flex ratios rather than a percentage
-width. A percentage child resolves against space that is still being
-measured, which fed back into the track's intrinsic width — a card with a
-fuller bar came out wider than one with an empty bar.
-
-`indeterminate` is the worked example of a
-[style loop](styling.md#loops): the block is absolutely positioned and
-travels on the logical `start` edge from `-40%` to `100%` of the track, so it
-mirrors with the text direction, is right at any width without measuring
-anything, and repaints the bar rather than the window. It reports
-`aria-busy` **with no value at all**, which is what tells a screen reader
-that a percentage is not coming.
-
-Under [reduced motion](system.md#usedesktopsettings--how-the-desktop-wants-an-app-to-feel)
-the loop never starts — that part is core's, and every loop in every app gets
-it — and the block parks in the middle of the track instead of at its
-off-screen starting point. A still bar that shows nothing would say the app
-had stopped; a full one would say it had finished.
+The indeterminate block is a [style loop](styling.md#loops) on the logical
+`start` edge, so it mirrors with the text direction and fits any width; it
+reports `aria-busy` **with no value**, telling a screen reader no percentage
+is coming. Under
+[reduced motion](system.md#usedesktopsettings--how-the-desktop-wants-an-app-to-feel)
+it does not move and parks mid-track.
 
 ## `Select`
 
-A dropdown whose menu is a real override-redirect `<popup>` window anchored
-below the trigger.
+A dropdown whose menu is an override-redirect `<popup>` anchored below the
+trigger.
 
 ```jsx
 import { Select } from 'react-x11';
@@ -709,11 +513,9 @@ import { Select } from 'react-x11';
 | `chevronStyle`          | the chevron's style, over `textMuted`     |
 | `native`, `nativeMenu`  | the platform's bezel, and its menu        |
 
-The two style slots restyle what is inside the trigger, and `style` restyles
-the trigger itself, so a select that has to wear somebody else's look — a
-toolbar's, or a web page's — is the widget restyled and keeps the menu, the
-keyboard, type-ahead and the focus ring. A borderless select that sits in a
-line of text:
+`style` restyles the trigger and the two slots what is inside it, keeping the
+menu, keyboard, type-ahead and focus ring. A borderless select in a line of
+text:
 
 ```jsx
 <Select
@@ -732,96 +534,57 @@ line of text:
 />
 ```
 
-The caption's `fontSize`, as a number, is the one the chevron is sized
-against, since the chevron is as tall as the capitals beside it and an
-`<Icon>`'s size does not inherit. `chevronStyle={{ display: 'none' }}` leaves
-it out, for a trigger whose arrow is drawn by something else. A select with
-either slot is drawn, where `controls: 'auto'` would otherwise use the
-platform's popup bezel, whose pixels no style reaches. The menu is not
-restyled: it is the same surface a menu is.
-
-**The menu can be the platform's.** On macOS, with `@windowkit/appkit` 0.20
-or later, a select under the native bezel drops a real `NSMenu`: the chosen
-row placed over the trigger and checked, the menu at least the trigger's
-width, AppKit's tracking, type-select and VoiceOver. A drawn menu sized as
-one was the best a drawn widget could do; this is the menu itself.
-`nativeMenu` is that choice on its own: it follows the trigger by default,
-`true` asks for the platform's menu under a drawn trigger too — what a
-browser does with a `<select>` a page styled, and what `<Html>` does — set
-at the caption's size and in the family its style names when the system
-has it, and `false` keeps the drawn menu. Elsewhere, and on an older
-bridge, the menu is drawn whatever the prop says. The menu is the
-platform's to dismiss: Escape, a click outside, or the application losing
-focus, and the select hears a pick or nothing.
-
-Behavior: the menu opens on the **press** — Space and Enter toggle it too;
-Escape, focus loss, or picking closes it; the option list scrolls when taller
-than 220px; the trigger participates in Tab traversal.
-
-**A caption is one line.** The trigger is as wide as the form made it and the
-value in it can be any length, so a caption with no room left ends in a `…`
-rather than wrapping to a second line — which there is no height for: the
-trigger is one row of label, and under a native popup bezel it is AppKit's
-own fixed height, so the wrapped line drew outside the control. The menu is
-sized to its longest option rather than to the trigger, so its rows are
-whole; where the screen is narrower than that longest label and the sheet is
-clamped to it, they end in a `…` too.
-
-The menu is the **same surface a menu is**: an ARGB popup rounded at
-`radiusPopup` with a hairline border where the display composites, and the
-active option is the same pill at `radiusPopupItem`, inset from the sheet's
-edge. A dropdown and a menu are one kind of thing, and two shapes for it
-would only say that the widgets were written at different times.
-
-Opening on the press rather than the release is deliberate, and it is the
-one control whose answer to a press is more than a colour: a dropdown exists
-to be looked at, so waiting for the button to come back up before showing it
-wastes the whole time the button is down. It is what every desktop toolkit
-does. A press while the menu is up dismisses it through the popup's pointer
-grab, so the two never fight over the toggle.
-
-Keyboard, while the trigger is focused (the popup is override-redirect and
-never takes focus, so the trigger keeps handling keys with the menu open):
-
-| key               | closed         | open                                    |
-| ----------------- | -------------- | --------------------------------------- |
-| `Down` / `Up`     | opens the menu | move the active option, wrapping around |
-| `Home` / `End`    | —              | first / last option                     |
-| `Enter` / `Space` | opens the menu | pick the active option                  |
-| `Escape`          | —              | close without picking                   |
-
-The menu opens with the current value active, hovering an option makes it
-active (pointer and keyboard share one highlight), and the active option is
-scrolled into view.
-
-**PageUp/PageDown** move by a menu viewport (`MAX_MENU_HEIGHT / ITEM_HEIGHT`
-options), clamping at the ends rather than wrapping the way the arrows do.
-
-**Losing the window** closes it too. That is not the same event as the
-trigger's own blur: a window losing the window manager's focus leaves the
-node inside it focused and merely stops it looking active — so without this
-the menu would still be up over an application you have switched away from,
-holding the pointer grab it opened with. The menus do the same.
-
-**Type-ahead.** Typing letters jumps to the matching option: with the menu
-open it moves the highlight, and with it closed it changes the value
-outright, the way a native select does. Keystrokes within 700ms accumulate
-into one query (`b`,`l` finds _blueberry_, not _banana_); repeating a
-single letter cycles through the options starting with it.
+The chevron is sized against the caption's numeric `fontSize`;
+`chevronStyle={{ display: 'none' }}` drops it. A select with either slot is
+drawn even under `controls: 'auto'`. The menu itself is not restyled.
+
+**The menu can be the platform's.** On macOS with `@windowkit/appkit` 0.20 or
+later, a select under the native bezel opens a real `NSMenu`: the chosen row
+over the trigger and checked, at least the trigger's width, with AppKit's
+tracking, type-select and VoiceOver. `nativeMenu` makes that choice alone: it
+follows the trigger by default; `true` uses the platform menu under a drawn
+trigger too (as a browser does for a styled `<select>`, and as `<Html>`
+does), at the caption's size and family when the system has it; `false`
+keeps the drawn menu. Elsewhere, or on an older bridge, the menu is drawn. A
+platform menu dismisses itself (Escape, a click outside, the app losing
+focus), and the select hears a pick or nothing.
+
+**Behaviour.** The menu opens on the **press**, as in every desktop toolkit;
+a press while it is up closes it. Space and Enter toggle it; Escape, focus
+loss, losing the window (switching applications) or picking close it. The
+list scrolls past 220px, is sized to its longest option (rows end in `…`
+only on a screen narrower than that), and is drawn as a menu is. The
+trigger is a Tab stop, and a caption with no room ends in `…` rather than
+wrapping.
+
+Keys go to the focused trigger, menu open or not:
+
+| key                   | closed         | open                                    |
+| --------------------- | -------------- | --------------------------------------- |
+| `Down` / `Up`         | opens the menu | move the active option, wrapping around |
+| `Home` / `End`        | —              | first / last option                     |
+| `PageUp` / `PageDown` | —              | a menu's height of options, clamped     |
+| `Enter` / `Space`     | opens the menu | pick the active option                  |
+| `Escape`              | —              | close without picking                   |
+
+The menu opens with the current value active; hovering an option makes it
+active (one highlight for pointer and keyboard), and it is scrolled into view.
+**Type-ahead**: letters typed within 700ms form one query (`b`,`l` finds
+_blueberry_, not _banana_), and a repeated single letter cycles; with the
+menu open this moves the highlight, closed it changes the value, as a native
+select does.
 
 ### Theming
 
-`Select` has no provider of its own — it reads the palette from
-[`ThemeProvider`](#theming) like every other widget. The trigger is
-`background`/`text` in a `border` box that turns `borderFocus` on focus or
-while open, the chevron and the placeholder text are `textMuted`, and the menu
-highlight is `hoverBackground`/`hoverText`.
+`Select` reads the palette from [`ThemeProvider`](#theming) like every
+widget: the trigger is `background`/`text` in a `border` box that turns
+`borderFocus` when focused or open; chevron and placeholder are `textMuted`;
+the menu highlight is `hoverBackground`/`hoverText`.
 
 ## `Calendar` / `DatePicker`
 
-Moved to [`@react-x11/components`](ecosystem.md). A date picker is a locale
-problem before it is a widget, and the calendar systems, holiday sets and
-range semantics people need do not belong in a renderer.
+Moved to [`@react-x11/components`](ecosystem.md): a date picker is a locale
+problem before it is a widget.
 
 ## `PasswordInput`
 
@@ -849,81 +612,35 @@ A masked field whose mask is a **scribble**, not a row of bullets.
 
 ### Why a scribble
 
-Bullets answer the wrong question. They report **how many characters** have
-been typed — countably, from across the room — and they report almost nothing
-about the keystroke that just landed, because one more identical dot at the
-end of a row of identical dots is the least visible change a field could
-make. The feedback is weakest exactly where a password field needs it, and
-strongest exactly where it should not be.
-
-So the mask is a single stroke through points chosen by a generator seeded
-from the window id and a hash of the value. Every keystroke reseeds it, so
-**the whole curve moves on every character** — feedback you cannot miss — and
-nothing in the shape is per-character: the pen visits a number of points taken
-from the mask's _width_, where a character is worth about half a point, so no
-part of the stroke can be matched to anything typed.
-
-It is a **scribble rather than a waveform**, and that is a decision rather
-than a look. A stroke whose `x` only ever increases is the plot of a
-function, and the eye reads it as one — value against position, meaning in
-the peaks — however wild the `y` is. So the points are laid out one per
-column, which is what makes the stroke cover the width it was given, and then
-visited **out of order**: the pen doubles back, crosses what it has already
-drawn, and leaves loops. The shuffle is local rather than global, because in
-a box seventeen pixels tall a jump right across it is a long shallow scratch,
-and a maskful of those is not a scribble either.
-
-What does grow is the width, because a mask that did not would say nothing
-about progress. Each position contributes an advance drawn from a **second,
-window-seeded** stream, so the width only ever grows as you type, never
-twitches when a character is replaced, and is not a clean multiple of
-anything a glance could divide.
-
-The honest limit, since a mask that oversells itself is worse than one that
-does not: **this hides a glance, not a recording.** Someone watching the
-field grow keystroke by keystroke still counts the keystrokes, and a long
-password still sits in a visibly different bracket from a short one.
+Bullets show how many characters were typed and barely show the keystroke
+that just landed. The scribble is the reverse: **the whole stroke changes on
+every character**, nothing in it is per-character, and its width only grows
+(never twitching when a character is replaced, never a clean multiple of
+anything). **It hides a glance, not a recording**: someone watching it grow
+still counts keystrokes. Design notes:
+[design/components.md](../design/components.md#why-a-scribble).
 
 ### Two states, and what holds across both
 
-**Masked**, editing is smaller than `<textinput>`'s, because a scribble has
-nowhere to put a caret: type, Backspace, Ctrl+Backspace / Ctrl+U / Delete to
-clear, Ctrl+V or Shift+Insert to paste, Enter to submit. No caret, no
-selection, no undo history — a rewindable secret is not a feature.
-
-**Revealed**, it is an ordinary text input, because that is what it looks
-like and anything else would be a trap. A real `<textinput>` takes the mask's
-place: caret, selection, arrow keys, a click into the middle of the word,
-undo, the edit menu. Focus follows the swap in both directions, and the
-reveal ends when the keyboard leaves the widget — not when it moves between
-the field and the input inside it.
-
-What holds in **both** states is that nothing leaves by a selection. Ctrl+C
-and Ctrl+X do nothing, the revealed input carries
-[`sensitive`](elements.md#sensitive) so its menu has no Cut or Copy, and
-neither state ever takes PRIMARY, so a middle click in another window cannot
-spend it. The line is between what is on screen and what is on the clipboard:
-the first stops being visible when the field is hidden, the second is
-readable by every client on the display until something else takes it.
-
-While the value is masked it is **never laid out and never drawn**: the mask
-is measured from one reference character, so the secret does not enter ntk's
-shaping cache and its glyphs never reach the X server. Revealing it costs
-what revealing it costs. The eye is a pointer affordance and not a tab stop,
-as GTK's peek icon is; `revealed` + `onRevealChange` put the toggle wherever
-your keyboard can reach it.
-
-Caps Lock is reported while it is on, from the modifier state on the keys as
-they arrive — the mistake that a masked field otherwise lets you make four
-times before telling you.
+**Masked**: type, Backspace, Ctrl+Backspace / Ctrl+U / Delete to clear,
+Ctrl+V or Shift+Insert to paste, Enter to submit. No caret, no selection, no
+undo history. **Revealed**: a real `<textinput>` takes its place — caret,
+selection, arrows, clicks, undo, the edit menu. Focus follows the swap both
+ways, and the reveal ends when the keyboard leaves the widget.
+
+In **both**, nothing leaves by a selection: Ctrl+C and Ctrl+X do nothing, the
+revealed input is [`sensitive`](elements.md#sensitive) (no Cut or Copy in its
+menu), and neither state takes PRIMARY. While masked the value is **never
+laid out or drawn**, so its glyphs never reach the display server. The eye is
+a pointer affordance, not a tab stop; `revealed` + `onRevealChange` put the
+toggle where the keyboard can reach it. Caps Lock is reported while it is on.
 
 ### Drawing your own mask
 
-`drawMask(ctx, info)` replaces the scribble entirely; `info` is
-`{ width, height, seed, color, length }`, where `width` is the mask width the
-field worked out and `seed` is the value-and-window seed. The scribble itself
-is `strokeScribble` in `src/components/scribble.js`, which is worth reading
-before replacing it — the reasoning for each number is there.
+`drawMask(ctx, info)` replaces the scribble; `info` is
+`{ width, height, seed, color, length }`, with the mask width the field
+worked out and the value-and-window seed. The scribble is `strokeScribble` in
+`src/components/scribble.js`, with the reasoning for each number.
 
 ```jsx
 <PasswordInput
@@ -936,12 +653,10 @@ before replacing it — the reasoning for each number is there.
 
 ### Password managers
 
-Paste and typing are the two seams that reach a field on this desktop, and
-both work here: XTEST auto-type arrives as ordinary key events, and Ctrl+V
-takes a secret from the clipboard with control characters stripped so a
-manager's trailing newline stays out of it. Which manager does what, what the
-window title has to do with it, and the seams that are _not_ a field —
-Secret Service, the sandbox portal, AT-SPI — are in
+XTEST auto-type arrives as ordinary key events, and Ctrl+V pastes with
+control characters stripped (so a manager's trailing newline stays out).
+Which manager does what, the window title's part, and Secret Service, the
+portal and AT-SPI:
 [desktop.md](desktop.md#password-fields-and-password-managers).
 
 ## `Slider`
@@ -972,9 +687,8 @@ import { Slider } from 'react-x11';
 | `trackStyle`            | the track's style, over `height` and `track`            |
 | `fillStyle`             | the filled part of the track, over `accent`             |
 
-The three style slots restyle the drawn parts without giving up what the
-widget does — the drag, the keyboard, the `aria-*` values, RTL and the target
-size. The flat slider most design systems draw is:
+The style slots restyle the parts and keep the drag, keyboard, `aria-*`
+values, RTL and target size. A flat slider:
 
 ```jsx
 <Slider
@@ -992,22 +706,15 @@ size. The flat slider most design systems draw is:
 />
 ```
 
-The thumb's `width` and `height`, as numbers, are the sizes the widget works
-with: the drag's travel is the track less one thumb, and the control is as tall
-as the taller of thumb and track, with its target still grown to 24. A
-`marginStart` and `marginEnd` of half a thumb on the track are what let the
-thumb overhang its ends. A slider with any slot is drawn, where `controls: 'auto'` would
-otherwise use the platform's bezel, whose pixels no style reaches.
-
-Dragging uses [pointer capture](events.md#pointer-capture): the press
-captures, so the thumb keeps following a pointer that has wandered far
-outside the widget, and releasing out there still ends the drag.
-
-Keyboard: arrows step, `Home`/`End` jump to the ends, `PageUp`/`PageDown`
-move by ten steps.
+The thumb is centred on its value, so the travel is the track less one thumb
+(numeric `thumbStyle` `width`/`height` are what the widget uses); the control
+is as tall as the taller of thumb and track, its target at least 24. Half a
+thumb of `marginStart`/`marginEnd` on the track lets the thumb overhang the
+ends. A slider with any slot is drawn even under `controls: 'auto'`.
 
-The thumb is centred on its value, so the usable travel is the track width
-minus one thumb width — otherwise `min` and `max` would be unreachable.
+Dragging uses [pointer capture](events.md#pointer-capture), so it follows
+the pointer anywhere and ends wherever it is released. Keyboard: arrows
+step, `Home`/`End` jump to the ends, `PageUp`/`PageDown` move ten steps.
 
 ## `Tooltip`
 
@@ -1030,36 +737,20 @@ import { Tooltip } from 'react-x11';
 | `width`, `height`       | pin an axis of the bubble exactly; anything not pinned is measured     |
 | `maxWidth`, `maxHeight` | cap what an element label measures out to, inside the screen's own cap |
 
-Wraps its children in a row box carrying the hover handlers and the anchor
-ref, so it composes around any element. Hides immediately on leave and on
-mousedown — a tooltip lingering over the menu you just opened is the
-classic annoyance.
-
-**One at a time**, per connection: a hint belongs to where the pointer is,
-and there is one pointer. A trigger taking the hover dismisses whatever is
-showing straight away rather than at the end of its own delay, so two are
-never up together saying different things about the same place. This does
-not fight the safe-polygon grace that lets a hint with content in it be
-reached — a trigger underneath an open hint cannot be hovered, the popup
-being a window above it.
-
-`direction` is which side of the trigger it opens on. The default, `'auto'`,
-takes the first side the hint fits on, preferring above — measured against
-the **screen**, because a popup is a real X window and the screen is what
-bounds it. A named side is a preference rather than a promise either way:
-it still flips to its opposite instead of opening off-screen. (`placement`
-is the older name for the same prop and still wins where it is given.)
-
-A **string** `label` is measured and the popup sized around it, because a
-`<popup>` is a real X window and needs its size before layout. An
-**element** label is measured too — nothing to size, nothing to guess: the
-popup is rendered once [`hidden`](elements.md#hidden--realized-laid-out-not-on-screen)
-at its natural size (a real layout of the real content, capped at the screen
-and at `maxWidth`/`maxHeight`), the size is read back, and the same
-placement math runs before anything is mapped. Both commits land in the same
-task and the popup maps last, so it is only ever on screen placed and at its
-final size. The element gets the bubble to fill, with no padding imposed on
-it:
+It wraps its children in a row box carrying the hover handlers and anchor ref,
+so it composes around any element, and hides at once on leave and on
+mousedown. **One at a time** per connection: a trigger taking the hover
+dismisses any showing hint immediately. `direction` is a preference: `'auto'`
+takes the first side that fits on the **screen**, preferring above, and a
+named side still flips rather than open off-screen. (`placement` is the older
+name and still wins where given.)
+
+An **element** `label` is measured like a string one: rendered
+[`hidden`](elements.md#hidden--realized-laid-out-not-on-screen) at its
+natural size (capped by the screen and `maxWidth`/`maxHeight`) and placed
+before it maps, so it never appears misplaced. It fills the bubble with no
+padding imposed; anything renders there, widgets included
+(`examples/tooltips.jsx`):
 
 ```jsx
 <Tooltip
@@ -1076,40 +767,25 @@ it:
 </Tooltip>
 ```
 
-`width`/`height` still pin an axis exactly: give both and the measuring pass
-is skipped entirely (the guaranteed-fit mode element labels used to
-require); give one and the other is measured for it, so `width={340}` is a
-fixed column whose height fits the message. The size is settled at open —
-content that changes size while the hint is up keeps the bubble it opened
-with until the next open, which is a hint's lifetime away.
-
-Anything renders in there, widgets included — it is a real tree in a real
-window, not a rich-text label. `examples/tooltips.jsx` has both kinds.
-
-**The palette inside the bubble is upside down.** A tooltip is drawn in the
-palette's ink so that it reads as a label over the desktop rather than as
-another panel of the app — so inside it, `$background` is the bubble and
-`$text` is the ink on it, published through a `ThemeProvider` so that
-`useTheme()` agrees. Write the content the way you would write anything
-else and it is legible in both schemes; hard-code a light text colour and
-it will be invisible on the light bubble a dark palette gives it. `textMuted`
-is derived for the same reason — the palette's own is a grey chosen against
-the app's background, not against this one — and `$surface` is the bubble
-too, so a card written for the app does not light up inside a tooltip.
-
-Where the display composites, the popup is an ARGB window: a bubble rounded
-at `radiusTooltip`, no border, and a small arrow pointing back at the middle
-of the trigger with everything neither covers left transparent. Without a
-compositor it is the square opaque rectangle it has always been and there is
-no arrow — those pixels would be black rather than empty.
+`width` and `height` together skip measuring; one alone fixes that axis and
+measures the other (`width={340}` is a column whose height fits). The size is
+settled at open and kept until the next.
+
+**The palette inside is inverted**: the bubble is drawn in the palette's ink,
+so inside it `$background` (and `$surface`) is the bubble and `$text` the ink,
+published through a `ThemeProvider` so `useTheme()` agrees, with `textMuted`
+derived to match. Write content with tokens and it reads in both schemes; a
+hard-coded light text colour vanishes on the light bubble of a dark palette.
+Where the display composites the bubble is rounded at `radiusTooltip`, with
+no border and a small arrow at the trigger's middle; elsewhere it is a
+square rectangle with no arrow.
 
 ## `Dialog`
 
-A dialog in a `<popup>`, centred over the owner window — and one the
-**window manager knows is a dialog**: it is a managed window with
-`WM_TRANSIENT_FOR` pointing at its owner, so it is framed, movable, closable
-through the WM, out of the taskbar and alt-tab list, and (on a full EWMH
-window manager) stacked above its owner and iconified with it.
+A `<popup>` centred over its owner that the **window manager knows is a
+dialog**: managed and transient for its owner (`WM_TRANSIENT_FOR` on X11) —
+framed, movable, closable through the WM, out of the taskbar and alt-tab, and
+on a full EWMH window manager stacked above its owner and iconified with it.
 
 ```jsx
 import { Button, Dialog } from 'react-x11';
@@ -1129,100 +805,65 @@ import { Button, Dialog } from 'react-x11';
 </Dialog>;
 ```
 
-| prop       |                                                                                                      |
-| ---------- | ---------------------------------------------------------------------------------------------------- |
-| `open`     | renders nothing when false; the popup exists only while true                                         |
-| `title`    | names the dialog, drawn once: the frame's caption when managed, a bold in-content heading when not   |
-| `children` | body content; strings become `<text>`                                                                |
-| `actions`  | elements for the right-aligned button row                                                            |
-| `onClose`  | Escape, or the window manager's close button                                                         |
-| `managed`  | `false` for the override-redirect popup 1.x shipped (below)                                          |
-| `width`    | popup width (default 360); `'auto'` for the content's                                                |
-| `height`   | popup height (default `'auto'`: the content's, capped at the monitor — [below](#size-and-placement)) |
-
-The focus behaviour is the **renderer's**, not the component's: `trapFocus`
-keeps Tab inside the dialog, stops presses elsewhere from moving focus, and
-hands focus back to whatever had it — usually the button that opened the
-dialog — when it closes. See
-[Focus scopes](events.md#focus-scopes-modals). Put `autoFocus` on a control
-inside to pick the first stop; with nothing to focus, the dialog surface
-takes focus itself (`tabIndex={-1}`) so Escape and Tab work immediately.
-
-Escape closes because keys go to the focused node inside the popup and
-bubble out through the popup's place in the JSX tree; so does the window
-manager's close button, through `onCloseRequest`. **Pointer modality is not
-enforced** — widgets in the owner window stay clickable behind the dialog —
-so it is for confirmations, not for guarding state. (`_NET_WM_STATE_MODAL`
-is the mechanism that would enforce it, and it means nothing without the
-`WM_TRANSIENT_FOR` this now sets; that is why the property had to come
-first.)
+| prop       |                                                                     |
+| ---------- | ------------------------------------------------------------------- |
+| `open`     | renders nothing when false; the popup exists only while true        |
+| `title`    | names the dialog; drawn once ([below](#managed))                    |
+| `children` | body content; strings become `<text>`                               |
+| `actions`  | elements for the right-aligned button row                           |
+| `onClose`  | Escape, or the window manager's close button                        |
+| `managed`  | `false` for an unframed override-redirect popup ([below](#managed)) |
+| `width`    | popup width (default 360); `'auto'` for the content's               |
+| `height`   | default `'auto'`, the content's ([below](#size-and-placement))      |
+
+Focus is the renderer's `trapFocus` ([Focus scopes](events.md#focus-scopes-modals)):
+Tab stays inside, presses elsewhere do not move focus, and focus returns to
+whatever had it (usually the opening button) on close. `autoFocus` picks the
+first stop; with nothing focusable the dialog surface takes focus
+(`tabIndex={-1}`), so Escape and Tab work at once. **Pointer modality is not
+enforced** — the owner stays clickable — so it is for confirmations, not
+guarding state.
 
 ### `managed`
 
-| `managed`        | what you get                                                                                                                                        |
-| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `true` (default) | a WM-managed window: frame, titlebar, movable, WM close button, transient for its owner, out of the taskbar. A press outside does **not** close it. |
-| `false`          | the override-redirect popup: no frame, not movable, a pointer grab, and a press anywhere outside calls `onClose`.                                   |
-
-The `title` follows the frame: managed, it is the frame's caption and the
-content starts with the body; unmanaged there is no frame, so the title is
-drawn as a bold heading at the top of the content instead. It is never drawn
-twice, and it names the dialog for accessibility either way.
-
-They are one choice, not two: a client-side pointer grab over a window the
-window manager is trying to let the user drag swallows the press that would
-start the drag, so `grab` and the frame turn on and off together. A managed
-dialog staying open when you click elsewhere is not a regression — it is what
-a dialog does. `managed={false}` is the right shape for a transient
-confirmation on a display with no window manager at all.
-
-The owner is resolved automatically: `Dialog` already keeps an out-of-flow
-`<box>` inside the owner window for placement, and a ref to any drawn node
-resolves to the window that owns it
+| `managed`        | what you get                                                                                                        |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `true` (default) | frame, titlebar (the `title`), movable, WM close button, transient for its owner; a press outside does not close it |
+| `false`          | no frame, not movable, a pointer grab, the `title` as a bold heading; a press outside calls `onClose`               |
+
+The frame and the grab go together (a grab would swallow the press that
+starts a window drag). `managed={false}` suits a display with no window
+manager. Either way the `title` names the dialog for accessibility, and the
+owner is found automatically
 ([`transientFor`](elements.md#transientfor--a-window-that-belongs-to-another)).
 
 ### Size and placement
 
-**The height is the content's** by default (`height="auto"`): ten lines and
-a row of buttons make a dialog as tall as ten lines and a row of buttons. The
-popup measures its content, centres itself over the owner window at that
-size and only then opens — it is born the right size in the right place,
-never shown at a guess and corrected
+**The height is the content's** (`height="auto"`): the dialog measures its
+content, centres over the owner at that size, and only then opens
 ([`placement: 'center'`](elements.md#centred-over-something)).
 
-- **Capped at the monitor.** Content taller than the usable height of the
-  monitor caps the dialog there; the body scrolls, and the `actions` row stays
-  pinned at the bottom of the window. The body is a tab stop only while it has
-  something to scroll. A numeric `height` scrolls the same way when the
-  content needs more than it, where the overflow, buttons included, used to
-  be cut off at the bottom edge (#940).
-- **Following its content.** A dialog whose content changes while it is open
-  re-fits to it, growing from its **top edge**: the title and the field the
-  user is looking at stay where they are, and only the bottom moves. It moves
-  up only as far as it takes to stay on the monitor. A managed dialog the user
-  dragged aside grows where they put it.
-- **Centred once,** over where the owner window was when the dialog opened,
-  and not tracked after that: moving the owner does not drag the dialog with
-  it, which is the window manager's call on a managed one.
-
-`width` stays a number by default, 360: a body of prose wraps to it, where a
-natural width would be as wide as its longest sentence. `width="auto"` is
-there for a dialog whose content has a width of its own (a grid of fields, an
-image). A number for either axis is that size exactly.
-
-`centerRect(node, {width, height})` is the same centring as a function,
-exported alongside `anchorRect` for window-centred popups of your own that
-know their size; one that does not uses `<popup anchor={{ rect, placement:
-'center' }}>` and lets the window work it out.
+- **Capped at the monitor**: taller content scrolls in the body while the
+  `actions` row stays pinned; the body is a tab stop only while it can
+  scroll. A numeric `height` scrolls the same way.
+- **Following its content**: content that changes while open re-fits the
+  dialog from its **top edge**, moving it up only to stay on the monitor; a
+  managed dialog the user dragged grows where they put it.
+- **Centred once**, over where the owner was at open; moving the owner does
+  not move it.
+
+`width` defaults to 360 so prose wraps; `width="auto"` is for content with a
+width of its own (a grid of fields, an image). A number is exact on either
+axis. `centerRect(node, {width, height})` is the same centring as a function,
+for popups of your own that know their size; one that does not uses
+`<popup anchor={{ rect, placement: 'center' }}>`.
 
 ## `MenuBar` / `ContextMenu`
 
-Pull-down and right-click menus, both rendered in `<popup>` windows so they
-escape the owner window, both anchored with `useAnchor`.
-
-On the Cocoa backend with native controls, the popups are sized as NSMenu
-sizes its own — 22pt rows, the 13pt menu font — so a context menu sits
-beside the system's like one of them ([macos.md](macos.md#menus-the-global-menu-finally-at-home)).
+Pull-down and right-click menus in `<popup>` windows, anchored with
+`useAnchor`. On the Cocoa backend with native controls they are sized as
+`NSMenu` sizes its own — 22pt rows, the 13pt menu font
+([macos.md](macos.md#menus-the-global-menu-finally-at-home)).
 
 ```jsx
 import { MenuBar, ContextMenu } from 'react-x11';
@@ -1253,16 +894,28 @@ import { MenuBar, ContextMenu } from 'react-x11';
 
 Item shape: `{ label, onSelect, type, items, enabled, visible, shortcut,
 toggleType, toggleState, icon, iconName, disposition, key }`. Both take an
-`onSelect(item)` prop as well, fired after the item's own. A bar menu opens on
-the **press**, for the reason `Select` does.
+`onSelect(item)` prop too, fired after the item's own. A bar menu opens on
+the **press**, like `Select`.
+
+**The vocabulary is `com.canonical.dbusmenu`'s** — `type: 'separator'`,
+`enabled: false`, `toggleType`/`toggleState` (`0`, `1`, or `-1` for
+indeterminate), `shortcut` as modifier tokens — because on a desktop whose
+panel shows application menus, `MenuBar` hands the array over and stops
+drawing, with the same JSX ([globalmenu.md](globalmenu.md), also for
+`globalMenu={false}`).
+
+**`shortcut` is a binding, not a label**: `[['Control', 'S']]` makes Ctrl+S
+fire the item's `onSelect` while the menu is mounted, unopened, gated by its
+`enabled` and `visible`, and still when a panel has taken the menu over. The
+same array is the drawn shortcut, the dbusmenu payload and the
+`aria-keyshortcuts` announcement. Chord rules, key names, `useAccelerator`
+and `accelerators={false}`: [events.md](events.md#accelerators).
 
 **A context menu's items can come from the right-click.** The click records
-only where it happened; what the menu shows, how big it is and where it fits
-are taken from the `items` of the render that follows. So a row that says
-which thing was right-clicked in its own `onContextMenu`, with the items
-derived from that, gets a menu for that thing, sized for it, on the first
-right-click. Items still empty in that render open nothing: no popup, no
-pointer grab, and the focus left where the press put it.
+only where it happened; the menu's content, size and placement come from the
+`items` of the next render, so items derived in a row's `onContextMenu` give
+a menu for that row on the first right-click. Items still empty open nothing
+— no popup, no grab, focus left where the press put it.
 
 ```jsx
 const [target, setTarget] = useState(null);
@@ -1276,87 +929,23 @@ const [target, setTarget] = useState(null);
 </ContextMenu>;
 ```
 
-**`shortcut` is a binding, not a label.** It is a list of alternatives, each a
-list of modifier tokens ending in the key — `[['Control', 'S']]` — and a
-mounted menu answers it: Ctrl+S fires that item's `onSelect` without the menu
-being opened, gated by the item's own `enabled` and `visible`, and it keeps
-working when the desktop's panel has taken the menu over. One array is then
-the drawn menu, the exported dbusmenu payload, the `aria-keyshortcuts`
-announcement and the binding, so there is nothing to keep in step by hand. The
-chord rules, the vocabulary the key tokens come from, `useAccelerator` for a
-shortcut that is not in a menu, and `accelerators={false}` for an app with its
-own dispatcher are all in [events.md](events.md#accelerators).
-
-**The vocabulary is `com.canonical.dbusmenu`'s**, and that is not incidental.
-On a desktop whose panel shows application menus, `MenuBar` hands this array
-straight over and stops drawing — no configuration, no second authoring model,
-the same line of JSX either way. `type: 'separator'` rather than
-`separator: true`, `enabled: false` rather than `disabled: true`,
-`toggleType`/`toggleState` rather than a bare `checked`, and `shortcut` as a
-list of modifier tokens rather than a display string, all follow from that.
-`toggleState` is `0`, `1` or `-1`, the last being indeterminate. See
-[globalmenu.md](globalmenu.md), which also covers `globalMenu={false}`.
-
-**The sheet.** Where the display composites, a menu is an ARGB window
-rounded at `radiusPopup` with a hairline border, and the highlight on a row
-is a pill: inset from the popup's edge by the list's own padding and rounded
-a step tighter (`radiusPopupItem`), so it reads as sitting _on_ the sheet
-rather than cutting across it. The fill is `hoverBackground` — the palette's
-selection colour, shared with `Select`'s active option and `Table`'s current
-row, so one token moves every highlight in the app. Without a compositor
-both go square, which is what those pixels can honestly be.
-
-**One selection at a time.** The bar item, the row under it and the row
-under that are one trail, and only its deepest level wears the selection
-colour; everything behind is drawn in `surfaceActive`.
-They are still chosen — they are the way back — but two selection-coloured
-rows in two menus claim the same thing twice, and only one of them is where
-the keys are going. A submenu that is open with _nothing_ selected in it has
-not taken over yet: the pointer is still on the row that opened it, so that
-row stays lit — which is why a menu bar item stays coloured until you touch
-a row in the menu it opened, and goes quiet then.
-
-The bar item wears the same pill as the rows, at `radiusPopupItem` — the same
-padding around the same capitals, so a title and the first row of the menu it
-opens are one shape in one size, inset into the bar by a few pixels of margin
-that sit outside that padding.
-
-**Titles that do not fit.** A bar narrower than its menus paints as many as
-fit and moves the rest behind a chevron at the end of it — the system set's
-`moreVertical`, drawn rather than a `»`, so it is a mark and not a font's
-opinion of one. The chevron is an ordinary bar entry whose items are the
-menus that were cut, so each row opens the menu it stands for as a submenu,
-and it is a real stop for Left/Right: **the keyboard walks exactly what is
-painted**, never a title laid out past the window's edge. Widen the window
-and the titles come back one at a time. The bar measures itself, so the
-first frame of a new bar always shows everything and the cut lands on the
-next — and none of this happens on a desktop whose panel has taken the menu,
-where there is no bar of ours to overflow.
-
-**Icons.** `icon` fills the column left of the label — the same column a
-`toggleType` mark uses, so an item that is both checked and iconned shows
-the check: the check is state, the icon is only identity. `icon` is drawn by
-react-x11 and never crosses the bus; `iconName` is the icon-theme name a
-panel uses ([globalmenu.md](globalmenu.md)). One column rather than
-two, because a second would indent every label in the menu to reserve room
-for icons most items do not have.
-
-The column is there for the menus that draw in it and gone from the ones
-that do not. What counts is what a row actually paints: one icon, or one
-toggle that is _on_, anywhere in a menu indents every label in it — and a
-menu of plain commands, or of checkboxes that all happen to be off, has no
-column at all and its labels sit where a label sits.
-
-So ticking the first item in such a menu moves its labels sideways, once.
-Toolkits that reserve the column unconditionally are buying stillness in
-that one frame, and paying for it with an indent on every menu that has a
-toggle anywhere in it — this one makes the other trade. A menu that already
-has a mark in it keeps the column whatever happens to the rest.
-
-Pass a **function** for anything real. It is called with the colour the
-row's label is being drawn in and the size the column allows, which is what
-lets one drawing follow its row into the highlight and into the disabled
-grey:
+**Look.** Where the display composites, a menu is rounded (`radiusPopup`,
+hairline border) and the row highlight an inset pill (`radiusPopupItem`) in
+`hoverBackground`, the token shared with `Select` and `Table` highlights;
+without a compositor both are square. Only the deepest open level wears
+`hoverBackground`; the bar item and parent rows behind it are
+`surfaceActive`. A bar too narrow for its titles moves the rest behind a
+`moreVertical` entry whose rows open them as submenus; the keyboard walks
+only what is painted. Design notes:
+[design/components.md](../design/components.md#menubar--contextmenu).
+
+**Icons.** `icon` fills the column left of the label, shared with the
+`toggleType` mark (a checked item with an icon shows the check). It is drawn
+locally and never crosses the bus; `iconName` is the icon-theme name a panel
+uses. The column exists only while some row paints in it, so ticking the
+first item of an unticked menu shifts its labels once. Pass a **function**:
+it gets the row's ink and the column size, so one drawing follows the
+highlight and the disabled grey —
 
 ```jsx
 const save = ({ color, size }) => (
@@ -1364,29 +953,19 @@ const save = ({ color, size }) => (
 );
 
 { label: 'Save', icon: save, shortcut: [['Control', 'S']], onSelect: onSave }
-```
-
-Paint the SVG in `currentColor` and the renderer caches it as coverage
-rather than as pixels, so recolouring per row is a composite and every
-colour of the icon shares one rendered copy
-([elements.md](elements.md#svg)). A [system icon](#system-icons) is already
-that, and takes the same two arguments:
-
-```jsx
 { label: 'Close', icon: (p) => <Icon name="close" {...p} />, onSelect: onClose }
 ```
 
-A **string** icon is drawn as text, which is a one-liner — but it is only as
-good as the font, and `✂` or `⏻` is an empty box on a machine without them.
-An element is rendered as-is. `examples/menu.jsx` has a worked set.
-
-The **toggle marks** are system icons for that reason: a checked item is a
-`check`, a radio one a `dot`, and the indeterminate third state a `dash`.
-They used to be `✓`, `●` and `–` set in the row's font, which is the same
-gamble this paragraph tells you not to take.
+— an SVG painted in `currentColor` is cached once for every colour
+([elements.md](elements.md#svg)), as a [system icon](#system-icons) is. A
+**string** icon is drawn as text and is only as good as the font (`✂` or `⏻`
+is an empty box without one); an element renders as-is. Toggle marks are
+the `check`, `dot` and `dash` icons. `examples/menu.jsx` has a worked set.
 
-**Submenus.** Give an item its own `items` and it becomes a submenu parent,
-marked with a `chevronRight` and opening to the side:
+**Submenus.** An item with its own `items` is a submenu parent, marked with a
+`chevronRight`. Nesting is unlimited; each level is a `<popup>` opening to the
+end side, its first item level with its parent row, flipping at a screen
+edge.
 
 ```jsx
 { label: 'Export', items: [
@@ -1395,72 +974,35 @@ marked with a `chevronRight` and opening to the side:
 ] }
 ```
 
-Nesting is unlimited. Each level is its own `<popup>` with `placement:
-'right'`, so it flips to the left near a screen edge like any other anchored
-popup. It hangs off the **menu's** outer edge and lines up with the row that
-opened it — two different nodes, which is what `anchorRect`'s `alignTo` is
-for. Anchoring both to the row would put the submenu inside its parent by
-the menu's border and padding, and the two would overlap.
-
-Lined up on the **items**, not on the boxes: a submenu whose top edge is
-level with its parent row starts its first item a border and a padding
-lower, and what the eye lines up is the text. `anchorRect`'s `alignOffset`
-is the shift that pays for the submenu's own chrome, so the row you came
-from and the row you arrive at are on one line.
-
-**Keyboard.** Up/Down move the active item, **skipping separators and
-disabled entries** and wrapping; Home/End jump to the ends; Right opens a
-submenu (selecting its first item) and Left leaves one; Enter/Space
-activate — or open a submenu, for a parent row; Escape closes **one level
-at a time**. In a `MenuBar`, Left/Right walk between menus _when there is
-no submenu to move through_, and with one menu open, hovering another
-switches to it. Hovering a submenu parent opens it with nothing selected
-inside.
-
-**PageUp/PageDown** step ten rows and then settle on the nearest selectable
-entry in the direction of travel, so a page never lands on a separator or a
-disabled row. Menus size to their content rather than scrolling, so the
-stride is fixed — deriving one from the menu height would just equal
-Home/End.
-
-**Type-ahead.** Typing letters jumps to the entry whose label starts with
-them, in whichever level is deepest open. Keystrokes within 700ms
-accumulate into one query, so `c`,`a` finds _Carrot_ rather than jumping to
-_Apple_ first; repeating a single letter cycles through the entries
-starting with it. Disabled entries and separators are never matched.
-
-Open state is a single path of active indices — one per open level — so
-moving the selection at any level truncates the path and closes deeper
-levels for free.
-
-Both keep focus on a node in the _owner_ window — the popup is
-override-redirect and never takes focus — which is the same arrangement
-`Select` uses. `ContextMenu`'s wrapper is focusable for that reason and
-takes focus when the menu opens.
-
-Switching between `MenuBar` menus reuses the same X window and moves it
-rather than destroying and recreating one, so there is no flicker.
+**Keyboard.** Up/Down move, **skipping separators and disabled entries**,
+wrapping; Home/End jump to the ends; PageUp/PageDown step ten rows, then to
+the nearest selectable one (menus size to content, never scroll); Right opens
+a submenu at its first item and Left leaves it; Enter/Space activate or open;
+Escape closes **one level at a time**. In a `MenuBar`, Left/Right move between
+menus when there is no submenu to move through, and with one menu open,
+hovering another switches to it. Hovering a parent opens its submenu with
+nothing selected. **Type-ahead** works in the deepest open level: 700ms
+queries (`c`,`a` finds _Carrot_), a repeated letter cycles, disabled entries
+and separators never match.
+
+Focus stays in the _owner_ window, as with `Select`; `ContextMenu`'s wrapper
+is focusable and takes focus when its menu opens, but is not a Tab stop
+(`tabIndex={-1}`). Losing the window closes an open menu.
 
 ### Safe-polygon hover
 
-Reaching a submenu means moving the pointer _diagonally_ across the rows in
-between, and reaching a tooltip means leaving the trigger it belongs to — so
-naive hover handling closes both just as the user aims at them. `MenuBar`,
-`ContextMenu` and `Tooltip` therefore use
+`MenuBar`, `ContextMenu` and `Tooltip` keep a submenu or hint open while the
+pointer crosses towards it, using
 [floating-ui's safePolygon](https://floating-ui.com/docs/usehover#safepolygon)
 idea: the triangle between where the pointer was and the near edge of the
-open surface counts as still hovering the parent.
-
-While the pointer is inside that triangle, hover changes are held back —
-but only for `SAFE_HOVER_DELAY` (320 ms), so a pointer that stops there
-still means what it landed on. Leaving the triangle switches immediately,
-and reaching the surface keeps it open for as long as the pointer stays.
+open surface counts as still hovering the parent. Inside it, hover changes
+wait at most `SAFE_HOVER_DELAY` (320 ms); leaving it switches at once, and
+reaching the surface keeps it open.
 
 The helpers are exported for widgets of your own:
 `movingToward(point, apex, rect)`, `safePolygon(apex, rect, buffer)`,
-`pointInPolygon(point, polygon)` and `screenPoint(ev)`. All coordinates are
-**screen** coordinates, because the trigger and the popup are different X
-windows.
+`pointInPolygon(point, polygon)` and `screenPoint(ev)`, all in **screen**
+coordinates, since trigger and popup are different windows.
 
 ## `Tabs`
 
@@ -1484,21 +1026,18 @@ One panel visible at a time, switched by a strip of tabs.
 | `orientation`            | `'horizontal'` (default) or `'vertical'`           |
 | `manual`                 | arrows move focus only; Enter or Space commits     |
 
-`content` may be a node or a function. A function is called only while that
-tab is selected, which is how to avoid building a panel nobody is looking
-at. Items with no `content` at all make `Tabs` a pure navigator — useful
-when the panel lives elsewhere, as in `examples/app.jsx`, where the strip is
-in one half of a `SplitPane` and the panel in the other.
-
-The strip is a **single tab stop**. Left/Right (Up/Down when vertical) move
-and wrap, Home/End jump to the ends, disabled tabs are skipped. Arrows
-select as they move, the way a desktop notebook behaves; `manual` splits
-focus from selection, which is what you want when a panel is expensive.
+`content` may be a node or a function, called only while its tab is
+selected. Items with no `content` make `Tabs` a pure navigator (in
+`examples/app.jsx` the strip is in one `SplitPane` half, the panel in the
+other). The strip is a **single tab stop**: Left/Right (Up/Down when
+vertical) move and wrap, Home/End jump, disabled tabs are skipped. Arrows
+select as they move; `manual` splits focus from selection, for expensive
+panels.
 
 ## `Table`
 
-A grid with a header that stays put, resizable columns, and only the rows in
-view actually built.
+A grid with a fixed header, resizable columns, and only the rows in view
+built.
 
 ```jsx
 <Table
@@ -1522,12 +1061,8 @@ view actually built.
 | `onColumnResize(id, width)`    | after a header drag                                 |
 
 `value(row)` feeds sorting and the default cell text; `render(row, { selected,
-column })` replaces the cell contents entirely.
-
-A `render` is **told when its row is selected**, because the selection is a
-filled bar and a colour picked against the resting background disappears
-into it — a directory in the accent, a failure in red. Fall back to
-`hoverText` there and let the glyph carry the meaning:
+column })` replaces the cell. `selected` is there because a colour picked for
+the resting row can vanish into the selection bar — fall back to `hoverText`:
 
 ```jsx
 render: (row, { selected }) => (
@@ -1537,35 +1072,23 @@ render: (row, { selected }) => (
 );
 ```
 
-**Rows must all be `rowHeight` tall.** That is the price of the table only
-building what is on screen: with ten thousand rows it mounts the twenty or
-so in the viewport and swaps them as you scroll, and everything above and
-below is a single spacer box, so the scrollbar still measures the whole
-list. Sorting a hundred thousand rows is still the caller's problem — pass
-`sort` and sort the data yourself when that matters.
-
-The **table** holds the focus, not the row: a row is unmounted as soon as it
-scrolls out of view, and focus would go with it. Up/Down move the selection,
-PageUp/PageDown by a viewport, Home/End to the ends, and the selection is
-kept on screen without building the rows in between. A click selects, a
-double click activates — the same `onActivate` Enter fires, counted from
-`ev.detail` like any other multi-click.
-
-The header scrolls sideways with the body but never vertically. Between two
-headers there is a hairline rule and, just left of it, a grab band seven
-pixels wide: the separator you see and the handle you hit are not the same
-size, because a boundary wants to be thin and a handle wants to be easy. The
-band is invisible until the pointer is on it and takes the accent while it is
-held, and it is a **sibling** of the header rather than a child of it — a
-click fires on the nearest common ancestor of press and release, so a handle
-inside the header would end every resize with a sort of the column that was
-just dragged. The handle takes focus on the press, so Left/Right resize by
-16px from the keyboard as well.
+**Every row must be `rowHeight` tall**: only the ~20 rows in view are
+mounted, swapped as you scroll, with spacers keeping the scrollbar true.
+Sorting a hundred thousand rows is still yours — pass `sort` and sort the
+data yourself.
+
+The **table** holds focus, not the row (rows unmount off screen). Up/Down
+move the selection, PageUp/PageDown by a viewport, Home/End to the ends; a
+click selects and a double click (`ev.detail`) or Enter fires `onActivate`.
+The header scrolls sideways with the body, never vertically. A seven-pixel
+grab band left of each header rule resizes the column (accent while held,
+no sort on release); it takes focus on the press, so Left/Right then resize
+by 16px.
 
 ## `Tree`
 
-Moved to [`@react-x11/components`](ecosystem.md): a tree wants virtualisation,
-drag-to-reorder and lazy children, none of which core has a reason to carry.
+Moved to [`@react-x11/components`](ecosystem.md): virtualisation,
+drag-to-reorder and lazy children do not belong in core.
 
 ## `SplitPane`
 
@@ -1585,26 +1108,22 @@ Two panes with a divider you can drag.
 | `onResize(size)`       | after a drag or a key step                      |
 | `min` / `minSecond`    | how small either pane may get                   |
 
-Only the first pane's size is stored; the second takes what is left, so a
-window resize can never leave a gap. The drag clamps against the container
-as it is laid out at that moment, so the limits stay honest when the window
-changes underneath it.
-
-The divider is focusable: arrows move it by 16px, Home/End drive it to
-either limit. Dragging captures the pointer, so it keeps tracking after the
-pointer leaves the six pixels it started on, and it keeps the grip where it
-was taken rather than jumping to the pointer.
+Only the first pane's size is stored; the second takes the rest, so a window
+resize never leaves a gap, and the drag clamps against the container as laid
+out at that moment. The divider is focusable: arrows move it 16px, Home/End
+to either limit. A drag captures the pointer and keeps the grip where it was
+taken.
 
 ## `Canvas3D`
 
-Moved to [`@react-x11/components/three`](ecosystem.md) as `<Canvas>`, with
-the scene graph it wrapped. Core keeps the `<glarea>` surface underneath it
-— see [gl.md](gl.md) and `examples/viewer3d.jsx`.
+Moved to [`@react-x11/components/three`](ecosystem.md) as `<Canvas>`. Core
+keeps the `<glarea>` surface under it — [gl.md](gl.md),
+`examples/viewer3d.jsx`.
 
 ## `useAnchor(ref)` / `anchorRect(node, options)`
 
-The placement math behind `Select` and `Tooltip`, exported for building
-your own popup-based widgets.
+The placement math behind `Select` and `Tooltip`, for popup widgets of your
+own.
 
 ```jsx
 const ref = useRef(null);
@@ -1623,39 +1142,29 @@ const rect = measure({ placement: 'bottom', align: 'center', width, height });
 | `at`              | a rect **inside** the node to anchor to instead — a caret, a cell                  |
 | `width`, `height` | size of the popup you are positioning                                              |
 | `alignTo`         | node the alignment reads, when it is not the anchor                                |
-
-`placement` is a **preference, not a promise**: a menu near the bottom of
-the screen flips above its trigger rather than opening off-screen, and the
-result is clamped into the screen either way. The side actually used comes
-back as `placement`. Where screen geometry is unavailable it places without
-clamping.
-
-`'center'` is no side: the popup goes **over** the anchor, middle on
-middle, and is only clamped — `align` and `offset` mean nothing to it. It is
-what a dialog is placed with ([`Dialog`](#size-and-placement)).
-
-`'start'` and `'end'` are the **logical** sides and are what a submenu
-wants: it opens away from the edge its parent's rows begin at, which is
-leftwards in a mirrored menu, and still flips at the screen edge from there.
-`'left'`/`'right'` stay physical. `align` mirrors the same way, but only
-when the popup is above or below its trigger — with one beside it the
-alignment axis is vertical, and nothing vertical mirrors. The direction is
-read off the anchoring node, so a menu inside a mirrored panel needs no
-argument.
-
-`alignTo` takes the two axes from **different nodes**: the placement edge
-from the anchor, the alignment from `alignTo`. A submenu is the case that
-needs it — it belongs against the outer edge of the menu it comes out of,
-but level with the row that opened it, and that row is inset by the menu's
-border and padding. Both nodes have to be in the same window.
+| `alignOffset`     | shift along the alignment axis in px, applied before clamping                      |
+
+`placement` is a **preference**: near a screen edge the popup flips to the
+opposite side, and it is clamped into the screen either way; the side used
+comes back as `placement`. With no screen geometry it does not clamp.
+`'center'` puts the popup **over** the anchor, middle on middle, only
+clamped (`align`/`offset` ignored) — what [`Dialog`](#size-and-placement)
+uses.
+
+`'start'`/`'end'` are **logical** (a submenu opens towards `'end'`, leftwards
+when mirrored); `'left'`/`'right'` are physical. `align` mirrors too, but
+only above or below the anchor. The direction is read off the anchoring
+node. `alignTo` takes the alignment from another node in the same window — a
+submenu sits against its menu's outer edge but level with the row that
+opened it, and `alignOffset` lines its first item up with that row's text.
 
 ### `at` — anchoring to part of a node
 
-`at` is a rect in the **anchor node's own coordinates**, and it becomes the
-anchor: the side that flips, the edge that aligns, the gap `offset` leaves,
-the rect tracking keeps in view. A caret is the case it exists for — a
-moving point inside one element — and a table cell, a chart datapoint or a
-highlighted span are the same shape.
+`at` is a rect in the **anchor node's own coordinates** that becomes the
+anchor — for a caret, a table cell, a datapoint, a highlighted span. `{x, y}`
+alone is a point; the popup `width` then defaults to the sub-rect's. Being
+node-relative, it lets `useAnchorTracking` follow a caret for free, out-of-view
+test included.
 
 ```jsx
 const measure = useAnchor(editorRef);
@@ -1667,51 +1176,33 @@ const rect = measure({
 });
 ```
 
-`width` and `height` are optional (`{x, y}` alone is a point), and `width`
-on the popup then defaults to the sub-rect's rather than the node's.
-
-Node-relative rather than screen-relative on purpose: the offset stays true
-through everything that moves the node, so `useAnchorTracking` follows a
-caret with no extra work — and its out-of-view test becomes the caret's,
-which is what you want, since an editor's own lines scroll away long before
-the editor does.
-
 ### `anchorScreenRect(app, rect, options)` — a rect with no node behind it
 
-The same placement against a rect on the **screen**: the item a tray click
-reports, or where the pointer was. `rect` and the answer are logical screen
-pixels, `{x, y}` alone is a point, and the popup is kept on the monitor the
-rect is on — the one the **whole rect** overlaps most, and the nearest where
-it overlaps none, because a tray item's frame starts just outside its own
-display. With no node to ask, `options.scale` is the display's — it
-defaults to 1 — and `options.direction` decides what `'start'` and `'end'`
-mean. A `<popup>` does this itself with
+The same placement against a **screen** rect in logical pixels — a tray
+item's frame, where the pointer was; `{x, y}` alone is a point. The popup
+stays on the monitor the whole rect overlaps most (the nearest if none).
+`options.scale` is the display's (default 1) and `options.direction` decides
+`'start'`/`'end'`. A `<popup>` does this itself with
 [`anchor={{ rect }}`](elements.md#a-popover-under-a-tray-item).
 
-**A popup that has to measure itself first anchors from the other side.**
-Rows sized to their labels, a menu as wide as its widest item: the size is
-not known until the popup's content is laid out, and by then React has
-already rendered. `<popup anchor={{ to: ref, at }}>` hands the placement to
-the popup, which does it in the one place the size is known —
+A popup that must **measure itself first** (rows sized to labels) cannot
+know its size at render; `<popup anchor={{ to: ref, at }}>` lets the popup
+place itself once laid out —
 [elements.md](elements.md#anchor--a-popup-that-places-itself).
 
 ### `anchorArea(node)`
 
-The rect a popup anchored to `node` may be placed in: the usable part of the
-monitor that node is on — per-monitor, `_NET_WORKAREA` taken off it, the
-same answer [`<window width="auto">`](elements.md#natural-size) is capped
-by. `null` where there is no display to ask.
-
-What needs it is a surface sizing itself: a menu measured to its longest
-label is never usefully wider than the screen it opens on, and `anchorRect`
-can slide a popup back from an edge but nothing rescues one that does not
-fit. `Select` and `ContextMenu` both cap themselves this way.
+The usable part of the monitor `node` is on — panels and docks taken off, the
+cap [`<window width="auto">`](elements.md#natural-size) uses — or `null` with
+no display. A surface sizing itself caps itself to it (`Select` and
+`ContextMenu` do), since `anchorRect` can slide a popup back from an edge but
+not rescue one too big for the screen.
 
 ## `useDropTarget(options)` / `useDragSource(options)`
 
-The render-state layer over the drag-and-drop props, for the cases a
-`':drag-over'` or `':dragging'` style block cannot cover — a hint label, a
-disabled sibling, a drag preview that follows the pointer.
+The render-state layer over the drag-and-drop props, for what a
+`':drag-over'` or `':dragging'` style block cannot do — a hint label, a
+disabled sibling, a preview that follows the pointer.
 
 ```jsx
 const { dropProps, isOver, isAccepted } = useDropTarget({
@@ -1725,25 +1216,16 @@ const { dragProps, isDragging, position } = useDragSource({
 });
 ```
 
-Spread `dropProps` / `dragProps` on any drawn element. Both are thin — the
-props they return are the same ones you can write by hand — so reach for
-them when the render changes, and for the plain props when it does not.
-`position` is `{ x, y, accepted }` in screen coordinates while a drag is in
-flight, which is what a `<popup dragPreview>` follows. Full reference:
-[drag-and-drop.md](drag-and-drop.md).
+Spread `dropProps` / `dragProps` on any drawn element; they are the same
+props you could write by hand, so use them when the render changes and the
+plain props when it does not. `position` is `{ x, y, accepted }` in screen
+coordinates during a drag — what a `<popup dragPreview>` follows. Full
+reference: [drag-and-drop.md](drag-and-drop.md).
 
 ---
 
-The other components — `Button`, `Checkbox`, `Radio`/`RadioGroup`,
-`Switch`, `ProgressBar` — are demoed together in `examples/widgets.jsx`.
-
-The `Select` source (`src/components/Select.js`) is the reference for building
-your own: hover/focus state with `useState`, a `<popup>` for anything that
-must escape the window bounds, and a ref to the trigger node for anchoring
-(`node.abs` + `node.root.window.x/y`).
-
-The window's screen position comes from the server (`TranslateCoordinates`),
-refreshed when the window is realized and whenever it is configured — not
-from `window.x`/`y`. Once a reparenting window manager has put the window
-inside its frame, those are relative to the _frame_, and a popup placed with
-them lands near the corner of the screen instead of under its trigger.
+To build a popup widget of your own, `src/components/Select.js` is the
+reference: state in React, `:hover` style blocks, a `<popup>` for anything
+that must escape the window, `useAnchor` on the trigger. Do not place a popup
+from a window's own `x`/`y` — under a reparenting window manager they are
+frame-relative; `useAnchor` and `ev.screenX`/`screenY` come from the server.