react-x11 2.51.0 → 2.52.0

package/docs/styling.md

@@ -0,0 +1,1928 @@
+# Styling
+
+Style lives in one place: the `style` prop. A style property passed flat is
+an error in development that names the fix, rather than the silent no-op an
+unrecognised prop used to be.
+
+## The rule
+
+One namespace per kind of thing, and no name in both:
+
+- **`style`** — everything CSS has a concept for: layout, paint, text,
+  `cursor`, `overflow`, `zIndex`, `pointerEvents`, `container`.
+- **props** — everything else: `title`, window geometry and size hints,
+  `resizable`, `appId`, `windowType`, `grab`, `value`, `src`, `focusable`,
+  `tabIndex`, `disabled`, handlers. The 3D elements of
+  `@react-x11/components/three`, under a reconciler of their own, keep flat
+  property props (`position`, `material`) — those are object properties, not
+  CSS.
+
+`style` takes an object or a nested array, flattened left-to-right with
+falsy entries skipped. That is what replaces the **selector** cascade:
+precedence is written at the call site instead of resolved by specificity.
+
+```jsx
+<box style={[s.card, isWide && s.wide, { backgroundColor: theme.panel }]} />
+```
+
+Inheritance is a different thing and it does happen — see
+[Inheritance](#inheritance-the-ink-the-face-and-the-size) below. The two are
+easy to conflate because CSS ships them together: what is gone here is
+_matching a rule against a tree_; what remains is a handful of properties
+that travel down it, which is the part that makes a theme, a caption block
+or a dimmed row expressible at all.
+
+## Lengths and shorthands
+
+A length is a distance in **logical pixels**: `12` and `'12px'` are the same
+value, and the display scale turns either into device pixels (see
+[scale.md](scale.md)). Where the layout takes them, `'50%'` and `'auto'`
+mean what they mean in CSS; a border's or an outline's width also takes
+`'thin'`, `'medium'` and `'thick'` (1, 3 and 5).
+
+### Relative units
+
+Every length also takes CSS's relative units, resolved for the node it is
+written on into the same logical pixels:
+
+| unit                       | one of it is                                                                                                          | resolved again when             |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| `em`                       | the node's own font size — and on `fontSize` itself, the size it inherits, so `'1.5em'` is half again its parent's    | an ancestor's font size changes |
+| `rem`                      | the palette's `fontSize`: the size every label that names none is set in, 14 by default                               | the theme changes               |
+| `vw`, `vh`, `vmin`, `vmax` | a hundredth of the window the node is in — the `<window>` or `<popup>`, the size a `'@width >= 600'` block asks about | the window is resized           |
+
+A **percentage on `fontSize`** is of the inherited size, as `em` is. A
+**percentage `borderRadius`** is of the box's shorter side: a corner here is
+a circle, so `'50%'` is a circle on a square and a pill on anything longer,
+where CSS would draw each corner as an ellipse. Everywhere else a percentage
+is the layout's, as before.
+
+`calc()`, `min()`, `max()` and `clamp()` over any of these resolve to one
+number where the style is — `'calc(1rem + 2px)'`, and fluid type as
+`fontSize: 'clamp(14px, 1rem + 0.5vw, 20px)'`. A **percentage takes part
+only alone** (`'calc(100% / 3)'`): yoga takes one unit per value, and what a
+percentage is of is decided inside the layout, so `'calc(100% - 16px)'` is an
+error that says so. Pad a `'100%'` box rather than subtracting from it, or
+give the room to `flexGrow`.
+
+`lineHeight` takes all of CSS's forms and comes to the multiple the text
+engines take: `1.5`, `'150%'` and `'1.5em'` are that multiple, and a length
+— `'24px'`, `'1.75rem'` — is divided by the node's own font size, which is
+what makes a design's "16 on 24" the line it asks for.
+
+What a relative length costs is the re-resolution, and only on the nodes that
+wrote one: a node records what its style read — the inherited size, the
+palette's, the window's — and is resolved again by the walk that already
+carries that change (the text cascade, the theme walk, the size-query
+registry). A style written in pixels reads none of them. Inside an
+`'auto'`-sized window a viewport unit makes the content depend on the window
+that depends on the content; like a size query, it settles where the two
+agree, so size such a window or keep the viewport units out of it.
+
+Some of CSS's units are **not read**, and a value in one is an error naming
+the unit and why — `invalid width "2ex" in <box style>: ex is not read — it
+needs the font's x-height`:
+
+- `ex` and `ch`, which need font metrics nothing measures yet (`0.5em` is the
+  usual stand-in);
+- the container units, `cqw` and the rest: a container's size is known only
+  after a layout pass, and a length in it would lay the tree out again on
+  every frame the container moves — a percentage of the parent, or an
+  `'@container'` block, says the same without that;
+- the print units, `pt`, `mm`, `in`: lengths here are logical pixels, which
+  the display scale turns into device ones.
+
+So is a second value where a property takes one. Yoga's own setters used to
+`parseFloat` whatever they were handed, so `'2ex'` was quietly two pixels.
+
+```jsx
+<box
+  style={{
+    padding: '8px 16px',
+    margin: '0 auto',
+    border: '1px solid $border',
+    borderBottom: '2px solid $accent',
+    background: 'linear-gradient($surface, $background) $surface',
+    ':focus-visible': { outline: '2px solid $accent' },
+  }}
+/>
+```
+
+CSS's shorthands are read the way CSS reads them, and expand into the
+longhands before anything else sees the style:
+
+| shorthand                                         | sets                                                                                      |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `padding`, `margin`                               | the four sides, by CSS's one-to-four rule — `'8px 16px'`, `'0 auto'`, `'1 2 3'`           |
+| `inset`                                           | `top`, `right`, `bottom`, `left`, the same way — `inset: 0`                               |
+| `borderWidth`, `borderColor`                      | the four sides' widths or colours, the same way                                           |
+| `paddingInline`, `marginInline`                   | `…Start` and `…End`: one value for both, or two                                           |
+| `paddingBlock`, `marginBlock`                     | `…Top` and `…Bottom`, the same way                                                        |
+| `gap`                                             | `rowGap` and `columnGap` — `'4px 8px'` is the row gap first, as in CSS                    |
+| `border`                                          | `borderWidth`, `borderStyle`, `borderColor`: `'1px solid $border'`                        |
+| `borderTop`/`Right`/`Bottom`/`Left`/`Start`/`End` | that side's width and colour: `borderBottom: '1px solid $border'`                         |
+| `outline`                                         | `outlineWidth` and `outlineColor`; `'none'` is `outlineWidth: 0`                          |
+| `background`                                      | `backgroundColor` and `backgroundImage` — a colour, a gradient, or both                   |
+| `flex`                                            | `flexGrow`, `flexShrink`, `flexBasis` — `1`, `'auto'`, `'none'`, `'1 1 0'`, `'0 0 240px'` |
+
+A `$token` may stand for any one value inside them — `padding: '$gutter 0'`,
+`border: '$hairline solid $border'` — and resolves before the value is read.
+
+**The more specific property wins, wherever it is written.** A longhand
+beats its shorthand, a side beats all four sides, and a pair beats all four
+too: `paddingTop` beside `padding: '8px 16px'` is the top padding whether it
+comes before or after it in the style. That is the rule `paddingLeft` beside
+`padding: 8` has always followed, and it is not CSS's, which goes by order.
+A flattened style array has no order left to go by — a longhand and its
+shorthand end up as two keys of one object — and "the specific one wins" is
+the rule you can read off a style without knowing how it was assembled.
+
+A part a shorthand leaves out is left unset rather than reset to CSS's
+initial value, since a longhand written beside it would win anyway. Three
+things differ from CSS on purpose, and say so:
+
+- **A line with no width is `medium`, 3px**, as in CSS; but a line with no
+  style is `'solid'` rather than CSS's `none`, because `borderWidth` alone
+  has always drawn here. `'none'` is a width of 0 — `border: 'none'`,
+  `outline: 'none'`.
+- **A line with no colour is [`currentColor`](#currentcolor)**, the node's
+  ink, as in CSS — but the weakest thing in the style rather than whatever
+  came last: a colour the style names for that side anywhere else is the one
+  it takes, so `borderBottom: '1px solid'` beside `borderColor: '$border'`
+  is a `$border` line wherever each is written.
+- **A box has one `borderStyle`.** `border`'s style is the box's, and a
+  side's only speaks when `border` named none; two shorthands naming
+  different ones are an error unless `borderStyle` says which.
+
+What is not here says what to write instead: `font` (the longhands),
+`paddingHorizontal` (React Native's name — `paddingInline`), a per-corner
+radius (`borderRadius` rounds all four), `border-radius` (style names are
+camelCase), and a misspelt name gets the nearest real ones. `background` and
+`outline` are paint all the way down, so a state block may set them;
+`border` sets a width, which is layout, so it may not. A `transition` keyed
+by a shorthand reaches the longhands it expands into —
+`transition: { border: 150 }` fades the `borderColor` a `border` set.
+
+## What it fixes on `<window>`
+
+`width`/`height` on a `<window>` are the real X window's geometry — the user
+can drag them, and `flush()` reads them back — so they must never reach the
+root yoga node. That used to mean stripping them out of the style bag
+(`_yogaProps`), and it forced the size hints to hide inside a `sizeHints`
+object because `minWidth`/`maxWidth` were already taken by yoga.
+
+With the split, both workarounds go:
+
+```jsx
+<window
+  title="Editor"
+  width={900}
+  height={600}
+  x={40}
+  y={40} // the X window
+  minWidth={400}
+  minHeight={300}
+  resizable // WM hints, flat, no nesting
+  style={{ flexDirection: 'row', backgroundColor: '#1e1e1e' }} // the root box
+/>
+```
+
+`WINDOW_HINT_PROPS` is mapped back to ntk's `sizeHints` shape in
+`windowAttributes()`, and `style.backgroundColor` is forwarded as the window's
+creation attribute — the ntk contract is unchanged, only the call site is.
+
+## Inline pseudo-states
+
+The thing inline CSS cannot do, and the reason people keep a stylesheet:
+
+```jsx
+<box
+  style={{
+    backgroundColor: theme.surface,
+    ':hover': { backgroundColor: theme.surfaceHover },
+    ':focus': { borderColor: theme.borderFocus },
+  }}
+/>
+```
+
+`:hover`, `:focus-within`, `:focus`, `:focus-visible`, `:active`,
+`:disabled`, `:drag-over`, `:dragging`.
+These are **node states, not selectors** — each is something the node itself
+already knows, so resolving them needs no specificity and no matching. The
+event manager already tracks the hover path, the press chain and the focused
+node; a state change recomputes one node's style and repaints. **No React
+render.**
+
+Precedence is fixed and low-to-high: `:hover` → `:focus-within` → `:focus` →
+`:focus-visible` → `:active` → `:disabled` → `:drag-over` → `:dragging`,
+merged per property, so a disabled control never looks hovered, a node that
+is itself focused can say something narrower than one that merely contains
+focus, and a drag in progress outranks all of the pointer and focus states.
+Because the hover _path_ is the ancestor chain, hovering a child lights up an
+ancestor's `:hover` block, exactly like CSS.
+
+`:active` is a press, and it follows the same chain for the same reason: the
+node under the pointer is whatever a control happens to be built out of — a
+button's label, a switch's thumb — and it is the control that has to draw
+the press. It is also **live for the whole gesture**: it drops when the
+pointer leaves the chain and comes back when it returns, so `:active` always
+means "releasing now activates this", matching the nearest-common-ancestor
+rule the click itself is synthesized on.
+
+This is not decoration. A control acts on the release, so `:active` is the
+only thing it can show while it is held, and a click held half a second is
+half a second of silence without it. Give every interactive thing one — see
+[components.md](components.md#the-press-state).
+
+```jsx
+<box
+  focusable
+  style={{
+    backgroundColor: theme.background,
+    ':hover': { backgroundColor: theme.surfaceHover },
+    ':active': { backgroundColor: theme.surfaceActive },
+  }}
+/>
+```
+
+A `transition` on the same property is welcome — what matters is that the
+change _starts_ on the press frame, not that it finishes there.
+
+The keyboard has no press state: Space and Enter act on the down, so the
+activation is immediate, but nothing draws held-ness. X reports auto-repeat
+as release/press pairs and neither ntk nor node-x11 implements XKB's
+`DetectableAutoRepeat`, so a held key cannot be told from fast tapping.
+
+`:focus-visible` is focus that came from the keyboard — Tab, an arrow inside
+a widget, `autoFocus`, `node.focus()`, a modal handing focus back as it
+closes. A **press** sets `:focus` and not `:focus-visible`, for the reason
+CSS grew the distinction: the user knows where they clicked, and a ring on
+every click is noise, where a ring on Tab is the only cue a keyboard user
+has. Put focus rings in `:focus-visible` and colour changes that are welcome
+either way in `:focus`.
+
+The exception is CSS's too: a press on a **text control** — `<textinput>`,
+`<textarea>`, or a custom element reporting editable text — does set
+`:focus-visible`. What the click told the user is where the caret went, not
+that every keystroke from now on lands there, and that second fact is what
+the ring is for.
+
+`:focus-within` is focus on this node **or inside it** — CSS's, and the
+answer to "the row should light up while the field in it is being typed
+into", which is the one thing a node's own states cannot say. It is diffed
+over the focused node's ancestor chain, the same walk `:hover` uses, and a
+`<popup>` counts as inside the node it hangs off in the JSX tree, so a
+`Select` with its menu open still reads as focused.
+
+```jsx
+<box
+  style={{
+    borderColor: theme.border,
+    ':focus-within': { borderColor: theme.borderFocus },
+  }}
+>
+  <textinput value={value} onChange={setValue} />
+</box>
+```
+
+The last two belong to drag and drop. `:drag-over` follows the pointer
+during a drag on exactly the same ancestor-path rule as `:hover` — and,
+like `:hover`, it says where the pointer is, not whether the node would
+accept the drop; `useDropTarget`'s `isAccepted` is the one that answers
+that. `:dragging` is set on the source node for the duration of a drag.
+See [drag-and-drop.md](drag-and-drop.md).
+
+**State blocks may only set paint properties** (`backgroundColor`,
+`borderColor` and the per-side `borderTopColor`/…, `borderRadius`, `zIndex`,
+`outlineWidth`, `outlineColor`,
+`outlineOffset`, `opacity`, `color`) — enforced at declaration
+time by `createStyles`. A `:hover` that could set `padding` would reflow the
+tree on pointer move: jitter, and the end of the "hover is a repaint" property
+that makes this worth having. Anything that changes layout or what renders
+stays in React state.
+
+### The focus ring
+
+**Every focusable node draws one already**, on `:focus-visible`, with no
+styling at all — a bare `<box focusable>` included. It is not something an
+application opts into, because a keyboard user cannot opt into needing it.
+A text field gets it from a click as well as from Tab; everything else waits
+for the keyboard (see `:focus-visible` above).
+
+`outlineWidth`, `outlineColor` and `outlineOffset` override it, and they are
+paint properties like any other: animatable, legal in a state block, and
+painted **outside the border box** so switching one on cannot move the thing
+it surrounds. That is the whole reason CSS has `outline` as well as `border`,
+and the reason these are not in the layout vocabulary.
+
+```jsx
+<box focusable />                                  {/* ring, for free */}
+<box focusable style={{ outlineWidth: 0 }} />      {/* opted out */}
+<box
+  focusable
+  style={{ ':focus-visible': { outlineWidth: 3, outlineColor: '#e17055' } }}
+/>
+```
+
+A theme sets `focusRing`, `focusRingWidth` and `focusRingOffset` to restyle
+every ring under it at once — the renderer reads them from the nearest
+`theme` prop, so `<ThemeProvider>` covers the widgets and anything an
+application writes itself.
+
+## Direction, and the logical edges
+
+```jsx
+<box style={{ direction: 'rtl' }}>
+  <box style={{ flexDirection: 'row', paddingStart: 12, gap: 8 }}>…</box>
+</box>
+```
+
+`direction` is CSS's, `'ltr' | 'rtl' | 'inherit'`, and it inherits: setting
+it mirrors that subtree and nothing above it. Rows run the other way, `flex-start`
+is the right-hand end, and every logical edge below swaps sides with it.
+
+**The default comes from the locale.** An app started under
+`LANG=ar_EG.UTF-8` is mirrored with no configuration, because that is what
+GTK and Qt both do and because the alternative is an Arabic desktop where
+one application's panels are on the wrong side. Every locale that is not
+written right to left answers `'ltr'`, so an app that never thinks about
+this pays nothing. The palette carries it — `theme.direction` — so an app
+with a language menu switches the whole UI with the `<ThemeProvider>` swap
+it was already doing for colours:
+
+```jsx
+<ThemeProvider value={{ direction: settings.rtl ? 'rtl' : 'ltr' }}>
+```
+
+Prefer the provider over a bare `direction` style when the region contains
+**widgets**. Yoga mirrors boxes on its own, so most of the widget set needs
+nothing — a `<Checkbox>` is a row with a gap — but the decisions yoga cannot
+make (which way an arrow key steps, which way a chevron points, which side a
+submenu opens on) are read from the palette through `useDirection()`. A
+provider plants the matching style property in the tree as it goes, so both
+routes always agree under one.
+
+### The logical edges
+
+| logical                          | physical in LTR                | in RTL  |
+| -------------------------------- | ------------------------------ | ------- |
+| `start` / `end`                  | `left` / `right`               | swapped |
+| `marginStart` / `marginEnd`      | `marginLeft` / `marginRight`   | swapped |
+| `paddingStart` / `paddingEnd`    | `paddingLeft` / `paddingRight` | swapped |
+| `borderStartWidth` / `…EndWidth` | `borderLeftWidth` / `…Right…`  | swapped |
+| `borderStartColor` / `…EndColor` | `borderLeftColor` / `…Right…`  | swapped |
+
+**A logical edge wins over the physical one even in LTR**, the way CSS's
+`padding-inline-start` wins over `padding-left`. Yoga's full order is
+start/end, then the physical side, then `EDGE_HORIZONTAL`, then
+`EDGE_ALL` — the opposite way round from what the vertical shorthands
+suggest, which is why it is pinned in a test.
+
+Write layout in the logical pair and it is the same layout in both
+directions. Use the physical one when you mean the screen: a drop shadow, a
+resize handle in a fixed corner.
+
+### What does not mirror
+
+- **`<canvas>`** — the drawing is the application's, and `ctx` keeps its
+  top-left origin. An app that wants mirrored art reads `node.direction`
+  from the ref it already has.
+- **A `<window>`'s or `<popup>`'s explicit `x`/`y`** — screen coordinates.
+- **Vertical anything.** `top`/`bottom`, a column's order, a vertical
+  scrollbar's travel, Up/Down on every control.
+- **The caret keys in a field.** Left and Right step through the _string_,
+  not across the screen, and so do Home and End — the editing model is
+  written in logical positions, and visual-order caret motion through bidi
+  text is its own question.
+
+What **does**, besides the box tree: a vertical scrollbar moves to the left;
+horizontal scrolling counts from the right-hand edge, so `scrollX: 0` still
+means "at the beginning"; `textAlign: 'start'`/`'end'` resolve against the
+box's direction rather than against the first strong character; a popup
+prefers the start side, so a submenu opens leftwards and still flips at the
+screen edge; and the inside of a `<textinput>`/`<textarea>` — see below.
+
+### Inside an editable field
+
+A field is laid out at its box's direction, exactly as a `<text>` is, and the
+direction does two separate things there:
+
+- **It is the base level the value is shaped at.** UAX#9 resolves a run of
+  neutral characters — `"(1) 12:30"`, a filename, a lone bracket — against
+  the paragraph level, and "take it from the first strong character" is only
+  the rule for when nobody said. A field that never said reorders an Arabic
+  word typed into an English form as though the whole line were Arabic, in an
+  **LTR** window. So the field says.
+- **It is the edge the text is against.** The value, the placeholder and the
+  caret start at the direction's start edge — the right-hand one under
+  `direction: 'rtl'` — and an unscrolled field still shows the _beginning_ of
+  its value, so a value too long for its box overflows towards the left.
+  Clicking, the caret, the selection bands and the scroll are read from one
+  placement, so they mirror together.
+
+`textAlign` works on a field too: `'start'` (the default) is the base
+direction's start edge, and `'center'`/`'end'` do what they say while the
+value fits. A value that overflows its box is pinned to the start edge
+whatever the alignment says, because that is what it is scrolled from.
+
+The text's _own_ direction is not consulted: a Latin value in an RTL field is
+placed at the field's right edge, the way `<input dir="rtl">` places one, and
+there is no `dir="auto"` equivalent yet.
+
+## Per-side borders
+
+```jsx
+<box
+  style={{ borderLeftWidth: 3, borderLeftColor: '$border', paddingLeft: 10 }}
+>
+  {children} {/* a blockquote bar, no extra node */}
+</box>
+```
+
+A side width overrides `borderWidth` exactly the way `paddingLeft`
+overrides `padding`, `borderBottom: '1px solid $border'` sets one side's
+width and colour together, and a side colour
+(`borderTopColor`/`Right`/`Bottom`/`Left`) falls back to `borderColor`.
+`borderStartWidth`/`borderStartColor` and their `End` counterparts are the
+[logical](#the-logical-edges) pair, and they win over the physical side. The
+widths are layout — yoga sees each edge, so the bar above insets content on
+the left only — and the colours are paint, legal in a state block like
+`borderColor` itself.
+
+This is what a rule or an accent edge should be built from: a blockquote's
+bar, a table's row separators (`borderBottomWidth: 1` on each row), a tab's
+underline. Composing the same line out of 1px `<box>`es works but pays a
+node per row into layout and paint, and scatters what is really one style
+value ("the table's border colour") across the tree.
+
+Two edges of the v1 shape:
+
+- **`borderRadius` requires uniform borders** — same width and colour on
+  all four sides. A non-uniform border paints square, ignores the radius,
+  and says so once in development; bars and rules are square, so this costs
+  nothing real.
+- Corners between two painted sides of different colours are square and
+  deterministic: top and bottom span the box's full width, left and right
+  run between them. CSS mitres that corner diagonally; nothing built from
+  bars and rules can tell the difference.
+
+## Gradients and shadows
+
+The two decorations a UI asks for after colour and radius, and the two that
+used to mean giving up on `<box>` and drawing the panel by hand:
+
+```jsx
+<box
+  style={{
+    padding: 16,
+    borderRadius: 10,
+    backgroundImage: 'linear-gradient(135deg, $accent, $accentActive)',
+    boxShadow: '0 2px 8px rgba(0, 0, 0, .4)',
+    ':hover': { boxShadow: '0 6px 20px rgba(0, 0, 0, .5)' },
+  }}
+>
+  <text style={{ color: '$accentText' }}>Header</text>
+</box>
+```
+
+Both are **paint** properties: legal in a state block, and outside layout
+entirely — a gradient fills the box the layout already decided on, and a
+shadow is drawn beyond it and moves nothing. Both are written in CSS's
+spelling, because both are values people already know by heart, and a
+`$token` resolves **inside** them as well as as a whole value, which is what
+keeps a themed decoration in a hoisted style.
+
+### `backgroundImage`
+
+`linear-gradient(<direction>?, <stop>, <stop>, …)` or `'none'`, resolved
+against the node's own box so it works wherever the node lands.
+
+- The direction is an angle in degrees clockwise from "up" (`135deg`), a side
+  (`to right`), or a corner (`to bottom right`). Left out, it is `to bottom`.
+- A stop is a colour, optionally followed by a `%` or a pixel position.
+  Positions left out are spread evenly; one that goes backwards is pulled up
+  to the one before it, so two stops at the same offset are a hard break.
+- It paints **over** `backgroundColor`, which is CSS's order — a translucent
+  gradient tints the colour underneath it rather than replacing it.
+
+Only linear gradients exist. A radial or conic one is a `<canvas onDraw>`
+away (`createRadialGradient` draws on every backend but Windows', and
+ntk's context has `createConicalGradient`),
+and CSS's sizing keywords for them are most of the work for very little of
+the demand.
+
+One cost worth knowing, because it is not where anyone would look for it: a
+gradient is a server-side source picture, so a **square** one is as cheap as
+a colour — but a **rounded** one is not. ntk's rounded-rect fast path (cached
+corner glyphs plus `FillRectangles`) only takes a solid colour, so a rounded
+gradient falls back to a coverage mask rasterized on the client and uploaded
+per fill: about 4 KB per box per repaint. Damage bounding means that is only
+paid where something changed, but a list of rounded gradient rows is the one
+shape to think twice about — see the `shapes: 24 gradient+shadow cards`
+scenario in `npm run bench`, which prices it.
+
+### `boxShadow`
+
+`<x> <y> [blur] [spread] [colour]`, comma-separated for several, painted
+first-on-top like CSS's. The colour may be left out, which means the node's
+own `color` — [`currentColor`](#currentcolor), which may be written out
+too. A blurred shadow is a real gaussian — RENDER's convolution over a
+coverage surface — cached by size, radius and blur, so a list of identical
+cards renders one and composites it many times.
+
+On macOS and Windows, which have no X server to bake one on, the shadow is
+the 2d context's own `shadowBlur`, and the context draws a rounded rect's
+shadow from a tile it makes once and stretches — see
+[macos.md](macos.md#a-shadow-from-a-tile). The rest of this section is the
+X11 route.
+
+The blur is **baked into the cached surface's pixels**, in two separable 1-D
+passes, rather than left as a filter on its picture. That is not an internal
+detail: XRender applies a picture's filter on every composite, so a shadow
+whose blur rode on the picture paid its whole kernel again every frame it was
+drawn — a card-sized coverage surface at a wide blur is hundreds of millions
+of multiply-accumulates, in the server, per shadow, per repaint. Baked, a
+repaint composites a plain mask however wide the blur is, and the convolution
+runs once per distinct geometry.
+
+What it does not do, and why:
+
+- **`inset` throws.** An inner shadow is a different drawing and a different
+  damage story, and painting an outer one where an inner was asked for is a
+  bug with no visible cause. An inset border or a `<canvas>` says it today.
+- **Ignored on `<window>` and `<popup>`** (with a warning in development). A
+  shadow is painted outside the box, and a toplevel owns no pixels there —
+  a real one needs the window to carry a translucent margin of its own,
+  which is a feature rather than a line in the painter. Put the shadow on a
+  `<box>` inside the window; for a floating menu, the popup's own
+  `borderRadius` plus a border is what reads as raised today.
+- **Neither transitions.** Both are several numbers and a colour in one
+  string, and `interpolate` moves one value; they snap. A card that wants to
+  rise on hover animates the `backgroundColor` or the border beside them.
+
+A shadow is the first thing in this vocabulary that inks pixels the node
+does not own, so it also widens what the node repaints — its offset, its
+spread and the blur's tail — and the frame that _removes_ one claims where
+it was. That is the renderer's business, not the application's, but it is
+the reason a shadow is not free the way a colour is: prefer one shadow on
+the card to one on every row inside it.
+
+## Opacity
+
+`opacity` fades a node **and everything in it, as one**, the way CSS's does:
+
+```jsx
+<box style={{ opacity: enabled ? 1 : 0.5, transition: { opacity: 150 } }}>
+  <svg viewBox="0 0 16 16">…</svg>
+  <text>Reminders</text>
+</box>
+```
+
+That is the difference from a colour's own alpha. `rgba(…, .5)` on a card's
+background fades the background; it cannot fade the card, because every part
+of it — the border, the icon, the caption — is drawn over the others, and at
+half alpha each one shows what is under it: the card through the icon. With
+`opacity` the subtree is drawn once, into an offscreen surface the size of
+what it paints, and the surface is composited at the alpha.
+
+It is a **paint** property: legal in a state block, and it transitions and
+loops like the others — a halo that pulses, a section that fades in:
+
+```jsx
+animation: { opacity: { from: 1, to: 0.5, duration: 800, alternate: true } }
+```
+
+What it costs is that surface: one per faded node, the size of its paint
+bounds inside the window, kept from one frame to the next while the node stays
+faded and released when it is opaque again. `0` draws nothing and costs
+nothing — and the node is still laid out and still hit, as in CSS. A value
+outside 0 to 1 is clamped; one that is not a number throws in development.
+
+On the Cocoa backend a faded box is drawn into the window's bitmap like this
+rather than lifted onto a layer of its own (docs/macos.md): a box and its
+content on separate layers would fade one over the other, which is the thing
+`opacity` exists not to do.
+
+## Measuring text to its letters
+
+```jsx
+<text style={{ fontSize: 24, textBoxTrim: 'cap-alphabetic', padding: 12 }}>
+  HEX
+</text>
+```
+
+`textBoxTrim` is CSS's `text-box-trim: trim-both` with `text-box-edge: cap
+alphabetic`: the `<text>`'s box becomes the capitals down to the last
+baseline, so padding around a label is measured from the letters and
+centring centres what you can see. Default `'none'`.
+
+The problem it solves is that **a line box is not the text**. It is the
+font's ascent plus its descent plus its line gap, and the space over a
+capital differs from the space under a baseline by `(ascent - capHeight) -
+descent` — a property of the typeface, so a label is only ever optically
+centred by luck. With the KaTeX face the tests use, a 24px label in a 12px
+padded box sits 17px below the top and 18px above the bottom; trimmed, it is
+12 and 12.
+
+**`lineHeight` is not an alternative.** It is a multiplier over the natural
+line box and the leading still splits evenly above and below, so it moves
+both edges by the same amount — it can change how much space there is, never
+how it is balanced.
+
+Two things worth knowing:
+
+- It applies to `<text>`. `<textinput>` and `<textarea>` keep their full line
+  box, because their caret and selection geometry is measured against it.
+- Trimming removes real space, so a control gets shorter: size the padding
+  for the result you want rather than to whatever the metrics happened to
+  add.
+
+**The built-in widgets set it on every label**, which is why `paddingY` in a
+palette is bigger than a CSS padding for the same look — it is the space you
+see, not the space plus whatever the ascent left over. Which way a face is
+off changes with the face: at 14px, SF NS leaves 3.7px above the capitals
+against 2.9px below the baseline, so an untrimmed label rides low, while
+Helvetica leaves 0.7 against 3.2 and it rides high. A widget cannot correct
+for that, because it does not know the face it will be drawn in.
+
+A glyph drawn as text — a check mark, a submenu arrow, an icon — is centred
+on its own middle rather than sitting on a baseline, so trimming its box
+moves it off centre. Those keep the full line box, and so should yours.
+
+`<textinput>` cannot trim — its caret and selection are measured against the
+full line box — so it reaches the same place from the other side: its **box**
+is the cap band, its baseline goes where the space above the capitals equals
+the space under it, and the glyphs are allowed to hang out of the box the way
+a trimmed label's descenders do. The drawing is clipped one step out, at the
+padding box, so an ascender and a descender are both there and neither can
+reach the border. The caret and the selection follow, being drawn from the
+same origin.
+
+That is what makes a field the same height as the controls beside it. Padding
+it with the palette's `paddingY` gives exactly the height a `<Button>` and a
+`<Select>` have, because all three are now the same sum — the capitals, plus
+that padding twice, plus the border:
+
+```jsx
+<textinput
+  style={{
+    paddingTop: '$paddingY',
+    paddingBottom: '$paddingY',
+    paddingLeft: 10,
+    paddingRight: 10,
+    borderWidth: '$borderWidth',
+  }}
+/>
+```
+
+`<textarea>` keeps its full line boxes, box and clip both: it is line spacing
+that a paragraph is made of, and nothing hangs out of a stack of them.
+
+## Keeping text on one line, and saying when it did not fit
+
+```jsx
+<text style={{ textWrap: 'nowrap' }}>{row.modified}</text>
+```
+
+`textWrap: 'nowrap'` is CSS's, and it is what separates a cell from a
+paragraph. A `<text>` measures height-for-width: hand it a narrow box and it
+wraps to fit, which is right for prose and wrong for a row of a fixed height —
+a date that wraps to two lines is not a taller row, it is a line and a half of
+date with the rest sliced off, top and bottom, spilling over the rows either
+side on the way. `'nowrap'` measures at unbounded width, so the overflow is
+horizontal, which `overflow: 'hidden'` on the box around it already knows what
+to do with. Default `'wrap'`.
+
+A date is the case that wants exactly that: it is a fixed width, it always
+fits, and clipping it would be a bug rather than a design. A **name** is not.
+Clipped, a truncated file name and a short one look equally complete, and the
+reader has no way to tell which they are looking at:
+
+```jsx
+<text style={{ textWrap: 'nowrap', textOverflow: 'ellipsis' }}>
+  {file.name}
+</text>
+```
+
+`textOverflow` is CSS's `text-overflow`: `'clip'` (the default) slices
+mid-glyph, `'ellipsis'` ends the line in a `…`. It is the careful version, not
+a substring —
+
+- the `…` is set in the font of the run it cut into, so an elided line ending
+  in a large or bold word gets a matching mark rather than one in the
+  paragraph's base style, and it falls back to `...` where neither that font
+  nor any fallback covers U+2026;
+- the cut is at a grapheme boundary and the tail is **re-shaped**, because
+  kerning and ligatures across the cut change widths;
+- it cuts the **visually** last run rather than the logically last one, so a
+  right-to-left line ends on its left.
+
+`maxLines` is the other half — CSS has no single-property spelling for it
+(`-webkit-line-clamp` is what everyone actually writes), so this is the name
+the platforms that got a clean shot at it chose. A three-line blurb that ends
+in a `…` is `{ maxLines: 3, textOverflow: 'ellipsis' }`; the lines past the
+cap are dropped before the box is measured, so the height is the kept lines'
+and not the whole paragraph's.
+
+**`textOverflow: 'ellipsis'` on its own means one line.** Eliding happens off
+a line count — the mark stands for the lines that were dropped — so an
+ellipsis with no cap would have nothing to say and would silently do nothing.
+One line is what a name, a path or a status line wants; `maxLines` is how to
+ask for two or three.
+
+### What `nowrap` and `ellipsis` do together
+
+They are not in tension, but they change what the `<text>` reports to layout,
+which is worth knowing before a row moves under you.
+
+A clipping `nowrap` label is measured at unbounded width, so it tells its
+container it needs the **whole string** — and CSS's automatic minimum size
+turns that into a floor. It cannot be squeezed, so a long name pushes the
+column next to it out of the row and the overflow is dealt with somewhere
+above.
+
+An eliding one is measured against the width on offer, because at unbounded
+width there is one line, one line is never over the cap, and nothing would
+ever be cut. So its floor is small and it **gives way**: it takes the room
+that is left, shows `Applicati…`, and the column beside it keeps its width.
+That is the behaviour a table wants — a column that cannot show a file name
+should say so rather than making every other column narrower to avoid it.
+
+`<Table>` sets `nowrap` and `ellipsis` on every cell and header for that
+reason.
+
+What is truncated is a fact about the pixels and nothing else. A `<text>` that
+was elided still reports the **whole** string as its accessible name, and the
+caret and selection indices still index into the whole string — a screen
+reader that read `Application Sup…` would be reading the layout instead of the
+content.
+
+## Inheritance: the ink, the face and the size
+
+Ten properties travel down the tree, and they are the ones CSS calls
+inherited:
+
+| property                |                                            |
+| ----------------------- | ------------------------------------------ |
+| `color`                 | the ink                                    |
+| `fontFamily`            | the face                                   |
+| `fontSize`              | the size                                   |
+| `fontWeight`            |                                            |
+| `fontStyle`             |                                            |
+| `fontVariationSettings` | a variable font's remaining axes           |
+| `textRendering`         | how glyph origins are rounded at draw time |
+| `letterSpacing`         | the space after every character            |
+| `fontVariantNumeric`    | which figures: tabular, oldstyle…          |
+| `fontFeatureSettings`   | any other OpenType feature, by tag         |
+
+So a block of quiet type is a `<box>` and not a decision repeated at every
+label inside it:
+
+```jsx
+<box style={{ color: theme.textMuted, fontSize: 12 }}>
+  <text>Last modified</text>
+  <text>{row.modified}</text>
+  <Icon name="moreVertical" />
+</box>
+```
+
+A style property on the node itself still wins, the way a property always
+wins over what a node inherits — and under the outermost element is the
+palette, so text that names none of this is set in the theme's `text`,
+`fontFamily` and `fontSize` ([theme tokens](#theme-tokens) below).
+
+It reaches everything that draws with type, not just `<text>`: a
+`<textinput>`, a `<canvas mono>` (which is what an `<Icon>` is), an `<svg>`
+resolving `fill="currentColor"`, and any custom element
+that asks `node.resolvedTextStyle()`
+([extending.md](extending.md#text-of-your-own)). A nested `<text>` span is
+the same mechanism seen from closer up.
+
+**A `:hover` block that sets `color` therefore reaches the labels inside.**
+That is how CSS behaves and it is why there is no "group hover" here to
+learn: `:hover` marks the row, `color` is inherited, and the row's label and
+its icon follow.
+
+```jsx
+<box style={{ color: theme.text, ':hover': { color: theme.accent } }}>
+  <text>Open recent</text>
+  <Icon name="chevronRight" />
+</box>
+```
+
+Nothing about that costs a layout pass. A state block may only set paint
+properties and `color` (see above), so the only inherited property a pointer
+can ever move is the ink — which drops the memoised text layouts under it
+and repaints, with no re-measuring and no reflow. A `fontSize` change
+_does_ re-measure, and it can only come from a React commit, a size query or
+a theme.
+
+What does **not** inherit: `textAlign`, `lineHeight`, `textWrap`,
+`textOverflow`, `maxLines` and `textBoxTrim`. CSS inherits the first two;
+here they are read by the node that owns the **box** the text flows in, and a
+box is not something a descendant has. `<Icon>`'s `size` does not inherit either — a glyph is a
+drawing rather than a letter, so it takes its default from the palette's
+`fontSize` and stays put when a label around it shrinks.
+
+**A value that is not one inherits.** `fontSize: '1.2ex'`, `fontStyle: 7`,
+`fontWeight: 1200` or `lineHeight: 'tall'` is an error at the commit in
+development, naming the property; where one gets past that — a `$token`, or
+a production build — the text sets as though it had not been written, the way
+CSS inherits past a declaration it cannot parse. Numbers may be numeric
+strings (`fontSize: '20'`), as they always could, and a size is a
+[length](#lengths-and-shorthands) like any other: `fontSize: '20px'` is 20,
+and `'1.5em'` or `'150%'` is half again the size inherited. A `lineHeight`
+in a length — `'24px'` — is that multiple of the node's own size. Before, a
+size in px set no text at all and the others threw from inside a frame.
+
+### `currentColor`
+
+The ink as a colour: `currentColor` is the node's own `color`, or the one it
+inherits. It goes wherever a colour does — `backgroundColor`, `borderColor`
+and each side of it, `outlineColor`, a `boxShadow`'s colour, a gradient stop,
+and inside `border`, `outline` and `background` — and a line those
+shorthands give no colour is drawn in it, as in CSS:
+
+```jsx
+<box style={{ color: theme.textMuted, ':hover': { color: theme.accent } }}>
+  <box style={{ borderBottom: '2px solid' }}>
+    <text>Inbox</text>
+  </box>
+</box>
+```
+
+The label and its underline turn together, and nothing re-renders. It is
+CSS's keyword in any case CSS takes it (`currentcolor` reads too), and on
+`color` itself it is the colour inherited — CSS's `inherit`.
+
+It stays the keyword in the node's style, which is CSS's computed value, and
+becomes a colour where it is painted, so it follows the ink wherever the ink
+moves: a `:hover` on a row above, a theme swap, a `color` transition frame by
+frame. A node painting in it repaints when its ink moves, bounded to that
+node, and a box does too although it draws no text; one that paints nothing
+in it still costs nothing when the ink above it moves. A `<popup>` written
+under the row inherits the ink like any other child and repaints with it.
+
+Two places it cannot simply follow:
+
+- **A transition runs between the colours at the swap.** `borderColor`
+  going from `'#d0d0d0'` to `'currentColor'` under a `transition` fades to
+  the ink as it is when the style changes, and lands on the keyword, which
+  follows the ink from then on. An ink moving under a `currentColor` that
+  stayed is not a change of the property and does not transition: the border
+  is the new ink at once. To fade it, transition `color`, and the border
+  rides along.
+- **A loop cannot end in it.** A loop's ends are fixed for as long as it
+  runs, so `animation: { borderColor: { to: 'currentColor', … } }` is an
+  error saying so. Loop `color` instead, and write the border in
+  `currentColor`.
+
+An element of your own that paints a colour from its style asks
+`node.resolveColor(value)` for it
+([extending.md](extending.md#text-of-your-own)).
+
+## A font file of your own
+
+An app that ships a face, or that shows one — a picker, a specimen, a
+preferences page with a family name in it — asks for the file by path (or by
+bytes) and gets back what to draw it with:
+
+```jsx
+import { loadFont } from 'react-x11';
+
+// `app` is the ntk connection — the one `createRoot({ app })` took, or
+// `useApp()`'s inside a tree
+const { font, family } = loadFont(app, '/path/to/Inter.ttf');
+
+<text style={{ fontFamily: family, fontSize: 20 }}>Handgloves</text>;
+```
+
+`family` comes **off the file** rather than out of the caller's head: it is
+the font's own name, so an app that ships `Inter.ttf` goes on writing
+`fontFamily: 'Inter'` in the styles it already has, and a registered face
+beats fontconfig for that name — which is the point of shipping one. Several
+faces of one family — regular, bold, italic — all keep the name and
+`fontWeight` picks between them. Only a second file that would be
+_unreachable_ under it, the same family at the same weight and slant, is
+scoped: that one comes back as `Inter 2`. Draw with the name that comes back
+and the question never arises.
+
+`loadFont(app, path, { family: 'preview' })` names it yourself instead —
+worth doing for a file the _user_ picked, to keep it out of the way of the
+app's own type. `weight` and `style` override what the file claims about
+itself, and `postscriptName` picks one face out of a `.ttc`.
+
+From a component, `useFont` is the same thing with the connection already in
+hand, and it returns null before anything is picked:
+
+```jsx
+function Specimen({ path }) {
+  const picked = useFont(path); // path may be null
+  return <text style={{ fontFamily: picked?.family }}>Handgloves</text>;
+}
+```
+
+A file that will not parse throws, which an error boundary is the right home
+for when the app ships the font and the wrong one when a user just chose it
+in a dialog — reach for `loadFont` in that handler and catch there.
+
+### Reading a font without installing it
+
+`openFont(app, source)` reads the file and changes nothing else:
+
+```js
+const font = openFont(app, path);
+font.metrics(30); // what the renderer lays out with
+font.variationAxes; // { wght: { name, min, default, max } }
+font.hasGlyph(0x20b8); // is the tenge sign in this face?
+```
+
+The difference from `loadFont` is worth knowing before a font browser picks
+one over the other. Registering a face does not only make a `fontFamily`
+resolve to it: every registered font is consulted, ahead of the system
+fonts, for **any codepoint the current face is missing**. That is exactly
+what an app shipping a symbol or icon face wants, and exactly what an app
+that is merely _previewing_ files does not — it would quietly change which
+face draws the bullets and the curly quotes in its own UI.
+
+Both verbs read a given file once per connection, however often they are
+called: the face is cached in the app's font manager, so `useFont` in a
+component that re-renders sixty times a second parses nothing, and
+`loadFont` after `openFont` on the same path registers the face already
+open. This matters more than it looks — a second copy of a font is a second
+glyph cache and a second server-side glyphset, and a node built against one
+copy cannot be painted by the other.
+
+`font` is ntk's `Font`, which has more on it than the four members above
+([ntk's docs/fonts.md](https://github.com/sidorares/ntk/blob/master/docs/fonts.md)). If you need
+anything else of ntk's — `Path2D`, `Image`, `Surface` — **import it from
+`react-x11/ntk`, never from `ntk`**, and never declare `ntk` as a dependency
+of your own. Two copies in one process are two font caches and two glyph
+atlases, with the same consequence as above and a great deal further from
+its cause.
+
+## `createStyles`
+
+Identity is the point — a hoisted style object lets `applyProps` skip the
+whole update with a `===` check, the same reason RN's `StyleSheet.create`
+still exists now that its id registry is gone. It also validates keys, which
+a bare object literal cannot: an unknown style property is an error at
+declaration instead of a silent no-op.
+
+## `flattenStyle`
+
+`flattenStyle(style)` collapses whatever the `style` prop accepts — an
+object, an array, nested arrays, holes — into one plain object, which is what
+the reconciler itself does before applying props. Two details are worth
+knowing if you call it: a lone object is returned **as-is**, not copied, so
+`===` still identifies a hoisted style; and a state block merges with one
+already collected rather than replacing it, so
+`[{ ':hover': { color } }, { ':hover': { backgroundColor } }]` keeps both.
+
+## In components
+
+Every component takes `style` and merges it after its own, so an override
+wins by position instead of clobbering a computed value:
+`style: [control.style, base, checked && on, style]`.
+
+`useControl(disabled, onActivate, { styled: true })` stops holding hover,
+focus and the press in React state: no enter/leave handlers, no re-render on
+pointer move. `Switch` and `Button` are the worked examples. Without it the
+hook returns `hover`/`focused`/`pressed` as React state, which is what a
+control needs when the part that has to change is not on the press chain —
+a `Checkbox`'s well is a sibling of the label the press lands on, and no
+node-local state block can cross that.
+
+A component's own props are never style. `ProgressBar` takes `color`,
+`Dialog` takes `width`/`height` — a dialog is a real popup window and needs
+its geometry up front — and `ContextMenu` takes `fontSize` because it
+measures labels with it. `Select` and `Slider` used to take `width` purely
+to put it in their own box; that is `style={{ width }}` now.
+
+## Theme tokens
+
+A style value of `'$name'` resolves against the nearest theme above the node
+— `<ThemeProvider value={palette}>`, or a `theme` prop on any element. The
+sigil is what keeps it unambiguous: `'red'` is a CSS colour, `'$red'` is a
+token.
+
+```jsx
+const s = createStyles({
+  card: { backgroundColor: '$panel', padding: '$gutter' },
+  title: { color: '$text', fontSize: 20 },
+});
+
+<window theme={palette} style={{ backgroundColor: '$bg' }}>
+  <box style={s.card}>…</box>
+</window>;
+```
+
+That is the point of tokens: the style is **hoisted** — declared once,
+outside render, with no access to React context — and still follows the
+theme. Without them a palette has to be threaded to every element that
+paints (`style={[s.card, { backgroundColor: theme.panel }]}`).
+
+Tokens are not colour-only; `padding: '$gutter'` resolves a number just as
+well. And they resolve wherever a style value is written: in a state block, in
+an `animation` declaration, and in a size, container or capability query block
+— `'@width >= 600': { padding: '$gutter' }` is the wide layout's gutter from
+the same palette.
+
+Three of them are read with no `$` anywhere, because they are what text falls
+back to rather than something a style asked for: **`text`, `fontFamily` and
+`fontSize` are the ink, the face and the size of every `<text>` that names
+none of its own** ([components.md](components.md#theming)). They are the floor
+under [inheritance](#inheritance-the-ink-the-face-and-the-size) — what a node
+resolves to when no element above it named one either — which is what makes
+`<ThemeProvider value={{ fontFamily: 'Inter' }}>` a sentence an app says once.
+A style property still wins over it, the way a style property always wins over
+what a node inherits:
+
+```jsx
+<window theme={{ fontFamily: 'Inter', fontSize: 16 }}>
+  <text>Inter at 16</text>
+  <text style={{ fontFamily: '$monoFamily' }}>the palette's mono face, 16</text>
+  <text style={{ fontSize: 24 }}>Inter at 24</text>
+</window>
+```
+
+**The floor is read from the window, not from the nearest provider.** That is
+the sentence to remember, because the failing shape looks right: a
+`<ThemeProvider value={palette}>` _inside_ a `<window>` feeds `useTheme()` and
+resolves every `$token` under it, so the styles that name a face get one — and
+every `<text>` that names none still falls back to the **window's** palette,
+which is the desktop's `sans-serif` unless the window itself was given a
+theme. An app that ships its own fonts then draws its headings in the face it
+shipped and its body copy in whatever the machine calls sans-serif, which is
+both wrong and slow: resolving a generic family costs an `fc-match` per weight
+on the first paint (~110ms each here).
+
+Three ways to say it. For a whole app the first says it once, for the widgets
+and every window; the last is the one for a subtree:
+
+```jsx
+<ThemeProvider value={palette}>     {/* above the windows: they take it */}
+  <App />
+</ThemeProvider>
+
+<window theme={palette}>            {/* the floor, for everything inside */}
+
+<box style={{ fontFamily: '$fontFamily', color: '$text' }}>
+  {/* or hand the face to a subtree by inheritance, which needs no window */}
+</box>
+```
+
+`monoFamily` has no such fallback — nothing is monospace unless it says so, and
+that is what the `$` above is for. It is a token so that the code surfaces of
+an app, which are written by components that never meet, can be set from one
+place.
+
+A `theme` prop anywhere scopes its subtree, and an inner one merges over the
+outer, so a panel can restate a colour or two without repeating a palette.
+Popups resolve through their place in the **tree**, not their window, so a
+menu inherits the theme of the UI that opened it even though it is a
+separate X window.
+
+Note that a raw `theme` prop is exactly the object you wrote: it merges, but
+nothing is computed from it. The widget palette's derived tokens — the
+pressed `accentActive`/`surfaceActive`/`textMutedActive`/`dangerActive`, the
+`…Text` ink on each fill, and `surface` following `background` — are filled in
+by `<ThemeProvider>`, which plants the resolved palette in the tree for this
+lookup to find. Hand-writing `theme={{ accentHover: … }}` on a box gets the
+merge and not the derivation.
+
+Changing the theme restyles the subtree in place. Nodes whose own props did
+not change are still updated — which is why a theme change also drops the
+memoised text layouts under it, or cached text would keep painting the old
+colour.
+
+An unknown token is **reported and dropped**: the message names the token,
+the element, the component that wrote it, and every token the palette in
+force does have; that one property goes missing, so the widget paints
+visibly wrong rather than the app dying; and `process.exitCode` is set to 1,
+so a test run, a CI job or a supervisor still counts the run as failed.
+
+That is deliberately not a throw. Resolution happens when a node's ancestry
+completes — inside a commit, and also from an X event when the desktop
+switches between light and dark — and on both of those paths a throw is
+uncatchable: it either lands on the `<window>` fiber above every error
+boundary the app wrote inside it, or it unwinds into the frame loop with no
+React on the stack at all. One wrong character in a style value should not
+be able to blank the screen.
+
+Set **`REACT_X11_STRICT_TOKENS=1`** to make it fatal again — for a kiosk, or
+a build that would rather stop than paint something wrong. Strict mode also
+throws in the right _place_: the error is raised from the offending node's
+own `commitMount`, so an error boundary at any depth inside the window
+catches it and shows a fallback for that subtree. Where React genuinely is
+not on the stack — the desktop appearance switch — strict mode crashes,
+which is what it was asked for.
+
+A token with **no** theme above it at all warns in dev — that one is
+otherwise silent, since the whole style is stripped rather than one value
+failing. Resolution is cached per (style object, theme object), so a hoisted
+style under one theme keeps its identity across renders and the `===` fast
+path still applies; a misspelling in a shared style is reported for every
+node that wears it, not just the first.
+
+Resolution walks the node tree, not React context, so a palette has to reach
+the tree to be seen. `<ThemeProvider>` puts it in both places — the context
+widgets read with `useTheme()`, and a `theme` prop on a node — which is what
+makes provider and token one mechanism rather than two
+([components.md](components.md#theming)). Widgets plant their own merged
+palette on their root node as well, so `$tokens` work inside a widget
+subtree — and in a style you pass one — with no provider anywhere.
+
+With no `theme` prop above it at all, a token resolves against **the
+desktop's palette** — `backgroundColor: '$background'` in an app that never
+wrote a `<ThemeProvider>` is dark on a dark desktop, which is how that app
+blends in ([appearance.md](appearance.md)). A token no palette defines is
+reported the same way, naming every token the one in force does have.
+
+## Sticky positioning
+
+`position: 'sticky'` is CSS's: the box is laid out in flow, exactly where
+`relative` would put it, and then held inside the nearest scroll pane by its
+insets. `top: 0` keeps a section's header at the top of the pane while the
+section scrolls under it — until the section's end arrives and carries the
+header off, which is how the next section's header takes over.
+
+```jsx
+const s = createStyles({
+  pane: { overflow: 'scroll', flexGrow: 1 },
+  section: { flexShrink: 0 },
+  header: { position: 'sticky', top: 0, backgroundColor: '$background' },
+});
+
+<box style={s.pane}>
+  {groups.map((group) => (
+    <box key={group.letter} style={s.section}>
+      <text style={s.header}>{group.letter}</text>
+      {group.people.map((person) => (
+        <Row key={person.id} person={person} />
+      ))}
+    </box>
+  ))}
+</box>;
+```
+
+- **The insets are thresholds, not offsets.** `top: 12` says the box's top
+  edge may come no nearer than 12px to the pane's top edge; it does not move
+  a box that is already further down. `top`, `bottom`, `left`, `right`,
+  `start` and `end` all work, in any combination, and a percentage is of the
+  pane's size. An edge with no inset does not stick.
+- **The pane is the nearest ancestor with `overflow: 'scroll'`** — a `<box>`
+  or the `<window>`. Its edges are inside its border and over its padding:
+  the band the content scrolls through. `overflow: 'hidden'` clips without
+  scrolling, so — unlike on the web — a rounded card between a header and
+  the pane does not quietly become the pane the header sticks to. With
+  nothing above that scrolls, the box stays where layout put it.
+- **The parent is the limit.** The box's margin box never leaves its
+  parent's content box, and that is the push. Wrap each header with the rows
+  it heads, as above: a header that is a sibling of every row has the whole
+  list for a parent and sticks for the whole list. A direct child of the
+  pane has the pane's content for a parent, and sticks for the whole scroll.
+- **It paints over its siblings.** A sticky box paints after its siblings of
+  the same `zIndex`, as CSS paints a positioned box over the ones in flow, so
+  the rows that scroll under a header do not paint over it, and it takes the
+  press where it covers them. `zIndex` still orders it first. Give it a
+  background, or the rows show through.
+- **It lands in the frame that scrolled.** The pane applies the offset in
+  the layout pass the scroll runs — never through a re-render — so a header
+  cannot trail its content by a frame, and a pane of headers keeps the
+  scroll blit: a header riding with its rows costs nothing, and a held one
+  repaints its own rect.
+- **`onLayout` reports where layout put the box**, not where it is held,
+  the same way a scroll does not fire it. Where it is held is
+  `getClientRects()`.
+
+Both axes at once, and one sticky box inside another, are what
+`examples/schedule.jsx` is made of: day banners pushed off by the next day, a
+row of room names held under the banner, a column of times held at the left,
+and the corner where the two meet.
+
+Not yet: CSS's `scroll-padding`. Scrolling a node into view — keyboard focus
+reaching a row — brings it to the pane's edge, which can be under a held
+header.
+
+Sticky is the built-in [custom position](#custom-positions): the same
+placement, written against the same context a registered one is handed.
+
+## Custom positions
+
+A position is CSS's positioning scheme: `relative` lays the box out in flow
+and moves it by its insets, `sticky` lays it out in flow and holds it against
+a scroll pane's edges. `registerPosition` adds one of your own — the box laid
+out in flow, then moved by an offset your scheme works out once the layout
+pass is done, in the same frame:
+
+```jsx
+import { registerPosition } from 'react-x11/host';
+
+// a layer that scrolls at a share of the pane's speed
+registerPosition('parallax', {
+  options: { rate: { type: 'number', default: 0.5 } },
+  place: (node, { pane, options }) =>
+    pane ? { x: 0, y: Math.round(pane.scrollY * options.rate) } : null,
+});
+
+<box style={{ overflow: 'scroll', flexGrow: 1 }}>
+  <image src={hero} style={{ height: 240, position: 'parallax' }} />
+  <box style={{ position: { name: 'parallax', rate: 0.2 } }}>…</box>
+</box>;
+```
+
+- **It is a `position` value**, by name or with its options, and switches
+  like one — from a container query block too. The box is laid out exactly
+  where `relative` would put it, and moved; nothing around it reflows.
+- **The insets are the scheme's.** Yoga never sees them as offsets: sticky
+  reads them as thresholds, and a registered position reads them as whatever
+  it documents.
+- **It runs on every layout pass**, the one a scroll runs included, so what
+  it moves lands in the frame that scrolled; one that animates asks for the
+  next frame itself. It paints and takes the press over its siblings of the
+  same `zIndex`, like sticky.
+- **Options are typed**: a `length` is written in logical pixels like any
+  length in a style, and a wrong option is reported, naming it, and takes
+  its default.
+
+The contract — what `place` is handed and may return — is in
+[extending.md](extending.md#a-position-of-your-own).
+
+## Grid
+
+`display: 'grid'` lays a box's children out as a CSS grid, written the way
+CSS writes one — `gridTemplateColumns` on the box, `gridColumn` on a child —
+so a grid copied from a web codebase lays out here as it was written:
+
+```jsx
+// a form: the labels as wide as the widest, the fields taking the rest
+<box
+  style={{
+    display: 'grid',
+    gridTemplateColumns: 'auto 1fr',
+    columnGap: 12,
+    rowGap: 6,
+  }}
+>
+  <text>Name</text>
+  <textinput />
+  <text>Postal address</text>
+  <textarea />
+  <box style={{ gridColumn: '1 / -1' }}>{/* a row the whole width */}</box>
+</box>
+
+// a gallery: as many columns of 200 and up as fit, each row as tall as its
+// tallest card
+<box
+  style={{
+    display: 'grid',
+    gridTemplateColumns: 'repeat(auto-fill, minmax(200px, 1fr))',
+    gap: 8,
+  }}
+>
+  {cards}
+</box>
+
+// an app's shell, by named areas
+<box
+  style={{
+    display: 'grid',
+    gridTemplateColumns: '200px 1fr',
+    gridTemplateRows: 'auto 1fr auto',
+    gridTemplateAreas: ['head head', 'side main', 'foot foot'],
+    flexGrow: 1,
+  }}
+>
+  <Header style={{ gridArea: 'head' }} />
+  <Sidebar style={{ gridArea: 'side' }} />
+  <Main style={{ gridArea: 'main' }} />
+  <Footer style={{ gridArea: 'foot' }} />
+</box>
+```
+
+| on the grid box                           | CSS                                |                                                                                                                                                                                                                            |
+| ----------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `gridTemplateColumns`, `gridTemplateRows` | `grid-template-*`                  | a track list — lengths in `px` (logical pixels), `%` and `fr`; `auto`, `min-content`, `max-content`; `minmax()`, `fit-content()`; `repeat()` with a count, `auto-fill` or `auto-fit` — or a number: that many equal tracks |
+| `gridTemplateAreas`                       | `grid-template-areas`              | one quoted string per row — `'"head head" "side main"'` — or an array of the rows                                                                                                                                          |
+| `gridAutoColumns`, `gridAutoRows`         | `grid-auto-*`                      | the size of a track the grid adds for a child placed past its template; a number is a length                                                                                                                               |
+| `gridAutoFlow`                            | `grid-auto-flow`                   | `'row'` (the default) or `'column'`, and `'dense'` to back-fill a hole                                                                                                                                                     |
+| `gap`, `columnGap`, `rowGap`              | `gap`                              | between the tracks                                                                                                                                                                                                         |
+| `justifyItems`, `alignItems`              | `justify-items`, `align-items`     | where each child sits in its area: `'stretch'` (the default), `'flex-start'`, `'center'`, `'flex-end'`                                                                                                                     |
+| `justifyContent`, `alignContent`          | `justify-content`, `align-content` | where the tracks sit when they leave room                                                                                                                                                                                  |
+| **on a child**                            |                                    |                                                                                                                                                                                                                            |
+| `gridColumn`, `gridRow`                   | `grid-column`, `grid-row`          | `2`, `'span 2'`, `'2 / 4'`, `'2 / span 3'`, `'1 / -1'`                                                                                                                                                                     |
+| `gridArea`                                | `grid-area`                        | a name from `gridTemplateAreas`, or four lines; `gridColumn` and `gridRow` beside it win for their own axis                                                                                                                |
+| `justifySelf`, `alignSelf`                | `justify-self`, `align-self`       | its own place in its area, over the grid's                                                                                                                                                                                 |
+
+Things to know:
+
+- **A number is a count** where CSS's value is a track list:
+  `gridTemplateColumns: 3` is three equal columns, `repeat(3, minmax(0,
+1fr))`, the way Tailwind's `grid-cols-3` means it — equal whatever is in
+  them. `'repeat(3, 1fr)'` is CSS's own, a column never narrower than what is
+  in it, so one long word widens its column. Inside a track list a length
+  takes its unit, `'200px 1fr'`; on `gridAutoRows` a number is a length, and
+  on `gridColumn` a line, counting from 1 at the start and from -1 at the
+  end.
+- **`layout: 'grid'` is the same request**, under the name every layout goes
+  by ([below](#custom-layouts)). A box whose `display` and `layout` disagree
+  — `display: 'grid'` beside `layout: 'masonry'`, or `layout: 'grid'` beside
+  `display: 'flex'` — is reported, and laid out as flexbox until they agree.
+- **The alignment keywords are this renderer's**, the ones `alignItems`
+  already takes: `'flex-start'` and `'flex-end'` where CSS grid writes
+  `start` and `end`. A value it does not take is an error listing the ones
+  it does.
+- **The lines are whole pixels.** Tracks are sized exactly and their lines
+  snapped, so neighbours in `'1fr 1fr 1fr'` meet on a shared pixel and every
+  gap is as wide as it was written. Chrome lays a track out at a fraction of
+  a pixel, so a row whose content fits in the fraction can wrap one line
+  differently here.
+- **It is checked against Chrome.** A corpus of grids Chrome laid out is
+  part of the test suite (`test/grid-conformance.test.js`) and lays out here
+  within a pixel of Chrome's, but for the fraction above.
+- **Not here:** subgrid (a grid's child lays its own children out), baseline
+  alignment, named lines (`[full-start]` — name an area instead) and the
+  `grid` and `grid-template` shorthands. A value that uses one is an error
+  naming it.
+- **It runs inside the layout pass**, as every layout does — on a window's
+  resize, a live one included, and in the frame a container query flips. A
+  query block can switch one property alone:
+  `'@container width < 500': { gridTemplateColumns: 1 }`. In a scroll pane,
+  the grid is a `<box>` inside the pane.
+- **What it costs** is its children's sizes, asked only where a track needs
+  them. Fixed tracks, `minmax(0, 1fr)` and a bare count never ask; `1fr`'s
+  minimum is the content floor, which is measured anyway; `auto`,
+  `min-content` and `max-content` columns ask each child once for each width;
+  `auto` rows ask each child its height at its column's width, which placing
+  it needs anyway. What a child answered is remembered until something inside
+  it changes, so a frame in which one card's text changed lays out that card.
+
+## Custom layouts
+
+`layout` hands a box's children to a layout algorithm in place of flexbox.
+[Grid](#grid) is one, and the other two built in are:
+
+```jsx
+// a board of notes, each dropped into whichever column is shortest so far
+<box style={{ layout: { name: 'masonry', columnWidth: 220 }, gap: 12 }}>
+  {notes.map((note) => (
+    <Note
+      key={note.id}
+      note={note}
+      style={note.pinned && { layoutItem: { span: 2 } }}
+    />
+  ))}
+</box>
+
+// a dialog's buttons, every one as wide as the widest, at the row's end
+<box style={{ layout: 'equal-row', gap: 8, justifyContent: 'flex-end' }}>
+  <Button>Cancel</Button>
+  <Button>Save changes</Button>
+</box>
+```
+
+**`masonry`** is columns, each child placed in the one that is shortest so
+far: the layout of a photo wall or a board of notes of different heights,
+which flexbox cannot write — a wrapping row lines its items up in rows. As
+many `columnWidth`-wide columns as fit (240 by default), or exactly
+`columns`, sharing the width; `columnGap`, `rowGap` and `gap` space them,
+and a child's `layoutItem: { span: 2 }` lays it across two.
+
+**`equal-row`** is a row whose children are all as wide as the widest of
+them. Flexbox makes siblings equal only by dividing a width it was given
+(`flex: 1`), and a row sized by its content — a dialog's buttons — has none
+to divide. Squeezed, the cells shrink together, down to the widest child's
+content floor and no further. `gap`, `justifyContent` and `alignItems` mean
+what they mean on a flex row, and `alignItems` defaults to `'stretch'`, so
+the cells are one height too.
+
+Things to know:
+
+- **It runs inside the layout pass.** The box's size is what the algorithm
+  answers and its children are where it puts them, in the same frame — on
+  a window resize, a live resize, a scroll or a container query flip, with
+  no React render involved. That is the difference from measuring in
+  `onLayout` and setting state, which paints the old arrangement first
+  ([react-features.md](react-features.md#measuring-a-node)).
+- **It is a style property**, so a container query block can switch it:
+  `'@container width < 500': { layout: { name: 'masonry', columns: 1 } }`.
+- **Right to left is mirrored for you.** An algorithm places from the left,
+  and the renderer mirrors each child across the box when it reads right to
+  left: a masonry fills from the right-hand column.
+- **Absolutely positioned children** are not the algorithm's: they are
+  placed by their insets against the box's padding box, as anywhere else.
+- **A child's content floor still holds.** A row inside a masonry card
+  squeezes its label only as far as its longest word, the rule everywhere
+  else ([elements.md](elements.md#everything-shrinks-nothing-shrinks-to-nothing)).
+- **Not on a scroll pane or a window.** A pane's size is its viewport's,
+  not its content's: put the layout on a `<box>` inside it, which is what it
+  scrolls. It is reported once, and the pane lays out as it would without.
+- **A layout that throws**, or a name nobody registered, is reported, and
+  the box is laid out as flexbox — in the same frame.
+
+Writing one of your own is `registerLayout` from `react-x11/host`
+([extending.md](extending.md#a-layout-algorithm-of-your-own)). The design
+record, with why it has to run in the pass rather than in an effect, is
+[architecture/custom-layout.md](architecture/custom-layout.md).
+
+## Transitions
+
+`transition` names how long a change takes. A number covers every animatable
+property; an object picks them individually.
+
+```jsx
+<box
+  style={{
+    backgroundColor: theme.surface,
+    transition: 120, // or { backgroundColor: 120, left: 200 }
+    ':hover': { backgroundColor: theme.surfaceHover },
+  }}
+/>
+```
+
+Numbers lerp and colours lerp per channel through ntk's own CSS colour
+parser, so anything the paint path accepts animates. Two percentages of the
+same unit lerp as numbers — `'-40%'` to `'100%'` is a value travelling across
+whatever contains it, with nothing measuring the container. A value with no
+meaningful midpoint — an enum like `flexDirection`, `auto`, a percentage
+against a pixel value — snaps instead, and `zIndex` is excluded on purpose:
+restacking every frame is not an animation. A duration keyed by a
+[shorthand](#lengths-and-shorthands) is its longhands', the longhand's own
+entry winning: `{ border: 150 }` fades the colour `border: '1px solid …'`
+set, and `{ padding: 200 }` moves each side `padding: '8px 16px'` expanded
+into.
+
+The easing is a fixed ease-out cubic. A transition starts from **what is on
+screen**, not from the declared value, so interrupting one reverses from
+where it got to rather than jumping to the end first. One to or from
+[`currentColor`](#currentcolor) runs between the colours as they are at the
+change.
+
+The animation _is_ the repaint loop: the window keeps asking its frame clock
+for frames while any transition is unfinished, and stops the frame the last
+one lands. Nothing polls, and there is no per-widget
+`requestAnimationFrame`.
+
+Transitions may animate layout properties, unlike state blocks. That is not
+an inconsistency: a pointer move must never reflow the tree, but an author
+who writes `transition: { left: 200 }` has asked for animated layout and
+pays a layout pass per frame for it, and a repaint of whatever that pass
+moves rather than of the window. `Switch` is the worked example — the
+thumb is absolutely positioned and slides on `start`, because
+`justifyContent` would flip between the ends with nothing in between.
+
+### Loops
+
+A transition is over when it arrives. `animation` is the other shape: a
+property that travels between two values and **keeps doing it**, for the
+spinner, the pulse, and everything else that means "working, no idea how
+long".
+
+```jsx
+<box
+  style={{
+    position: 'absolute',
+    start: '-40%',
+    width: '40%',
+    animation: { start: { to: '100%', duration: 1100 } },
+  }}
+/>
+```
+
+Per property, and each one names where it goes and how long a crossing
+takes:
+
+| key         |                                                                  |
+| ----------- | ---------------------------------------------------------------- |
+| `to`        | the far end                                                      |
+| `from`      | the near end; **defaults to what the style declares**            |
+| `duration`  | one crossing, in ms                                              |
+| `easing`    | `'linear'` (default), `'ease-in'`, `'ease-out'`, `'ease-in-out'` |
+| `alternate` | turn around at each end instead of wrapping back to `from`       |
+| `delay`     | when the loop's own time starts, in ms; negative starts it early |
+
+`from` defaulting to the declared value is what makes a pulse read as a
+resting colour plus somewhere to go:
+
+```jsx
+style={{
+  backgroundColor: theme.track,
+  animation: {
+    backgroundColor: { to: theme.accent, duration: 900, alternate: true },
+  },
+}}
+```
+
+That value is also **where the property rests whenever the loop is not
+running** — before the first frame, off screen, or under reduced motion — so
+a loop never leaves a node with no value for the thing it animates.
+
+Every loop starts when its node gets the style, so loops with one duration
+move together for good. `delay` is how they stop doing that — CSS's
+`animation-delay`. A positive delay holds `from` that long before the first
+crossing, once rather than every cycle; a negative one starts the loop that
+far in, already moving, which is the way to say a phase:
+
+```jsx
+const TypingDot = ({ index }) => (
+  <box
+    style={{
+      width: 6,
+      height: 6,
+      borderRadius: 3,
+      backgroundColor: theme.textMuted,
+      opacity: 0.3,
+      animation: {
+        opacity: { to: 1, duration: 500, alternate: true, delay: -index * 160 },
+      },
+    }}
+  />
+);
+```
+
+A changed `delay` is a different loop and starts from the top, as a changed
+`duration` does.
+
+Why this and not a repeating `transition`: a transition is defined by a
+_change_, from what is on screen to a new target, and it has no cycle to
+repeat. A loop has no target — it has two ends and a period. They are
+different declarations because they are different things, and one of them
+would otherwise have to be spelled as the other with a flag.
+
+The easing default differs from a transition's for the same reason. A change
+that ends looks right slowing into its new value; a cycle that restarts
+would stutter at the wrap, so a loop is `linear` unless you say otherwise.
+
+**A loop costs a repaint of what moves.** It is the same machinery
+transitions run on — the window's own frame clock, a damage region claimed
+per frame — so an indeterminate progress bar repaints the bar, not the
+window. The alternative an app would otherwise write, `setInterval` →
+`setState`, is a re-render of the component and a repaint of whatever the
+damage heuristics decide, at a cadence unrelated to when the window can
+present.
+
+On macOS a loop — or a transition — on a plain box's colour, border width
+or radius is handed to Core Animation instead and costs no frames at all:
+the layer presenter runs it on the node's own layer, and the surface
+presenter promotes the node to a layer of its own above the window for as
+long as it animates, where nothing is painted over it
+([macos.md](macos.md#layer-promotion-the-animated-few-on-their-own-layers-above-the-surface-presenter)).
+So is a loop on an inset of a box out of the flow that says no pointer
+lands on it — `position: 'absolute'` and `pointerEvents: 'none'`, as the
+block of `<ProgressBar indeterminate>` does — since it moves that box and
+nothing else: it becomes the layer's position. Without `pointerEvents:
+'none'` it stays on the clock, because input is hit where the layout put
+the box.
+Anything else runs as above. `examples/animation.jsx` has both shapes side
+by side, with a frame counter in the terminal that shows the difference.
+
+**And it stops itself**, which is the whole reason this is core's job. A
+forever-loop keeping a frame clock alive is invisible when it is wrong, so
+every way of going off the screen is wired to it:
+
+|                                                                                                                            |     |
+| -------------------------------------------------------------------------------------------------------------------------- | --- |
+| the window is unmapped, minimized, or fully obscured under a bare WM                                                       |     |
+| anything above the node hides it — `display: 'none'`, `<Suspense>`, `<Activity>`                                           |     |
+| the node unmounts, or the style stops declaring the loop                                                                   |     |
+| the desktop asked for **reduced motion** ([system.md](system.md#usedesktopsettings--how-the-desktop-wants-an-app-to-feel)) |     |
+| all the loop can draw is out of sight — scrolled out of its pane, clipped away by a box above it, off the window           |     |
+
+Each one leaves the frame clock idle, and every one of them runs the loop
+again when it goes away — with its phase reset, since a loop that resumes
+mid-cycle would have been drawing where nobody could see it.
+
+Out of sight is judged after each layout pass, by what **every** frame of
+the loop can reach and never by where the current one has the node: the
+block of `<ProgressBar indeterminate>` starts each crossing off its track,
+and is judged by the track it slides in. A loop on a colour, an opacity or
+a radius reaches what the node and its children cover. One on the outline,
+or one that moves or sizes a node out of the flow (`position: 'absolute'`),
+reaches the nearest box that clips it, or the whole window when nothing
+does. And one that moves or sizes a node in the flow is never out of sight
+at all: each of its frames can move the node's siblings and resize the
+boxes above it, so it runs for as long as its window is up.
+
+Reduced motion is honoured in core, once, for every loop in every
+application: `Gtk/EnableAnimations` off means loops do not start. What core
+cannot decide is what the _still_ frame should look like, which is the
+author's — `<ProgressBar indeterminate>` parks its block inside the track
+rather than at its off-screen starting point, so a bar that cannot move
+still shows something in progress.
+
+Nothing about this is a per-frame callback: `animation` describes the motion
+and the renderer runs it. For a `<glarea>` drawing its own frames,
+[`frameLoop`](gl.md) is the per-frame seam, and a 2D one is not
+built yet.
+
+## Window size queries
+
+`'@width >= 600'` and friends are the X11 analogue of `@media`: what a style
+can usefully ask about here is the window it is laid out in, not the screen.
+
+```jsx
+const s = createStyles({
+  bar: {
+    flexDirection: 'column',
+    gap: 4,
+    '@width >= 600': { flexDirection: 'row', gap: 16 },
+  },
+});
+```
+
+`width` and `height`, with `>=`, `<=`, `>` or `<`. Blocks that match are
+merged in declaration order, before state blocks — so a `:hover` inside the
+wide layout still wins over the wide layout.
+
+**A size query may set layout properties, unlike a state block.** That is
+not an inconsistency: a pointer state must never reflow the tree, but a size
+query is only ever re-evaluated inside a layout pass that a resize has
+already required, so it costs nothing extra. Nodes that declare one are
+registered with their window and re-resolved just before it lays out, and
+only when the size actually changed.
+
+A malformed query is an error rather than a key that silently never
+matches.
+
+## Container queries
+
+`'@container width >= 400'` asks about the box a node is inside rather than
+the window it is in — CSS's `@container`, for the case a window query cannot
+tell apart: the same card in a 220px sidebar and in a 600px pane, in one
+900px window.
+
+```jsx
+const s = createStyles({
+  pane: { container: true, flexGrow: 1, minWidth: 0, overflow: 'scroll' },
+  card: {
+    flexDirection: 'column',
+    gap: 8,
+    '@container width >= 400': { flexDirection: 'row', gap: 16 },
+  },
+});
+
+<box style={s.pane}>
+  <box style={s.card}>…</box>
+</box>;
+```
+
+A container is declared with the **`container` style property** — CSS's
+`container-type` and `container-name` in one — and a block answers to the
+**nearest ancestor that declares one**. Wrapping the card in another `<box>`
+for a border changes nothing: the parent is not the container, the declared
+ancestor is, which is what lets a component be put anywhere and still get
+the answer its author meant. The declaration changes nothing about the
+container itself; it is neither layout nor paint, only what the blocks under
+it resolve against. Being a style property, it can be set from inside a
+query block — a box that is a container only in the wide layout — and
+`false` takes a declaration back from earlier in a style array.
+
+`width` and `height`, with `>=`, `<=`, `>` or `<`, in the logical pixels the
+dependent's own lengths are written in. Blocks that match are merged in
+declaration order with the other query blocks, before the state blocks.
+
+### Named containers
+
+`container: 'pane'` names the container, and `'@container pane width >= 300'`
+asks for it by name — **reaching past** any nearer container. A card that is
+a container for its own contents does not capture a query a label inside it
+meant for the pane:
+
+```jsx
+const s = createStyles({
+  pane: { container: 'pane', flexGrow: 1, minWidth: 0, overflow: 'scroll' },
+  card: {
+    container: true, // the card's contents ask about the card…
+    '@container width >= 380': { flexDirection: 'row' }, // …and the card asks the pane
+  },
+  detail: { '@container width < 220': { display: 'none' } }, // the card
+  label: {
+    display: 'none',
+    '@container pane width >= 300': { display: 'flex' }, // the pane, past the card
+  },
+});
+```
+
+`examples/container-queries.jsx` is that design in full: one `<Card>` in a
+sidebar and in a main pane, both panes named `pane`, so the labels come and
+go with whichever pane a card is in.
+
+A name nothing above carries makes the block **not apply, quietly** — that
+is what lets one component render inside and outside a `sidebar`. An
+**unnamed** query with no container above it is reported in development,
+the way an unknown token is: the window already has a spelling (`'@width'`),
+so the only thing a silent fallback to it could hide is a forgotten
+declaration. `REACT_X11_STRICT_TOKENS=1` makes the report a throw.
+
+### When it is answered, and what it costs
+
+Like a size query, a container block **may set layout properties**, and for
+the same reason: it is only ever re-evaluated inside a layout pass. Unlike
+one, it cannot be answered _before_ the pass — a container's size is what
+the pass produces — so the blocks are resolved after it, and the tree is laid
+out once more when an answer moved. A frame where no answer crosses a
+threshold (a scroll, a hover, a resize between two breakpoints) pays one
+size read per container and nothing else. A frame where one does pays what
+the same change would have cost had React made it.
+
+When what depends on the size is not a style — how many rows to build, which
+component to render — the same size reaches React through `onLayout` on any
+element ([react-features.md](react-features.md#measuring-a-node)). It
+arrives after the pass, so the reaction lands a frame later than a block
+would; that is the reason to write a style as a block where one can.
+
+### A block must not move the size it asks about
+
+CSS makes this impossible by construction: `container-type: inline-size` is
+size containment, the container is sized as if it had no content, and
+nothing a descendant does can move it. Yoga has no containment, so here it is
+a rule, and breaking it is detected rather than prevented. A block that
+grows the container past the very threshold that turned it on — and shrinks
+it back when it turns off — has no size that satisfies it. The renderer
+notices (the node comes back to an answer it already held this frame),
+**holds the answer it has**, and says so once in development, naming the
+node. The answer stays held until the container's size moves for some other
+reason.
+
+The way to stay clear of it is also what makes a good container: a size that
+does not come from the content below it.
+
+|                                                  |                                                                   |
+| ------------------------------------------------ | ----------------------------------------------------------------- |
+| an explicit `width` / `height`                   | fixed, whatever is inside                                         |
+| a flex item with `minWidth: 0` and a `flexBasis` | the parent distributes it; `flex: 1` is both in one               |
+| `overflow: 'scroll'`                             | **the natural container**: content overflows rather than grows it |
+
+The common responsive pattern — less content when narrow, more when wide —
+is monotone and settles on the first re-layout; a warning means the design
+genuinely contradicts itself.
+
+## Capability queries
+
+`'@supports transparency'` is to `@supports` what the size queries are to
+`@media`: what a style can ask about the **server**, rather than about the
+window it is in.
+
+```jsx
+const s = createStyles({
+  menu: {
+    backgroundColor: '#1c1c22', // works everywhere
+    borderWidth: 1,
+    borderColor: '#3a3a44',
+    '@supports transparency': {
+      backgroundColor: 'rgba(24, 24, 30, 0.86)',
+      borderRadius: 14,
+      borderWidth: 0,
+    },
+  },
+});
+```
+
+Write the design that works everywhere as the base and the enhancement in
+the block — the same way you would write a `@media` query for a wider
+screen. That ordering is the point: get it the other way round and the
+fallback is the _unusual_ case, which is the one nobody tests.
+
+`transparency` is true only when **both** halves hold: the window was
+created on a 32-bit visual (`<window transparent>`, and the display had one
+to give), **and** a compositor is running to blend it. Either half missing
+and a transparent corner is a _black_ corner — X shows the raw pixels — so
+the honest answer is no, and the block does not apply.
+
+It is answered **per window**, not per display. A component rendered inside
+a `<popup transparent>` gets the translucent design; the same component
+nested in a plain `<window>` gets the opaque one, without being told which
+it is in.
+
+The answer can change while the app runs — a compositor being started or
+stopped is a checkbox on some desktops — and blocks are re-resolved when it
+does. That is why `transparent` takes the 32-bit visual even when nothing is
+compositing yet: a window's _visual_ is fixed at creation and cannot follow,
+but what it paints can.
+
+For decisions that are not styling — sizing a popup to hold a shadow margin,
+say, which has to happen before the window exists — there is
+[`useSupports('transparency')`](elements.md#transparent--rounded-corners-and-translucency),
+which answers the same question about the display.
+
+An unknown feature name is an error, like a malformed size query.
+
+Running with `REACT_X11_NO_TRANSPARENCY=1` makes the answer false on any
+display, so the base design — the one nobody tests, being the unusual case —
+can be looked at without stopping the compositor for the whole session. See
+[debugging.md](debugging.md#react_x11_no_transparency1).
+
+## Decided
+
+- **`':hover'`, not `_hover`.** The CSS spelling costs a pair of quotes and
+  buys transfer from every other styling system.
+- **Declared containers, not the parent.** `'@container'` answers to the
+  nearest ancestor that _declares_ itself one, never to whatever happens to
+  be the parent: a wrapper `<box>` added for a border must not change a
+  component's answer. CSS spent a decade on element queries before shipping
+  container queries with exactly this requirement. Nor is a scroller a
+  container without saying so — it is the ideal one to declare, but the
+  presence of one between a node and its container must not silently change
+  which box answers. And there is no self query: a node's own size deciding
+  its own layout is the cycle containment exists to forbid.
+- **Inherited properties, no relational selectors.** `color` and the font
+  properties travel down the tree; nothing matches a rule against it. So
+  there is no `:hover > child`, no sibling combinator and no Tailwind-style
+  `group`. Each of those exists to move a value across the tree, and
+  inheritance already does it in the one direction that is cheap: a parent's
+  `:hover` reaches its children because `color` is inherited, and a child's
+  hover reaches its parents because the hover path is the ancestor chain.
+  What is left over — a **sibling** reacting to a sibling — stays in React,
+  where `useControl` already returns `hover`/`focused`/`pressed` as state
+  ([components.md](components.md#basic-controls)). `<Checkbox>` does exactly
+  that, because its well is a sibling of the label the press lands on.
+- **`currentColor` resolves where it is painted, not in the style.**
+  Resolving it where a `$token` resolves, once per style swap, would have
+  made every reader of a colour simpler and every inherited change wrong: a
+  `:hover { color }` on a row restyles no node under it, so an ink baked
+  into their styles would be stale in every one. So the style keeps the
+  keyword, as CSS's computed value does, and every reader — the paint on
+  each backend, a Cocoa layer's properties, the blits deciding what a box
+  covers — asks `resolveColor`.
+- **Sticky sticks to a pane that scrolls, not to anything that clips.** CSS
+  makes every `overflow` but `visible` a scroll container, so a header
+  inside a card with `overflow: hidden` sticks to the card — which never
+  scrolls — and appears to do nothing, the most asked-about sticky bug there
+  is. Here `'hidden'` is CSS's `clip`: it clips and scrolls nothing, and only
+  `overflow: 'scroll'` makes a pane (see
+  [Sticky positioning](#sticky-positioning)). A header inside a rounded card
+  sticks to the list the card scrolls in, and stays inside the card.
+- **A registered position is a `position` value, not a property of its
+  own.** CSS's `position` already picks a positioning scheme, and sticky is
+  one whose insets mean something other than an offset; a scheme of your own
+  is the same kind of thing. The first spelling, `placement`, was already
+  the anchor vocabulary — which side of its trigger a popup opens on — and
+  threw on the first `<popup placement>` it met. What one property costs is
+  composing a scheme with `absolute`, which a wrapping box answers.
+- **A layout is a style property, and runs inside the pass.** What a layout
+  decides depends on sizes the pass produces, so a React-side one —
+  measure in `onLayout`, set state — paints the old arrangement first, and
+  misses every pass React never sees: a scroll, a live resize, a
+  transition. A style property is also one a container query block can
+  switch in the same frame.
+- **The renderer mirrors right to left, not the algorithm.** An algorithm
+  places from the left, once, and each slot is mirrored across the box when
+  it reads right to left — the way yoga mirrors a flex row, so no layout can
+  forget to.
+- **`null` is unset, and a layout value the layout cannot take is an error
+  where it is written.** `width: wide ? 240 : null` leaves the width to the
+  layout, as `undefined` does — yoga's own setters threw on `null`.
+  `width: 'hidden'`, `padding: 'auto'` or `flexDirection: 'sideways'` is an
+  error at the commit in development, naming the property, and that includes
+  a query block that does not match yet: the block is applied when it starts
+  matching, which is inside a frame, and a throw from there used to take the
+  process down. A value that only turns out wrong in a frame — a `$token`
+  resolving to one — is dropped there and reported, the way CSS drops a
+  declaration it cannot parse, and the rest of the block still applies.
+- **A colour that does not parse is dropped, not painted.**
+  `backgroundColor: 'nonsense'`, `7` or `'#12'` is an error at the commit in
+  development, naming the property — in the style, in a state block, as a
+  gradient stop or as a shadow's colour. `''`, like `undefined`, means
+  unset. Where one gets past that — a `$token` whose palette entry is not a
+  colour, or any value in a production build — the paint drops it the way
+  CSS drops a declaration it cannot parse: no fill and no stroke, no
+  gradient or shadow at all rather than half of one, and the inherited ink
+  for text. On X11 it used to throw from the frame, where no error boundary
+  could catch it, and the other backends painted it black.
+
+- **The more specific property wins, not the later one.** CSS resolves a
+  longhand against its shorthand by order. A flattened style has no order
+  left — `[base, { padding: '8px 16px' }]` and `{ paddingTop: 0, … }` are
+  keys of one object by the time anything reads them — so a longhand beats
+  its shorthand and a side beats all four, wherever each is written. It is
+  the rule `paddingLeft` beside `padding: 8` always followed.
+- **A length is pixels, and a unit nothing reads is an error.** `'12px'` is
+  12 — scaled for the display like any number, where it used to reach yoga
+  as a string the scale skipped and the border setter read as NaN — and
+  `'2ex'` names its unit rather than becoming 2.
+- **`rem` is the palette's `fontSize`, not 16.** CSS's root font size is
+  whatever the document's root says, and here that is the theme: the size
+  every label nobody styled is set in. So spacing written in `rem` follows a
+  theme that sets a bigger type size, as the palette's own radii and
+  paddings already do, and an app porting web numbers that assume 16 sets
+  `fontSize: 16` on its theme. The nearest palette is the one read, the way
+  a `$token` is — a `<ThemeProvider value={{ fontSize: 12 }}>` around a
+  dense panel re-bases it.
+
+## Elements that are not styled
+
+The declarative SVG children carry a vocabulary of their own — `<circle cx
+r fill>` is SVG's, not the style channel's — so the style channel does not
+apply to them, the same way it does not apply to an `<input type>` in the
+DOM. They report
+`stylable === false` and their props are passed through untouched.
+
+## Next
+
+A
+`boxShadow` that a `<popup>` can cast (the window needs a translucent margin
+around itself first — see [elements.md](elements.md) on `transparent`
+popups). Container queries shipped; the design record, with the targeting
+forms considered and the cost measured, is
+[architecture/container-queries.md](architecture/container-queries.md).