@jsenv/navi 0.29.56 → 0.29.57

package/docs/AI_INSTRUCTIONS.md

@@ -70,7 +70,8 @@ consistency across the app, not from any single call site.
 - `docs/list_refresh.md` — what a write sends back to the network and what stays
   on screen meanwhile: stale data returned by `useAsyncData({ loading: true })`,
   what updates from a response without any request, `rerunOn` and its defaults,
-  and how a paginated `<List.Items>` re-reads its slices without disappearing.
+  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.
 - `docs/error_handling.md` — the two kinds of error and how navi keeps them

package/docs/list_refresh.md

@@ -69,10 +69,10 @@ list containing it drops it too.
 
 ## A paginated list stays on screen too
 
-A `<List.Items>` reading through `GET_RANGE` holds the slices it received —
-places in a collection, not a list of ids — so nothing the store does can fix
-them: a row that changed tab, or one that was deleted, moves every row after it
-one rank up, and only the collection knows who fills the last place.
+A `<List.Items>` reading through `GET_RANGE` draws places in a collection, not
+a list of ids, so nothing the store does can fix them: a row that changed tab,
+or one that was deleted, moves every row after it one rank up, and only the
+collection knows who fills the last place.
 
 It is told, and it re-reads by itself:
 
@@ -84,7 +84,7 @@ It is told, and it re-reads by itself:
 />
 ```
 
-The reader keeps no value, so there is nothing to rerun; what it has is a
+The reader keeps no response, so there is nothing to rerun; what it has is a
 signal, bumped by the verbs `rerunOn.GET_RANGE` lists (`["POST", "DELETE"]` by
 default — `DELETE` is in there precisely because the store cannot fix places).
 A run hearing it asks again **for the window it is drawing**, and keeps drawing
@@ -108,11 +108,43 @@ itself: it is the one rendering the row, so it draws it loading, muted, or not
 at all. The run is not told about rows, only about the collection.
 
 ```jsx
-// ✗ remounting the run to refresh it: every row on screen becomes a skeleton
-//   again, and the list reopens where it opens, not where it was being read
+// ✗ remounting the run to refresh it: the list reopens where it opens, not
+//   where it was being read, and the reader is asked again for that window
 <List.Items key={`${scope}:${moved}`} … />
 ```
 
+## Leaving the screen and coming back
+
+A router renders one branch: opening a row unmounts the list that led to it.
+Coming back draws the rows from before, with no first load, because the reader
+keeps the collection's **composition** — which rank holds which id, and how many
+ranks there are — for each set of resolved bound params:
+
+```
+GAME.GET_RANGE { scope: "thread" }  →  { count: 412, byIndex: 0 → "W-ABC", 1 → … }
+GAME.GET_RANGE { radar: "R-42" }    →  { count: 18,  byIndex: … }
+```
+
+Ids, never rows: the rows are in the store already, shared and live, and a row
+dropped from the store simply stops resolving — a composition cannot hold a
+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.
+
+What a composition is about is the **values** its params hold, not the reader
+instance: `GET_RANGE.bindParams({ scope: "thread" })` called from two places
+reads and writes the same one (and gives back the same reader, memoized the way
+an action's `bindParams` is).
+
+The rest follows the rules already stated: a verb in `rerunOn.GET_RANGE`, or
+`reader.invalidate()`, drops the compositions — they stand for an order that is
+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.
+
 ## `rerunOn`, verb by verb
 
 `rerunOn` says which verbs invalidate this resource's `GET` / `GET_MANY` /

package/docs/resource.md

@@ -98,14 +98,20 @@ makes a change detectable), so the one the list is holding is the one it was
 given. Relations are not concerned: they are keyed by owner, and a row reading
 `game.candidates` reads the shared collection whatever object carries it.
 
-`GET_RANGE` is a **reader, not an action**. It keeps no value and takes no place
-in the rerun graph, which is what makes it usable per slice:
+`GET_RANGE` is a **reader, not an action**. It keeps no response and takes no
+place in the rerun graph, which is what makes it usable per slice:
 
 - the list already holds the slices it received and glues them back together —
   a second memory holding one of them would fight it;
 - a `POST` invalidating "the collection" would otherwise send every slice ever
   loaded back to the network at once.
 
+What it keeps instead is the collection's composition — which rank holds which
+id, and how many ranks there are, per resolved bound params — so a list drawing
+this collection again after its screen went away finds it drawn and revalidates
+it rather than starting over
+([list_refresh.md](./list_refresh.md#leaving-the-screen-and-coming-back)).
+
 What it does not give is membership: an item that leaves the collection stays on
 screen until the rows are asked for again. Give the screen its own way to ask
 (a refresh gesture, a `key` on the run).

package/package.json

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