@jsenv/navi 0.29.67 → 0.29.69

package/docs/AI_INSTRUCTIONS.md

@@ -72,8 +72,11 @@ consistency across the app, not from any single call site.
   what updates from a response without any request, `rerunOn` and its defaults,
   and how a paginated `<List.Items>` re-reads its slices without disappearing,
   including on its way back from a screen that unmounted it.
-  Read it before adding verbs to `rerunOn`, hiding a list on `loading`, or
-  remounting a list with a `key` to refresh it.
+  It also says who decides a re-read on the way back — the source the list
+  reads through, never the navigation and never a route transition.
+  Read it before adding verbs to `rerunOn`, hiding a list on `loading`,
+  remounting a list with a `key` to refresh it, or reporting that a page
+  stopped refreshing since a transition was defined on its pair.
 - `docs/error_handling.md` — the two kinds of error and how navi keeps them
   apart: where an error is shown depending on where it came from (a control's
   action shows it on what was clicked, a route action replaces the page, a
@@ -162,14 +165,17 @@ 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>`,
-  tab rows (`Nav` / `Link` / `RouteTravel`), and the few cases where tabs are
-  legitimately not URLs. Read it before writing any routing code — the
+  tab rows (`Nav` / `Link` / `RouteTravel`), where a navigation lands
+  (scroll: a push arrives at the top, a back or forward lands where the page
+  was left), and the few cases where tabs are legitimately not URLs. Read it before writing any routing code — the
   position of the user belongs in the URL by default, and that decision is
   not retrofittable.
 - Source code and demos on GitHub:

package/docs/list_refresh.md

@@ -132,8 +132,9 @@ stale copy of anything.
 A run that finds a composition takes the `refreshing` line of the table above
 rather than the loading one: the rows are on screen while it asks again for the
 window it draws. So the two lists an app cannot tell apart from the outside —
-one reading `GET_MANY`, one reading `GET_RANGE` — behave the same on the way
-back.
+one reading `GET_MANY`, one reading `GET_RANGE` — look the same on the way back:
+neither blanks, neither shows a first load. What they do behind that is not the
+same, and the next section is about exactly that.
 
 What a composition is about is the **values** its params hold, not the reader
 instance: `GET_RANGE.bindParams({ scope: "thread" })` called from two places
@@ -145,6 +146,89 @@ The rest follows the rules already stated: a verb in `rerunOn.GET_RANGE`, or
 gone — and `memoryBudget` (1000 ranks by default) trims the ranks far from any
 window, which are asked for again if the user goes back to them.
 
+### Who decides the re-read — and who does not
+
+The navigation decides nothing. Neither the back button, nor the movement
+playing between the two pages: the **source** the list reads through is what
+answers, and it answers the same way whether the user arrived by a link, by
+`history.back()`, or under a route transition.
+
+| The list reads through          | Coming back to it                                                                                     |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `routeAction` over `GET_MANY`   | **nothing goes out** — the action holds its response, and `.run()` on a `COMPLETED` action is a no-op |
+| `<List.Items>` over `GET_RANGE` | **one ask goes out** — the reader kept ranks, not rows, and revalidates the window it draws           |
+
+Both are deliberate, and they are not in tension: an action that kept its answer
+has the answer, while a composition is a claim about an order that any write
+elsewhere may have made false. What a `GET_MANY` list wants on the way back it
+has to say itself — `.rerun()` when the route becomes current again, or a verb
+in `rerunOn` if a write is what makes it stale.
+
+Nothing above changes when `defineRouteTransition` is written for the pair the
+list is walked through. A transition states a relation between two pages (see
+[route_transitions.md](./route_transitions.md)); it takes the document's
+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 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.
+
+### 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
 
 `rerunOn` says which verbs invalidate this resource's `GET` / `GET_MANY` /

package/docs/navigation.md

@@ -294,6 +294,42 @@ settings page rising over whatever showed it — are animated with
 `defineRouteTransition` instead, and a given pair must be animated by one of
 the two, never both: see [route_transitions.md](./route_transitions.md).
 
+## Where a navigation lands: the scroll
+
+Three cases, and they are not a policy to configure but three different facts:
+
+- **Going somewhere new** (a `<Link>`, anything that pushes) lands at the top.
+  It is an arrival: the offset one had elsewhere means nothing here, and left
+  alone the new entry would be born holding the previous page's offset — which
+  the browser would then hand back as if it were this page's own.
+- **Going back or forward** (the browser's buttons, `navBack()`,
+  `history.back()`) lands where that page was left. navi keeps the position and
+  puts it back once the page is really rendered, which is what the browser
+  cannot do: it restores at the instant the entry changes, when the document
+  still holds the page being left, so anything further down than that page is
+  tall is clamped away.
+- **A reload** lands where one was, as it would have without navi.
+
+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
+clamped as it was before. Only the page knows when it is whole.
+
 ## Creating something, then editing it
 
 The create screen, the page of what was created, the edit screen — three routes,

package/docs/route_transitions.md

@@ -1,14 +1,15 @@
 # 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.
 
 Demos: [the movements](../src/nav/demos/route_transition/route_transition.html),
 [a default transition](../src/nav/demos/route_transition/route_transition_default.html),
-[pages between fixed bars](../src/nav/demos/route_transition/route_transition_fixed_bars.html),
+[pages between fixed bars](../src/nav/demos/route_transition_fixed_bars/route_transition_fixed_bars.html),
 [with a RouteTravel inside](../src/nav/demos/route_transition/route_transition_with_travel.html)
 
 ## What a transition is for
@@ -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
@@ -110,6 +182,12 @@ through, not the page's own size: a page is as tall as its content, and a
 vertical movement measured on the picture would send it several screens away —
 off screen for most of the transition, flying past at the end.
 
+A page that was **scrolled** is photographed where the reader was, and travels
+from there: the document is not put back to its top until the picture has been
+taken. Without that wait the picture keeps only the band the browser had
+already painted at the new offset, and the movement carries a fragment of the
+page instead of the page.
+
 With an area marked, the page around it is left LIVE rather than photographed:
 the bars keep answering the pointer for the whole movement, which a captured
 element cannot do. The flip side is that anything around the area which must
@@ -145,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:
@@ -176,6 +268,37 @@ animates. A `<RouteTravel>` rendered inside the `element` of each of the routes
 it travels between is destroyed mid-travel by the router. Give the row a single
 branch — its tabs as params of one route is the usual shape.
 
+## A transition says nothing about data
+
+A relation is about the map of the app, and about nothing else. Defining one
+does not change what the page arriving loads, reloads, or keeps:
+
+- an action that `COMPLETED` still holds its response, on the way back as on the
+  way in — a page wanting fresh data says `.rerun()`, with or without a
+  movement;
+- a `<List.Items>` reading through `GET_RANGE` still revalidates the window it
+  draws when it is mounted again.
+
+What a transition takes is the document's **rendering** for the one frame the
+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.
+
+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.
+
 ## 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.67",
+  "version": "0.29.69",
   "type": "module",
   "description": "Library of components including navigation to create frontend applications",
   "repository": {