@jsenv/navi 0.29.392 → 0.29.394

package/docs/AI_INSTRUCTIONS.md

@@ -98,8 +98,10 @@ to start when unsure which export solves a problem.
   action from a component, and before putting a delay on params.
 - `resource.md` — REST state: `resource()`, the callback contract of each
   relationship method (not guessable), `GET_RANGE`, a search as the same
-  `GET_MANY`, `withParams()` scopes and `dependencies`. Read before writing a
-  resource; never encode a sub-route as an `op` discriminator.
+  `GET_MANY`, `withParams()` scopes and `dependencies`, `persist` (the last
+  `GET` answer drawn again after a reload). Read before writing a resource, and
+  before caching a response in localStorage; never encode a sub-route as an
+  `op` discriminator.
 - `data_states.md` — `data`, `loading` and `error` are three questions; the
   four combinations of the first two; `loading: true` never suspends; a skeleton
   is told whether it is loading. Read before drawing a skeleton on `!data` or

package/docs/data_states.md

@@ -82,7 +82,10 @@ whose params name a row the store already holds — read earlier by a `GET_MANY`
 a relation, a list — starts on the second line, not the first: the row is drawn
 and the request goes out behind it. The response replaces it, and a failure
 lands beside it like any refresh failure. A `GET` of a row the store lacks
-still starts on the first line, so what is drawn is never a different row.
+still starts on the first line, so what is drawn is never a different row. A
+row known from the previous page load counts too, when the resource asks for
+it: [`persist`](./resource.md#persist-the-last-answer-drawn-again-after-a-reload)
+puts a reload on the second line as well.
 
 **The emptiness test is `data === undefined`, never `loading`.** Reading
 `loading` as "there is nothing to display" blanks the screen on every refresh —

package/docs/navigation.md

@@ -431,6 +431,47 @@ param that qualifies a screen is not a place, and one entry per write turns a
 single back-press into as many as the user moved. A state whose values ARE
 places says so — see [`history: "push"`](#a-state-whose-values-are-places-history-push).
 
+#### A value written per frame
+
+Every write of the signal reaches the address, synchronously, and browsers
+refuse an address written too often: Safari throws a `SecurityError` past 100
+writes per 10 seconds, and the state then runs ahead of an address that stopped
+following. A value dragged at 60 Hz gets there in under two seconds. Chromium
+drops the writes silently, so a developer working there never sees it; navi
+warns in dev when the budget is reached.
+
+**An address is not a recording of a gesture.** What the address records is
+where the value was PUT DOWN, not the path the finger took. So the value one
+drags belongs to the gesture, and the state bound to the url is written when the
+gesture ends:
+
+- **A gesture with a release** — a disc turned, a slider dragged: hold the value
+  in the component while the pointer is down, and write the signal on release.
+  Re-reading the signal meanwhile would pull the control back mid-gesture, so
+  the held value is the one drawn.
+- **A movement with no release** — a wheel zooming, a fly-to animation: write
+  the signal when the movement has settled (a short idle timer, or the end of
+  the animation).
+
+When every intermediate value IS a valid address — the centre of a panned map,
+where each frame is a place one could reload into — the state can ask navi to
+debounce the browser's address instead, in milliseconds:
+
+```js
+const eastSignal = stateSignal(0, {
+  id: "e",
+  type: "number",
+  debounceUrl: 200,
+});
+```
+
+The routes, the document url and the renders still follow every write; only the
+browser's copy of the address (`window.location`) waits for the state to stay
+still that long, and is then written with the last value. A push is never
+debounced, and a push or a state written onto the entry flushes what is pending
+first. A back pressed before the write keeps the entry at the last address
+written: the drag in progress, and nothing else.
+
 ## Rendering routes
 
 `<Route>` is the only primitive. With `children` it is a container that renders

package/docs/network_policy.md

@@ -195,8 +195,11 @@ one says why is something navi has nothing to decide it with.
 - **What a screen says on a `NetworkPolicyError`** — "no network" is a fact
   about the device, "offline mode" a decision, "we are only looking" neither;
   `error.reason` is there so the screen says the right one.
-- **Persisting the store to disk**, so that a reload offline reopens a full
-  app rather than an empty one.
+- **Which answer is worth keeping across a reload.** A resource declaring
+  [`persist`](./resource.md#persist-the-last-answer-drawn-again-after-a-reload)
+  has its last `GET` answer back in the store at the first run, and under the
+  policy that row answers the `GET`: a reload offline reopens on it. Which
+  resource, into which signal, and for which session, is the app's to say.
 - **A queue of writes to replay** once the network is back. Deliberately not
   navi's: what a replayed write means (a score entered twice? a seat taken
   since?) is the app's business.

package/docs/resource.md

@@ -34,6 +34,7 @@ Actions are read in components through the action system (`useAsyncData`,
 looks like ([data_states.md](./data_states.md#data-and-loading-are-independent)).
 
 - [`store.upsert()` is not how data enters the store](#storeupsert-is-not-how-data-enters-the-store)
+- [`persist`: the last answer, drawn again after a reload](#persist-the-last-answer-drawn-again-after-a-reload)
 - [`GET_RANGE`: feeding a list that loads as it scrolls](#get_range-feeding-a-list-that-loads-as-it-scrolls)
 - [Searching the same collection](#searching-the-same-collection)
 - [Relations: pick one of the four methods](#relations-pick-one-of-the-four-methods)
@@ -62,7 +63,8 @@ that does not return what it should.
 it yourself is the point:
 
 - seeding it with data that came from elsewhere — state rendered by the server,
-  a local cache, a websocket message;
+  a websocket message (the resource's own last answer is not "elsewhere": that
+  is [`persist`](#persist-the-last-answer-drawn-again-after-a-reload), below);
 - absorbing the parent object a relation route answered with: the relation
   callback only writes the relation, so the parent's own fields have nowhere
   else to land (see [When the backend answers a sub-route with the whole
@@ -71,6 +73,98 @@ it yourself is the point:
 A list that loads its rows a slice at a time is **not** one of those cases — that is
 `GET_RANGE`, right below.
 
+## `persist`: the last answer, drawn again after a reload
+
+Some `GET`s are the app. `GET /me` answers who is signed in, their things, what
+the header and the tab bar draw; until it lands, a page that is rendered has
+nothing to draw. On a reload, or when the app is reopened from the home screen,
+that wait is pure loss: the previous answer was on screen a moment ago and is
+almost always still true, and a server waking up makes it last seconds.
+
+What is wanted is the second line of the table in
+[data_states.md](./data_states.md#data-and-loading-are-independent) reached on
+a reload: the last known row drawn, the request out behind it, the fresh answer
+replacing it. `persist` names the resource whose answer is worth keeping, and
+the signal that keeps it — a `stateSignal` that persists, the primitive navi
+has for a state that survives a reload:
+
+```js
+const mePersistedSignal = stateSignal(undefined, {
+  id: `me@${APP_VERSION}`,
+  persists: true,
+  type: "object",
+});
+const ME = resource("me", {
+  persist: {
+    signal: mePersistedSignal,
+    when: () => !viewAsSignal.value,
+  },
+  GET: () => fetchJson(`/me`),
+});
+ME.one("user", USER);
+ME.many("my_games", GAME);
+```
+
+From there navi does the rest:
+
+- **the rows `GET` lands with are written into the signal** — one per params
+  the `GET` was asked with, so a `GET` without params keeps one row. Where the
+  signal keeps its value is the signal's business: `persists: true` is
+  localStorage, and a plain `signal()` keeps it for the page's lifetime, which
+  is what a test wants;
+- **the first run of the `GET` draws the kept row.** It enters the store and
+  becomes the action's provisional value: `data` is set while `loading` is
+  `true`, the row is on screen and the request is out behind it. Nothing else
+  moves — `runningState` is `running`, the answer replaces the row, an error
+  lands in `errorSignal` beside it;
+- **the copy follows the store.** It is written with its relations inline — the
+  shape the `GET` callback returns, so it re-enters through the same setters a
+  real answer goes through — and rewritten whenever the row or a row it reaches
+  through a relation changes: a `PUT` on the item, a list upserting one of its
+  children, a game joining `my_games`. A rewrite that changes nothing is
+  skipped, so the signal moves only when the copy does;
+- **under a network policy answering reads from the store, the kept row answers
+  the `GET`** ([network_policy.md](./network_policy.md)): a reload with no
+  network reopens on the last answer rather than on nothing.
+
+What stays the app's, because only the app knows:
+
+- **the key.** A stored copy is only as good as the code reading it: a deploy
+  that changes the shape of the answer must not draw the old one. Put in the
+  signal's `id` whatever makes a copy unusable — the deployed version — and a
+  new id starts clean.
+- **`when`: is the copy about this session?** A tab viewing as someone else, an
+  account being switched — the row in the store is somebody's, and it must not
+  be kept for the next person. `when` is read whenever the copy is about to be
+  read or written: `false` reads nothing, writes nothing, and empties the
+  signal. It is a function so it can read a signal, and it has to: a plain
+  variable is only looked at again when the store changes.
+- **the moment, not the state.** Sign-out is not a condition that holds, it is
+  something that happens: writing `undefined` into the signal
+  (`mePersistedSignal.value = undefined`) forgets the copy at once, and nothing
+  is written until a `GET` lands again. The store rows stay — the screen keeps
+  what it shows until the app resets the action, as it does today.
+- **what the `GET` feeds beside its return value.** Counts, badges, a feature
+  flag set from the response are the app's signals, not the row; they are not
+  kept, and the callback does not run on a kept row. Anything the app wants
+  back before the answer, it stores itself.
+- **the veil.** A loading screen that waits on the `GET` being `running` stays
+  over the drawn row for the whole request. It waits on `data` being set —
+  the emptiness test of data_states.md — and the refresh is shown as usual.
+
+What the copy is not:
+
+- **an answer.** The `GET` goes out every time; the copy is a drawing aid. A
+  screen must not read `data` as "the server confirmed": that is `loading`,
+  and the two are independent.
+- **a store on disk.** One row per params key, `GET` only — a resource whose
+  `GET` is asked for every id would keep every id. It is meant for a singleton
+  or a handful of rows.
+- **seeded at declaration.** The row enters the store at the first run of the
+  `GET`, once the relations are declared, so that its relation values are
+  normalized into their stores as a real answer's are. `ME.store` read before
+  that first run is empty.
+
 ## `GET_RANGE`: feeding a list that loads as it scrolls
 
 A `<List.Items>` asks for the rows it is about to draw and keeps what it gets.

package/package.json

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