@jsenv/navi 0.29.387 → 0.29.388

package/docs/list_refresh.md

@@ -184,7 +184,8 @@ sends nothing and changes no state, so the network is silent and
 `onRequestStateChange` — which reports what a request is doing — has no request
 to report. A run that declined and a run that was never mounted look identical.
 `debugScroll` is where that difference is visible; it carries the render window
-and the run's asking, which are one subject.
+and the run's asking, which are one subject. It logs in navi's development build
+only.
 
 ```jsx
 window.askLog = [];
@@ -251,6 +252,11 @@ Defaults are `{ GET: false, GET_MANY: ["POST"], GET_RANGE: ["POST", "DELETE"] }`
 | `GET_MANY: ["POST"]`            | Whether a new item belongs in this list depends on filters, pagination, sort — the backend knows, the client does not. `DELETE` is excluded because the store already removes the item from every list.                                                                             |
 | `GET_RANGE: ["POST", "DELETE"]` | A slice is a range of places: a row leaving the collection shifts every place after it, which the store cannot do. Add the verb that moves an item in or out of the collection — a `PATCH` that archives, one that changes an item's tab.                                           |
 
+A `rerunOn` given replaces the `GET` and `GET_MANY` defaults whole: a key it
+leaves out reruns nothing, so `rerunOn: { GET_RANGE: ["POST", "DELETE", "PATCH"] }`
+alone also turns off `GET_MANY`'s `["POST"]`. Only `GET_RANGE`, left out, keeps
+its default. Restate every key the resource is read through.
+
 Adding `PUT`/`PATCH` to `GET_MANY` is the usual over-correction: it costs a
 request and a `loading` pass to obtain something the response already contained.
 When a `PATCH` "doesn't show", the fix is almost always server-side — return the

package/docs/mobile_layout_pitfalls.md

@@ -91,9 +91,9 @@ far from the wrapper:
 other axis to `auto`.
 
 Note: `overflow: hidden` on `<html>` would additionally create a new containing block,
-which could break `position: fixed` in edge cases. Any element that needs correct
-`position: fixed` behavior (like `<dialog>`) should be moved to `document.body` directly
-anyway (which `dialog.jsx` already does).
+which could break `position: fixed` in edge cases. A dialog in the top layer is out of
+reach of that: the top layer takes it out of every ancestor's containing block, which is
+why navi's `Dialog` stays where it is written, in its opener's subtree.
 
 ### The wrapper is a net, not a fix: find what overflows
 
@@ -132,8 +132,9 @@ scrolls down to it when it opens.
 Fix: **place `<dialog>` as the first child of `<body>`**, before any scrollable content.
 `scrollIntoView` on an element already at the top of the document has no effect.
 
-In `dialog.jsx`, `showModal()` moves the dialog to `document.body` (prepending it)
-before opening for this reason.
+This is advice for a `<dialog>` written by hand. navi's `Dialog` is not moved: it
+renders in its opener's subtree (see
+[css_architecture.md](./css_architecture.md#counting-children-what-navi-puts-in-your-tree)).
 
 ### Summary
 

package/docs/navigation.md

@@ -713,12 +713,14 @@ too early and put back:
   hands out.
 
 **Only where the row owns the document**: nothing between the travelling box and
-the viewport may scroll or clip. A row inside a scroller of its own — a frame in
-an article, a panel beside other content — shares nothing with the document, and
+the viewport may scroll. A row inside a scroller of its own — a frame in an
+article, a panel beside other content — shares nothing with the document, and
 the offset there belongs to the page around it, which the reader never left; the
-travel leaves it alone. An `overflow: hidden` or `clip` on any ancestor is
-enough to put the row outside the document's scrollport, so a row that should
-give positions back and does not is worth looking at from that angle first.
+travel leaves it alone. An `overflow: hidden` on any ancestor is enough to put
+the row outside the document's scrollport — it holds an offset of its own even
+without a scrollbar, whereas `overflow: clip` holds none and does not count — so
+a row that should give positions back and does not is worth looking at from
+that angle first.
 
 Pages that scroll inside themselves rather than scrolling the document are not
 concerned either way: each one brings its own scrollport, which goes away with

package/docs/network_policy.md

@@ -29,8 +29,11 @@ cache the app never has to write:
 - **A route action left behind is aborted, not reset.** Its value survives; only
   a run in flight is called off.
 - **Running a completed action is a no-op.** Coming back to `/games/abc` from
-  the list sends nothing — `run()` on a `COMPLETED` action already has its data.
-  Only `rerun()` goes back to the network (see [actions.md](./actions.md)).
+  the list sends nothing while the instance that read it is alive — `run()` on a
+  `COMPLETED` action already has its data. Only `rerun()` goes back to the
+  network (see [actions.md](./actions.md)). An instance nothing references any
+  more is asked again, with the store row drawn meanwhile; under the policy
+  that ask is answered from the store (below).
 - **A failed rerun keeps the previous value.** Only `errorSignal` and the
   running state move; what was on screen stays on screen.
 
@@ -109,7 +112,11 @@ was asked:
 
 Which actions the policy sees: those declaring a verb (`meta.verb`) — every
 action a `resource()` makes. A plain `createAction` may not touch the network
-at all, so it is left alone; give it `meta: { verb: "GET" }` to opt in.
+at all, so it is left alone. `createAction(callback, { meta: { verb } })` opts
+it into what the action layer holds — a control bound to a write verb is
+read-only, a completed `"GET"` is not rerun — but its callback is still called
+when it runs: answering from the store and settling with a `NetworkPolicyError`
+are done by the callbacks a `resource()` wraps.
 
 ## Holding writes while reads go out
 

package/docs/pan_zoom.md

@@ -73,8 +73,8 @@ Opt-in, and for the same reason its opposite is (see
 [`data-drag-on-contact`](./drag_interactions.md#a-finger-that-does-not-have-to-wait-data-drag-on-contact)):
 navi cannot see whether anything behind the surface scrolls. You know;
 say so. It spends the hold, though: a `longpress` declared beside a `pan` that
-waits asks one finger to answer two waits of the same length, and only one of
-them is answered.
+waits asks one finger to answer two waits, and the surface's — the shorter one
+— is the one answered.
 
 The wait is then asked before every pan, which is right while each finger
 landing there is genuinely ambiguous. Once the user has settled into the plan it

package/docs/popup_backdrop.md

@@ -62,9 +62,10 @@ dismissing click must not also press what is under it — without dimming the
 page for it. `backdrop={false}` is for a popup that must not absorb at all.
 
 **It is what decides whether a popup is modal.** `Popover` is never modal,
-either layer. A `Dialog` is modal exactly when it has a wall: with one, a
-top-layer dialog is `showModal()`'d and the browser makes everything behind
-genuinely inert; without one it goes to the same top layer through the Popover
+either layer, and neither is a `layer="local"` dialog. A top-layer `Dialog` is
+modal exactly when it has a wall: with one it is `showModal()`'d and the
+browser makes everything behind genuinely inert; without one it goes to the
+same top layer through the Popover
 API (`popover="manual"`), placed against the screen just the same, over a page
 that stays live. `Popup` forwards `backdrop` in both modes, so which of popover
 or dialog the small-screen resolution picks says nothing about whether one
@@ -179,7 +180,12 @@ panel that closes on that press then reopens on the click that follows is a
 panel meant to stay open, blinking.
 
 ```jsx
-<SidePanel id="error_panel" signal={openCardIdSignal} closeByPressOutside>
+<SidePanel
+  id="error_panel"
+  signal={openCardIdSignal}
+  backdrop={false}
+  closeByPressOutside
+>
   …
 </SidePanel>
 
@@ -198,7 +204,7 @@ adds a whole thing to the popup's ground — the card, its count, its buttons
 and nothing in it is a dismissal.
 
 It reads a press the page hears, so it belongs with a popup that has no wall
-(`backdrop={false}`, or a popover): behind a wall, no card is pressable.
+(`backdrop={false}`): behind a wall, no card is pressable.
 
 ### `pointer-events: none` and `inert` are not this
 

package/docs/popup_lift.md

@@ -132,8 +132,9 @@ corners itself, or on the card inside it, reads the same.
 
 ## Same width, or a wider box
 
-`dialogSizeFromAnchor` makes the trigger's box a floor for the dialog;
-`dialogMaxWidth="var(--anchor-width)"` makes it the ceiling too. Together they
+On a `Picker`, `dialogSizeFromAnchor` makes the trigger's box a floor for the
+dialog; `dialogMaxWidth="var(--anchor-width)"` makes it the ceiling too (on a
+`Dialog` the same props are `sizeFromAnchor` and `maxWidth`). Together they
 say "the same card, brought forward": the box travels and may grow in height,
 never in width. Left out, `dialogExpandX` lets the sheet take the room it has,
 and the width change is animated — the card keeps its scale inside a box
@@ -334,7 +335,8 @@ into the picture of the state it closes into.
 
 ## What it costs, and where the time goes
 
-Measured at CPU ×6 on the demo bench (`12_picker_card_demo.html#lift-bench`),
+Measured at CPU ×6 on the demo bench
+(`src/control/demos/picker/12_picker_card_demo.html#lift-bench`),
 a card of a real edit sheet's weight (≈215 elements, 13 fields, 62 picker
 nodes):
 

package/docs/popup_open.md

@@ -91,7 +91,7 @@ where that state lives:
 
 | what opens it                      | how                                                    |
 | ---------------------------------- | ------------------------------------------------------ |
-| a button                           | `command` / `commandfor` attributes, no `open`         |
+| a button                           | `command` / `commandFor` props, no `open`              |
 | a gesture, an event, a JS decision | `triggerNaviCommand(...)`, still no `open`             |
 | a state the app holds              | `signal` — [below](#when-the-app-holds-the-open-state) |
 | where the user is                  | `navState`, or a route `stateSignal` given to `signal` |
@@ -99,7 +99,7 @@ where that state lives:
 ## A button opens it: the attributes
 
 ```jsx
-<Button command="--navi-open" commandfor="note-dialog">
+<Button command="--navi-open" commandFor="note-dialog">
   Read the note
 </Button>
 <Dialog id="note-dialog">…</Dialog>
@@ -123,7 +123,7 @@ press:
 ## Something else opens it: `triggerNaviCommand`
 
 The attributes fire on every click of the element that carries them, and they
-cover more than "this button opens that dialog": `commandfor` says to whom,
+cover more than "this button opens that dialog": `commandFor` says to whom,
 `value` says what it is about, `--navi-x:argument` says how. Before writing any
 JS here, check none of those is the answer — `triggerNaviCommand` is the last
 resort, not the general way to run a command.
@@ -209,7 +209,7 @@ closes the popup as usual.
 
 ```jsx
 <Row
-  commandfor="row_menu"
+  commandFor="row_menu"
   interactions={{
     longpress: (event) =>
       triggerNaviCommand(event.target, "--navi-open", event),
@@ -225,7 +225,8 @@ own opening press from somebody else's comes from that gesture.
 The first argument is the command's **source** — the element it is triggered
 _from_. The target is resolved from it, in this order:
 
-1. `commandfor="someId"` on the source,
+1. `commandFor="someId"` on the source (written to the DOM as the HTML
+   `commandfor` attribute, which is what is read),
 2. `navi-command-target="parent-control" | "child-control"`,
 3. the command's own fallback — for the popup commands, `closest("[aria-expanded]")`.
 
@@ -234,7 +235,7 @@ element itself as the source resolves to that popup: `closest()` starts at the
 element itself. That is the short form used above, and it is enough whenever the
 JS that decides already holds the popup's ref.
 
-To trigger from another element instead, give that element a `commandfor`
+To trigger from another element instead, give that element a `commandFor`
 pointing at the popup's `id` — attribute-driven target resolution, JS-driven
 timing.
 
@@ -250,10 +251,11 @@ names none, and on whoever asked when nothing else says. In that order:
 3. **`detail.source`** — who asked. A button therefore opens the popup on
    itself, and a popup passed as its own source is its own anchor.
 
-For `Dialog` the anchor does nothing at all unless `sizeFromAnchor` is passed
-(then, and only then, it feeds the `--anchor-width`/`--anchor-height` CSS vars);
-for `Popover`, which really is positioned relative to its anchor, say what the
-anchor is:
+For `Dialog` the anchor does nothing at all unless `sizeFromAnchor` asks for
+it (it then feeds the `--anchor-width`/`--anchor-height` CSS vars) or
+`animation="lifting"` does (the box the dialog comes out of, see
+[popup_lift.md](./popup_lift.md)); for `Popover`, which really is positioned
+relative to its anchor, say what the anchor is:
 
 ```jsx
 <Popover ref={popoverRef} anchor={rowRef}>
@@ -261,8 +263,9 @@ anchor is:
 
 `anchorCustomEventDetail="ignore"` drops the open's side of that order
 entirely, leaving the `anchor` prop alone — for a popover that must never be
-anchored to whatever opened it (`SidePanel` does this), and for a
-`sizeFromAnchor` dialog that must never be sized from it.
+anchored to whatever opened it (`SidePanel` does this), and for a dialog that
+must never be sized from it (`sizeFromAnchor`) or lifted out of it
+(`animation="lifting"`).
 
 ## Opening it ON something
 
@@ -272,8 +275,8 @@ row is one dialog with two modes, and the press is the only thing that knows
 which one — so the press says it, with its own value:
 
 ```jsx
-<Button command="--navi-open" commandfor="radar-dialog">Nouveau radar</Button>
-<Button value={radar.id} command="--navi-open" commandfor="radar-dialog" />
+<Button command="--navi-open" commandFor="radar-dialog">Nouveau radar</Button>
+<Button value={radar.id} command="--navi-open" commandFor="radar-dialog" />
 
 <Dialog
   id="radar-dialog"
@@ -629,7 +632,7 @@ command once it succeeded.
 ```jsx
 // Stays open while save() runs, closes when it resolves, stays open if it
 // throws — with what was typed still there and the error on the button.
-<Button command="--navi-close" commandfor="note-dialog" action={save}>
+<Button command="--navi-close" commandFor="note-dialog" action={save}>
   Save
 </Button>
 ```
@@ -689,12 +692,12 @@ the popup without closing it, and the error callout stays where the press was.
 The gestures that close a popup do not all mean the same thing, and that is on
 purpose:
 
-| gesture                        | what it means | who decides                       |
-| ------------------------------ | ------------- | --------------------------------- |
-| Escape                         | cancel        | `escapeEffect="cancel"` (default) |
-| a press outside                | close, keep   | `pressOutside="close"` (default)  |
-| a close cross (`--navi-close`) | close, keep   | [the cross](#the-close-cross)     |
-| `--navi-cancel` on a button    | cancel        | the button                        |
+| gesture                        | what it means | who decides                                                                                            |
+| ------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------ |
+| Escape                         | cancel        | always, for a `Dialog`/`Popover`; `escapeEffect="cancel"` (the default) for a `Picker`                 |
+| a press outside                | close, keep   | `pressOutside="close"` — the default of a `Dialog` and of a `Picker`; a bare `Popover` says `"ignore"` |
+| a close cross (`--navi-close`) | close, keep   | [the cross](#the-close-cross)                                                                          |
+| `--navi-cancel` on a button    | cancel        | the button                                                                                             |
 
 Escape says "forget it". It is the one gesture that has meant that everywhere,
 for as long as there have been dialogs, and navi keeps it that way. **A popup
@@ -757,7 +760,8 @@ empty.
 
 ### `escapeEffect="close"`, and why it is a last resort
 
-`escapeEffect="close"` makes Escape say what a click outside says. It exists,
+`escapeEffect="close"` — a `Picker` prop; a `Dialog`/`Popover` has no such
+switch — makes Escape say what a click outside says. It exists,
 and it is almost never what you want: it takes away the only key that undoes,
 and a popup with no way back is one people stop opening. Reach for a close
 cross first.
@@ -996,7 +1000,8 @@ one fill above.
 
 A press on another card is not an outside press once the card names the panel
 with `data-navi-popup-inside` (see [popup_backdrop.md](./popup_backdrop.md)).
-The full example is `src/layout/demos/7_slot_demo.html`, "two side panels".
+The full example is `src/layout/demos/7_slot_demo.html`, "Two side-panel
+slots".
 
 ## A popup that loads data
 
@@ -1116,14 +1121,20 @@ half-typed form where it left them.
 "Closed" is two states, not one — never opened yet, and closed again after an
 opening — so the `mount` prop answers both at once:
 
-| `mount`                       | before the first open | after a close |
-| ----------------------------- | --------------------- | ------------- |
-| `"always"`                    | mounted               | mounted       |
-| `"from-first-open"` (default) | not mounted           | mounted       |
-| `"while-opened"`              | not mounted           | not mounted   |
+| `mount`                       | before the first open       | after a close |
+| ----------------------------- | --------------------------- | ------------- |
+| `"always"`                    | mounted                     | mounted       |
+| `"idle"`                      | mounted once the page idles | mounted       |
+| `"from-first-open"` (default) | not mounted                 | mounted       |
+| `"while-opened"`              | not mounted                 | not mounted   |
 
 `"always"` is for content something depends on before any opening: a value read
 off it, fields a surrounding form submits, a size measured from outside.
+`"idle"` is `"always"` minus the cost on the render that draws the page.
+
+Whatever the value but `"while-opened"`, intent on the anchor — a pointer
+entering it, focus landing in it — builds the content ahead of the click that
+will open it.
 
 `"while-opened"` is what an uncontrolled field seeded from a `defaultValue`
 needs: without it, a popup reopened after the underlying value changed still

package/docs/resource.md

@@ -93,14 +93,15 @@ const GAME = resource("game", {
 ```
 
 The callback receives the bound params merged with the range the list asks for
-(`start`, `end`, `limit`, `before`, `after`, `around`, `count`), and a `signal`
-as second argument — aborted when the list stops wanting those rows. It returns
-a range the way a `Content-Range` does: **`{ items, start, count }`** — these
-rows, at this place, out of that many. `start` may be omitted when the list
-asked for a positive one; `count` defaults to `start + items.length` (a source
-that does not know its total). The items are upserted on their way in, so the
-list draws store items — never copies of the JSON — and a request sent from a
-row is read back on that row.
+(`start`, `end`, `limit`, `before`, `after`, `around`, `count`), and `{ signal }`
+as second argument — a signal aborted when the list stops wanting those rows.
+It returns a range the way a `Content-Range` does: **`{ items, start, count }`**
+— these rows, at this place, out of that many. `start` may be omitted when the
+list asked for one at or after `0` (a negative `start` counts back from the end,
+and the source must then say where the slice landed); `count` defaults to
+`start + items.length` (a source that does not know its total). The items are
+upserted on their way in, so the list draws store items — never copies of the
+JSON — and a request sent from a row is read back on that row.
 
 A row that must follow its **own fields** through a write reads them from the
 store rather than from the object it was handed:
@@ -131,9 +132,12 @@ this collection again after its screen went away finds it drawn and revalidates
 it rather than starting over
 ([list_refresh.md](./list_refresh.md#leaving-the-screen-and-coming-back)).
 
-What it does not give is membership: an item that leaves the collection stays on
-screen until the rows are asked for again. Give the screen its own way to ask
-(a refresh gesture, a `key` on the run).
+Membership is what a re-read answers: a verb listed in `rerunOn.GET_RANGE`
+(`["POST", "DELETE"]` by default) tells the run the collection moved, and it
+asks again for the window it draws, rows staying on screen meanwhile. A write
+that moves an item in or out through another verb — a `PATCH` that archives —
+is added there, or `reader.invalidate()` is called; a `key` on the run is not the
+way ([list_refresh.md](./list_refresh.md#a-paginated-list-stays-on-screen-too)).
 
 It reads a collection, so it lives on the resource itself (or on a
 `withParams()` of it), not on a relation.
@@ -411,14 +415,17 @@ rules, verified by `src/state/rest/tests/resource_graph_parent_rerun.test.js`:
   reruns the parent. Declare it explicitly with `dependencies` if you need it
   (see [`dependencies`](#dependencies-rerun-after-another-resource-writes)).
 - Within a relationship resource, the usual defaults still apply: its own
-  `GET_MANY` reruns after its own `POST`; its `GET` is reset (not rerun) by its
-  `DELETE`. Override per relation with `rerunOn`/`dependencies`, which every
-  relationship method accepts.
+  `GET_MANY` reruns after its own `POST`. A `.one`/`.many` `GET` is reset (not
+  rerun) by its own `DELETE`, as a root `GET` is; a scoped `GET` is not reset —
+  its data simply resolves to nothing once the child is dropped. Override per
+  relation with `rerunOn`/`dependencies`, which every relationship method
+  accepts.
 
 Splitting a sub-resource out of a parent `PATCH` therefore changes the refresh
-graph: what used to be refreshed by the parent's own response is now refreshed
-only by these rules. When a parent field genuinely depends on a child mutation,
-say so with `dependencies` rather than relying on a rerun that will not happen.
+graph: a parent field the parent's own response kept fresh is, once the relation
+is a resource of its own, refreshed only by these rules. When a parent field
+genuinely depends on a child mutation, say so with `dependencies` rather than
+relying on a rerun that will not happen.
 
 ## `withParams()`: a scope with reruns of its own
 

package/docs/route_transitions.md

@@ -132,8 +132,9 @@ relation was written for. Two situations, two answers:
   deserves a direction. This is the case the export exists for.
 
 A default has no direction (nothing says which of two arbitrary pages is
-"before" the other), so only directionless movements make sense there. Written
-relations, and `"none"`, always win over it.
+"before" the other), so only directionless movements make sense there: navi's
+`slide-*` and `cover-*` are written on the direction, and as the default they
+play nothing. Written relations, and `"none"`, always win over it.
 
 ## When one navigation knows better
 
@@ -179,7 +180,8 @@ the same forms `defineRouteTransition` takes, plus `direction`. It overrides
 answers for. So:
 
 - `{ direction: "back" }` keeps the pair's movement and only turns it round;
-- `"zoom"` swaps the movement, keeping nothing else;
+- `"zoom"` swaps the movement; the way round and the pace are still the
+  pair's;
 - `"none"` cuts, where the pair — or the default — would have played;
 - `{ duration: 500 }` re-times what was already going to play.
 
@@ -525,12 +527,13 @@ await page.goBack();
 The window is **one frame**: the hold is given back inside the view
 transition's callback, which the browser runs at its next rendering
 opportunity. `tests/route_transition_list_revisit/` walks it the wrong way on
-purpose in its last case — under a movement the list that comes back is the same
-DOM element ten times out of ten and asks for nothing, while the same walk
-without a movement is a real one — and the window measured there is a back at 0
-or 8ms losing every round trip, at 16ms losing only the first, and past 64ms
-losing none. No thumb moves in one frame; an automated click continues in the
-same millisecond. This is a testing trap, not a user-facing behaviour.
+purpose in its last case — a back pressed the instant the URL changes — and
+which side of that frame a cycle lands on belongs to the machine's load: under
+a movement the list that comes back is either the element that never left,
+asking for nothing, or one truly remounted, asking once, while the same walk
+without a movement is a real one every time. No thumb moves in one frame; an
+automated click continues in the same millisecond. This is a testing trap, not
+a user-facing behaviour.
 
 ## The rest, briefly
 
@@ -538,6 +541,6 @@ same millisecond. This is a testing trap, not a user-facing behaviour.
   a per-relation `{ type, duration }` for one relation.
 - The URL leads: transitions play on navigations somebody else started (a
   `<Link>`, the back button, `history.back()`). Nothing here navigates.
-- A browser without view transitions (Firefox) navigates with a cut. The app
+- A browser without view transitions navigates with a cut. The app
   must remain fully usable that way — which it is, if the transitions state
   relations rather than carry information.

package/docs/safe_area.md

@@ -80,8 +80,8 @@ uneven writes `--navi-app-inset-left` / `-right` directly instead.
 In pixels: popup placement reads this value back from CSS to compute its own
 margins, and a custom property computes to a token stream rather than to a
 length, so `40rem` would arrive there as the string `"40rem"`. A non-px value
-still caps the popup's size (that part is pure CSS) but leaves the margins
-viewport-sized, and says so in the console.
+still caps the popup's size (that part is pure CSS) but leaves its margins and
+its placement viewport-sized, and says so in the console.
 
 Every popup follows: `Dialog`, `Popover`, and everything built on them
 (`Picker`, `Select`…). It is a ceiling and nothing more — on a screen narrower
@@ -98,11 +98,13 @@ Two ways NOT to get this:
   popovers would keep sizing themselves against 1500px;
 - setting `--dialog-max-width` on `.navi_dialog` from the app. It is a
   `--component-*` token, declared on the element (see
-  [css_architecture.md](./css_architecture.md#--navi--vs---component--where-the-override-has-to-go)),
-  so components that write it themselves outrank an app rule of lower
-  specificity — `.navi_picker[aria-haspopup="dialog"] .navi_dialog` does exactly
-  that, and the app's cap silently disappears for every picker. It is also the
-  knob a single popup uses to ask for a specific size, not a ceiling:
+  [css_architecture.md](./css_architecture.md#--navi--vs---component--where-the-override-has-to-go)):
+  every dialog resets it on itself in an unlayered rule, so that a nested
+  dialog does not inherit its parent's size, and a `maxWidth` prop writes it
+  inline (a `Picker` under `dialogSizeFromAnchor` does) — an app rule of the
+  same specificity does not reliably win, and the cap silently disappears. It
+  is also the knob a single popup uses to ask for a specific size, not a
+  ceiling:
   `--navi-app-max-width` feeds `--dialog-maxmax-width`, the hard ceiling _under_
   that knob, so a popup that genuinely needs its own `maxWidth` can still say
   so without escaping the app's screen.
@@ -154,10 +156,12 @@ Beware of making that container scrollable by accident — see
 `var(--navi-safe-area-inset-bottom)` in any rule. It is always declared, whether
 or not the app ever mounts a bar.
 
-Reading it from **JS** takes a probe: an unregistered custom property keeps its
-`calc()` unresolved through `getComputedStyle`. Give a hidden box
-`height: var(--navi-safe-area-inset-bottom)` and measure it — see
-`src/layout/demos/fixed_bar/keyboard.html`.
+From **JS**, the four `--navi-safe-area-inset-*` are registered as lengths
+(`@property`, in `safe_area.js`), so
+`getComputedStyle(document.documentElement).getPropertyValue("--navi-safe-area-inset-bottom")`
+gives pixels. The level-1 `--navi-app-inset-*` are not registered and keep their
+`calc()` unresolved there: give a hidden box `height: var(…)` and measure it —
+see `src/layout/demos/fixed_bar/keyboard.html`.
 
 ### Putting something new into it
 
@@ -182,24 +186,36 @@ truth:
 
 ## The trap: which viewport
 
-Three heights are in play and they are not the same one.
+Three heights are in play and they are not the same one — and which of them
+the keyboard moves depends on the browser.
 
-| what                             | shrinks when the keyboard opens |
-| -------------------------------- | ------------------------------- |
-| `window.innerHeight` / `100dvh`  | no                              |
-| `visualViewport.height`          | yes                             |
-| `--navi-vvh` (tracks the visual) | yes                             |
+| what                             | shrinks when the keyboard opens                 |
+| -------------------------------- | ----------------------------------------------- |
+| `window.innerHeight` / `100dvh`  | no                                              |
+| `visualViewport.height`          | yes, except where the keyboard overlays (below) |
+| `--navi-vvh` (tracks the visual) | same as `visualViewport.height`                 |
+
+Wherever the browser has the VirtualKeyboard API (Chromium), navi makes the
+keyboard overlay the page rather than shrink it (`src/layout/virtual_keyboard.js`):
+no viewport shrinks, and the keyboard arrives as `--navi-keyboard-inset-bottom`
+(`env(keyboard-inset-height)`), which `--navi-app-inset-bottom` adds. Firefox,
+Safari, and an app that called `disableVirtualKeyboardOverlay()` shrink the
+visual viewport instead, and `--navi-keyboard-inset-bottom` stays 0. Either way
+`--navi-app-height` and the popup ceilings answer the part of the screen left
+visible.
 
 `position: fixed` — so every `FixedBar` — is laid out against the **layout**
-viewport. A bottom bar therefore stays at the bottom of a window the keyboard is
-covering: it ends up _behind_ the keyboard, and no inset says so, because
-nothing reduced the layout viewport.
+viewport. Where the visual viewport is what shrinks, a bottom bar therefore
+stays at the bottom of a window the keyboard is covering: it ends up _behind_
+the keyboard, and no inset says so, because nothing reduced the layout viewport.
+Where the keyboard overlays, the bar is pinned to `--navi-app-inset-bottom`,
+which counts it, and sits above it.
 
 The consequence for anything measuring against the insets: mix the two families
 and you get a drift that only appears with a keyboard open. `getBoundingClientRect`
 is in layout-viewport coordinates, so what is compared to it must be too
-(`100dvh`), while `--navi-app-*` derives from `--navi-vvh` because what navi
-_sizes_ must fit what is actually visible.
+(`100dvh`), while `--navi-app-*` derives from `--navi-vvh` (plus the keyboard
+inset) because what navi _sizes_ must fit what is actually visible.
 
 `src/layout/demos/fixed_bar/keyboard.html` puts all of these on screen at once
 and turns the bottom bar's number red when it goes under the keyboard. On a

package/docs/scroll.md

@@ -47,7 +47,7 @@ Two shapes, and they do not behave the same:
 | `header` / `footer` alone | the container itself scrolls, and they are `position: sticky` at its edges — the content scrolls under them                                                                                       |
 | a `body` as well          | the container becomes a flex column, its own overflow turns to `hidden`, and the **body is the only thing that scrolls**; header and footer sit outside it (`position: static`, `flex-shrink: 0`) |
 
-Two consequences worth knowing before fighting them:
+Three consequences worth knowing before fighting them:
 
 - the body is `flex: 0 1 auto` — **it shrinks, it never grows**. A short body
   leaves the footer right under it rather than pushed to the bottom of a box it
@@ -61,7 +61,8 @@ Two consequences worth knowing before fighting them:
   them — positioned or not. Write `style={{ "--box-header-z-index": "auto" }}`
   (`--box-footer-z-index` likewise) at the call site that needs the opposite: a
   badge or a stamp overflowing a row is otherwise sliced by a header it never
-  scrolls under. `isolation: isolate` on the box keeps either value local to it.
+  scrolls under. The box is `isolation: isolate` already, so either value stays
+  local to it.
   See `docs/z_index.md` and `src/box/demos/9_scrollable_z_index_demo.html`.
 
 Padding belongs on the parts, not on the scrolling box: padding on a scroller
@@ -237,10 +238,11 @@ A dialog is already bounded by the room its container leaves it
 (`--dialog-maxmax-height`), so a `maxHeight` is only for making it smaller than
 that.
 
-`dialog.jsx` deliberately declares no `overflow` of its own: a modal dialog
-would inherit `auto` from the UA stylesheet and a `layer="local"` one gets
-nothing, so without a scrolling rule its `max-height` would only decide how big
-the box looks while the content kept painting straight through it.
+`dialog.jsx` deliberately declares no `overflow` of its own: the
+`[data-scrollable]` the dialog carries is its scrolling rule. A modal dialog
+would get `auto` from the UA stylesheet anyway, but a `layer="local"` one gets
+nothing, and without that rule its `max-height` would only decide how big the
+box looks while the content kept painting straight through it.
 
 ### `scrollCapture`
 
@@ -309,7 +311,7 @@ So: nothing scrollable between the cap and the slides. A `<Box body>` around
 them is a scroller (see the table at the top of this file) — and so is a bare
 `overflow="auto"` on a wrapper. The dialog keeps a shared `header` if the tabs
 are shared, with an explicit `flexShrink="0"` since the rule that gives it for
-free lives inside `[data-scrollable]`.
+free applies only next to a `body`.
 
 **Padding goes on the slide** — or on its parts, since the slide is now the
 scroller (see the top of this file) — but never on the container nor on
@@ -393,8 +395,8 @@ browser paints first — what a phone screen shows, plus a few — and `after` f
 the paint on. The switch waits for the paint itself, not for an effect: preact
 runs a component's pending effects early when that component renders again,
 and something always re-renders before a popup has painted. Do not rebuild
-this by hand with a `useEffect` that widens a slice — that is the thing it
-replaces, and it fails for that reason. The runs ask their source for `after`
+this by hand with a `useEffect` that widens a slice: that effect is one preact
+runs early, and it fails for that reason. The runs ask their source for `after`
 rows from the start, so the smaller first window costs no second request.
 
 ### Doing it well