@jsenv/navi 0.29.415 → 0.29.417

package/docs/AI_INSTRUCTIONS.md

@@ -79,7 +79,10 @@ to start when unsure which export solves a problem.
   map; a pair of routes is animated by `RouteTravel` or by a transition, never
   both; a test waits for the page arriving, never for its address; the page
   being left stays mounted, hidden, until the movement is over (so what it
-  registers globally must let the last arrival win); what a transition costs.
+  registers globally must let the last arrival win, and an action it reads
+  goes through `useAsyncData`, which leaves a page no longer shown alone —
+  `.value` on the action's signals re-renders it hidden); what a transition
+  costs.
   Read before animating a navigation, before writing a custom movement, and
   before believing a symptom that only appears once a pair is animated.
 - `view_transitions.md` — what the browser does to any transition an app
@@ -221,9 +224,10 @@ to start when unsure which export solves a problem.
 - `mobile_touch.md` — what Chrome and Safari do with a finger a gesture also
   reads, measured: they commit it to their own pan ~8px in (read a finger's
   intent before that), `touch-action` restarts at every scroller, when the
-  click survives, the tap Chrome drops after a touch drag, and how to reproduce
-  all of it without a device (Chrome's mobile touch emulator, Safari in the iOS
-  simulator). Read before reading a finger yourself, and before concluding a
+  click survives, the tap Chrome drops after a touch drag, the capture every
+  finger lands with (which `hasPointerCapture` misses on a field), and how to
+  reproduce all of it without a device (Chrome's mobile touch emulator, Safari
+  in the iOS simulator). Read before reading a finger yourself, and before concluding a
   gesture works because it works with a mouse.
 
 ### Layout, CSS and text

package/docs/mobile_touch.md

@@ -19,6 +19,7 @@ changes, measure again before trusting a number here.
 - [Only the start is contested](#only-the-start-is-contested)
 - [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)
 - [A finger never makes a wheel event](#a-finger-never-makes-a-wheel-event)
 - [Verifying without a device](#verifying-without-a-device)
 
@@ -160,6 +161,40 @@ Chromium's `gesture_provider.cc` (`ignore_single_tap_`, reset on the next down)
 and `tap_suppression_controller.cc` (the tap that stops a fling, 180ms) for the
 two mechanisms that do NOT explain it.
 
+## A finger is captured to what it touched, inside shadow trees too
+
+A touch pointer is captured the moment it lands, by the browser, to the element
+it landed on — nobody calls `setPointerCapture`. A mouse and a pen are not.
+That capture is announced like any other, with a `gotpointercapture` just
+before the first pointer event that follows, and a finger resting still sends
+one soon: its contact changes, so `pointermove`s with unchanged coordinates
+come within the first 100ms or so. Nearly every touch press therefore sees a
+`gotpointercapture` it never asked for. Code that reads it as "another gesture
+took this press" gives up on almost every finger.
+
+Recognising that capture is where Chrome misleads: **it goes to the deepest
+element under the finger, shadow trees included.** On an `<input>` or a
+`<textarea>` that is the inner editor, inside the field's own shadow tree; in a
+web component, whatever its shadow root holds there. `hasPointerCapture` on
+what the page sees — the field, the host — answers `false` at `pointerdown`,
+after `gotpointercapture`, and for the whole press. Yet the `gotpointercapture`
+reaches the page retargeted to that same element. An open shadow root shows
+both halves: the host answers `false`, the element inside it `true`.
+
+So the browser's capture is recognised by where it lands, never asked for: on
+a touch press, a capture announced on the press's own target is the browser's,
+whenever it arrives. Compare both events from the same tree: each is
+retargeted to the shadow host from outside. A gesture that takes the press onto
+that same element cannot be told apart from it, so it has to say so another way.
+
+Measured in Chromium 153 through `Input.dispatchTouchEvent`. The capture does
+not depend on the slop, so the desktop path shows it; see
+[Verifying without a device](#verifying-without-a-device). The same `false` on
+a field shows on an Android phone (Chrome 153). Not measured in Safari.
+
+Reference: `implicitCaptureHolder` and `takePress` in `@jsenv/dom`'s
+`press_held.js`.
+
 ## A finger never makes a wheel event
 
 No mobile browser turns a touch into `wheel` events: those come from a mouse

package/docs/resource.md

@@ -292,9 +292,26 @@ Keep their **ids**, not the objects: an object is a snapshot, and it stops
 following its row the moment anything writes to it. `RESOURCE.useAllByIds(ids)`
 reads those rows as they are now — a kept id turned back into something that
 stays fresh, and the ids the store no longer holds simply drop out.
-`RESOURCE.useById(id)` is the singular, `RESOURCE.useArray()` the whole store;
-all three subscribe the render that calls them, and none is a hook (a `.map()`
-over them is fine).
+`RESOURCE.useById(id)` is the singular, `RESOURCE.useArray()` the whole store.
+None is a hook (a `.map()` over them is fine), and each subscribes the render
+that calls it to what it returns: `useById` and `useAllByIds` to the rows they
+hand back — a card reading its own row stays still while other rows of the
+store are written, and re-renders when its row is — `useArray` to the whole
+store. An entry of `useAllByIds` given by a unique key rather than by id can
+only be found by reading the whole store, and that read follows it too.
+
+A row counts as written only when something in it changed:
+
+- **An answer** — what a callback returns — is compared to the row held in
+  depth. Parsed JSON makes every object nested in a row a new one; a
+  revalidation returning the same rows keeps every one of them, and their
+  readers stay still.
+- **A relation** changes its row when the row points at other children. What
+  happens to the children themselves is followed through the relation:
+  `game.place.label` read in a render re-renders it when the place is written,
+  and the game row stays the one it was.
+- **A value written with `store.upsert()`** is compared by reference: a new
+  object is a change, whatever it holds.
 
 ## Relations: pick one of the four methods
 

package/docs/route_transitions.md

@@ -552,9 +552,11 @@ Measured on that page, first frame of the movement: 63 → 45 ms at full speed,
 What that means for a page and for the application around it:
 
 - **It is still mounted for the length of the movement.** Its effects keep
-  running, and it still reads the address: whatever re-renders when the URL
-  changes re-renders in it too, hidden (see
-  [What a transition costs](#what-a-transition-costs)).
+  running, and it still reads the address: a component reading the URL, a
+  route or a signal directly re-renders in it too, hidden (see
+  [What a transition costs](#what-a-transition-costs)). What it reads through
+  `useAsyncData` does not: navi leaves a page alone as soon as its container
+  would no longer show it.
 - **It is taken down after the page arriving is up.** A cleanup that puts back
   what it found — a document title, a class on `<body>`, a value in a shared
   store — puts a stale value back over the new page's. Such a registration is
@@ -643,10 +645,30 @@ elements):
   at a route (`<Link route>`, `<Button route>`) reads one flag — whether it is
   current — and stays still unless that flips: a profile opening leaves the
   links to a hundred other profiles exactly as they were (on the list of
-  thirty cards: 90 re-renders gone, first frame 58 → 41 ms). What else reacts
-  is worth keeping to what has to — measured: every card of the page being
-  left re-rendering when the page arriving loads its own games into the store
-  the cards read theirs from.
+  thirty cards: 90 re-renders gone, first frame 58 → 41 ms). A row read with
+  `RESOURCE.useById` follows that row only, so the page arriving loading rows
+  of its own into the same store leaves the cards of the page being left as
+  they were. What moves last is the page's own reading of its route's action
+  — its params, its data and its state all change as the route stops
+  matching. `useAsyncData` gives no render to a page its container no longer
+  shows: the page is about to be taken down, or hidden until the movement is
+  over (on the list of thirty cards: about 450 component renders gone from the
+  callback, first frame 10–20 ms sooner at 4× CPU, nothing measurable at full
+  speed). A component reading the action's signals itself
+  (`action.dataSignal.value`) does not get that, and re-renders in the hidden
+  page.
+- **Restyling the page arriving more than once.** Built inside the update
+  callback, it is styled as it lands; anything written afterwards that its
+  elements inherit, or that re-selects them, restyles all of them again. On the
+  list of thirty cards (~7,000 elements) three did, 16–19 ms each at full
+  speed: the height of a list group's sticky label, written on the group once
+  measured (navi keeps it from being inherited, which took the movement 17 ms
+  sooner); the room a fixed bar takes (`--navi-fixed-bar-space-*`, feeding the
+  inherited `--navi-safe-area-inset-*`), which changes on the root when a bar
+  arrives or leaves with the page; and an app's `:has()` rule on the list
+  container over its rows (`.navi_list_container:has(.card) …`), evaluated
+  again as the rows land. An attribute the app sets on the container says the
+  same thing as that `:has()`, for nothing.
 - **Re-rendering what did not change, on the press itself.** A component that
   only wants a yes or a no reads a computed flag, not the signal it is derived
   from: a list whose rows each read the count of runs in flight re-rendered

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/navi",
-  "version": "0.29.415",
+  "version": "0.29.417",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {
@@ -34,7 +34,7 @@
     "preact": "^11.0.0-rc.2"
   },
   "dependencies": {
-    "@jsenv/dom": "0.17.83",
+    "@jsenv/dom": "0.17.84",
     "@jsenv/humanize": "1.8.6",
     "@jsenv/validity": "0.4.5"
   },