@jsenv/navi 0.29.445 → 0.29.447

package/docs/AI_INSTRUCTIONS.md

@@ -186,11 +186,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/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

package/package.json

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