@jsenv/navi 0.29.69 → 0.29.70

package/docs/AI_INSTRUCTIONS.md

@@ -168,8 +168,12 @@ consistency across the app, not from any single call site.
   default is right, how one link or one `navTo` overrides what the pair says
   for the length of a single navigation (`<Link routeTransition>`), marking the page
   area between fixed bars, and why a pair of routes is animated by
-  `RouteTravel` or by a route transition but never both. Read it before
-  animating any navigation.
+  `RouteTravel` or by a route transition but never both. It also says why a
+  test must wait for the page arriving rather than for its address — a back
+  taken before the page has rendered returns to a page that never left, which
+  looks exactly like the arriving page failing to load or refresh. Read it
+  before animating any navigation, and before believing a symptom that only
+  appears once a pair is animated.
 - `docs/navigation.md` — how to build navigation: declaring routes
   (`route()` / `setupRoutes()`), when a section is a route of its own rather
   than a param, search params bound to signals, rendering with `<Route>`,

package/docs/list_refresh.md

@@ -4,6 +4,9 @@ When a write touches one item of a list, two questions decide what the user
 sees: **what goes back to the network**, and **what stays on screen meanwhile**.
 Getting either wrong turns "pause one row" into a full page reload.
 
+The same two questions decide what a list does when the user leaves it and
+comes back, which is the second half of this file.
+
 The short answer:
 
 - A write that returns the modified item fixes every list containing it, with
@@ -11,6 +14,8 @@ The short answer:
 - `useAsyncData(action, { loading: true })` keeps returning the previous data
   while the action re-runs — the list is never taken away unless the component
   throws it away.
+- On the way back, the **source** decides whether anything is asked again — not
+  the navigation, and not a transition playing between the two pages.
 
 ## `loading: true` returns the previous value
 
@@ -173,10 +178,18 @@ it back. It never decides what the page arriving is allowed to ask for. Held by
 and without a relation on the pair — and walks the way back ten times on each,
 counting what goes out at every revisit.
 
-So the first thing to check, when a list stops refreshing after a transition was
-added, is which row of the table above it is on: a `GET_MANY` list never
-refreshed on its own, and what changed is whatever else in the app was doing the
-re-read.
+When a list stops refreshing after a transition was added, two things account
+for it, in this order:
+
+1. **The revisit did not happen.** A back taken before the page being opened was
+   ever on screen returns to a list that never left, and a page that never left
+   has nothing to come back from (see
+   [route_transitions.md](./route_transitions.md#waiting-for-a-navigation-the-address-is-not-the-page)).
+   This is what an automated walk does by default, and it is the answer far more
+   often than the next one.
+2. **The list is on the first row of the table.** A `GET_MANY` list never
+   refreshed on its own; what changed is whatever else in the app was doing the
+   re-read.
 
 ### Watching what the run asks for
 
@@ -228,6 +241,9 @@ the first revisit can start refreshing on the first two as soon as a
 
 An absence in the trace is a fact too: no line for a revisit means the run never
 rendered, which is about the list being mounted, not about what it asked for.
+The usual cause is a revisit that never happened — a back taken before the page
+being opened was ever on screen, which returns to a list that never left (see
+[route_transitions.md](./route_transitions.md#waiting-for-a-navigation-the-address-is-not-the-page)).
 
 ## `rerunOn`, verb by verb
 
@@ -290,6 +306,9 @@ runs it again.
 
 ## See also
 
+- [route_transitions.md](./route_transitions.md#waiting-for-a-navigation-the-address-is-not-the-page)
+  — why a walk away and back has to wait for the page arriving, and what a list
+  does when it did not
 - [resource.md](./resource.md) — `resource()`, relations, callback return
   contracts
 - [resource_dependencies.md](./resource_dependencies.md) — invalidating a

package/docs/route_transitions.md

@@ -289,16 +289,60 @@ one app mounted twice, the two mounts differing by a single
 `defineRouteTransition` line, walked back and forth **ten times each** with what
 goes to the network counted on every revisit. The loop is the point — a
 difference that came and went would pass a single comparison often enough to
-look like an invariant.
-
-What the test holds is that shape: pages between fixed bars, a marked area, a
-list virtualized against its scroller, held on a row the url names. It is
-evidence about the mechanism, not a proof about every application; a page that
-loses its revisit only under a movement is worth reporting with the loop above
-run against it. See
+look like an invariant. Three decors, chosen to be opposites: a long list
+virtualized against its scroller, the same one held on a row the url names, and
+a one-row list against the document scroller with its count known from
+elsewhere.
+
+One thing does make a page lose its revisit under a movement and not without
+one, and it is not about data either: a back taken before the page being opened
+has rendered, which returns to a page that never left. It has its own section
+below. See
 [list_refresh.md](./list_refresh.md#who-decides-the-re-read--and-who-does-not)
 for which source refreshes on a revisit and which does not.
 
+## Waiting for a navigation: the address is not the page
+
+A navigation changes the URL first and the screen after — always. Under a
+transition the gap is wider on purpose: the rendering hold above spans the frame
+the picture is taken in, so for that frame the address says one page and the
+screen still shows the other. That is what makes the picture honest, and it is
+also long enough to be walked through by mistake.
+
+So a test that waits on the URL has not waited for anything to happen:
+
+```js
+// ✗ resolves while the page being left is still the page on screen
+await page.getByTestId("game_card").click();
+await page.waitForURL(/\/games\//);
+await page.goBack();
+```
+
+That back does not come back from anywhere. Nothing was unmounted, so nothing
+remounts — the list the user "returns to" is the element that never left, with
+no first load, no revisit, and no re-read (see
+[list_refresh.md](./list_refresh.md#who-decides-the-re-read--and-who-does-not)).
+Every symptom of the arriving page being wrong follows from a walk that never
+took place.
+
+Wait for the page instead — anything only it can show:
+
+```js
+await page.getByTestId("game_card").click();
+await expect(page.getByTestId("game_edit_link")).toBeVisible();
+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.
+
 ## The rest, briefly
 
 - Pace: `--navi-route-transition-duration` (CSS, default 300ms) for everyone;

package/package.json

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