@jsenv/navi 0.29.68 → 0.29.69

package/docs/AI_INSTRUCTIONS.md

@@ -165,9 +165,11 @@ 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. Read it before
+  animating any navigation.
 - `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

@@ -170,11 +170,64 @@ 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.
 
-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.
+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.
+
+### 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)
+```
+
+| 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.
 
 ## `rerunOn`, verb by verb
 

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,11 +284,18 @@ 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.
+
+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
 [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.
 

package/package.json

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