@johnmorrisdotca/kazoku-ui 0.7.2 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [0.9.0] - 2026-11-02
+
+The sixth and seventh parts: the shared 3D renderer, at `@johnmorrisdotca/kazoku-ui/renderer`, and the freeze checks for a 3D package's e2e, at `@johnmorrisdotca/kazoku-ui/testing`.
+
+- **One WebGL context per page.** `createSharedRenderer({ load: () => import("three") })` makes one renderer and moves its canvas to the focused view's host (`view.focus()`); every other view shows a still. Thirty views and fifty changes of focus make one context and one canvas. three.js is an optional peer (`peerDependencies`, `peerDependenciesMeta`) and is never imported or bundled by this package: the page passes the dynamic import, so three loads only when the first view goes live (a demo page checks it).
+- **Shared assets with reference counts** (`createAssetCache`, and `assets.acquire(key, make, dispose)` inside an item's `build`): made once per key, freed after a short linger when the last view lets go; `disposeDeep` frees a loaded model.
+- **Stills** (`view.showStill()`): rendered once from the same renderer, one at a time, into a PNG blob in an `<img>`; items with the same key share one; a least-recently-used list with a byte budget (32 MB decoded) frees the rest, and an evicted still is made again when needed.
+- **Drawing on demand** (`createScheduler`): one frame loop for every view, nothing drawn or requested at rest, exactly one frame requested at a time (a change event inside a draw adds none), a per-frame budget (2 draws, 10 ms) with the focused view first, and no frames while the view is out of sight or the tab hidden. After `releaseMs` (30 s) out of sight the context is let go and made again when the view is seen.
+- **Pixel budget in one place** (`pixelRatioFor`): 6 million pixels, 4096 a side, ratio 2; a 5K screen at ratio 2 is drawn inside it, not at 24 MP.
+- **Context loss** (`webglcontextlost` and `webglcontextrestored`) is handled in one place: drawing stops and the still shows, then the view draws again; `onContext` is told.
+- **`/testing`**: `COUNT_SCRIPT` (an init script that counts WebGL contexts, GPU objects made and deleted, draws and animation frames), `readCounts`, `gpuObjects`, `canvasSize`, `withinPixelBudget`. It names no test framework.
+- Demo `renderer.html` (thirty views on one renderer, Fill the window) and `renderer-lazy.html`; `e2e/renderer.demo.mjs` asserts contexts = 1 over fifty focus changes, 0 draws and 0 frame requests at rest, flat GPU objects, cache and heap over fifty more, the canvas within budget on a 5120x2880 screen at ratio 2, a lost and restored context, out of sight, the stills' byte budget, and three.js fetched only on demand. Docs: `docs/renderer.md`. Size: 8.9 KB gzipped for the renderer and 1.6 KB for the kit.
+
+## [0.8.0] - 2026-11-02
+
+The view controls show the zoom, control the auto-turn speed, and come in two levels so the bar stays simple.
+
+- **Zoom readout.** A button between zoom out and zoom in shows the zoom (`1×`, `2.4×`); tapping it goes back to Fit. A screen reader is told "Zoom level 2.4×" once the zoom has settled (a polite status, not on load, not for every step of a pinch).
+- **Auto-turn speed.** Slow, Medium and Fast: half, once and twice the `speed` attribute (30 degrees a second). It never stops or restarts the turn. Kept in the address as `?speed=slow` or `?speed=fast` (key renameable with `address-keys="speed:pace"`); Medium leaves the address, and a page's own `speed` value is left alone. `parseAddress` and `formatAddress` take and give an optional `pace`.
+- **`controls="basic|advanced"`.** Basic is the default and shows the angle slider, Auto-turn, zoom out and in with the readout, Fit and a small More button. Advanced (More, or the attribute) adds tilt, speed, Front, 2 times, the pan pad and Move or Turn. The reader's choice is remembered in `localStorage` (`kazoku-view-controls`, or the key `storage` names) and beats the attribute written in the markup; the host carries `data-level`.
+- **Changed default.** The default bar is simpler than 0.7: tilt, Front, 2 times, the pan pad and Move or Turn are behind More. A page that wants them from the start sets `controls="advanced"`.
+- New pure exports from `view-controls`: `parseLevel`, `parsePace`, `zoomText`, `PACES`, `PACE_FACTOR`, `LEVEL_STORAGE_KEY`. New labels `zoomLevel`, `zoomReset`, `more`, `speed`, `slow`, `medium`, `fast` in English and Japanese (the Japanese is to be read by a native speaker).
+
+## [0.7.3] - 2026-11-02
+
+One agent-instruction template for the family's package repos. Tooling and docs only; the package is unchanged.
+
+- `templates/AGENTS.md`: the family rules above a marker (read spx-stats `docs/package-work.md` first, the board and ticket prefix with `--area`, ports, commits, checks, the release path, hand-off project, reporting) and a Facts table plus a "This repo" section below it for what is true only in one repo. Public: no private host, path or key.
+- `docs/agents-template.md`: how to adopt it, and which repos would. `test/template.test.ts` holds the marker, the table and the privacy rule.
+
 ## [0.7.2] - 2026-11-02
 
 One release workflow for all the family's packages.

package/README.md

@@ -2,14 +2,14 @@
 
 <picture>
 <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kazoku-ui/main/docs/images/hero-dark.webp">
-<img alt="The demo: in its header the English and 日本語 choice and the Light, Dark and Auto switch; below, a white card with a blue circle and a black triangle, turned a little and tipped, in a frame with a dotted floor. Under it the view controls: Angle and Tilt sliders, Auto-turn and Front buttons, zoom out, 2 times, zoom in and Fit, four arrows to move the zoomed view, and the Move and Turn choice for a drag." src="https://raw.githubusercontent.com/johnmorrisdotca/kazoku-ui/main/docs/images/hero-light.webp" width="720">
+<img alt="The demo: in its header the English and 日本語 choice and the Light, Dark and Auto switch; below, a white card with a blue circle and a black triangle, turned a little and tipped, in a frame with a dotted floor. Under it the view controls: an Angle slider, an Auto-turn button, zoom out, the zoom readout, zoom in and Fit, and a small More button." src="https://raw.githubusercontent.com/johnmorrisdotca/kazoku-ui/main/docs/images/hero-light.webp" width="720">
 </picture>
 
 The family's shared interface parts, as their own versioned package: one part per subpath, so a page loads only what it uses. No runtime dependencies, MIT.
 The first part is the **view controls** for any 3D or zoomable view. They never draw the scene: they tell your page what the reader chose, and your canvas, WebGL,
 SVG or CSS 3D applies it.
 
-[Demo](https://johnmorrisdotca.github.io/kazoku-ui/) · [Strict-CSP demo](https://johnmorrisdotca.github.io/kazoku-ui/csp.html) · [Theme switch](docs/theme-switch.md) · [Language picker](docs/language-picker.md) · [Address state](docs/address-state.md) · [Save image](docs/save-image.md) · [Content-Security-Policy](docs/csp.md) · [Labels, English and 日本語](docs/labels.md) · [Changelog](CHANGELOG.md)
+[Demo](https://johnmorrisdotca.github.io/kazoku-ui/) · [Strict-CSP demo](https://johnmorrisdotca.github.io/kazoku-ui/csp.html) · [Theme switch](docs/theme-switch.md) · [Language picker](docs/language-picker.md) · [Address state](docs/address-state.md) · [Save image](docs/save-image.md) · [Shared 3D renderer](docs/renderer.md) · [Content-Security-Policy](docs/csp.md) · [Labels, English and 日本語](docs/labels.md) · [Changelog](CHANGELOG.md)
 
 ```sh
 npm install @johnmorrisdotca/kazoku-ui
@@ -31,13 +31,16 @@ Parts (each its own subpath; later ones: picture-tile pickers, Help, GitHub and
 | `@johnmorrisdotca/kazoku-ui/save-image` | The formats, the file name, the size and the functions that render and download a canvas, an SVG or an element as PNG or SVG. Imports on a server. |
 | `@johnmorrisdotca/kazoku-ui/save-image/element` | The `SaveImageElement` class (needs a browser). |
 | `@johnmorrisdotca/kazoku-ui/save-image/define` | Registers `<kazoku-save-image>` (once, and only if the tag is free). |
+| `@johnmorrisdotca/kazoku-ui/renderer` | The shared 3D renderer: one WebGL context for the focused view, shared assets, stills, drawing on demand, a pixel budget. three.js is an optional peer, loaded by your `import("three")`. Imports on a server. |
+| `@johnmorrisdotca/kazoku-ui/testing` | The freeze checks for a 3D package's e2e: count contexts, GPU objects, draws and frames; the canvas size against the budget. No test framework named. |
 | `@johnmorrisdotca/kazoku-ui/address-state` | Choices kept in the address: read, write and subscribe to URL parameters with `replaceState`. No element; imports on a server. |
 
 ## View controls
 
-- Angle and tilt sliders, Auto-turn with play and pause, Front.
-- Zoom out, 2 times, zoom in and Fit. Zoom is about the pointer (and Ctrl or Command with the wheel, or a trackpad's pinch).
-- The four-arrow pan pad (shown once zoomed in) and the Move or Turn choice for what a drag does.
+- **Two levels, so the bar stays simple.** The default, `controls="basic"`, shows the angle slider, Auto-turn, zoom out and in with a **zoom readout** (`2.4×`; tap it to go back to Fit), Fit, and a small More button. More (or `controls="advanced"`) adds the tilt slider, the auto-turn **speed** (Slow, Medium, Fast), Front, 2 times, and, once zoomed in, the four-arrow pan pad and the Move or Turn choice for what a drag does. The reader's choice with More is remembered in `localStorage` and beats the attribute.
+- The zoom readout is the view's `zoom` (1× is Fit). A screen reader is told "Zoom level 2.4×" once the zoom has settled for a moment, not for every step of a pinch.
+- Auto-turn with play and pause; its speed is Slow (half the `speed` attribute), Medium (the `speed` attribute, 30 degrees a second) or Fast (twice it), kept in the address as `?speed=slow` or `?speed=fast`.
+- Zoom is about the pointer (and Ctrl or Command with the wheel, or a trackpad's pinch).
 - Touch: one finger turns at 1x and moves the view when zoomed in; two fingers pinch.
 - Keys on the view: arrows turn and tip it, `+` and `-` zoom, `0` or Home is Front and Fit.
 - The choices are kept in the address, with keys you can rename.
@@ -178,10 +181,12 @@ An `init` event is sent once, a moment after the element connects, with the star
 | `tilt-step` | Round the tilt of a drag to a multiple of this many degrees (`1` gives whole degrees). 0 by default: not rounded. |
 | `autoplay` | Turn by itself from the start, unless the reader prefers reduced motion. |
 | `autoplay-for` | Seconds of turning after which the `autoplay` turn stops by itself (as Auto-turn pressed). Left out, it never stops. Time spent paused off screen or in a hidden tab is not counted, and a reader's own Auto-turn press has no limit. |
-| `speed` | Degrees a second (30). |
+| `speed` | Degrees a second at Medium (30); Slow is half and Fast twice. |
+| `controls` | `basic` (the default) or `advanced`: which controls are shown (see above). Written in the page's markup it is where the reader starts; what the reader chose with More is remembered under `kazoku-view-controls` in `localStorage` (or the key `storage` names) and wins. Setting the attribute later changes the level at once. The host carries `data-level` with the level now. |
+| `storage` | The `localStorage` key the level is remembered under (`kazoku-view-controls`). |
 | `flat` | The view cannot turn: no angle, tilt, Auto-turn or Front, and a drag moves it. |
 | `tilt-max`, `zoom-min`, `zoom-max` | The limits (30, 1, 5). |
-| `address` | Keep the choices in the page's address (`?yaw=40&tilt=10&zoom=2&drag=turn`). |
+| `address` | Keep the choices in the page's address (`?yaw=40&tilt=10&zoom=2&drag=turn&speed=fast`). |
 | `address-keys` | Other keys: `yaw:a,zoom:z`. |
 | `theme` | `light` or `dark`; otherwise the page's colour scheme. |
 | `overlay` | Sit over the bottom of a positioned parent. |
@@ -191,7 +196,7 @@ Colours are custom properties: `--kazoku-ink`, `--kazoku-surface`, `--kazoku-lin
 
 ### The address
 
-Only what a reader chose is kept: angle, tilt, zoom and the drag choice. The pan is in pixels of one screen and the turning is of a moment, so neither is; while the view turns by itself the angle is left out. A value at its start (Fit, or the `zoom` the page opens at) leaves the address, and other parameters are kept. The address is written at most four times a second (Safari stops a page that changes its address more than 100 times in 30 seconds). Without the element: `parseAddress(search, keys?)` and `formatAddress(search, choices, keys?, leaveYaw?, startZoom?)`.
+Only what a reader chose is kept: angle, tilt, zoom, the drag choice and the auto-turn speed (`speed=slow` or `speed=fast`; Medium leaves the address, and another value of `speed`, a page's own, is left alone). The pan is in pixels of one screen and the turning is of a moment, so neither is; while the view turns by itself the angle is left out. A value at its start (Fit, or the `zoom` the page opens at) leaves the address, and other parameters are kept. The address is written at most four times a second (Safari stops a page that changes its address more than 100 times in 30 seconds). Without the element: `parseAddress(search, keys?)` and `formatAddress(search, choices, keys?, leaveYaw?, startZoom?)`.
 
 ### Why the tag is only defined when it is free
 
@@ -244,6 +249,20 @@ See [docs/address-state.md](docs/address-state.md); the demo's `address.html` sh
 
 What a picture of an element cannot carry (web fonts, `::before`, cross-origin images), the element-free `renderImage` and `saveImage`, and the one `img-src data:` a strict policy needs are in [docs/save-image.md](docs/save-image.md); the demo's `save-image.html` saves all three kinds.
 
+## Shared 3D renderer
+
+A page with many 3D views gets one WebGL context, handed to the focused view; the others are stills made once from the same renderer, kept in a budgeted list. Shared geometries,
+materials, textures and models are counted and freed when the last view lets go. Nothing is drawn while the page rests or the view is out of sight, one animation frame is
+requested at a time, and a canvas never passes 6 million pixels or 4096 a side. Context loss is handled in one place. **three.js is a peer dependency and is never bundled**:
+your page passes `load: () => import("three")`, so it loads only when the first view goes live. How a package uses it, the API and the freeze checks: [docs/renderer.md](docs/renderer.md). Demo: `renderer.html`.
+
+```ts
+import { createSharedRenderer } from "@johnmorrisdotca/kazoku-ui/renderer";
+const renderer = createSharedRenderer({ load: () => import("three") });
+const view = renderer.view(host, item);   // item: { key, build({ three, assets, width, height }) => { scene, camera } }
+host.addEventListener("focus", () => view.focus());
+```
+
 ## One release workflow for the family's packages
 
 `.github/workflows/reusable-release.yml` is the release written once: from main, the tag must equal `package.json`'s version, the repo's check script runs, a version already on npm is skipped, the `v<version>` tag is made if missing, and `npm publish --provenance` runs by trusted publishing (no token). A package repo's `release.yml` calls it:
@@ -256,17 +275,21 @@ jobs:
 
 npm accepts a called workflow: the trusted-publisher entry on npmjs.com names the **calling** file (`release.yml`), and `id-token: write` goes on both. To move a repo over, keep its file name `release.yml`, replace the body with the call, and pin to a released tag. The inputs, the sources and the steps are in [docs/release-workflow.md](docs/release-workflow.md).
 
+## One AGENTS.md for the family's package repos
+
+`templates/AGENTS.md` is the agent-instruction file every package repo can start from: the family rules (read spx-stats `docs/package-work.md` first, the board and ticket prefix, ports, checks, release, hand-off) above a marker, and the repo's own facts below it. See [docs/agents-template.md](docs/agents-template.md).
+
 ## Content-Security-Policy
 
 The styles are adopted as a constructable stylesheet (`adoptedStyleSheets`), so a page with `style-src 'self'` and no `'unsafe-inline'` needs no hash and no allowance. A browser without it gets a `<style>` carrying the element's `nonce`. What a page needs is in [docs/csp.md](docs/csp.md), and the demo's `csp.html` runs under a strict policy.
 
 ## Size
 
-Gzipped, unbundled. View controls: the element and its definition about 5.0 KB, the controller 4.3 KB, the maths 1.4 KB, the address 1.2 KB, the labels 0.7 KB and the styles 1.6 KB. Theme switch: the element and its definition 3.3 KB, the choices 1.0 KB, the labels 0.3 KB and the styles 0.3 KB. Language picker: the element and its definition 2.8 KB, the codes and names 1.7 KB, the labels 0.3 KB. Save image: the element and its definition 3.0 KB, the rendering 3.6 KB, the formats and file names 1.0 KB, the labels 0.4 KB. Address state: 2.1 KB. Shared by parts: the style adoption 0.8 KB, the base styles 1.0 KB, the page's colours 0.5 KB and the target and the store 0.6 KB. `pnpm test:package` prints them. Nothing is loaded from the network.
+Gzipped, unbundled. View controls: the element and its definition about 6.9 KB, the controller 4.4 KB, the maths 1.4 KB, the address 1.4 KB, the levels 0.4 KB, the labels 0.9 KB and the styles 1.7 KB. Theme switch: the element and its definition 3.3 KB, the choices 1.0 KB, the labels 0.3 KB and the styles 0.3 KB. Language picker: the element and its definition 2.8 KB, the codes and names 1.7 KB, the labels 0.3 KB. Save image: the element and its definition 3.0 KB, the rendering 3.6 KB, the formats and file names 1.0 KB, the labels 0.4 KB. Address state: 2.1 KB. Shared 3D renderer: 8.9 KB (the renderer 4.5, the scheduler 1.2, the assets 1.4, the stills 0.6, the pixel budget 0.8, the index 0.4), the test kit 1.6 KB; three.js is the page's own and is not counted. Shared by parts: the style adoption 0.8 KB, the base styles 1.0 KB, the page's colours 0.5 KB and the target and the store 0.6 KB. `pnpm test:package` prints them. Nothing is loaded from the network.
 
 ## Checks
 
-`pnpm check` (lint, types, 75 unit tests of the maths, the address, the controller and the package, the build and the packed package), and `pnpm test:demo` (the demo in Chromium and WebKit at a phone's width and a desk's: the controls in the first screen, a toggle during Auto-turn leaves the angle advancing, a button or link inside the view still clicks while a drag turns it, the opening zoom and fit scale, zoom about the pointer, zoom about an anchor (`?anchor=pin`), Arrow Up either way (`?key-tilt=wheel`), `?stop-turn`, `?tilt-step=1`, pan when zoomed, touch, the address, the labels, reduced motion, the controls styled under a strict `style-src` with no violation, `demo/csp.html`, the theme switch and the language picker in each browser and size, the address state, back and forward and no history added, on `demo/address.html`, and the save buttons: each file read back from disk, on `demo/save-image.html`).
+`pnpm check` (lint, types, 99 unit tests of the maths, the address, the controller and the package, the build and the packed package), and `pnpm test:demo` (the demo in Chromium and WebKit at a phone's width and a desk's: the controls in the first screen, a toggle during Auto-turn leaves the angle advancing, a button or link inside the view still clicks while a drag turns it, the opening zoom and fit scale, zoom about the pointer, zoom about an anchor (`?anchor=pin`), Arrow Up either way (`?key-tilt=wheel`), `?stop-turn`, `?tilt-step=1`, pan when zoomed, touch, the address, the labels, reduced motion, the controls styled under a strict `style-src` with no violation, `demo/csp.html`, the theme switch and the language picker in each browser and size, the address state, back and forward and no history added, on `demo/address.html`, and the save buttons: each file read back from disk, on `demo/save-image.html`, and the shared 3D renderer on `demo/renderer.html`: one WebGL context over fifty focus changes, nothing drawn or requested at rest, the GPU objects and heap flat, the canvas within budget at 5K, context loss, out of sight, the stills' byte budget, and three.js fetched only when a view goes live).
 
 ## Not yet
 

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 /** The subpaths of the parts, in the order they were added. */
-export declare const PARTS: readonly ["view-controls", "theme-switch", "language-picker", "address-state", "save-image"];
+export declare const PARTS: readonly ["view-controls", "theme-switch", "language-picker", "address-state", "save-image", "renderer", "testing"];
 export type Part = (typeof PARTS)[number];

package/dist/index.js

@@ -1,3 +1,3 @@
 // Kazoku UI 家族: the family's shared interface parts, each its own subpath so a page loads only what it uses.
 /** The subpaths of the parts, in the order they were added. */
-export const PARTS = ["view-controls", "theme-switch", "language-picker", "address-state", "save-image"];
+export const PARTS = ["view-controls", "theme-switch", "language-picker", "address-state", "save-image", "renderer", "testing"];

package/dist/renderer/cache.d.ts

@@ -0,0 +1,38 @@
+export interface Timers {
+    set(callback: () => void, ms: number): unknown;
+    clear(handle: unknown): void;
+}
+export interface AssetCacheOptions {
+    /** Milliseconds an asset with no users is kept before it is disposed (1000). 0 disposes at once. */
+    lingerMs?: number;
+    timers?: Timers;
+}
+export interface AssetCacheStats {
+    /** Assets held, with or without users. */
+    entries: number;
+    /** Users of assets, in all. */
+    refs: number;
+    /** Asks answered from the cache. */
+    hits: number;
+    /** Asks that made the asset. */
+    misses: number;
+    /** Assets disposed. */
+    disposed: number;
+}
+/** What one view takes: it asks for assets through its scope and lets all of them go with one `release()`. */
+export interface AssetScope {
+    acquire<T>(key: string, make: () => T, dispose?: (value: T) => void): T;
+    release(): void;
+}
+export interface AssetCache {
+    /** The asset for `key`, made by `make` the first time. Every `acquire` needs a `release` of the same key (a scope does that for you). `dispose` is kept from the first ask. */
+    acquire<T>(key: string, make: () => T, dispose?: (value: T) => void): T;
+    release(key: string): void;
+    scope(): AssetScope;
+    /** Dispose every asset now, used or not (the page is done with the renderer). */
+    clear(): void;
+    stats(): AssetCacheStats;
+}
+export declare function createAssetCache(options?: AssetCacheOptions): AssetCache;
+/** Free what a loaded model holds (its geometries, materials and the textures of those), for a `dispose` that frees a whole scene. Duck-typed, so it needs no three.js import. */
+export declare function disposeDeep(root: unknown): void;

package/dist/renderer/cache.js

@@ -0,0 +1,104 @@
+// Shared assets with reference counts: a geometry, a material, a texture or a loaded model is made once for everyone who asks for its key, and disposed when
+// the last one lets go (after a short linger, so a view that lets go just before the next takes the same thing does not rebuild it). Nothing here knows about
+// three.js; the `dispose` you pass says how to free a thing. A model that loads asynchronously is cached as its promise.
+const defaultTimers = { set: (callback, ms) => setTimeout(callback, ms), clear: (handle) => clearTimeout(handle) };
+export function createAssetCache(options = {}) {
+    const lingerMs = options.lingerMs ?? 1000;
+    const timers = options.timers ?? defaultTimers;
+    const entries = new Map();
+    const counts = { hits: 0, misses: 0, disposed: 0 };
+    const drop = (key) => {
+        const entry = entries.get(key);
+        if (entry === undefined)
+            return;
+        entries.delete(key);
+        if (entry.timer !== undefined)
+            timers.clear(entry.timer);
+        counts.disposed += 1;
+        entry.dispose?.(entry.value);
+    };
+    const cache = {
+        acquire(key, make, dispose) {
+            const held = entries.get(key);
+            if (held !== undefined) {
+                counts.hits += 1;
+                if (held.timer !== undefined) {
+                    timers.clear(held.timer);
+                    held.timer = undefined;
+                }
+                held.refs += 1;
+                return held.value;
+            }
+            counts.misses += 1;
+            const value = make();
+            entries.set(key, { value, refs: 1, dispose: dispose, timer: undefined });
+            return value;
+        },
+        release(key) {
+            const entry = entries.get(key);
+            if (entry === undefined || entry.refs === 0)
+                return;
+            entry.refs -= 1;
+            if (entry.refs > 0)
+                return;
+            if (lingerMs > 0)
+                entry.timer = timers.set(() => {
+                    if (entry.refs === 0)
+                        drop(key);
+                }, lingerMs);
+            else
+                drop(key);
+        },
+        scope() {
+            const taken = [];
+            return {
+                acquire(key, make, dispose) {
+                    taken.push(key);
+                    return cache.acquire(key, make, dispose);
+                },
+                release() {
+                    for (const key of taken.splice(0))
+                        cache.release(key);
+                },
+            };
+        },
+        clear() {
+            for (const key of [...entries.keys()])
+                drop(key);
+        },
+        stats() {
+            let refs = 0;
+            for (const entry of entries.values())
+                refs += entry.refs;
+            return { entries: entries.size, refs, ...counts };
+        },
+    };
+    return cache;
+}
+/** Free what a loaded model holds (its geometries, materials and the textures of those), for a `dispose` that frees a whole scene. Duck-typed, so it needs no three.js import. */
+export function disposeDeep(root) {
+    const seen = new Set();
+    const free = (thing) => {
+        if (typeof thing !== "object" || thing === null || seen.has(thing))
+            return;
+        seen.add(thing);
+        const object = thing;
+        for (const value of Object.values(object)) {
+            // A texture sits in a material's own property (map, normalMap, ...); an object's own children are walked by `traverse` below.
+            if (typeof value === "object" && value !== null && value.isTexture === true)
+                free(value);
+        }
+        object.dispose?.();
+    };
+    const visit = (node) => {
+        const object = node;
+        free(object.geometry);
+        for (const material of Array.isArray(object.material) ? object.material : [object.material])
+            free(material);
+    };
+    const walk = root;
+    if (typeof walk?.traverse === "function")
+        walk.traverse(visit);
+    else
+        visit(root);
+}

package/dist/renderer/index.d.ts

@@ -0,0 +1,5 @@
+export { createAssetCache, disposeDeep, type AssetCache, type AssetCacheOptions, type AssetCacheStats, type AssetScope, type Timers } from "./cache.ts";
+export { MAX_PIXELS, MAX_RATIO, MAX_SIDE, pixelRatioFor, type PixelLimits } from "./pixels.ts";
+export { createSharedRenderer, type BuildContext, type GLRenderer, type Item3D, type RendererStats, type Scene3D, type SharedRenderer, type SharedRendererOptions, type ThreeLike, type View, type ViewOptions } from "./renderer.ts";
+export { browserClock, createScheduler, type FrameClock, type Job, type Priority, type Scheduler, type SchedulerOptions, type SchedulerStats } from "./scheduler.ts";
+export { createStillCache, STILL_BYTES, type Still, type StillCache, type StillCacheOptions } from "./stills.ts";

package/dist/renderer/index.js

@@ -0,0 +1,7 @@
+// The shared 3D renderer: one WebGL context per page for the focused view, shared assets with reference counts, stills in a budgeted list, drawing on demand,
+// a pixel budget and context-loss handling. three.js is not imported here: the page passes `load: () => import("three")`. Nothing touches the DOM until a view is made, so it imports on a server.
+export { createAssetCache, disposeDeep } from "./cache.js";
+export { MAX_PIXELS, MAX_RATIO, MAX_SIDE, pixelRatioFor } from "./pixels.js";
+export { createSharedRenderer } from "./renderer.js";
+export { browserClock, createScheduler } from "./scheduler.js";
+export { createStillCache, STILL_BYTES } from "./stills.js";

package/dist/renderer/pixels.d.ts

@@ -0,0 +1,16 @@
+/** Most pixels a canvas may hold. */
+export declare const MAX_PIXELS = 6000000;
+/** Most pixels along one side (a common GPU texture limit). */
+export declare const MAX_SIDE = 4096;
+/** Most device pixels to a CSS pixel; a ratio of 3 or 4 adds detail nobody sees on a moving 3D view. */
+export declare const MAX_RATIO = 2;
+export interface PixelLimits {
+    maxPixels?: number;
+    maxSide?: number;
+    maxRatio?: number;
+}
+/**
+ * The pixel ratio to draw a `width` by `height` CSS pixel canvas at: the device's, held to `maxRatio`, then lowered until the canvas fits `maxPixels` and
+ * `maxSide`. Rounded down, so `floor(width * ratio)` never passes a limit. A view bigger than the limits on its own is drawn below 1 and scaled up by CSS.
+ */
+export declare function pixelRatioFor(width: number, height: number, deviceRatio: number, limits?: PixelLimits): number;

package/dist/renderer/pixels.js

@@ -0,0 +1,25 @@
+// The pixel budget of a canvas, in one place: a canvas of a big screen at a high pixel ratio is tens of millions of pixels (a 5K screen at ratio 2 asked for
+// 24 MP in one package), and a GPU that is asked for that stalls the page. Pure, so a server or a test can use it.
+/** Most pixels a canvas may hold. */
+export const MAX_PIXELS = 6_000_000;
+/** Most pixels along one side (a common GPU texture limit). */
+export const MAX_SIDE = 4096;
+/** Most device pixels to a CSS pixel; a ratio of 3 or 4 adds detail nobody sees on a moving 3D view. */
+export const MAX_RATIO = 2;
+/**
+ * The pixel ratio to draw a `width` by `height` CSS pixel canvas at: the device's, held to `maxRatio`, then lowered until the canvas fits `maxPixels` and
+ * `maxSide`. Rounded down, so `floor(width * ratio)` never passes a limit. A view bigger than the limits on its own is drawn below 1 and scaled up by CSS.
+ */
+export function pixelRatioFor(width, height, deviceRatio, limits = {}) {
+    const { maxPixels = MAX_PIXELS, maxSide = MAX_SIDE, maxRatio = MAX_RATIO } = limits;
+    if (!(width > 0) || !(height > 0))
+        return 1;
+    let ratio = Math.min(Number.isFinite(deviceRatio) && deviceRatio > 0 ? deviceRatio : 1, maxRatio);
+    ratio = Math.min(ratio, maxSide / Math.max(width, height), Math.sqrt(maxPixels / (width * height)));
+    const floored = Math.floor(ratio * 1000) / 1000;
+    // Floating point can leave the product a pixel over a limit; step down until it is not.
+    let r = Math.max(floored, 0.001);
+    while (r > 0.001 && (Math.floor(width * r) * Math.floor(height * r) > maxPixels || Math.max(Math.floor(width * r), Math.floor(height * r)) > maxSide))
+        r = Math.floor((r - 0.001) * 1000) / 1000;
+    return r;
+}

package/dist/renderer/renderer.d.ts

@@ -0,0 +1,118 @@
+import { type AssetCache, type AssetScope } from "./cache.ts";
+import { type FrameClock, type Scheduler } from "./scheduler.ts";
+import { type Still, type StillCache } from "./stills.ts";
+/** What of three's `WebGLRenderer` the renderer uses. */
+export interface GLRenderer {
+    readonly domElement: HTMLCanvasElement;
+    setPixelRatio(ratio: number): void;
+    setSize(width: number, height: number, updateStyle?: boolean): void;
+    render(scene: unknown, camera: unknown): void;
+    dispose(): void;
+    forceContextLoss(): void;
+}
+/** What of the `three` module the renderer uses; the whole module is handed to `build`, so an adapter can use all of it. */
+export interface ThreeLike {
+    WebGLRenderer: new (...args: never[]) => GLRenderer;
+}
+/** A scene ready to draw, made by an item's `build`. Everything but `scene` and `camera` is optional. */
+export interface Scene3D {
+    scene: unknown;
+    camera: unknown;
+    /** Called before each draw while the view is live. Return true while something is moving; the view is then drawn again next frame, else it rests. */
+    update?(dt: number, now: number): boolean | void;
+    /** The view's size in CSS pixels changed (set the camera's aspect). */
+    resize?(width: number, height: number): void;
+    /** Free what only this scene owns. Shared assets are freed by the cache. */
+    dispose?(): void;
+}
+export interface BuildContext<T extends ThreeLike = ThreeLike> {
+    three: T;
+    /** Take every geometry, material, texture and model through here: they are shared by key and released when the view lets go. */
+    assets: AssetScope;
+    width: number;
+    height: number;
+}
+/** The package's adapter for one kind of thing: the scene for it and its framing. */
+export interface Item3D<T extends ThreeLike = ThreeLike> {
+    /** What the item looks like, for its still and for the cache: items with the same key share one picture. */
+    key: string;
+    build(context: BuildContext<T>): Scene3D | Promise<Scene3D>;
+}
+export interface SharedRendererOptions<T extends ThreeLike = ThreeLike> {
+    /** `() => import("three")`: where three is loaded from, once, when a view first goes live or a still is first made. */
+    load: () => Promise<T>;
+    maxPixels?: number;
+    maxSide?: number;
+    maxRatio?: number;
+    /** Longest side of a still, in pixels (320). */
+    stillSize?: number;
+    /** Decoded bytes the stills may hold (32 MB). */
+    stillBytes?: number;
+    /** Milliseconds an unused shared asset is kept (1000). */
+    lingerMs?: number;
+    /** Milliseconds out of sight, in a hidden tab, after which the context is let go and the views show stills (30000). It comes back when the view does. */
+    releaseMs?: number;
+    antialias?: boolean;
+    /** Called when the context is lost or restored, or WebGL is not available. */
+    onContext?: (state: "lost" | "restored" | "unavailable") => void;
+    clock?: FrameClock;
+    document?: Document;
+    /** Your own cache or scheduler, for a test or to share them. */
+    assets?: AssetCache;
+    scheduler?: Scheduler;
+}
+export interface ViewOptions {
+    /** The `<img>` that shows the still. Left out, one is made inside the host. `null` shows no still. */
+    still?: HTMLImageElement | null;
+}
+export interface View {
+    readonly host: HTMLElement;
+    readonly item: Item3D;
+    /** True while this view has the renderer's canvas and a scene. */
+    readonly live: boolean;
+    /** The scene while live. */
+    readonly scene: Scene3D | undefined;
+    /** Take the renderer. The view that had it goes back to its still. Resolves true when this view is live, false if another took it meanwhile or WebGL is not available. */
+    focus(): Promise<boolean>;
+    /** Give the renderer back (the view shows its still). */
+    blur(): void;
+    /** Draw this view at the next frame. Call it when the camera or the scene changed; nothing is drawn without it. */
+    invalidate(): void;
+    /** Make the view's still if there is none (one at a time, from the same renderer) and show it. Call it when the view comes into sight. */
+    showStill(): Promise<Still | undefined>;
+    dispose(): void;
+}
+export interface RendererStats {
+    /** WebGL contexts made over the page's life: 1, unless the page let it go while hidden. */
+    contexts: number;
+    /** Draws of live views. */
+    draws: number;
+    /** Stills made. */
+    snapshots: number;
+    live: boolean;
+    lost: boolean;
+    /** The canvas's size in device pixels now. */
+    canvas: {
+        width: number;
+        height: number;
+        pixels: number;
+    };
+    frames: Scheduler["stats"];
+    assets: ReturnType<AssetCache["stats"]>;
+    stills: {
+        count: number;
+        bytes: number;
+    };
+}
+export interface SharedRenderer<T extends ThreeLike = ThreeLike> {
+    view(host: HTMLElement, item: Item3D<T>, options?: ViewOptions): View;
+    /** The view that is live, if any. */
+    readonly focused: View | undefined;
+    readonly stats: RendererStats;
+    readonly assets: AssetCache;
+    readonly stills: StillCache;
+    readonly scheduler: Scheduler;
+    /** Let go of everything: views, the context, the assets and the stills. */
+    dispose(): void;
+}
+export declare function createSharedRenderer<T extends ThreeLike = ThreeLike>(options: SharedRendererOptions<T>): SharedRenderer<T>;