0038. Images load through a runtime cache: one fetch and one decode per address
- Status: Proposed
- Date: 2026-11-14
- Decided by: integrator (internal only), pending Mik's approval
- Planning item: WP7 (kit: images)
Context
Feeds and galleries show the same picture many times: an avatar on every post, a thumbnail and then the full image, the same photo on the list screen and the detail screen. Handing every <img> its address lets the browser decide when to decode, which on a phone means jank as a screen appears, a flash of empty boxes, and the same picture decoded again when a list row is rebuilt. Native targets have the same problem and solve it with an image cache (SDWebImage, Coil). The kit's Image also needs to know when loading fails, to show a fallback, and when it succeeds, to fade in.
Decision
- **The runtime loads every
<image>, never the browser directly.** On the web the emitter writessrcasdata-src, and the runtime's image module (packages/client/src/web/image.ts) loads it. - The caching rule: one entry per absolute address, for the life of the app. The first image that needs an address fetches and decodes it once (
HTMLImageElement.decode()), off the main thread, and the entry keeps the decoded picture alive. Every later image with that address, on this screen or another, waits for the same entry, or once it has loaded, shows the picture at once: no placeholder, no fade, no second request and no second decode. The cache keeps the 200 most recently used addresses and evicts the oldest. A failed address is remembered for 10 seconds, so a list of broken images makes one request each, and coming back later tries again. - Loading looks the same everywhere: while loading, the image's box shows its
placeholdercolour (a theme colour name, or a colour such as the image's average); a theme colour name is the theme's token, and anything else, such as#8a9bb0ortomato, is a CSS colour as written. Then the image fades in from a blur over 320 ms, unless the device asks for reduced motion or the picture was already decoded.on:loadruns when it shows;on:errorwhen it cannot be loaded, so a part can show a fallback. - **
lazy** images wait until they are within 300 points of the visible area (an IntersectionObserver), unless the cache already has them. - Images need a description:
alt, ordecorativefor an empty one (E0160). An emptyalt="",alt={undefined}anddecorative={false}count as absent. - Bound flags are followed.
decorative={condition}empties the description while the condition holds and gives the image its own back afterwards.zoomable={condition}adds and removes the zoom gestures as it changes (we chose following it over rejecting a bound zoomable with a diagnostic: a gallery that zooms only once a picture has loaded is a fair use, and the runtime cost is one attribute observer).zoomable="false"andlazy="false"are off, likelazy={false}. - **A project's
public/folder** (decision 0042) is copied to the site as it is, byte for byte, so an app ships its own images (public/photos/lake.jpgis/photos/lake.jpg).
Alternatives considered
| Option | Why not |
|---|---|
| Rely on the browser's HTTP and memory caches | No guarantee against a second decode, no load or error signal before the swap, and nothing to share with native |
loading="lazy" and decoding="async" on the <img> | Lazy only; no placeholder, no fade, no fallback signal, and still a decode per element |
| A cache keyed by the image element | Misses the main case, the same address in different elements and on different screens |
| An unbounded cache | Memory grows with every picture a long session sees |
| Remember failures for ever | A picture that was briefly unreachable would stay broken until a reload |
Consequences
decodeCount(url)in the image module reports decodes per address; the kit's browser tests assert one decode and one request per address.- Native targets will implement the same rule in their engine adapter: one entry per address, the same limits, the same placeholder and fade.