react-x11 2.51.0 → 2.52.0

package/docs/architecture/container-queries.md

@@ -0,0 +1,525 @@
+# Container queries: what the window queries already answer, and what a per-node one would cost
+
+_Research document, 2026-09-06. Written against the `master` checkout at c9ce902
+(react-x11 2.6.1; `src/nodes.js` @ 12,354 lines, `src/styles.js` @ 1,694). The
+one measurement is a yoga-only spike (§7), run in-process on one machine (Apple
+M1 Pro, node 26); nothing here was run against an X server, because nothing
+here needs one. file:line references are to that checkout and will drift._
+
+_Implemented after this was written, along the lines of §5 and §8:
+[styling.md](../styling.md#container-queries) is the reference and
+`examples/container-queries.jsx` the demonstration._
+
+---
+
+## 0. TL;DR
+
+**Feasible, and most of the machinery already exists.** A window size query
+(`'@width >= 600'`, [styling.md](../styling.md#window-size-queries)) and a
+container query differ in exactly one structural way: a window's size is an
+_input_ to layout and a container's size is an _output_ of it. So a container
+query cannot be resolved where the window queries are resolved — before the
+pass — but has to be resolved _after_ a pass, and the tree laid out once more
+if any answer changed. That loop is not new either: it is what `realize()`
+already runs for an auto-sized window that carries `@width` blocks
+(`nodes.js:9480-9503`, the "measure, re-resolve, measure once more" rule).
+Everything else — the grammar, the per-window registry, per-node
+re-resolution, pushing a style diff into yoga, the layout diff that turns a
+reflow into damage — is reusable as it stands.
+
+Findings, compressed:
+
+1. **The cost is bounded and small.** After a pass, reading the size of 300
+   registered containers costs 0.04 ms; a second yoga pass costs in proportion
+   to the subtrees whose style actually changed — 0.46 ms when one card's
+   block flips, 3.0 ms when all 300 do (≈ 1.7× a window-resize pass), on a
+   3,600-node tree. Frames where no answer crosses a threshold — every scroll
+   notch, every hover, most resize frames — pay the reads and nothing else
+   (§6).
+
+2. **The cycle is the real design question, and it is a detection problem
+   here rather than a prevention one.** CSS makes a container query safe by
+   _containment_: `container-type: inline-size` computes the container's
+   inline size as if it had no content, so nothing a descendant does can move
+   it. Yoga has no containment. It does have three constructions where a
+   node's size is already independent of its subtree (an explicit size, a
+   flex item with its content floor off, a scroller) and one clean signal
+   when a design is unsatisfiable: the second look disagrees with the first.
+   Settle once, pin the answer, and warn naming the node (§3).
+
+3. **On targeting** (§4): the recommendation is CSS's rule — the **nearest
+   ancestor that declares itself a container**, with an optional **name** to
+   skip past nearer ones — as one grammar, `'@container [name] width >= 400'`,
+   with the declaration a _style property_ (`container: true | 'sidebar'`).
+   **Direct parent** is rejected as a grammar (one wrapper `<box>` changes the
+   answer silently, which is the exact failure that made CSS abandon element
+   queries), though `container: true` on the parent spells the same thing
+   explicitly. **Self** queries are possible only paint-only and are deferred.
+   Making **scrollers implicit containers** is rejected in favour of
+   documenting them as the ideal thing to declare one on. And a general
+   `onLayout` on any `<box>` — today only a scroller has `onViewport` — is the
+   React-side seam that should ship first regardless.
+
+## 1. What exists: the window size queries
+
+The pieces, because the design below is mostly "the same, later":
+
+- **Grammar and resolution** (`styles.js`). `SIZE_QUERY` (`:479`) parses
+  `@width|@height op number`; `parseQuery` (`:498`) memoizes per key;
+  `resolveQueries(style, { size, supports })` (`:561`) merges every matching
+  block in declaration order over the base and returns the base itself when
+  nothing matches, so the identity fast path survives. `validateStyle`
+  (`:602`) makes a malformed key an error at `createStyles` time, and a query
+  block — unlike a state block — may carry layout properties, because it is
+  only ever re-evaluated inside a layout pass a resize already required.
+- **Per-node registration** (`nodes.js`). `_syncStyle` (`:1975`) registers a
+  node with its window's `_sizeQueryNodes` when `styleHasSizeQueries`
+  (`:2000-2007`) and folds the matching blocks into `_baseStyle` _before_ the
+  state blocks (`:2036-2042`), so a `:hover` inside the wide layout still
+  wins over the wide layout. `_registerSizeQueries` (`:2391`) is the recursive
+  hook `insertBefore` runs so a subtree attached after a resize matches
+  against the size the window is now.
+- **Per-node re-resolution.** `_sizeQueriesChanged` (`:2708`) is the whole of
+  it: `_syncStyle` again, `localTextStyleChanged` for the node-local text
+  props, and `applyLayoutStyle(yoga, style, before)` (`styles.js:1543`) to
+  push only the layout properties that moved into yoga — which dirties the
+  yoga node, so the next pass re-lays out that subtree and nothing else.
+- **The window's trigger.** `_resolveSizeQueries(deviceW, deviceH)`
+  (`:10987`) divides by the scale, compares with the last `querySize`,
+  re-resolves every registered node and marks the content floors dirty
+  (`_floorsDirty`). It runs from `flush()` before `_layoutRoot` (`:11385`),
+  and twice inside `realize()`'s auto-size `measure()` loop (`:9488`,
+  `:9503`) — the second time _after_ a measurement, re-measuring once if the
+  answer moved. That second call is a container query in everything but name:
+  it resolves blocks against a size the layout produced.
+- **Damage.** `_absolutizeChildren` (`:11416`) runs once after whatever
+  layout passes the frame needed, and `_assignAbs` (`:3719`) claims the old
+  and new rect of every node the pass moved through `layoutDiffSink`. Any
+  number of yoga passes before that walk cost nothing in damage terms.
+
+One property of the current path is worth naming because the container path
+must not inherit it: every registered node re-runs `_syncStyle` whenever the
+window's logical size changes at all (`:11002`), not only when one of _its_
+blocks changed answer. At window-resize frequency that is fine. A container's
+size can move on far more frames than a window's, so the container path has
+to gate the re-sync on an answer actually flipping (§5).
+
+## 2. What is different about a container
+
+Four things, and only the first is structural:
+
+1. **Input versus output.** The window's size is known before the pass; a
+   container's size is what the pass produces. Resolution moves to _after_
+   `_layoutRoot`, and a changed answer costs one more pass.
+2. **A target.** Which ancestor. The window query has one implicit target per
+   tree; a container query needs a rule for finding its container (§4) and a
+   cache for the answer, dropped when the tree above the node changes — the
+   shape `direction` already has (`:2482`, resolved nearest-first through
+   `parent`, cached, invalidated by `_redirectSubtree`).
+3. **Many registries.** One `_sizeQueryNodes` per window becomes a set of
+   dependents per window, each with a pointer to the container(s) it asks
+   about, and a remembered last answer per block.
+4. **The cycle** (§3). A window cannot be moved by the styles inside it; a
+   container can.
+
+## 3. The cycle
+
+CSS's answer is `container-type: inline-size`: size containment on that axis,
+so the container is sized as if empty and no descendant's style can feed back
+into the size the descendants are querying. Yoga has no containment. What it
+has instead are the three constructions under which a node's size on an axis
+is _already_ independent of its subtree:
+
+- an explicit `width` / `height`;
+- a flex item whose size the parent distributes, with its **content floor
+  off** — `minWidth: 0` plus a fixed `flexBasis` (or `flex: 1`, which expands
+  to basis `0`). The automatic minimum is the one route by which content
+  feeds back into a flex item's size, and `minWidth: 0` is its documented
+  switch ([elements.md](../elements.md#a-floor-the-content-decides));
+- a **scroller**: `overflow: 'scroll'` implies `minWidth: 0`,
+  `minHeight: 0` and — when it grows — `flexBasis: 0`
+  (`styles.js:1343`, `resolveComputedStyle`). Content overflows a scroller
+  rather than growing it, which is containment in everything but name. It is
+  the natural container, and the docs should say so.
+
+Where none of those hold, the design can be unsatisfiable. The spike's last
+section (§7) shows the shape: a card at 230 px whose block, below 250, sets a
+`flexBasis` that makes it 310, whose block above 250 sets one that makes it
+230 — and so on for as many passes as one is willing to run. No number of
+passes settles it, and no size satisfies it.
+
+Three ways to live with that:
+
+| option                                                                                                                  | verdict                                                                                                                                                                                                                                                                                                                    |
+| ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **(i) Settle once, pin, warn.** Re-lay out once; if a second look disagrees, keep the answer and say so in development. | **Recommended.** Mirrors `realize()`'s rule. CSS makes the bad case impossible; this makes it _visible_, with the container, the dependent and the axis named. The common responsive pattern (less content when narrow) is monotone and settles on the first re-layout, so a warning means a genuine design contradiction. |
+| **(ii) Paint-only container blocks**, like state blocks.                                                                | No cycle can form, but the main use case — a column becoming a row, a sidebar folding away — is layout. Rejected as the default; it is the right rule for _self_ queries (§4 D).                                                                                                                                           |
+| **(iii) A development-time check that the queried axis is pinned** by one of the three constructions above.             | Rejected: it is a heuristic (a parent with an explicit width pins a child's row too, invisibly to a per-node check), it would refuse designs that settle, and the runtime detection in (i) is exact.                                                                                                                       |
+
+The pinning rule in (i) needs one refinement, or it strobes. Take a frame
+that starts with blocks resolved as B₀ and lays out to size S₁. Resolving
+against S₁ gives B₁. If B₁ = B₀, done — the common case, and no extra pass.
+Otherwise apply B₁ and lay out again, to S₂; resolve to B₂. If B₂ = B₁,
+settled at one extra pass. If not, the design oscillates — and _leaving it
+there_ means the next frame's first pass starts from B₁/S₂, finds B₂, applies
+it, gets S₁, finds B₁ again, and every frame that runs layout flips the block.
+The fix is to remember the pair (S₂, B₁) on the dependent and hold B₁ while
+the first pass keeps producing S₂; the query re-evaluates when the container's
+size moves for some _other_ reason. A few lines, and the warning fires once.
+
+Nested containers need the cap stated correctly too. If an outer container's
+dependent flips, the second pass can legitimately move an _inner_ container
+past one of its own thresholds — a cascade, not an oscillation. So the loop
+runs up to a small fixed number of passes (three is enough for any nesting
+seen in the examples), and "oscillation" is defined as a dependent returning
+to an answer it already held _this frame_, which is exact where "changed on
+the second look" would pin a cascade wrongly.
+
+## 4. Targeting the container
+
+The question this document was asked. Each row is a way for a style to say
+_which_ box it is asking about.
+
+| how it reads                                                   | setup                                  | survives a wrapper `<box>`?     | lookup                                                             | cycle exposure                                            | CSS transfer                                          |
+| -------------------------------------------------------------- | -------------------------------------- | ------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------- | ----------------------------------------------------- |
+| **A. nearest declared ancestor** — `'@container width >= 400'` | `container: true` on the ancestor      | yes                             | walk `parent` to the first declaring node; cached like `direction` | as §3                                                     | `@container (min-width: 400px)`                       |
+| **B. named** — `'@container sidebar width >= 400'`             | `container: 'sidebar'` on the ancestor | yes                             | same walk, filtered by name; skips past nearer containers          | as §3                                                     | `container-name` / `@container sidebar (…)`           |
+| **C. direct parent** — `'@parent width >= 400'`                | none                                   | **no**                          | one property read                                                  | as §3                                                     | none — this is the element-query proposal CSS dropped |
+| **D. self** — `'@self width >= 400'`                           | none                                   | n/a                             | none                                                               | the self-cycle — safe only if the block is **paint-only** | none                                                  |
+| **E. nearest scroller, implicitly**                            | none                                   | yes, unless the wrapper scrolls | walk `parent` to the first `overflow: 'scroll'`                    | none — a scroller's size is content-independent           | none                                                  |
+| **F. React-side** — `onLayout` + context, `useContainerSize()` | a component around the subtree         | yes                             | none in the renderer                                               | none (it is a state update)                               | `ResizeObserver` + a hook                             |
+| **G. by kind or role** — `'@container [role=list] …'`          | none                                   | yes                             | walk with a predicate                                              | as §3                                                     | relational selectors                                  |
+
+**Recommendation: A and B as one grammar; F beside them as the seam; D
+deferred; C, E and G rejected.** The reasons, one per row:
+
+- **A** is CSS's default and the one that survives composition. A component
+  that adapts to where it is put must not have its answer changed by the
+  consumer wrapping it in a `<box>` for a border, and an explicit declaration
+  on the container is the only thing that guarantees that.
+- **B** exists for the case A gets wrong: a component that is itself a
+  container for its own rows (a card sizing its columns) would otherwise
+  capture every unnamed query inside it, including the ones its children
+  meant for the page. A name lets a query reach past. The one decision B
+  forces is what an **unmatched name** does. CSS's rule is that the query
+  simply does not apply, and that is the right one here too — it is what lets
+  the same component render inside and outside the `sidebar` — even though it
+  means a typo in a name is not an error. Worth a line in the debugging
+  guide; not worth making the component unusable outside its context.
+  An **unnamed** query with no declared container above it, on the other
+  hand, should be a development-time **error**: CSS silently falls back to
+  the viewport there, but this codebase already has a spelling for the window
+  (`'@width'`), so the fallback would only ever hide a forgotten declaration.
+- **C** reads as the least setup, and it is the closest to "adapt to the slot
+  I was put in" — which is the point of the feature. But the parent of a
+  reusable component is whatever its consumer rendered, and the moment that
+  consumer adds a wrapper for padding or a border the query is asking a
+  different box a question with a different answer, with nothing in the
+  program having changed its mind. CSS went through exactly this — element
+  queries were proposed for a decade and never shipped, and container
+  queries shipped with a required declaration. A with `container: true` on
+  the parent is C spelled so that it cannot drift.
+- **D** is the one shape CSS cannot offer at all, because of the self-cycle,
+  and this codebase _could_: the paint-only restriction state blocks already
+  live under (`STATE_PROPS`, `styles.js:429`) is exactly the restriction that
+  makes a self query safe. The use cases are thin — a card muting its title
+  when narrow, a border that drops at a small size — so it is a possible
+  later addition, not part of this design.
+- **E** is tempting because the scroller is the one place a cycle cannot
+  form (§3). But _implicit_ containers mean the presence of a scroller
+  between a node and its intended container changes which box answers, with
+  no declaration anywhere to point at. Explicit wins; the docs should
+  recommend declaring `container` on the scroller.
+- **F** is not a competitor but the seam ("decide it, then leave a way out",
+  AGENTS.md). Decisions that are not styles — how many columns to
+  virtualize, which component to render at all — need a size in React, and
+  today only a scroller offers one (`onViewport`, `nodes.js:6216`, fired from
+  layout via `setImmediate`). Generalizing it to `onLayout` on any `<box>` is
+  small: `_assignAbs` already detects the size change; it lacks only the
+  deferred notification. What F cannot do is what makes the renderer-native
+  query worth having: its answer lands a **frame late**. A size change
+  reaches React after the commit that caused it, React re-renders, a second
+  commit re-lays out — one frame drawn at the wrong layout on every threshold
+  crossing during a drag. A renderer query resolves inside the same flush and
+  is never seen wrong.
+- **G** is a relational selector, which styling.md's "Decided" section rules
+  out for the whole style system: inheritance and node state, no matching
+  against other nodes.
+
+**Where the declaration lives.** As a **style property**, not an element
+prop. AGENTS.md draws the line — props carry element semantics, `style`
+carries the CSS-like vocabulary — and `container` is CSS vocabulary
+(`container-type`/`container-name`). It also has to be settable from _inside_
+a query block (a box that becomes a container only in the wide layout), which
+only a style property can be. It joins `STYLE_PROPS` beside `cursor` and
+`hitSlop` as a property that is neither yoga nor paint, and DevTools' style
+editor lists it for free through `STYLE_PROP_NAMES`.
+
+**Units.** A threshold is in logical pixels like every other length in the
+block, and it should be divided out by the **dependent's** `scale`, not the
+container's: the author wrote `'@container width >= 400'` next to their own
+`width: 400`, and the two numbers must mean the same thing. The two scales
+differ only when the dependent adds a `scale` of its own under the container,
+which is rare and then reads as CSS's rule that query lengths resolve in the
+querying element's context.
+
+## 5. Mechanism, at the hook points
+
+`styles.js`:
+
+- `CONTAINER_QUERY = /^@container(?:\s+([A-Za-z_][\w-]*))?\s+(width|height)\s*(>=|<=|>|<)\s*(\d+(?:\.\d+)?)$/`,
+  parsed into `{ kind: 'container', name, axis, op, value }` by `parseQuery`;
+  `sizeMatches` is reused unchanged. `validateStyle`'s message grows a third
+  example. `styleHasContainerQueries` joins the two existing `hasQueryOfKind`
+  predicates, and `resolveQueries` takes a third option, `containers`: a map
+  from name (`''` for unnamed) to the container's logical size, built per
+  dependent by the node. `resolveQueries` is public through `react-x11/style`;
+  widening its options object is the shape it already has.
+- `container` joins `STYLE_PROPS`, validated as `true | string`.
+
+`nodes.js`, on `Node`:
+
+- `_syncStyle` records `_containerQueried` and the set of names the style asks
+  about, and registers the node with `root._containerQueryNodes`, exactly as
+  `_queried` does today (`:2000-2007`). `_registerSizeQueries` (`:2391`)
+  re-registers it on insert.
+- `_containerFor(name)`: walk `parent` to the first node whose `style.container`
+  matches (`true` for unnamed, the string for named), cached on the node and
+  dropped when the node is inserted and when any ancestor's `container` value
+  changes (a subtree walk from the changed node, the way `_redirectSubtree`
+  (`:2506`) drops `direction`). Containers are declared rarely and changed
+  more rarely, so the walk is not a hot path.
+- Per dependent, the last boolean answer of each block, so that a re-sync runs
+  only when one flips (§1's caveat). `_sizeQueriesChanged` (`:2708`) is then
+  the re-sync as it stands.
+
+`nodes.js`, on `WindowNode`, in `flush()`:
+
+- `_resolveContainerQueries()` runs **after** the layout passes (`_layoutRoot`
+  or `_applyContentFloors`, `:11385-11392`) and **before**
+  `_absolutizeChildren(0, 0)` (`:11416`). For each dependent it reads its
+  containers' `yoga.getComputedWidth()`/`Height()` — yoga's computed values,
+  not `abs`, which is still the previous frame's — divides by the dependent's
+  scale, evaluates each block, and calls `_sizeQueriesChanged()` on the
+  dependents whose answer set changed. Their yoga nodes are dirty now; the
+  same style route a prop change takes marks their content floors stale
+  (`_floorsStale` / `_floorsDirty`, `:2350`), and one more layout step runs.
+  Then the §3 loop: re-read, pin what returned to an earlier answer, stop at
+  the cap. `_absolutizeChildren` runs once, against the final layout, so the
+  damage claims are right by construction.
+- The same call goes inside `realize()`'s `measure()` loop (`:9480-9503`),
+  under the same cap, so an auto-sized window's natural size accounts for the
+  container blocks its content will resolve to.
+- Windows are boundaries, as for every other walk (`!child.isWindow`): a
+  `<popup>` inside a container is a root of its own and asks its own window.
+- `yoga.hasNewLayout()` is **not** the way to find containers that moved: it
+  is the scroller's witness, "consumed here and nowhere else" (`:6089`), and
+  reading it for 3,600 nodes costs seven times what reading the registered
+  containers does (§6). The container pass keeps its own last-size
+  bookkeeping and never calls `markLayoutSeen`.
+
+One pre-existing quirk the new blocks would inherit, and the same PR should
+fix: `flattenStyle` (`styles.js:663`) merges a **state** block that appears in
+two entries of a style array but **replaces** a query block
+(`isState(key) && into[key]`), so `[{ '@width >= 600': { a } }, { '@width >= 600': { b } }]`
+keeps only `b`. Query keys should merge the same way.
+
+## 6. Cost
+
+The spike (§7) builds 3,613 yoga nodes — 12 sections of 25 cards of 11 leaves,
+the shape of a card gallery — lays it out, then changes one layout property on
+some of the cards and times the second pass. Medians of 7, in-process,
+Apple M1 Pro:
+
+| case                                           | second pass | nodes yoga re-laid out |
+| ---------------------------------------------- | ----------: | ---------------------: |
+| nothing changed                                |    0.005 ms |                      1 |
+| 1 card flipped a block                         |     0.46 ms |                     93 |
+| 3 cards (1%)                                   |     0.65 ms |                    297 |
+| 30 cards (10%)                                 |      2.1 ms |                  2,007 |
+| all 300 cards                                  |      3.0 ms |                  3,613 |
+| the window resized by 100 px (for scale)       |      1.8 ms |                  3,613 |
+| **reading** width of 300 registered containers |    0.044 ms |                        |
+| reading width + height of all 3,613 nodes      |     0.82 ms |                        |
+| `hasNewLayout()` over all 3,613 nodes          |     0.33 ms |                        |
+
+What this says: yoga's second pass is incremental — it re-lays out the dirtied
+subtrees and reuses the cached layout of everything else — so the extra pass
+costs in proportion to how much of the design actually changed, and even the
+worst case (every card flips at once, which is a threshold crossing during a
+resize, not a steady state) is under twice the resize pass it follows. The
+counts are larger than the flipped subtrees alone because a card sits in a
+wrapping row: a card that grows taller re-stretches every card on its line,
+which is yoga doing exactly what the layout asks and what a real design pays
+too.
+Reading the containers is negligible **if** it reads the registered
+containers directly and not a whole-tree flag walk.
+
+What it does not measure, and where the real cost is:
+
+- The JS half of a flip: `_syncStyle` on each dependent whose answer moved —
+  flatten, tokens, scale, `_retarget` — and the incremental content floors
+  for those nodes. This is the same per-node cost the window path pays today
+  for _every_ registered node on every resize; here it is paid per _flipped_
+  node, which is what the answer gating buys.
+- The content floors are the expensive half of any relayout — three extra
+  passes were 21 of a 44 ms frame on 3,600 nodes before they were made
+  incremental (`_applyContentFloors`, `nodes.js:9257`). A container flip
+  re-measures only the flipped nodes' extents, but a flip that changes a
+  row's main-axis items does re-run the width pass for that row.
+
+Frames where no block crosses a threshold — every scroll notch, every hover,
+every resize frame between two breakpoints — pay the reads: tens of
+microseconds at hundreds of containers.
+
+## 7. The spike
+
+Reproduced so the numbers can be re-run: save it at the repo root and run it
+with `node`; it needs only `src/yoga.js`.
+
+```js
+import { loadLayout, Yoga } from './src/yoga.js';
+await loadLayout();
+const all = [],
+  cards = [];
+const node = (parent, i, setup) => {
+  const n = Yoga.Node.create();
+  setup?.(n);
+  parent?.insertChild(n, i);
+  all.push(n);
+  return n;
+};
+const root = node(null, 0, (n) => {
+  n.setWidth(1200);
+  n.setHeight(800);
+});
+for (let s = 0; s < 12; s++) {
+  const sec = node(root, s, (n) => {
+    n.setFlexDirection(Yoga.FLEX_DIRECTION_ROW);
+    n.setFlexWrap(Yoga.WRAP_WRAP);
+    n.setGap(Yoga.GUTTER_ALL, 8);
+    n.setPadding(Yoga.EDGE_ALL, 8);
+  });
+  for (let c = 0; c < 25; c++) {
+    const card = node(sec, c, (n) => {
+      n.setFlexDirection(Yoga.FLEX_DIRECTION_ROW);
+      n.setFlexWrap(Yoga.WRAP_WRAP);
+      n.setGap(Yoga.GUTTER_ALL, 4);
+      n.setPadding(Yoga.EDGE_ALL, 6);
+      n.setFlexGrow(1);
+      n.setFlexBasis(200);
+      n.setMinWidth(0);
+    });
+    cards.push(card);
+    for (let l = 0; l < 11; l++)
+      node(card, l, (n) => {
+        n.setWidth(40);
+        n.setHeight(20);
+      });
+  }
+}
+let width = 1200;
+const layout = () => root.calculateLayout(width, 800, Yoga.DIRECTION_LTR);
+const time = (fn) => {
+  const t = performance.now();
+  fn();
+  return performance.now() - t;
+};
+const median = (xs) => xs.sort((a, b) => a - b)[xs.length >> 1];
+const trial = (name, prep) => {
+  const xs = [];
+  let touched;
+  for (let i = 0; i < 7; i++) {
+    prep(i);
+    all.forEach((n) => n.markLayoutSeen());
+    xs.push(time(layout));
+    touched = all.filter((n) => n.hasNewLayout()).length;
+  }
+  console.log(name, median(xs).toFixed(3), 'ms', touched, 'nodes re-laid out');
+};
+const flip = (card, i) =>
+  card.setFlexDirection(
+    i & 1 ? Yoga.FLEX_DIRECTION_ROW : Yoga.FLEX_DIRECTION_COLUMN,
+  );
+layout();
+trial('nothing changed', () => {});
+trial('1 card', (i) => flip(cards[7], i));
+trial('3 cards', (i) => {
+  for (let k = 0; k < 300; k += 100) flip(cards[k], i);
+});
+trial('30 cards', (i) => {
+  for (let k = 0; k < 300; k += 10) flip(cards[k], i);
+});
+trial('all cards', (i) => cards.forEach((c) => flip(c, i)));
+trial('window resized', (i) => {
+  width = i & 1 ? 1100 : 1200;
+  root.setWidth(width);
+});
+const reads = (name, fn) =>
+  console.log(
+    name,
+    median(Array.from({ length: 7 }, () => time(fn))).toFixed(3),
+    'ms',
+  );
+reads('read 300 containers', () => cards.forEach((c) => c.getComputedWidth()));
+reads('read all nodes w+h', () =>
+  all.forEach((n) => n.getComputedWidth() + n.getComputedHeight()),
+);
+reads(
+  'hasNewLayout over all',
+  () => all.filter((n) => n.hasNewLayout()).length,
+);
+
+// pass 1: queried 230 -> now 310 / pass 2: queried 310 -> now 230 / …
+// the cycle (§3): a block that moves the axis it queries never settles
+const c = cards[0];
+c.setFlexBasis(200);
+layout();
+for (let i = 0; i < 4; i++) {
+  const w = c.getComputedWidth();
+  c.setFlexBasis(w < 250 ? 300 : 200);
+  layout();
+  console.log(`pass ${i + 1}: queried ${w} -> now ${c.getComputedWidth()}`);
+}
+```
+
+## 8. Decisions the implementing PR has to make, and the suggested answer
+
+| question                                    | suggested answer                                                                                                                                                                |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| spelling                                    | `'@container width >= 400'`, `'@container sidebar width >= 400'`; declaration `container: true` or `container: 'sidebar'` in style. Same operators and unit as `'@width'`.      |
+| unnamed query, no container above           | development-time error naming the node, pointing at `container` and at `'@width'` for the window.                                                                               |
+| named query, no such container above        | the block does not apply. Component reuse across contexts wins over catching a typo.                                                                                            |
+| a block that never settles                  | pinned at the answer it first held this frame, one development warning naming container, dependent and axis; re-evaluated when the container moves for another reason (§3).     |
+| how many extra passes                       | a fixed small cap (3); "oscillation" is a dependent returning to an answer it already held this frame, so a nested cascade is not mistaken for one.                             |
+| scale                                       | thresholds divided by the dependent's `scale`.                                                                                                                                  |
+| window boundaries                           | a window/popup never depends on a container in another window.                                                                                                                  |
+| `display: 'none'` container                 | nothing inside it is laid out or shown; nothing to decide.                                                                                                                      |
+| transitions                                 | a flipped block's paint properties transition through `_retarget` exactly as a window query's do today.                                                                         |
+| nested state block inside a container block | already allowed inside a window block (`validateStyle` recurses); same behaviour.                                                                                               |
+| types                                       | a `ContainerQuery` template-literal type beside `SizeQuery` (`style.d.ts:362`); `container` typed as `true` or a string in `StyleProperties`; one line in `test/types/api.tsx`. |
+| docs                                        | a section after "Window size queries" in styling.md; the "Next" list there drops its container-queries line; a scroller is named as the natural container.                      |
+| the seam                                    | `onLayout` on any `<box>` (generalizing `_reportViewport`'s trigger to `_assignAbs`), shipped first and on its own — useful with or without the query.                          |
+
+Tests, in the shape of `test/size-queries.test.js`: a container crossing a
+threshold under a window resize changes a dependent's style **and** its `abs`;
+a `_layoutPasses` count that grows by one only on the frame an answer flips;
+a wrapper `<box>` inserted between container and dependent changing nothing;
+a named query reaching past a nearer unnamed container; an unnamed query with
+no container throwing; a flattened array merging two blocks under the same
+query key; and the oscillating design warning once and holding still across
+frames.
+
+## 9. Verdict
+
+Container queries are feasible on this renderer at moderate size — on the
+order of 60 lines in `styles.js`, 150 in `nodes.js`, the declaration and type
+test, a doc section and a test file — and with no new primitive: the
+after-layout resolve-and-relayout loop is the one `realize()` already runs,
+made general and gated on answers actually flipping. The one thing CSS has
+that yoga does not, containment, is replaced by exact runtime detection of
+the only failure containment prevents, at a cost of one development warning
+where CSS would have made the design unwritable. The targeting grammar should
+be CSS's — nearest declared ancestor, optional name — for the reason CSS
+arrived at it: it is the only rule under which a component's answer does not
+depend on how its consumer chose to wrap it.