@jsenv/navi 0.30.5 → 0.30.7

package/docs/drag_to_travel.md

@@ -48,9 +48,22 @@ web does, and these are its rules, not ours:
 
 What stays ours:
 
-- **A travel asked for** (a tab, a key, a command, a state) plays in `duration`,
-  one box long whatever the distance, in `SlideContainer`. In `RouteTravel` it is
-  the browser's smooth scroll.
+- **A travel asked for** (a tab, a key, a command, a state) is one box long whatever
+  the distance: the pages in between are not crossed. In `SlideContainer` it plays in
+  `duration`. In `RouteTravel` it is the browser's smooth scroll, which has no
+  duration to ask for. A finger landing on it finishes it first.
+- **A press beats a row still moving.** It sets off at once from what is on screen,
+  and the row never lands where the hand was sending it. In `SlideContainer`
+  `onCurrentChange` hears about the slide pressed and not about that one, and on iOS a
+  swipe during that travel is ignored, and the next one works.
+- **What says where one is follows the screen.** While a hand holds the row, one is on
+  the page held. Once it has let go, what reads the row reads where it is going:
+  `useSlideContainer` (`current`, `can`, `held`), a `Nav`'s tabs, a `StepList`'s steps
+  and the chevrons in `SlideContainer`, so Next pressed during a snap counts from there;
+  a link's current state and `routeTravelSettledPageSignal` in `RouteTravel`. A trackpad
+  has no lift, so the nearest page answers. What the state holds waits for rest: the
+  bound signal and `onCurrentChange`, and in `RouteTravel` the address, except where it
+  runs ahead to build a page.
 - **A direction that is refused is the end of the row.** Whatever holds the user
   where they are (a `<Slide required>` waiting for its answer, a `preventNavNext`)
   takes what lies beyond off the row, so nothing can be scrolled to. There is no
@@ -231,7 +244,7 @@ A row of screens is a scroll container, and contains itself.
 | what says which is here       | a `signal`, `current` / a command | the URL                                     |
 | what a screen not on it shows | itself, built or `mount="near"`   | itself once visited; before that, see below |
 | what says the order           | the layout map                    | the `<Route>` children, or `routes`         |
-| a travel asked for            | plays in `duration`, one box long | the browser's smooth scroll                 |
+| a travel asked for            | plays in `duration`, one box long | the browser's smooth scroll, one box long   |
 
 A `RouteTravel` page not visited yet can only be built by the address moving, since
 a route's actions ask only while it matches. So the address moves once the hand has

package/docs/mobile_touch.md

@@ -9,8 +9,8 @@ fixed, they differ between engines, and **none of them shows with a mouse**. A
 gesture can pass a whole session of desktop testing and still fail one swipe
 in three on a phone.
 
-What follows is measured, not remembered: Chromium 153 through its mobile touch
-emulator, and Safari on the iOS 26.5 simulator driven with real touches (see
+What follows is measured, not remembered: Chromium 153 and Chrome 156 through the
+mobile touch emulator, and Safari on the iOS 26.5 simulator driven with real touches (see
 [Verifying without a device](#verifying-without-a-device)). When an engine
 changes, measure again before trusting a number here.
 
@@ -22,6 +22,7 @@ changes, measure again before trusting a number here.
 - [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)
+- [A snap keeps running after the finger](#a-snap-keeps-running-after-the-finger)
 - [Verifying without a device](#verifying-without-a-device)
 
 ## The browser decides about 8px in, and does not wait
@@ -229,6 +230,11 @@ where it lands, never asked for: on a touch press, a capture announced on the
 press's own target (compared from the same tree) is the browser's, and a gesture
 taking the press onto that same element has to say so another way.
 
+The rest of the touch goes there too, **even once that element has left the document**:
+a page re-rendering under the finger takes it out, and its `touchend` is dispatched on
+the detached node and reaches no ancestor. Nothing on the page around it hears the
+lift. What has to hear it listens on `event.target` from the `touchstart`.
+
 Measured in Chromium 153 (`Input.dispatchTouchEvent`: the capture does not
 depend on the slop) and on an Android phone (Chrome 153); not in Safari.
 Reference: `implicitCaptureHolder` and `takePress` in `@jsenv/dom`'s
@@ -243,6 +249,51 @@ paths differ in timing: a wheel gesture is claimed and refused on its very first
 event, so the browser never gets a moment to decide, while a finger has to
 travel a few pixels before anything can be read.
 
+## A snap keeps running after the finger
+
+A row with `scroll-snap-type: mandatory` goes on moving once the finger has lifted:
+about 600ms in Chrome, about 700ms in Safari, slowing all the way, so the last 300ms
+cover barely 40px of a 390px box. A press on something outside the row arrives during
+that time and gets its click, in Safari too. What it does to the row depends on the
+engine, because neither plays that movement on the main thread:
+
+| Asked of a row mid-snap           | Chrome                                                                | Safari on iOS               |
+| --------------------------------- | --------------------------------------------------------------------- | --------------------------- |
+| Instant `scrollTo`                | Ignored: the snap goes on and overwrites it                           | Stops it                    |
+| Smooth `scrollTo`                 | Replaces it until it ends: a short trip gets the snap back, and loses | Not measured                |
+| `scroll-snap-type: none`          | Ignored                                                               | Jumps to the target at once |
+| `overflow: hidden`, held          | Moves nothing, but the snap resumes when it is taken back             | Stops it                    |
+| `overflow: clip`, held two frames | Stops it: there is no scroller left to play it on                     | Stops it                    |
+| `display` changed for one layout  | Stops it (see below)                                                  | Stops it (see below)        |
+
+A change undone in the same task reaches nothing in Chrome, whatever the property,
+since the compositor never hears of it: only a `display` change acts that fast. It
+rebuilds the box, and it costs: `display: none` starts every CSS animation and
+transition inside over, `display: block` brings a scroller inside back to its top
+unless what the row holds keeps its size for that layout, and WebKit (desktop, under a
+synthetic wheel) then ignores the next write to the position and loses a scroller's
+own position inside.
+
+On Safari the last three rows were measured with a write following them, and a write
+alone is enough, so they say nothing of their own there.
+
+`scrollend` says little here: in Chrome a write gets one at once, with the row still
+moving. A row moved by other means with its snap left running ends worse than late:
+with a track animated over it, tens of pixels off any slide in Chrome, half a box off
+in Safari, and it stays there. Anything that moves a row on a press has to end the snap
+first.
+
+A box given `overflow: clip` is no scroller until it is given back, and that has its
+own cost: **a touch landing meanwhile starts no scroll in Safari**, even when the page
+gives the scroller back on `pointerdown`, since the scroll view does not exist yet when
+the finger lands. Chrome takes that swipe. Given back, the row stands where it stood
+with nothing written, but for the rest of that task WebKit still starts from 0: a smooth
+scroll to 0 sees nothing to do, and the row stays where it is, off any page. Ask a frame
+later.
+
+Firefox is not in this table: Playwright's synthetic wheel never leaves its row
+mid-snap, so it takes real input, events posted through the OS (`CGEvent` on macOS).
+
 ## Verifying without a device
 
 Both engines can show the browser's own answers — the pan, the
@@ -262,6 +313,10 @@ configuration: "mobile" })`, then `Input.dispatchMouseEvent` with
 - those calls are **never acknowledged**: send them without awaiting, with a
   sleep between moves (~16ms is a frame).
 
+A tap through this path waits about 300ms for a possible double tap, under
+`isMobile` too, so a press meant for a moment in a movement lands 300ms after it, at
+the end of a snap. `touch-action: manipulation` on what is pressed removes the wait.
+
 `Input.dispatchTouchEvent` — what Playwright's `touchscreen` uses — goes
 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.
@@ -304,9 +359,13 @@ its momentum included (over 3 s: flings closer than that add up). The window
 has to be on screen in the current Space: when it is not, activating the
 Simulator does not bring it, and the events land in whatever window is under
 the pointer — check which window is topmost at the points of the drag before
-sending any, and wait for the Space to switch after activating. What the page
-records is read back through a request it sends itself (the page runs on a
-local server), since nothing can query it.
+sending any, and wait for the Space to switch after activating. On screen is not
+on top: behind another app's window, activating does not raise it either, System
+Events does (`set frontmost to true`, then `AXRaise`), and another app can come back
+over it within seconds, so raise it and check right before each gesture, and again
+after any pause inside one. A tap works the same way, and reaches other elements
+during momentum. What the page records is read back through a request it sends itself
+(the page runs on a local server), since nothing can query it.
 
 What to synthesize is the hand's imperfection — a gesture simulated as clean,
 evenly spaced points passes forever and proves nothing: a slow start landing a

package/docs/navigation.md

@@ -613,9 +613,10 @@ const shownId = settledPage ? settledPage.params.gameId : currentId;
 
 It holds the `{ route, params }` the hand set off from, and is `null` from the moment
 a lifted finger leaves the row moving, the URL being the truth again: the row is only
-playing out what the browser decided. A trackpad has no lift, so there it lasts until
-the row has come to rest, and a tab already built waits for that too. A tab pressed
-holds nothing, and `null` is all it ever reads. One signal for the document: on a
+playing out what the browser decided. A trackpad has no lift, so there it holds the
+page nearest the row until the row has come to rest, and the URL of a tab already built
+waits for that too. A tab pressed holds nothing, and `null` is all it ever reads, even
+over a row a hand has left moving: the press wins at once. One signal for the document: on a
 page with several boxes, `route` says which row it is.
 
 `RouteTravel` is for pages that form a ROW the finger can push; pages related

package/package.json

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