@johnmorrisdotca/kazoku-ui 0.7.3 → 0.9.0

package/dist/renderer/renderer.js

@@ -0,0 +1,472 @@
+// The family's shared 3D renderer: ONE WebGL context for the page, handed to the view that has the focus. Every other view shows a still. A browser keeps
+// about 16 contexts and silently kills the older ones, so a page of 40 live views is a page of broken ones; one context moved between hosts has no such limit.
+//
+// three.js is never imported here: the page passes `load: () => import("three")`, so three stays the page's own (peer) dependency, loads only when a view first
+// goes live, and a page of stills ships no 3D code at all. What a view shows is an adapter the package supplies (`Item3D`): it builds a scene from shared assets.
+import { createAssetCache } from "./cache.js";
+import { MAX_PIXELS, MAX_RATIO, MAX_SIDE, pixelRatioFor } from "./pixels.js";
+import { createScheduler } from "./scheduler.js";
+import { createStillCache } from "./stills.js";
+export function createSharedRenderer(options) {
+    const limits = { maxPixels: options.maxPixels ?? MAX_PIXELS, maxSide: options.maxSide ?? MAX_SIDE, maxRatio: options.maxRatio ?? MAX_RATIO };
+    const stillSize = options.stillSize ?? 320;
+    const releaseMs = options.releaseMs ?? 30_000;
+    const doc = () => options.document ?? globalThis.document;
+    const scheduler = options.scheduler ?? createScheduler(options.clock === undefined ? {} : { clock: options.clock });
+    const assets = options.assets ?? createAssetCache(options.lingerMs === undefined ? {} : { lingerMs: options.lingerMs });
+    const views = new Set();
+    const byKey = (key) => [...views].filter((v) => v.item.key === key);
+    const stills = createStillCache({
+        ...(options.stillBytes === undefined ? {} : { maxBytes: options.stillBytes }),
+        onEvict: (key) => {
+            for (const v of byKey(key))
+                if (v.img !== null && !v.live)
+                    v.img.removeAttribute("src");
+        },
+    });
+    const counts = { contexts: 0, draws: 0, snapshots: 0 };
+    let three;
+    let gl;
+    let canvas;
+    let creating;
+    let focused;
+    let token = 0;
+    let lost = false;
+    let lostPause = false;
+    let sightPause = false;
+    let onScreen = true;
+    let idleTimer;
+    let listening = false;
+    let queue = Promise.resolve();
+    const shooting = new Map();
+    let sized = "";
+    // --- the one context ---------------------------------------------------------------------------------------------------------------------------------
+    const onLost = (event) => {
+        event.preventDefault();
+        lost = true;
+        if (!lostPause) {
+            lostPause = true;
+            scheduler.pause();
+        }
+        if (canvas !== undefined)
+            canvas.style.visibility = "hidden";
+        if (focused?.img)
+            focused.img.style.visibility = "";
+        options.onContext?.("lost");
+    };
+    const onRestored = () => {
+        lost = false;
+        if (lostPause) {
+            lostPause = false;
+            scheduler.resume();
+        }
+        if (canvas !== undefined)
+            canvas.style.visibility = "";
+        sized = "";
+        if (focused?.live) {
+            applySize(focused);
+            scheduler.invalidate(focused.job);
+        }
+    };
+    function ensureGL() {
+        if (gl !== undefined && !lost)
+            return Promise.resolve(gl);
+        if (gl !== undefined && lost)
+            releaseGL();
+        creating ??= (async () => {
+            try {
+                three ??= await options.load();
+                const element = doc().createElement("canvas");
+                element.addEventListener("webglcontextlost", onLost);
+                element.addEventListener("webglcontextrestored", onRestored);
+                const Renderer = three.WebGLRenderer;
+                const made = new Renderer({ canvas: element, antialias: options.antialias ?? true, alpha: true, powerPreference: "default" });
+                canvas = element;
+                gl = made;
+                counts.contexts += 1;
+                sized = "";
+                return made;
+            }
+            finally {
+                creating = undefined;
+            }
+        })();
+        return creating;
+    }
+    /** Let go of the context (forced, so the GPU memory is free now) and of the scene using it. The views keep their stills. */
+    function releaseGL() {
+        if (focused?.live)
+            detach(focused, true);
+        if (canvas !== undefined) {
+            canvas.removeEventListener("webglcontextlost", onLost);
+            canvas.removeEventListener("webglcontextrestored", onRestored);
+            canvas.remove();
+        }
+        try {
+            gl?.dispose();
+            gl?.forceContextLoss();
+        }
+        catch {
+            /* already gone */
+        }
+        gl = undefined;
+        canvas = undefined;
+        lost = false;
+        if (lostPause) {
+            lostPause = false;
+            scheduler.resume();
+        }
+        sized = "";
+    }
+    // --- size: the pixel budget ----------------------------------------------------------------------------------------------------------------------------
+    /** The size the canvas will fill: the host's padding box (the canvas is laid inside its border), whole CSS pixels. */
+    function measure(host) {
+        const r = host.getBoundingClientRect();
+        return { width: Math.max(1, Math.floor(host.clientWidth || r.width)), height: Math.max(1, Math.floor(host.clientHeight || r.height)) };
+    }
+    function applySize(v) {
+        if (gl === undefined || canvas === undefined)
+            return;
+        const { width, height } = measure(v.host);
+        const ratio = pixelRatioFor(width, height, globalThis.devicePixelRatio || 1, limits);
+        const mark = `${width}x${height}@${ratio}`;
+        if (mark === sized)
+            return;
+        sized = mark;
+        gl.setPixelRatio(ratio);
+        gl.setSize(width, height, false);
+        v.scene?.resize?.(width, height);
+    }
+    // --- going live and back to a still --------------------------------------------------------------------------------------------------------------------
+    function showImage(v, shown) {
+        if (v.img !== null)
+            v.img.style.visibility = shown ? "" : "hidden";
+    }
+    function paintStill(v) {
+        const still = stills.get(v.item.key);
+        if (v.img !== null && still !== undefined && v.img.getAttribute("src") !== still.url)
+            v.img.src = still.url;
+        return still;
+    }
+    async function build(v, scope, width, height) {
+        return v.item.build({ three: three, assets: scope, width, height });
+    }
+    /** Take the canvas, with a scene, into the host. */
+    async function goLive(v, mine) {
+        let renderer;
+        try {
+            renderer = await ensureGL();
+        }
+        catch {
+            if (mine === token)
+                options.onContext?.("unavailable");
+            return false;
+        }
+        if (mine !== token || v.disposed)
+            return false;
+        const scope = assets.scope();
+        const size = measure(v.host);
+        let scene;
+        try {
+            scene = await build(v, scope, size.width, size.height);
+        }
+        catch {
+            scope.release();
+            return false;
+        }
+        if (mine !== token || v.disposed || gl !== renderer || canvas === undefined) {
+            scene.dispose?.();
+            scope.release();
+            return false;
+        }
+        v.scene = scene;
+        v.assets = scope;
+        v.live = true;
+        v.seen = false;
+        if (globalThis.getComputedStyle(v.host).position === "static")
+            v.host.style.position = "relative";
+        canvas.style.cssText = "position:absolute;inset:0;width:100%;height:100%;display:block";
+        v.host.append(canvas);
+        sized = "";
+        applySize(v);
+        watch(v);
+        scheduler.invalidate(v.job);
+        return true;
+    }
+    /** Take the canvas out of the host and let the scene go; the host shows its still. `keep` leaves the wish to be live (the context is being let go). */
+    function detach(v, keep = false) {
+        if (!keep)
+            unwatch(v);
+        scheduler.remove(v.job);
+        if (canvas !== undefined && canvas.parentElement === v.host)
+            canvas.remove();
+        v.scene?.dispose?.();
+        v.assets?.release();
+        v.scene = undefined;
+        v.assets = undefined;
+        v.live = false;
+        if (!keep)
+            v.wantsLive = false;
+        if (sightPause) {
+            sightPause = false;
+            scheduler.resume();
+        }
+        clearTimeout(idleTimer);
+        idleTimer = undefined;
+        showImage(v, true);
+        if (v.img !== null)
+            void showStill(v);
+    }
+    // --- out of sight: no frames, then no context ----------------------------------------------------------------------------------------------------------
+    function watch(v) {
+        unwatch(v);
+        onScreen = true;
+        if (typeof ResizeObserver === "function") {
+            v.watchers.resize = new ResizeObserver(() => {
+                if (!v.live)
+                    return;
+                sized = "";
+                applySize(v);
+                scheduler.invalidate(v.job);
+            });
+            v.watchers.resize.observe(v.host);
+        }
+        if (typeof IntersectionObserver === "function") {
+            v.watchers.sight = new IntersectionObserver((entries) => {
+                const last = entries[entries.length - 1];
+                if (last === undefined)
+                    return;
+                onScreen = last.isIntersecting;
+                sight();
+            });
+            v.watchers.sight.observe(v.host);
+        }
+        if (!listening) {
+            listening = true;
+            doc().addEventListener("visibilitychange", sight);
+        }
+        sight();
+    }
+    function unwatch(v) {
+        v.watchers.resize?.disconnect();
+        v.watchers.sight?.disconnect();
+        v.watchers.resize = undefined;
+        v.watchers.sight = undefined;
+    }
+    function sight() {
+        const v = focused;
+        if (v === undefined || !v.wantsLive)
+            return;
+        const idle = !onScreen || doc().visibilityState === "hidden";
+        if (idle && !sightPause && gl !== undefined) {
+            sightPause = true;
+            scheduler.pause();
+            idleTimer = setTimeout(() => {
+                // Out of sight for good: free the GPU. The view keeps its still, and goes live again when it is seen.
+                if (focused === v)
+                    releaseGL();
+            }, releaseMs);
+        }
+        else if (!idle && sightPause) {
+            sightPause = false;
+            scheduler.resume();
+            clearTimeout(idleTimer);
+            idleTimer = undefined;
+            if (gl === undefined && v.wantsLive)
+                void goLive(v, ++token);
+            else
+                scheduler.invalidate(v.job);
+        }
+        else if (!idle && gl === undefined && v.wantsLive && !v.live)
+            void goLive(v, ++token);
+    }
+    // --- stills --------------------------------------------------------------------------------------------------------------------------------------------
+    function showStill(v) {
+        const have = paintStill(v);
+        if (have !== undefined)
+            return Promise.resolve(have);
+        const key = v.item.key;
+        let pending = shooting.get(key);
+        if (pending === undefined) {
+            pending = (queue = queue.then(() => shoot(v)).catch(() => undefined));
+            shooting.set(key, pending);
+            void pending.finally(() => shooting.delete(key));
+        }
+        return pending.then((still) => {
+            if (still !== undefined && !v.disposed)
+                paintStill(v);
+            return still;
+        });
+    }
+    /** One still, made now, from the same renderer, then the canvas is put back as it was (all in one task, so nothing is shown at the wrong size). */
+    async function shoot(v) {
+        const have = stills.get(v.item.key);
+        if (have !== undefined)
+            return have;
+        // A lost context is left for its owner to restore or rebuild; a still waits for it.
+        if (lost || v.disposed)
+            return undefined;
+        let renderer;
+        try {
+            renderer = await ensureGL();
+        }
+        catch {
+            options.onContext?.("unavailable");
+            return undefined;
+        }
+        if (lost)
+            return undefined;
+        const host = measure(v.host);
+        const scale = stillSize / Math.max(host.width, host.height);
+        const width = Math.max(1, Math.round(host.width * scale));
+        const height = Math.max(1, Math.round(host.height * scale));
+        const scope = assets.scope();
+        let scene;
+        try {
+            scene = await build(v, scope, width, height);
+            if (gl !== renderer || canvas === undefined || lost)
+                return undefined;
+            const element = canvas;
+            scene.resize?.(width, height);
+            renderer.setPixelRatio(1);
+            renderer.setSize(width, height, false);
+            renderer.render(scene.scene, scene.camera);
+            const blob = new Promise((resolve) => element.toBlob(resolve, "image/png"));
+            sized = "";
+            if (focused?.live) {
+                applySize(focused);
+                scheduler.invalidate(focused.job);
+            }
+            const made = await blob;
+            if (made === null)
+                return undefined;
+            const still = { url: URL.createObjectURL(made), width, height, bytes: width * height * 4 };
+            stills.set(v.item.key, still);
+            counts.snapshots += 1;
+            return still;
+        }
+        catch {
+            return undefined;
+        }
+        finally {
+            scene?.dispose?.();
+            scope.release();
+        }
+    }
+    // --- views ---------------------------------------------------------------------------------------------------------------------------------------------
+    const renderer = {
+        view(host, item, viewOptions = {}) {
+            const own = viewOptions.still === undefined;
+            let img = viewOptions.still ?? null;
+            if (own) {
+                img = doc().createElement("img");
+                img.alt = "";
+                img.decoding = "async";
+                img.className = "kazoku-still";
+                img.style.cssText = "display:block;width:100%;height:100%;object-fit:contain";
+                host.append(img);
+            }
+            const v = {
+                host,
+                item: item,
+                img,
+                ownImg: own,
+                scene: undefined,
+                assets: undefined,
+                live: false,
+                wantsLive: false,
+                disposed: false,
+                seen: false,
+                watchers: { resize: undefined, sight: undefined },
+                job: {
+                    draw: (now, dt) => {
+                        const scene = v.scene;
+                        if (scene === undefined || gl === undefined || lost)
+                            return;
+                        const moving = scene.update?.(dt, now) === true;
+                        gl.render(scene.scene, scene.camera);
+                        counts.draws += 1;
+                        if (!v.seen) {
+                            v.seen = true;
+                            showImage(v, false);
+                        }
+                        return moving;
+                    },
+                },
+                api: undefined,
+            };
+            v.api = {
+                host,
+                item: item,
+                get live() {
+                    return v.live;
+                },
+                get scene() {
+                    return v.scene;
+                },
+                async focus() {
+                    if (v.disposed)
+                        return false;
+                    if (focused === v && v.live) {
+                        if (!lost)
+                            return true;
+                        detach(v, true);
+                    }
+                    const mine = ++token;
+                    if (focused !== undefined && focused !== v)
+                        detach(focused);
+                    focused = v;
+                    v.wantsLive = true;
+                    return goLive(v, mine);
+                },
+                blur() {
+                    if (focused !== v)
+                        return;
+                    token += 1;
+                    detach(v);
+                    focused = undefined;
+                },
+                invalidate() {
+                    if (v.live)
+                        scheduler.invalidate(v.job);
+                },
+                showStill: () => showStill(v),
+                dispose() {
+                    if (v.disposed)
+                        return;
+                    v.api.blur();
+                    v.disposed = true;
+                    views.delete(v);
+                    if (v.ownImg)
+                        v.img?.remove();
+                },
+            };
+            views.add(v);
+            return v.api;
+        },
+        get focused() {
+            return focused?.api;
+        },
+        get stats() {
+            const width = canvas?.width ?? 0;
+            const height = canvas?.height ?? 0;
+            return { ...counts, live: focused?.live === true, lost, canvas: { width, height, pixels: width * height }, frames: { ...scheduler.stats }, assets: assets.stats(), stills: { count: stills.size, bytes: stills.bytes } };
+        },
+        assets,
+        stills,
+        scheduler,
+        dispose() {
+            token += 1;
+            for (const v of [...views])
+                v.api.dispose();
+            focused = undefined;
+            releaseGL();
+            if (listening)
+                doc().removeEventListener("visibilitychange", sight);
+            listening = false;
+            assets.clear();
+            stills.clear();
+        },
+    };
+    return renderer;
+}

package/dist/renderer/scheduler.d.ts

@@ -0,0 +1,42 @@
+export interface FrameClock {
+    request(callback: (now: number) => void): number;
+    cancel(id: number): void;
+    now(): number;
+}
+export declare const browserClock: () => FrameClock;
+export interface Job {
+    /** Draw once. `dt` is seconds since this job's last draw while it kept animating, else 0. Return true to be drawn again next frame (an animation); anything else leaves it at rest. */
+    draw(now: number, dt: number): boolean | void;
+}
+export type Priority = "focus" | "ambient";
+export interface SchedulerOptions {
+    clock?: FrameClock;
+    /** Most jobs drawn in one frame (2). */
+    maxDraws?: number;
+    /** Milliseconds after which no further job is started in a frame (10). A job already started is finished. */
+    budgetMs?: number;
+}
+export interface SchedulerStats {
+    /** Animation frames asked for. */
+    requests: number;
+    /** Frames that ran. */
+    frames: number;
+    /** Jobs drawn. */
+    draws: number;
+    /** Jobs left for the next frame because the budget was spent. */
+    deferred: number;
+}
+export interface Scheduler {
+    /** Ask for a draw. Asking again before it happens changes nothing. */
+    invalidate(job: Job, priority?: Priority): void;
+    /** Forget a job (a view that is gone). */
+    remove(job: Job): void;
+    /** Stop asking for frames (nothing can see the views). Counts, so pauses nest. Drawing resumes when the last is undone. */
+    pause(): void;
+    resume(): void;
+    readonly paused: boolean;
+    /** True while a frame is requested and has not run yet. */
+    readonly pending: boolean;
+    readonly stats: SchedulerStats;
+}
+export declare function createScheduler(options?: SchedulerOptions): Scheduler;

package/dist/renderer/scheduler.js

@@ -0,0 +1,91 @@
+// One frame loop for every view on the page. A view is drawn only when it asked to be (`invalidate`), so a page at rest asks the browser for nothing;
+// exactly one animation frame is requested at a time, whoever invalidates and whenever (a change event during a draw adds nothing, which is the fault that once
+// doubled a package's frame requests every frame); and a frame has a budget (draws and milliseconds), with the focused view first and ambient work shed first.
+export const browserClock = () => ({
+    request: (callback) => globalThis.requestAnimationFrame(callback),
+    cancel: (id) => globalThis.cancelAnimationFrame(id),
+    now: () => globalThis.performance.now(),
+});
+export function createScheduler(options = {}) {
+    const clock = options.clock ?? browserClock();
+    const maxDraws = options.maxDraws ?? 2;
+    const budgetMs = options.budgetMs ?? 10;
+    const dirty = new Map();
+    const lastDraw = new Map();
+    const stats = { requests: 0, frames: 0, draws: 0, deferred: 0 };
+    let frame = 0;
+    let running = false;
+    let pauses = 0;
+    // The only place a frame is asked for, and it asks only if none is.
+    const ensure = () => {
+        if (frame !== 0 || running || pauses > 0 || dirty.size === 0)
+            return;
+        stats.requests += 1;
+        frame = clock.request(run);
+    };
+    function run(now) {
+        frame = 0;
+        running = true;
+        stats.frames += 1;
+        const started = clock.now();
+        const order = [...dirty].sort((a, b) => Number(a[1] === "ambient") - Number(b[1] === "ambient"));
+        let drawn = 0;
+        try {
+            for (const [job, priority] of order) {
+                if (drawn >= maxDraws || (drawn > 0 && clock.now() - started > budgetMs)) {
+                    stats.deferred += order.length - drawn;
+                    break;
+                }
+                dirty.delete(job);
+                const before = lastDraw.get(job);
+                const dt = before === undefined ? 0 : Math.min(0.1, (now - before) / 1000);
+                drawn += 1;
+                stats.draws += 1;
+                if (job.draw(now, dt) === true) {
+                    lastDraw.set(job, now);
+                    dirty.set(job, priority);
+                }
+                else
+                    lastDraw.delete(job);
+            }
+        }
+        finally {
+            running = false;
+            ensure();
+        }
+    }
+    return {
+        invalidate(job, priority = "focus") {
+            if (!dirty.has(job))
+                dirty.set(job, priority);
+            ensure();
+        },
+        remove(job) {
+            dirty.delete(job);
+            lastDraw.delete(job);
+        },
+        pause() {
+            pauses += 1;
+            if (frame !== 0) {
+                clock.cancel(frame);
+                frame = 0;
+            }
+        },
+        resume() {
+            if (pauses === 0)
+                return;
+            pauses -= 1;
+            // Time spent paused is not a frame's worth of animation.
+            if (pauses === 0)
+                lastDraw.clear();
+            ensure();
+        },
+        get paused() {
+            return pauses > 0;
+        },
+        get pending() {
+            return frame !== 0;
+        },
+        stats,
+    };
+}

package/dist/renderer/stills.d.ts

@@ -0,0 +1,27 @@
+export interface Still {
+    /** An object URL (or any image URL) for an `<img>`. */
+    url: string;
+    width: number;
+    height: number;
+    /** What it costs in memory once decoded: width x height x 4. */
+    bytes: number;
+}
+export interface StillCacheOptions {
+    /** The most decoded bytes the list may hold (32 MB). The picture just set is always kept. */
+    maxBytes?: number;
+    /** Called with a picture that leaves the list, to revoke its URL (`URL.revokeObjectURL` by default). */
+    free?: (still: Still) => void;
+    onEvict?: (key: string, still: Still) => void;
+}
+export interface StillCache {
+    /** The picture for `key`, marked as just used. */
+    get(key: string): Still | undefined;
+    set(key: string, still: Still): void;
+    delete(key: string): void;
+    clear(): void;
+    readonly bytes: number;
+    readonly size: number;
+    keys(): string[];
+}
+export declare const STILL_BYTES: number;
+export declare function createStillCache(options?: StillCacheOptions): StillCache;

package/dist/renderer/stills.js

@@ -0,0 +1,50 @@
+// Stills: a picture of a view, made once and shown whenever the view is not live. They sit in a least-recently-used list with a byte budget, so a wall of
+// hundreds of views holds only the pictures it has used lately; an evicted picture is made again when its view next needs it.
+export const STILL_BYTES = 32 * 1024 * 1024;
+export function createStillCache(options = {}) {
+    const maxBytes = options.maxBytes ?? STILL_BYTES;
+    const free = options.free ?? ((still) => globalThis.URL?.revokeObjectURL?.(still.url));
+    const list = new Map();
+    let total = 0;
+    const remove = (key) => {
+        const still = list.get(key);
+        if (still === undefined)
+            return;
+        list.delete(key);
+        total -= still.bytes;
+        free(still);
+        options.onEvict?.(key, still);
+    };
+    return {
+        get(key) {
+            const still = list.get(key);
+            if (still === undefined)
+                return undefined;
+            list.delete(key);
+            list.set(key, still);
+            return still;
+        },
+        set(key, still) {
+            remove(key);
+            list.set(key, still);
+            total += still.bytes;
+            for (const old of [...list.keys()]) {
+                if (total <= maxBytes || old === key)
+                    break;
+                remove(old);
+            }
+        },
+        delete: remove,
+        clear() {
+            for (const key of [...list.keys()])
+                remove(key);
+        },
+        get bytes() {
+            return total;
+        },
+        get size() {
+            return list.size;
+        },
+        keys: () => [...list.keys()],
+    };
+}