@jsenv/navi 0.29.446 → 0.29.448

package/docs/AI_INSTRUCTIONS.md

@@ -83,7 +83,8 @@ start when unsure which export solves a problem.
   running (`{ run: true }` is the fallback), `action` versus `uiAction`, an
   action and a command on one press. Before running an action from a component.
 - `resource.md` — `resource()` and its relations (never an `op` discriminator),
-  `GET_RANGE`, a search as the same `GET_MANY`, `withParams()` scopes and
+  `GET_RANGE` (its inclusive `end`, the count for the screen around the list, a
+  question following a search field), a search as the same `GET_MANY`, `withParams()` scopes and
   `dependencies`, `persist` (and `keepPageOnScreen` for the page on screen), a
   function versus the verb's instance. Before writing a resource, and before
   caching a response yourself.
@@ -186,11 +187,13 @@ start when unsure which export solves a problem.
   `scroller`, where a list opens (a position handed back whole, `visibleCount`
   included), a list that comes back (its `id` names one list of the app), a
   popup that scrolls, many rows (`<List.Items>`, the render window and its first
-  picture, skeletons at the size of their item, `itemSize`, `findText`), many
+  picture, skeletons at the size of their item, `itemSize`, `findText`, how far
+  ahead its images load and `loading` before `src`), many
   sections (`<Box mount="after-paint">` and what it leaves out of reach), hover
   while scrolling. Before writing CSS to make something scroll, before
   rendering a collection as `<List.Item>` children, before writing a
-  `renderSkeleton`, and before deferring part of a page.
+  `renderSkeleton`, before putting images in a run, and before deferring part
+  of a page.
 - `z_index.md` — DOM order first; a `z-index` without `isolation: isolate`
   competes with the page; navi's bands. Before writing a `z-index`.
 - `typography.md` — text is a component; `maxLines` is the one truncation; one

package/docs/resource.md

@@ -269,13 +269,20 @@ const GAME = resource("game", {
 
 The callback receives the bound params merged with the range the list asks for
 (`start`, `end`, `limit`, `before`, `after`, `around`), and `{ signal }`,
-aborted when the list stops wanting those rows. It returns a range the way a
-`Content-Range` does: **`{ items, start, count }`** — these rows, at this place,
-out of that many. `start` may be omitted when the list asked for one at or after
-`0` (a negative `start` counts back from the end, and the source must then say
-where the slice landed); `count` defaults to `start + items.length`. The items
-are upserted on their way in, so the list draws store items, never copies of the
-JSON.
+aborted when the list stops wanting those rows. `end` is the last place asked
+for, included, as in `Range: items=0-99`: `limit` is `end - start + 1`, and an
+API whose end is excluded is called with `start + limit`. It returns a range the
+way a `Content-Range` does: **`{ items, start, count }`** — these rows, at this
+place, out of that many. `start` may be omitted when the list asked for one at
+or after `0` (a negative `start` counts back from the end, and the source must
+then say where the slice landed); `count` defaults to `start + items.length`.
+The items are upserted on their way in, so the list draws store items, never
+copies of the JSON.
+
+The count is also what the screen around the list says — "5 of 83 books". The
+run hands it out with `onCountChange`: `undefined` until a slice has answered,
+then each count a slice brings, and again for each collection the run draws, so
+the number always belongs to the rows on screen.
 
 But the list keeps the object it was handed, and an update replaces the item
 object (the store holds values, which is what makes a change detectable). So a
@@ -304,6 +311,30 @@ rows staying on screen
 reads a collection, so it lives on the resource (or on a `withParams()` of it),
 not on a relation.
 
+### A question that follows a search field
+
+A reader bound to other params is another collection, and the run draws it
+from its first item — it needs no `key` for that. A param following what is
+typed then makes one collection per key, and one request each, the server
+receiving every one even when the list calls it off. `debounce` on the run
+waits for the reader to hold still, and keeps the collection from before drawn
+meanwhile, `refreshing`:
+
+```jsx
+<List.Items
+  itemsAction={BOOK.GET_RANGE.bindParams({ q: searchSignal.value })}
+  debounce={300}
+  onCountChange={(count) => {
+    bookCountSignal.value = count;
+  }}
+  renderItem={renderBook}
+/>
+```
+
+A `key` that follows the field defeats it: the run remounts at each key, and
+its wait with it. Demo: `src/control/demos/integration/1_list_loaded_by_scroll_demo.html`
+("Une recherche qui suit la frappe").
+
 ## Searching the same collection
 
 A screen showing a collection soon asks a second question about it: the list

package/docs/scroll.md

@@ -482,6 +482,44 @@ is never revealed. navi's own does.
 
 Reference: `src/control/demos/19_list_find_in_page_demo.html`.
 
+### Images in a run
+
+An `<img>` asks for its file once it is in the DOM, and an item outside the
+render window is not. So in a run, two things decide how far ahead of the screen
+images load, the window and the browser, and the nearer one wins:
+
+- **Without `loading="lazy"`**, the window decides. Every item it draws loads
+  its images, so the lookahead that keeps a fling covered (three quarters of
+  what the screen leaves of `renderBudget`, which is dozens of items with the
+  default) is downloaded when the list opens, and again each time the window
+  slides.
+- **With `loading="lazy"`**, the browser decides inside the window, and each
+  engine decides differently. Measured in October 2026, this is how far below
+  the screen an image's top is when its request starts:
+
+  | engine                        | distance           |
+  | ----------------------------- | ------------------ |
+  | Chromium                      | ~3000 px           |
+  | WebKit (every browser on iOS) | ~1 viewport height |
+  | Firefox                       | ~600 px            |
+
+  Chromium keeps the same distance on 3G and on 4G. When the window's lookahead
+  is shorter than the engine's distance, the window decides again.
+
+It is a trade between bytes and images that are ready. Lazy images follow the
+screen, and nothing the user never reaches is downloaded. Eager ones are
+already there when a fling arrives, at the cost of a whole window of downloads.
+How far ahead is enough depends on how fast the screen is crossed and how fast
+a file arrives. Like the window's own lookahead, it is measured on the slowest
+device and connection the list serves. Whichever you choose, give each image
+its dimensions (see
+[What the list knows, and what it guesses](#what-the-list-knows-and-what-it-guesses)).
+
+`loading` only holds if it is set before `src`. `Image` does this whatever the
+order of its props. A plain `<img>` written in JSX must put `loading` first:
+WebKit decides when `src` is set, and an image whose `src` came first loads
+whatever `loading` says afterwards.
+
 ### Doing it well
 
 - **Skeletons at the size of their item**, and `itemSize` when the items above
@@ -498,10 +536,14 @@ Reference: `src/control/demos/19_list_find_in_page_demo.html`.
   item and the index it is given rather than closing over state.
 
 The rest — `virtualItemSize`, the room an item not drawn is held at (uniform
-items, or the smallest one of a mixed list — the worst case, see above), a `key`
-on the run when the collection changes as a whole (never to refresh it, see
+items, or the smallest one of a mixed list — the worst case, see above), a
+collection that changes as a whole (another array, another reader — drawn from
+its first item; never a `key` to refresh it, see
 [list_refresh.md](./list_refresh.md#a-paginated-list-stays-on-screen-too)),
-`groupBy` for sections — is in the JSDoc of `List` and `List.Items`
+`debounce` for a question following a search field
+([resource.md](./resource.md#a-question-that-follows-a-search-field)),
+`onCountChange` for the screen around the list to say how many items there
+are, `groupBy` for sections — is in the JSDoc of `List` and `List.Items`
 (`src/control/list/list.jsx`). Demos:
 `src/control/demos/17_virtual_scroll_and_filter_demo.html` (a run in memory,
 searched), `src/control/demos/integration/1_list_loaded_by_scroll_demo.html` (a

package/package.json

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