@jsenv/navi 0.29.387 → 0.29.389

package/docs/error_handling.md

@@ -184,12 +184,16 @@ report — window `error`, the jsenv overlay in dev — and that is the right an
 for it: nothing had to guess whether someone was waiting.
 
 **Some runs have nobody to reject at**, and they say so where they start: one
-started from a signal effect because its params changed, one whose failure the
-control that started it already draws, a routing whose result every caller drops.
+started from a signal effect because its params changed, one started by the
+render that reads it (`{ run: true }`), one whose failure the control that
+started it already draws, a routing whose result every caller drops.
 They pass through [`runUnwatched()`](../src/action/run_unwatched.js), which takes
-the rejection without hiding the error — it stays in `errorSignal`. That is the
-whole list of places navi swallows one, and taking it is what obliges that place
-to ask the next question: did anything display this error? (below).
+the rejection without hiding the error — it stays in `errorSignal`. That is
+every place navi swallows one but the prefetch on intent, dropped without a
+word since nothing on screen asked for it and the arrival runs the action again
+([dynamic_import.md](./dynamic_import.md#ahead-of-the-render-intent)). Taking
+it is what obliges that place to ask the next question: did anything display
+this error? (below).
 
 Two things must never become a rejection, and do not. **A navigation**: the
 routing's promise is what the browser calls the navigation itself, and rejecting
@@ -212,24 +216,19 @@ Whatever displays the error sets `error.__handled_by__` (via
 one thing and only one: **this error is on screen somewhere.**
 
 It is the same mark the jsenv supervisor reads to keep its dev overlay out of
-the way. It has to exist because `preact/debug` re-throws, in a `setTimeout`,
-**every error a boundary handled** — deliberately, so that React-style dev
-overlays keep working:
-
-```js
-// when an error was handled by an ErrorBoundary we will nonetheless emit an error
-// event on the window object. This is to make up for react compatibility in dev mode
-// and thus make the Next.js dev overlay work.
-```
-
-Without the mark, an app calmly displaying "you are offline" gets a crash
-overlay thrown over it.
+the way: a window `error` or `unhandledrejection` carrying it is not shown. An
+error on screen can still reach window another way — a run started by hand and
+never awaited — and without the mark an app calmly displaying "you are offline"
+gets a crash overlay thrown over it. navi's own report reads the same mark
+(below).
 
 Everything navi ships already marks: `<ErrorBoundary>` when it renders its
-fallback, `<ActionRenderer>` / `<Button action>` when they render their error
-branch, `useAsyncData({ error: true })`
-when it hands the error to the component, and a run given an `onError` — asking
-for the error is taking it.
+fallback, `<ActionRenderer>` when it renders its error branch,
+`useAsyncData({ error: true })` when it hands the error to the component, and a
+run given an `onError` — asking for the error is taking it. Every control with
+an `action` runs it that way, so the control claims the failure whatever it
+then shows: a callout, a boundary (`actionErrorEffect="throw"`), or nothing
+(`"none"`, a mapping returning nothing).
 
 ## Taken by nobody: the report
 
@@ -240,10 +239,9 @@ code that produced it.
 **Being read is enough to call the report off**, displayed or not. Once a render
 has the error, everything that can happen next is already covered without this
 module: it is displayed (and marked), or it is thrown — and a thrown error either
-finds a boundary that displays it, or reaches window on its own, since
-`preact/debug` re-throws what a boundary caught and an unbounded throw aborts the
-render loudly. Reporting it here too would be a second voice, and the wrong one:
-this module cannot see which of those happened.
+finds a boundary that displays it, or reaches window on its own, since preact
+re-throws what no boundary handled. Reporting it here too would be a second
+voice, and the wrong one: this module cannot see which of those happened.
 
 **And a render stopped in the middle read nothing after it.** `useAsyncData`
 delegates a failure by throwing it out of the render — that is how the error
@@ -259,9 +257,11 @@ one, is not covered: nothing tells it apart from an action nobody reads.
 
 One error is never reported whoever looks at it: a **`NetworkPolicyError`**.
 The app declared the state that produced it and the request never left, so there
-is no bug to point at — it is data a screen shows. navi also cancels the window
-`error` event that displaying it produces in dev, which keeps the browser
-console and the jsenv overlay out of it
+is no bug to point at — it is data a screen shows. When one reaches window
+anyway, navi cancels the event, which keeps the browser console and the jsenv
+overlay out of it. A boundary displaying one still leaves a `console.error` line
+in dev: `preact/debug` logs every error a boundary catches, and reads nothing
+that would tell it the error is handled
 ([network_policy.md](./network_policy.md)).
 
 So what reaches the report is an error **nothing looked at** — an action nobody
@@ -287,8 +287,9 @@ easy to miss when writing another one:
 
 - **Mark only what you actually render.** Marking on catch, before knowing
   whether anything is displayed, turns a boundary into a bug swallower: a
-  `TypeError` in a component becomes a blank page AND a silent one, since the
-  mark muted the overlay that would have pointed at it. navi's boundary marks
+  `TypeError` it then re-throws reaches window marked as on screen, so the
+  overlay that would have pointed at it stays out of the way — a blank page AND
+  a silent one. navi's boundary marks
   just before rendering its fallback, and re-throws untouched when it has no
   fallback — nothing to display means nothing handled.
 - **Reset on the document URL, not only on the rerun.** Re-running the failed

package/docs/field_validation.md

@@ -25,7 +25,8 @@ a validity rule, and the constraint is only its browser-side caller.
 
 ## Constraints
 
-A constraint is `{ name, check(field) }`. `check` returns `null` when the value
+A constraint is `{ name, check(field) }` — a bare `check` function is accepted
+too. `check` returns `null` when the value
 passes, or the message to show — a string, or `{ message, target }` when the
 callout belongs on another element than the control itself.
 
@@ -44,7 +45,7 @@ plain HTML.
 | ------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------- |
 | `required`, `pattern`           | same                                        | what the platform's attributes mean                                             |
 | `minLength`, `maxLength`        | same                                        | a string too short or too long                                                  |
-| `min`, `max`, `step`            | same                                        | a number, date, time or duration out of range                                   |
+| `min`, `max`, `step`            | same                                        | a number, date, time or duration out of range, or off its step                  |
 | `singleSpace`                   | `data-single-space`                         | a leading or trailing space, two in a row                                       |
 | `displayable`                   | `data-displayable`                          | zalgo, a value showing nothing, blank lines in series, a joiner joining nothing |
 | `maxStackedMarks`               | `data-max-stacked-marks`                    | (parameter of `displayable`)                                                    |
@@ -64,9 +65,34 @@ A boolean switch (`displayable`, `singleSpace`, `noEmoji`) passed as `false` is
 off, so `noEmoji={settings.strictNames}` says what it looks like it says. The
 others carry a value — a count, a selector — and are off by being absent.
 
-Each constraint has a `<name>Message` prop (and a `data-<name>-message`
-attribute) to replace its sentence for one field. To change it everywhere,
-override the i18n key instead — see below.
+**`singleSpace="autoFix"` corrects the value instead of refusing it.** A text
+field ends with a space more often than anyone means it to — a pause after a
+word, a mobile keyboard after a suggestion, a paste — and a refusal then asks
+the person to find and delete a character they cannot see. With `"autoFix"`,
+the leading and trailing spaces are removed and a run of spaces becomes one:
+
+```jsx
+<Input name="title" singleSpace="autoFix" />
+```
+
+- **At commit, never while typing.** The correction runs when the field is
+  left, and before an action reads the value. Correcting on each keystroke would
+  eat the space the person is about to follow with a word, so an action run
+  from typing (a search, debounced or not) reads the value as typed.
+- **Nothing to say.** The correction is validity's own `SINGLE_SPACE_RULE`, so
+  the value always passes the rule: no callout, and a server re-checking with
+  `singleSpace: true` accepts what it receives.
+- **It lands everywhere the value lives**: the field, its ui state, the bound
+  `signal`. A `disabled` or `readOnly` field is left alone, since its value is
+  the app's and not the person's.
+- **`singleSpace` is the only constraint that offers it.** A correction is worth
+  it only where it cannot change what the person meant; a `maxLength` silently
+  cutting a text would.
+
+Most constraints take a `<name>Message` prop to replace their sentence for one
+field (`requiredMessage`, `singleSpaceMessage`, `oneOfMessage`…; `step` and the
+time span constraints have none). To change it everywhere, override the i18n
+key instead — see below.
 
 Two props sit beside them and belong to the browser alone, because they act
 before there is a value to validate: `charGuard` blocks a keystroke that is not
@@ -78,7 +104,10 @@ silently swallowing it.
 field can refuse the keystroke with the same knowledge the value is checked
 against: `charGuard="tel"`, `charGuard="slug"`, `charGuard="noEmoji"`. Refusing
 the keystroke and refusing the value are different jobs — the pair
-`maxLengthGuard`/`maxLength` is the same split — and a field usually wants both.
+`maxLengthGuard`/`maxLength` is the same split — and a guard brings the value
+check along: `maxLengthGuard` is checked at submit as `maxLength`, `charGuard`
+sets an `Input`'s `pattern` from its class unless one is given. `maxLength`
+alone is the submit-only half.
 
 **A guard answers for the gesture, never for what the field already holds.** A
 value can arrive already outside the class or already too long — a

package/docs/i18n.md

@@ -117,10 +117,17 @@ resolved at registration time — so register `"fr"` before `"fr-CA"`.
 ### What comes out
 
 `i18n(key, values, { lang })` returns the translation with placeholders
-replaced. When nothing matches it returns the key itself, so a missing
-translation degrades to readable text rather than blank space or a crash. Pass
-`fallbackLang` at creation to fall through to another language first, per key —
-a half-translated language stays usable.
+replaced. The language is resolved per key: the preferred languages in order
+(`lang`, or the whole `languagesSignal` list by default), then the
+`fallbackLang` given at creation, and the first one translating the key wins. A
+half-translated language therefore shows its own words where it has them and the
+next language's everywhere else.
+
+When none of them translates the key, it comes back as is, so a missing
+translation degrades to readable text rather than blank space or a crash. With
+opaque keys that text is the key's name, which is why an instance with opaque
+keys wants a `fallbackLang` holding every key — `naviI18n` falls back to
+English.
 
 `i18n.has(key)` is the way to tell "no translation" apart from "translation that
 happens to equal the key".
@@ -139,9 +146,11 @@ setPreferredLanguage("fr"); // what this user picked, from a language picker
 ```
 
 `setSupportedLanguages` matters more than it looks: without it, a browser
-preferring German resolves to German, and every key missing in German falls back
-to its key. With it, that browser lands on the app's best available language
-instead.
+preferring German reads German wherever German exists — navi's time wording,
+every date and number — and the next language it lists, or English, for the
+rest: navi's buttons and messages, the app's own texts. One page, two
+languages. With it, that browser lands on the app's best available language for
+all of them.
 
 It decides more than the wording: `<Time>` and the format helpers
 (`formatNumber`, `formatTime`, …) read the same signal, so **a document that never calls it follows the browser,

package/docs/interactions.md

@@ -104,20 +104,21 @@ which the carrying interactions answer with).
 Two holds on one press — a `longpress` declared on something inside an
 element that declares one too — are answered by the nearer one, the way a
 click is the innermost target's: the inner hold fires, the outer wait is given
-up. Delays being equal; an outer hold made shorter than the inner one fires
-first. A press that lands on something carried inside the element (`move`,
-`moving`, `reorder`…) is that thing's the same way: the outer hold does not
-wait on it, whether the source drags by holding or by distance — except a
-source that says `"refuse"` for this press, which carries nothing.
+up. That is with equal delays; an outer hold made shorter than the inner one
+fires first. navi says so in dev, once per element, the first time it happens:
+the outer hold is a declaration that can never fire, and a picker opened by
+`openOn="longpress"` around a card that already holds one is exactly where it
+happens. One hold has one meaning — two things on one card want two gestures
+(a hold and a click), not two holds. A press that lands on something carried
+inside the element (`move`, `moving`, `reorder`…) is that thing's the same
+way: the outer hold does not wait on it, whether the source drags by holding
+or by distance — except a source that says `"refuse"` for this press, which
+carries nothing.
 
 There is no `dblclick` in that table, on purpose: the browser fires it for a
 mouse and never for a finger, so an element declaring it would answer half the
 hands that reach it. `double_click` is the same gesture counted from the
-pointer — see [Twice, whichever hand it is](#twice-whichever-hand-it-is). navi says so in dev, once per element, the first time it happens: the
-outer hold is a declaration that can never fire, and a picker opened by
-`openOn="longpress"` around a card that already holds one is exactly where it
-happens. One hold has one meaning — two things on one card want two gestures
-(a hold and a click), not two holds.
+pointer — see [Twice, whichever hand it is](#twice-whichever-hand-it-is).
 
 A name nothing knows how to detect produces a dev warning naming the detectors
 that exist. The carrying family and the two surface streams each have a file of
@@ -148,8 +149,9 @@ ancestor can also listen for one, and `preventDefault()` on it means "not this
 time".
 
 The lower-level event the interaction was read from is reachable too:
-`interactionEvent.detail.event` is the `pointerdown` a swipe or a hold was made
-of — which is how a menu is opened at the point the press happened.
+`interactionEvent.detail.event` is the `pointerdown` a hold or a drag was made
+of (a drag's release included), and the `pointerup` that ended a swipe or a tap
+— which is how a menu is opened at the point the press happened.
 
 ## Reaching the control
 
@@ -157,8 +159,8 @@ Everything goes through the interaction gate of the **nearest control** — itse
 an ancestor, or the one control it wraps, in that order. So a disabled, read-only
 or busy control answers a swipe the way it answers a click: it says why, where the
 interaction happened, and nothing runs. A `Box` with no control anywhere near it
-still answers a callback; only `"request_action"` has nothing to ask, and says so
-in dev.
+still answers a callback; only the two requests (`"request_action"`,
+`"request_ui_action"`) have nothing to ask, and say so in dev.
 
 A `Box` that lays out **several** controls — a row of badges, a toolbar — belongs
 to none of them: its interactions are its own, answered with no gate, exactly as
@@ -544,10 +546,11 @@ returns how to undo whatever it did. Listeners, attributes, anything: it is a
 plain setup and teardown, so a detector counts what it needs in its own closure
 and nothing has to hold state on its behalf.
 
-`claims` takes a **set** of names rather than one, because interactions sharing an
-input have to be arbitrated together — a swipe, a hold and a click dispute the
-same press, and read apart they walk over each other. `types` (third argument) is
-which of them were actually declared here.
+`claims` is asked one name at a time, and a detector claims a **set** of them
+rather than one, because interactions sharing an input have to be arbitrated
+together — a swipe, a hold and a click dispute the same press, and read apart
+they walk over each other. `types` (third argument) is which of them were
+actually declared here.
 
 `trigger(type, originalEvent, detail)` says the interaction happened. Called with
 a single event — `trigger(event)` — the type is the detector's own, which only
@@ -577,17 +580,18 @@ container above it does not take the gesture:
   under the same finger reads it before answering: a list reordered vertically
   inside a row of slides swiped sideways leaves the sideways gesture alone, and a
   piece carried both ways inside a bottom sheet takes the press whole. Nothing to
-  wire — see `docs/drag_to_travel.md`. A `Dialog` docked to the bottom edge goes
+  wire — see `docs/drag_to_travel.md`. A `Dialog` docked to an edge goes
   further and reads the press only on its header (plus anything carrying
   `data-swipe-grip`), so its body is free whatever is in it.
 - **A hold does not take the context menu.** Declaring `longpress` says what a
   held finger does; a right click comes from the other button and keeps opening
   the browser's menu. Declare `contextmenu` beside it to make the right click do
   the same thing. (A held _finger_ is the system's own context-menu gesture, and
-  that one is refused while the wait runs.)
+  that one is refused for the length of the press, not just of the wait.)
 - **Where the press already means something, text is not selected.** An element
-  declaring `longpress` or a swipe, and a drag source standing in a
-  `data-drag-on-contact` place, keep their text unselectable: the browser answers
+  declaring `longpress`, a swipe or a counted tap (`double_click`,
+  `single_click`), and a drag source standing in a `data-drag-on-contact`
+  place, keep their text unselectable: the browser answers
   that same press with a selection of its own — the word under the thumb, blue,
   with handles — and nothing takes it back once the press is over. For every
   pointer, mouse included, which cannot finish a selection begun where the press
@@ -621,6 +625,7 @@ container above it does not take the gesture:
 - `src/control/interaction/interaction_press.js` — swipes, holds and the two
   taps, and what a swipe writes on the element.
 - `src/control/interaction/interaction_keyboard.js`,
-  `interaction_native.js` — the other two detectors.
+  `interaction_native.js` — shortcuts, and the browser's own events. The
+  carrying and surface detectors are referenced from their own docs.
 - `src/control/demos/38_interactions_demo.html` — every case above, plus a
   mailbox, a board, a surface, and a custom gesture registered from the page.

package/docs/list_action.md

@@ -29,7 +29,8 @@ refuses in the meantime, which is what you want when the rows are alternatives.
 ```
 
 A press on another row while it runs is refused and says so, in the selection's
-own words ("la sélection est en cours d'enregistrement") rather than in a row's.
+own words ("le choix est en cours d'enregistrement", "la sélection…" in a
+`multiple` list) rather than in a row's.
 
 ## On a row's control: that row waits alone
 
@@ -38,8 +39,9 @@ part of it: it holds no action, nothing about it is busy, and the other rows
 stay live. Two rows can be in flight at once.
 
 ```jsx
-<List selectable multiple>
+<List id="the_list" selectable multiple>
   <List.Item
+    id={rowId}
     selectable
     value={person}
     readOnly={pending}
@@ -60,7 +62,7 @@ stay live. Two rows can be in flight at once.
 
 The command is what marks the row, and it runs **only if the action succeeded**
 — a button given both runs its action first and lets its command follow (see
-[actions.md](./actions.md)). So a refused invitation leaves the row unmarked
+[actions.md](./actions.md#a-press-that-opens-something-and-waits-for-the-answer)). So a refused invitation leaves the row unmarked
 without anything to undo.
 
 `selectableArea="manual"` is about the row's own surface, not about the button:
@@ -149,8 +151,9 @@ nothing about a row's own action stops someone from starting one on every row it
 draws — a dozen requests in flight because the list happened to be long.
 
 So a list allows **four runs at once by default**. While that many are out,
-every row that is not running goes read-only and says how many it is waiting on;
-the next press is possible again the moment one comes back.
+every control in it that would start another run goes read-only and says how
+many it is waiting on; the next press is possible again the moment one comes
+back.
 
 ```jsx
 <List parallelGuard={2}>      // stricter

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,12 @@ 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.                                           |
 
+`rerunOn` is read key by key: a key it names replaces that default, a key it
+leaves out keeps it. `rerunOn: { GET_RANGE: ["POST", "DELETE", "PATCH"] }`
+changes what re-reads the slices and nothing else — `GET_MANY` still reruns after
+`POST`. `false` turns a key off. A `withParams()` scope or a relation reads its
+own `rerunOn` the same way, against the resource it is declared on.
+
 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.
 
@@ -97,10 +100,18 @@ was asked:
   the reason.
 
   It is an error only in the way it travels. Nothing treats it as a bug: navi
-  never reports it as unhandled, and the window `error` event a boundary's
-  display produces in dev is cancelled, so neither the browser console nor the
-  jsenv overlay says anything. The person reads the screen; nobody else has to
-  hear about it.
+  never reports it as unhandled, and when one reaches `window` anyway — a run
+  called by hand whose failure nobody catches, a render throw no boundary took
+  — navi cancels the event, so neither the browser console nor the jsenv
+  overlay says anything. The person reads the screen; nobody else has to hear
+  about it.
+
+  One line is left, in dev only. A boundary displaying it — `<ErrorBoundary>`,
+  a control with `actionErrorEffect="throw"` — makes `preact/debug` log it with
+  `console.error`, as it logs every error a boundary catches, 404s and failed
+  fetches included. `preact/debug` reads no option or flag that would say the
+  error is handled, so that line stays. The jsenv overlay stays quiet, and a
+  build does not load `preact/debug`.
 
 - **A write is refused before the press.** A control bound to a `POST`, `PUT`,
   `PATCH` or `DELETE` action — or any control inside a `<Form>` bound to one —
@@ -109,7 +120,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

@@ -47,7 +47,9 @@ the release leaves behind. A pointer pans only once it has travelled a few px
 `pan` still gets its hold, and a `double_click` still gets its two presses.
 
 Declared alone, `zoom` takes two fingers and the wheel and leaves one pointer to
-whatever else reads it; `pan` alone leaves the wheel to the page.
+whatever else reads it: nothing captures it, waits on it or swallows its click
+until a second finger lands, so a `click` or a `longpress` declared beside `zoom`
+answers it as it would anywhere. `pan` alone leaves the wheel to the page.
 
 ### A surface that scrolls past: `data-pan-after-hold`
 
@@ -73,8 +75,12 @@ 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.
+
+On a surface that only zooms there is no pan to wait for: one finger is the
+page's to scroll, two are the surface's, and `"kept"` (below) has nothing to
+keep.
 
 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
@@ -152,11 +158,11 @@ place `data-pan-after-hold` is.
 
 ### When the surface has the hand: `grab`, `release`, `[data-grabbed]`
 
-A surface that is asked for — by a hold, or by the first few pixels of travel —
-has an instant where it becomes the hand's, and nothing on screen says it. The
-hand then moves too early and scrolls the page instead, or waits long past the
-moment out of doubt. So the surface says it, the same two words a carried element
-says (`grab`, `release`) and the same attribute:
+A surface that is asked for — by a hold, by the first few pixels of travel, or
+by a second finger — has an instant where it becomes the hand's, and nothing on
+screen says it. The hand then moves too early and scrolls the page instead, or
+waits long past the moment out of doubt. So the surface says it, the same two
+words a carried element says (`grab`, `release`) and the same attribute:
 
 ```jsx
 <Box
@@ -180,7 +186,8 @@ says (`grab`, `release`) and the same attribute:
 }
 ```
 
-`[data-grabbed]` is on the element for as long as a hand is on the surface, so
+`[data-grabbed]` is on the element for as long as a hand is on the surface (on
+one that only zooms, from the second finger landing to the last one lifting), so
 a contour, a veil or a raised shadow needs no listener — which is what this is
 usually for. (`[data-hand-kept]` is the other one, and it outlasts the finger:
 see [`data-pan-after-hold`](#a-surface-that-scrolls-past-data-pan-after-hold).) `grab` and `release` are for the rest: a vibration, a state kept

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):