@jsenv/navi 0.29.68 → 0.29.70

package/docs/AI_INSTRUCTIONS.md

@@ -165,9 +165,15 @@ consistency across the app, not from any single call site.
 - `docs/route_transitions.md` — how pages move against each other on
   navigation (`defineRouteTransition`): a transition states a relation the
   user reads as a map, which movement fits which relation, when a global
-  default is right, 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.
+  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. 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
 
@@ -170,11 +175,75 @@ list is walked through. A transition states a relation between two pages (see
 rendering hold for the one frame the browser needs to photograph it, and gives
 it back. It never decides what the page arriving is allowed to ask for. Held by
 `tests/route_transition_list_revisit/`, which mounts the same app twice — with
-and without a relation on the pair — and compares both counts.
+and without a relation on the pair — and walks the way back ten times on each,
+counting what goes out at every revisit.
+
+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
+
+A run that decides **not** to ask is invisible from the application's side: it
+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.
+
+```jsx
+window.askLog = [];
+<NaviDebug debugScroll={(...args) => window.askLog.push(args.join(" "))}>
+  <MyList />
+</NaviDebug>;
+```
+
+One line per pass of the run, whatever the outcome:
+
+```
+ask 0-49: sent (revalidating=true holdPending=false count=412)
+ask -1--1: nothing missing (revalidating=false holdPending=false count=412)
+ask 0-49: held on a row not reached yet (revalidating=true holdPending=true count=412)
+```
 
-So a list that stopped refreshing after a transition was added has, in the
-overwhelming majority of cases, never refreshed on its own: it was reading
-through `GET_MANY`, and something else in the app was doing the re-read.
+| outcome                              | what it means                                                                                           |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `sent`                               | the range on the line went out                                                                          |
+| `nothing missing`                    | the run holds every row it draws and has nothing to revalidate                                          |
+| `held on a row not reached yet`      | the list is on its way somewhere the window does not frame; only the row it is held on can be asked for |
+| `already revalidating`               | a revalidation for this window is in flight                                                             |
+| `a request still covers this window` | what is in flight is still what the list would draw                                                     |
+| `this range was asked for already`   | asking again could only produce the same answer                                                         |
+
+The state that decides is on the line rather than left to be inferred:
+
+- **`revalidating`** — the run knows what it holds is from before. A revisit
+  showing `revalidating=false` never restored a composition, which is a
+  different problem from one showing `revalidating=true` and no `sent`.
+- **`holdPending`** — the list is held somewhere it has not reached.
+- **`count`** — how many rows the run stands for, `undefined` before its first
+  answer.
+
+**Record, do not print.** The sink is called during rendering: push into an
+array. Formatting an object in a console costs far more than what it measures,
+and a timing-sensitive symptom moves under one — a list that fails to refresh on
+the first revisit can start refreshing on the first two as soon as a
+`console.log` is in the way, which makes the log a report about the log.
+
+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
 
@@ -237,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/navigation.md

@@ -310,11 +310,21 @@ Three cases, and they are not a policy to configure but three different facts:
   tall is clamped away.
 - **A reload** lands where one was, as it would have without navi.
 
-The consequence worth knowing when building a screen: **a "back" written as a
-`<Link>` is a push**, so it lands at the top like any arrival — no mechanism
-can guess that a push was morally a return. A back arrow that should feel like
-one is `navBack()`. Where there may be nothing to go back to (a shared link
-opened cold), decide what the arrow does from the history, not from the link.
+One consequence is softened where the browser exposes its stack (the
+Navigation API — everywhere but Firefox today): **a `<Link>` whose destination
+is the entry right next to the current one becomes a real traversal** instead
+of a push. A "back" link to the page one just came from therefore behaves as a
+back — the stack stays what the reader thinks it is (no A, B, A, B… growth)
+and the scroll comes back; one step forward too, so returning to the page one
+just left resumes it where it was. Only towards entries of this document (a
+traversal to another one would be a full page load no link asked for), and
+never when the push carries explicit state.
+
+Everywhere else a `<Link>` is an arrival and lands at the top. A back arrow
+that must ALWAYS behave as a back — even far from the entry it targets, even
+in a browser with no Navigation API — is `navBack()`. Where there may be
+nothing to go back to (a shared link opened cold), decide what the arrow does
+from the history, not from the link.
 
 What is not covered: a page whose height depends on something still loading is
 not tall enough at the moment its position is put back, so a deep position is

package/docs/route_transitions.md

@@ -1,8 +1,9 @@
 # Route transitions
 
 How pages of an app move against each other when the user navigates —
-`defineRouteTransition`, `defineRouteDefaultTransition`, and the thinking that
-decides which movement (if any) a navigation deserves. The API grammar itself
+`defineRouteTransition`, `defineRouteDefaultTransition`, what one link or one
+`navTo` may ask for on top of them, and the thinking that decides which
+movement (if any) a navigation deserves. The API grammar itself
 (accepted forms, shipped type names) lives in the JSDoc of
 `defineRouteTransition`; this file holds what a signature cannot say.
 
@@ -77,6 +78,77 @@ A default has no direction (nothing says which of two arbitrary pages is
 "before" the other), so only directionless movements make sense there. Written
 relations, and `"none"`, always win over it.
 
+## When one navigation knows better
+
+A relation is written on a PAIR, so it holds for every way of reaching the
+page — and some ways are walked against the map. Two pairs that are travelled
+in both directions, with one direction common and one rare:
+
+- a game ↔ a player's profile: the name of a player, tapped from the game, is
+  the common way in; a badge on a profile that leads back to the game it was
+  won in is the rare one;
+- a profile ↔ the cards it describes: going down into the cards is the
+  structural descent; a card that leads up to the player it describes goes back
+  out.
+
+Written for the common direction, the rare one plays backwards. And `"none"`
+cannot fix it: navi does not tell a link from the back button, so silencing the
+bad direction silences the good one too.
+
+So the navigation itself may ask, and what it asks holds for **that navigation
+and no other**:
+
+```jsx
+// The rare way round: the pair's movement, turned round.
+<Link
+  route={GAME_ROUTE}
+  routeParams={{ id }}
+  transition={{ direction: "back" }}
+>
+  {badge.gameName}
+</Link>
+```
+
+```js
+// The same thing said by a call rather than by an element.
+navTo(GAME_ROUTE.buildUrl({ id }), { routeTransition: { direction: "back" } });
+GAME_ROUTE.navTo({ id }, { routeTransition: { direction: "back" } });
+```
+
+The request is `"slide-x"`-style shorthand or `{ type, duration, direction }`,
+the same forms `defineRouteTransition` takes, plus `direction`. It overrides
+**field by field**: what it does not name, the relation (or the default) still
+answers for. So:
+
+- `{ direction: "back" }` keeps the pair's movement and only turns it round;
+- `"zoom"` swaps the movement, keeping nothing else;
+- `"none"` cuts, where the pair — or the default — would have played;
+- `{ duration: 500 }` re-times what was already going to play.
+
+A pair no relation was ever written for answers the same way: silence is what
+the routes say, and a link that asks for a movement gets it, forward unless it
+says otherwise. That is the whole shape of the control:
+`defineRouteTransition` is what the app's map says and applies by default; a
+link, or a programmatic `navTo`, overrides it for the length of one navigation.
+Navigate again by any other means and the relation is back in charge — nothing
+is remembered.
+
+The link wears what it asks as an attribute, so a plain `<a>` says it too (a
+type name, or the object as JSON):
+
+```html
+<a href="/game/42" data-navi-route-transition-request='{"direction":"back"}'
+  >…</a
+>
+```
+
+**Not yet: a movement chosen by HOW one navigated.** Playing one movement for
+the back button and another for a link would be written on the same request —
+`{ back: "slide-x", forward: "slide-y" }` — but the History API does not say
+which way a traversal went, and navi runs on it today (see
+`browser_integration/via_history.js`). The Navigation API does; the notation is
+kept in mind for the day navi navigates through it.
+
 ## Pages between fixed bars: the transition area
 
 By default the movement plays on the document itself — right when pages are the
@@ -151,6 +223,20 @@ movement against the view transition pseudo-elements — of the document, or of
 the marked area. See the JSDoc of `defineRouteTransition` for the selector
 shape, and the `spin` type in the demo for a working one.
 
+What is left to write is the `animation-name`s and nothing else: navi attaches
+to ANY named type what makes a movement look like one — each picture at the
+size it was taken at (a page half the height of the one it crosses would
+otherwise be seen inflating over the length of the movement), two solid pages
+rather than two panes of glass, and the animation held where it ends. The
+untyped cross-fade keeps the browser's defaults, since scaling one picture into
+the other is the whole idea there.
+
+The one knob a custom movement may want back: a movement that animates ONE of
+its two sides leaves the other on the browser's fade, and a fade needs its two
+half-transparent pictures to add up rather than cover each other
+(`mix-blend-mode: plus-lighter`, as the shipped `zoom` and the demo's `spin`
+both do). A movement where both pages move wants what navi poses.
+
 ## Route transitions and `RouteTravel` — one pair, one system
 
 `RouteTravel` and `defineRouteTransition` answer different questions:
@@ -198,14 +284,65 @@ browser needs to photograph the page being left (see `rendering_hold.js`), and
 it gives it back in the same callback. The hold is about a picture, not about
 data: nothing waits on it, nothing is skipped because of it.
 
-So "this list stopped refreshing since we animated the pair" is a claim worth
-checking twice before believing: it is held by
-`tests/route_transition_list_revisit/`, which mounts one app twice — the two
-mounts differing by a single `defineRouteTransition` line — and compares what
-each one sends to the network on the way back. See
+That is the design, and it is held by `tests/route_transition_list_revisit/`:
+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. 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.68",
+  "version": "0.29.70",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {