@jsenv/navi 0.29.458 → 0.29.460

package/docs/actions.md

@@ -222,6 +222,21 @@ decided to write, whatever its parameter, and `{ run: true }` says it — a toke
 a share button must already hold when pressed, for instance, since the OS share
 sheet only opens inside the gesture, never after an `await`.
 
+**A head start is `{ prerun: true }`.** When the params are known before the
+component owning the read exists — a card already says which chapter a book
+has, the book page draws its pages once the book is there — a component
+drawing nothing can send the read ahead, on the instance the owner will read:
+
+```jsx
+// draws nothing: the pages leave with the book instead of after it
+useAsyncData(chapterPagesAction, { prerun: true });
+```
+
+It needs no `<Loading>`, and its failure reaches no boundary: nothing on screen
+asked for a prerun, so the owner's `{ run: true }` asks again, once, when it
+reads it. A failure of the owner's own run is shown, and asked again by a
+`rerun()`, never by a render. A head start still running is the owner's wait.
+
 `{ onLoad }` is what the screen does with the data **once, when it becomes
 known** — seed the fields someone is about to edit, focus something, remember
 where a list was:

package/docs/mobile_touch.md

@@ -17,6 +17,7 @@ changes, measure again before trusting a number here.
 - [The browser decides about 8px in, and does not wait](#the-browser-decides-about-8px-in-and-does-not-wait)
 - [touch-action stops at the first scroller](#touch-action-stops-at-the-first-scroller)
 - [Only the start is contested](#only-the-start-is-contested)
+- [A rounded clip makes the scroll wait for the main thread](#a-rounded-clip-makes-the-scroll-wait-for-the-main-thread)
 - [The click is the browser's call as much as ours](#the-click-is-the-browsers-call-as-much-as-ours)
 - [A tap dropped after a touch drag](#a-tap-dropped-after-a-touch-drag)
 - [A finger is captured to what it touched, inside shadow trees too](#a-finger-is-captured-to-what-it-touched-inside-shadow-trees-too)
@@ -122,6 +123,48 @@ it back:
 A gesture that has won the start keeps the touch. What loses gestures is the
 first ~8px.
 
+## A rounded clip makes the scroll wait for the main thread
+
+Before it scrolls under a finger, Chrome's compositor finds the scroller under
+it. Where it cannot tell on its own, it asks the main thread, and the scroll
+starts when the main thread answers — after whatever task is running there.
+Meanwhile the finger keeps moving: the content holds still, then catches up in
+one step. A small scroll is mostly its start, so that is where it is felt. The
+wheel asks the same way on a desktop, where the main thread is rarely busy at
+that moment.
+
+Two things make Chrome ask (Chrome 155, mobile emulation; not measured in
+Safari):
+
+- **A rounded clip on the scroller or around it**: `overflow` other than
+  `visible` with a `border-radius`, or a rounded `clip-path`. Every scroll
+  start inside it is asked, wherever the finger lands. A popup that scrolls is
+  one: a rounded `overflow: auto` box.
+- **Anything painted over the scroller**, even with `pointer-events: none` and
+  square corners (an overlay drawing an edge above the items, say), but only
+  where it covers it: a 6px band along the top leaves the rest decided on the
+  compositor.
+
+The wait costs whatever runs at the touch: 0.1–2ms when nothing does; with a
+render built on the touch at 6× CPU, 7.5ms median and up to 27ms, and a scroll
+started a frame late one time in three. So navi keeps both away from what
+scrolls. A framed `List` does not clip to its rounded corners: its edge stays
+under the items, and one with a background covers the inside of the curve. A
+picker popup whose list scrolls itself does not clip either. And a finger on
+something that opens builds nothing before it has been held ~80ms. Wrapping a
+`List` in a rounded box of your own with `overflow: hidden` brings the wait
+back.
+
+A box that stops clipping needs `min-height: 0` if it is a flex or grid item
+holding the scroller: without a clip its minimum height is its content's, so a
+box given a height grows to all its items and the page scrolls instead. Nothing
+waits for the main thread then, because the wrong thing scrolls — check that
+the scroller's own `scrollTop` moved.
+
+Reference: `.navi_list_container` in `src/control/list/list.jsx`, the
+`[data-picker-popup]` rules in `src/control/picker/picker_custom.jsx`,
+`TOUCH_WARM_HOLD_MS` in `src/layout/popup_content_mount.js`.
+
 ## The click is the browser's call as much as ours
 
 - **Chrome** clicks after a touch that moved up to 8px and never beyond, whether
@@ -221,6 +264,19 @@ configuration: "mobile" })`, then `Input.dispatchMouseEvent` with
 through the desktop configuration instead: a 15px slop. Anything deciding at
 10px wins there, and the race that loses swipes on a phone is invisible.
 
+Where a scroll's start is decided shows only in a trace, never in the page's
+events: `Tracing.start` with `input`, `cc` and `disabled-by-default-cc.debug`.
+After the last `InputHandlerProxy::HandleTouchStart`, a
+`WidgetInputHandlerManager::FindScrollTargetOnMainThread` is the scroller looked
+up on the main thread, the gap between the two
+`InputHandlerProxy::HandleGestureScrollBegin` is how long that took, and a
+`delta_y` larger than one move on the first
+`InputHandler::ScrollLatchedScroller` says the first step merged two moves.
+Not under Playwright: its injected script puts a non-passive `touchstart`
+listener on `window`, which makes every touch blocking and changes the path
+being measured. Start Chrome by hand (`--headless=new
+--remote-debugging-port`) and drive the page's websocket directly.
+
 **Safari**: the iOS simulator, driven by `safaridriver`, which turns W3C touch
 actions into real UIKit touches — Safari's own pan recognizers compete for
 them exactly as on a phone:

package/docs/navigation.md

@@ -784,8 +784,10 @@ Every piece of it answers something:
   off screen;
 - **no `defineRouteTransition` for it.** The page beneath does not change, so
   there is no pair of pages to move between — route transitions are for pages
-  replacing pages ([route_transitions.md](./route_transitions.md)). When a link
-  inside the layer does change it, see
+  replacing pages ([route_transitions.md](./route_transitions.md)). Nor does
+  what is open on it: a popup or a section kept with `navState` stays open under
+  the layer ([popup_open.md](./popup_open.md#navstate--the-history-entry-holds-it)).
+  When a link inside the layer does change the page, see
   [below](#a-link-inside-the-layer-leads-to-a-page).
 
 ### Places inside the layer

package/docs/popup_open.md

@@ -680,6 +680,23 @@ picker open and come back to is a new mount, and the state stays in the entry
 with nothing to read it (navi warns). A picker whose popup leads somewhere, a
 link inside it, has an `id`.
 
+What a new entry inherits is decided by the page, not by the address. A push to
+another path starts its entry empty: a popup open on the page being left
+describes that page alone, and carried onto the next one it would open whatever
+mounts there under the same key. A push that keeps the path — a
+[layer](./navigation.md#a-layer-over-the-screen-what-its-address-may-say)
+opening over the page, a
+[state whose values are places](./navigation.md#a-state-whose-values-are-places-history-push)
+— stacks an entry over a page that is still mounted, and that entry starts with
+what the one below it held: an `Expandable` section open under the layer stays
+open, and closing the layer finds it as it was, with nothing played again. The
+scroll reads the same rule
+([navigation.md](./navigation.md#where-a-navigation-lands-the-scroll)).
+
+A link inside the popup follows the same rule: one to the same path with other
+search params leaves the popup open on the entry it pushes. A link whose press
+is a choice that ends the popup says so itself, with `command="--navi-close"`.
+
 The two meet when the signal IS a route's: a search-param `stateSignal` given to
 `signal` puts the open state in the address itself, where a link can point at
 it — the shape of a popup that is a LAYER over the screen, whose address is

package/docs/resource.md

@@ -613,6 +613,27 @@ is inferred — a relation that really is a sub-route of the parent is modelled
 with the relationship methods ([above](#relations-and-autorerun)), never
 declared as a dependency.
 
+When only some writes change what the reads show — a count of videos moves
+when one is created or deleted, not when a chapter is rated — name them with
+`on`:
+
+```js
+const SUMMARY = resource("summary", {
+  dependencies: [
+    BOOK, // every write
+    { resource: VIDEO, on: ["PATCH_MANY", "DELETE"] },
+    { resource: VIDEO_FILE, on: ["POST", "DELETE"] },
+  ],
+  GET: …,
+});
+```
+
+`on` names callbacks, not verbs: `PATCH` does not cover `PATCH_MANY` the way it
+does in `rerunOn`, so each write keeps its own answer. A name that is not a
+write, or that the resource does not define, throws at declaration — a
+dependency that never fires leaves a count on its old value with nothing to say
+so.
+
 ## A function calling the verb, or the instance
 
 Both forms are real, and what separates them is narrower than it looks:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.458",
+  "version": "0.29.460",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {