@tongue-core/ui 0.0.0-stage → 0.1.0-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Backpine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# @tongue-core/ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+What a film's interface is built from: a **player**, a **timeline's state and geometry**, and
+**unstyled React primitives** over the two. [@tongue-core/studio](../studio) is our app built from these
+alone; a client builds theirs from the same pieces and gets the same speed, because the speed lives
+below the UI. [docs/ui.md](../../docs/ui.md) is the design, with the budgets and what was measured.
+
+```bash
+bun add @tongue-core/ui@next react react-dom effect @effect/atom-react   # the last four are peers
+```
+
+The player's worker (`@tongue-core/ui/player/worker`) is a script of its own: bundle it next to your
+app and pass its URL to `createPlayer`.
+
+## Entry points
+
+| Import | Holds | Depends on |
+|---|---|---|
+| `@tongue-core/ui/player` | `createPlayer`: a build played on a canvas, with workers, readiness, the frame cache, video and sound; and its parts (`FilmNeeds`, `AssetLoader`, `FrameCache`, `Transport`, `wantedFrames`) | the engine (in the workers only), `@tongue-core/project` |
+| `@tongue-core/ui/player/worker` | the worker script: bundle it and pass its URL | the engine |
+| `@tongue-core/ui/timeline` | `makeTimeline`: a timeline as Effect Atoms; `connectPlayer`; pure models of the film, the view, the ruler, selection, rows and previews | Effect, `@tongue-core/project/doc` |
+| `@tongue-core/ui/react` | `TimelineProvider`, the `Timeline.*` primitives, `usePlayer`, `useTransport`, `useTimelineKeys`, `useAtomEffect` | React 19 (peer), `@effect/atom-react` |
+
+The entries are boundaries, checked by bundling each alone: `/timeline` carries no engine and no
+React; `/player`'s page code carries no React and no engine (the raster stays in the worker).
+
+## A player
+
+```ts
+import { createPlayer } from "@tongue-core/ui/player";
+
+const player = createPlayer({ canvas, workerUrl: new URL("./worker.js", import.meta.url) });
+await player.load({ build: "https://cdn.example/films/promo/" });   // or "/build/": any folder with build.json
+player.on("frame", ({ frame }) => …);
+player.on("readiness", ({ ranges, progress }) => …);               // what can be drawn, what is loaded
+player.seek(240); player.play(); player.pause();
+player.fit(canvas.clientWidth);                                      // render at the size it is shown
+const bitmap = await player.preview(900, 160);                       // a thumbnail, when the workers are free
+```
+
+A build is static files: `build.json`, `film.json`, `scenes/*.js`, `assets/…` (`tongue build`
+writes one). The player fetches the manifests and bundles, then the asset files frames need, nearest
+the playhead first, each checked against its hash. **A frame is drawn only once every file it needs
+is there**; until then the last frame stays up. Video plays from the proxy segments import makes
+(H.264, decoded with WebCodecs in a worker), sound from the soundtrack mixed a few seconds at a time.
+Frames, video frames and sound are byte-for-byte what Bun makes from the same build.
+
+## A timeline
+
+```ts
+import * as AtomRegistry from "effect/reactivity/AtomRegistry";
+import { connectPlayer, makeTimeline } from "@tongue-core/ui/timeline";
+
+const registry = AtomRegistry.make();
+const timeline = makeTimeline();
+const part = connectPlayer(registry, timeline, player);   // reports in, commands out
+
+registry.get(timeline.model);                                     // rows, clips, edges: film.json laid out
+registry.set(timeline.commands, { type: "nextEdge" });            // intents; the player carries them out
+registry.set(timeline.view, { type: "zoom", factor: 2, anchor: 300 });
+registry.subscribe(timeline.items("base"), (items) => …);         // what a row draws at this zoom
+```
+
+What depends on what decides what it costs: the model is rebuilt only for a new film.json; what a
+row draws changes only when the view crosses a power-of-two step of frames or of zoom; the playhead
+is a report that nothing heavy reads. Commands are numbered, so a reported playhead never becomes a
+seek. Everything under the atoms is pure and tested on its own (`view.ts`, `ticks.ts`, `items.ts`…).
+
+## React
+
+```tsx
+import { Timeline, TimelineProvider, usePlayer, useTimelineKeys } from "@tongue-core/ui/react";
+
+<TimelineProvider timeline={timeline} registry={registry} previews={player}>
+  <Timeline.Root>
+    <Timeline.Scroller>
+      <Timeline.Ruler />
+      <Timeline.Ready />
+      <Timeline.Rows>{(row) => <Timeline.Row key={row.id} row={row} />}</Timeline.Rows>
+      <Timeline.Playhead />
+    </Timeline.Scroller>
+  </Timeline.Root>
+  <Timeline.Timecode />
+</TimelineProvider>
+```
+
+Unstyled: every element has `data-tl-*` attributes to style by (`[data-tl-clip][data-selected]`,
+`[data-tl-clip][data-kind="video"]`, `[data-tl-run]`…). Positions are frames in CSS variables times
+the zoom (`--tl-ppf`), so zooming and scrolling are the browser's work, not React's; the playhead and
+the timecode write to their own elements, so playing commits nothing. Clips narrower than a few
+pixels join runs, one element each, so an hour of a thousand clips is a few hundred elements zoomed
+out. `useAtomEffect(atom, f)` is the same trick for your own readouts.
+
+## Checks
+
+`bun test` runs the pure parts and the atom graph (in a bare registry). In headless Chrome:
+`tools/ui-bench/player-check.ts` (the player on built projects, local and cross-origin, against the
+budgets), `tools/ui-bench/react-check.ts` (the primitives on an hour of clips) and
+`tools/ui-bench/studio-check.ts` (the studio). The lab pages they drive are in `lab/`.

package/dist/budgets.d.ts

@@ -0,0 +1,17 @@
+export interface Budgets {
+    /** From load() to the first frame on screen, warm cache, local build. */
+    readonly firstFrameMs: number;
+    /** A jump anywhere while paused, to the frame on screen (assets already loaded): p95. */
+    readonly seekP95Ms: number;
+    /** Frames shown per second while scrubbing (dragging the playhead). */
+    readonly scrubFps: number;
+    /** Frames dropped per minute of playback at 1080p, 30 fps, render scale 0.5. */
+    readonly droppedPerMinute: number;
+    /** Frame time while panning and zooming a timeline of 1,000 clips: p95. */
+    readonly timelineFrameP95Ms: number;
+    /** React commits per playback frame (the playhead is drawn outside React). */
+    readonly commitsPerPlaybackFrame: number;
+    /** Bytes of rendered frames kept in memory. */
+    readonly frameCacheBytes: number;
+}
+export declare const BUDGETS: Budgets;

package/dist/budgets.js

@@ -0,0 +1,12 @@
+// The performance budgets every layer of the UI is built and measured against. The benchmark
+// harness (tools/ui-bench) runs generated films (an hour with a thousand clips, ten minutes of
+// footage) in headless Chrome and fails when one is exceeded. docs/ui.md explains each.
+export const BUDGETS = {
+    firstFrameMs: 1000,
+    seekP95Ms: 120,
+    scrubFps: 20,
+    droppedPerMinute: 30,
+    timelineFrameP95Ms: 16.7,
+    commitsPerPlaybackFrame: 0,
+    frameCacheBytes: 256 * 1024 * 1024,
+};

package/dist/player/assets.d.ts

@@ -0,0 +1,48 @@
+export interface AssetFileInfo {
+    /** Relative to the build's assets folder: fonts/inter.ttf. */
+    readonly path: string;
+    /** Its size, when the build says (0 when unknown). */
+    readonly bytes: number;
+    /** SHA-256, hex, when the build says. */
+    readonly hash: string | null;
+}
+export type AssetStatus = "waiting" | "loading" | "ready" | "failed";
+export interface AssetProgress {
+    readonly files: number;
+    readonly ready: number;
+    readonly failed: number;
+    /** Bytes of every file, and of those ready (sizes the build gives). */
+    readonly bytes: number;
+    readonly bytesReady: number;
+}
+export type FetchBytes = (path: string, signal: AbortSignal) => Promise<Uint8Array>;
+export declare class AssetLoader {
+    private readonly fetchBytes;
+    private readonly concurrency;
+    private readonly entries;
+    private readonly listeners;
+    private readonly abort;
+    private active;
+    constructor(files: ReadonlyArray<AssetFileInfo>, fetchBytes: FetchBytes, concurrency?: number);
+    /** Asks for files at a priority: lower is sooner. Files the build doesn't list are ignored. */
+    want(paths: Iterable<string>, priority: number): void;
+    status(path: string): AssetStatus | null;
+    readonly isReady: (path: string) => boolean;
+    /** A ready file's bytes. */
+    data(path: string): Uint8Array | null;
+    /** Why a file failed. */
+    error(path: string): string | null;
+    progress(): AssetProgress;
+    /** Takes over files another loader (the last build's) already has, where the hashes match: a
+     *  rebuild fetches only what changed. Returns the paths taken over. */
+    carryOver(previous: AssetLoader): ReadonlyArray<string>;
+    /** Files that failed go back in the queue. */
+    retry(): void;
+    onChange(listener: (path: string) => void): () => void;
+    dispose(): void;
+    private changed;
+    /** The most urgent file asked for and not started. */
+    private next;
+    private pump;
+    private load;
+}

package/dist/player/assets.js

@@ -0,0 +1,133 @@
+// The player's one fetcher of imported asset files. Files are fetched most urgent first (a lower
+// priority number is sooner; a file keeps the most urgent priority anyone asked it at), a few at a
+// time, each checked against the hash its build gives it. Every file has a status, and the loader
+// says when one changes: that is what readiness, progress bars and "can this frame be drawn
+// exactly" are made of. Nothing here knows about frames.
+async function sha256(bytes) {
+    const copy = new Uint8Array(bytes.length);
+    copy.set(bytes);
+    const digest = await crypto.subtle.digest("SHA-256", copy);
+    return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+export class AssetLoader {
+    fetchBytes;
+    concurrency;
+    entries = new Map();
+    listeners = new Set();
+    abort = new AbortController();
+    active = 0;
+    constructor(files, fetchBytes, concurrency = 6) {
+        this.fetchBytes = fetchBytes;
+        this.concurrency = concurrency;
+        for (const info of files)
+            this.entries.set(info.path, { info, status: "waiting", priority: Number.POSITIVE_INFINITY, data: null, error: null });
+    }
+    /** Asks for files at a priority: lower is sooner. Files the build doesn't list are ignored. */
+    want(paths, priority) {
+        for (const path of paths) {
+            const e = this.entries.get(path);
+            if (e && priority < e.priority)
+                e.priority = priority;
+        }
+        this.pump();
+    }
+    status(path) {
+        return this.entries.get(path)?.status ?? null;
+    }
+    isReady = (path) => this.entries.get(path)?.status === "ready";
+    /** A ready file's bytes. */
+    data(path) {
+        return this.entries.get(path)?.data ?? null;
+    }
+    /** Why a file failed. */
+    error(path) {
+        return this.entries.get(path)?.error ?? null;
+    }
+    progress() {
+        let ready = 0, failed = 0, bytes = 0, bytesReady = 0;
+        for (const e of this.entries.values()) {
+            bytes += e.info.bytes;
+            if (e.status === "ready") {
+                ready++;
+                bytesReady += e.info.bytes;
+            }
+            if (e.status === "failed")
+                failed++;
+        }
+        return { files: this.entries.size, ready, failed, bytes, bytesReady };
+    }
+    /** Takes over files another loader (the last build's) already has, where the hashes match: a
+     *  rebuild fetches only what changed. Returns the paths taken over. */
+    carryOver(previous) {
+        const taken = [];
+        for (const [path, e] of this.entries) {
+            const old = previous.entries.get(path);
+            if (!old || old.status !== "ready" || old.data === null || e.info.hash === null || old.info.hash !== e.info.hash)
+                continue;
+            e.data = old.data;
+            e.status = "ready";
+            taken.push(path);
+        }
+        return taken;
+    }
+    /** Files that failed go back in the queue. */
+    retry() {
+        for (const e of this.entries.values())
+            if (e.status === "failed") {
+                e.status = "waiting";
+                e.error = null;
+            }
+        this.pump();
+    }
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    dispose() {
+        this.abort.abort();
+        this.listeners.clear();
+    }
+    changed(path) {
+        for (const listener of this.listeners)
+            listener(path);
+    }
+    /** The most urgent file asked for and not started. */
+    next() {
+        let best = null;
+        for (const e of this.entries.values()) {
+            if (e.status === "waiting" && e.priority < Number.POSITIVE_INFINITY && (!best || e.priority < best.priority))
+                best = e;
+        }
+        return best;
+    }
+    pump() {
+        while (this.active < this.concurrency && !this.abort.signal.aborted) {
+            const e = this.next();
+            if (!e)
+                return;
+            this.active++;
+            e.status = "loading";
+            this.changed(e.info.path);
+            void this.load(e).finally(() => {
+                this.active--;
+                this.pump();
+            });
+        }
+    }
+    async load(e) {
+        try {
+            const data = await this.fetchBytes(e.info.path, this.abort.signal);
+            if (e.info.hash !== null && (await sha256(data)) !== e.info.hash)
+                throw new Error("its contents don't match the build (the hash differs)");
+            e.data = data;
+            e.status = "ready";
+        }
+        catch (error) {
+            if (this.abort.signal.aborted)
+                return;
+            e.status = "failed";
+            e.error = error instanceof Error ? error.message : String(error);
+        }
+        this.changed(e.info.path);
+    }
+}

package/dist/player/audio.d.ts

@@ -0,0 +1,44 @@
+import type { MixResult } from "./pool.js";
+export interface SoundtrackOptions {
+    readonly fps: number;
+    /** The film's length in frames. */
+    readonly length: number;
+    /** Mixes frames [from, to). */
+    readonly mix: (from: number, to: number) => Promise<MixResult>;
+    /** Frames per chunk (default 5 seconds). */
+    readonly chunk?: number;
+    /** Chunks kept mixed ahead of the playhead (default 3). */
+    readonly ahead?: number;
+}
+export declare class Soundtrack {
+    private readonly options;
+    private context;
+    private readonly chunks;
+    private readonly mixing;
+    private playing;
+    private readonly size;
+    private readonly ahead;
+    private volume;
+    private gain;
+    private generation;
+    constructor(options: SoundtrackOptions);
+    /** The audio clock in seconds, when it is running (it runs only after a user gesture). */
+    clock(): number | null;
+    /** Creates or resumes the audio context; call it from a click or key press. */
+    wake(): void;
+    setVolume(volume: number): void;
+    /** Whether the chunk under `frame` is mixed (playback waits for it when there is a clock). */
+    ready(frame: number): boolean;
+    /** Mixes the chunks from `frame` on that aren't mixed yet. */
+    prepare(frame: number): void;
+    /** Starts sound at `frame`, at audio time `time` (from clock()). */
+    start(frame: number, time: number): void;
+    /** Schedules the chunks that are mixed and due; call it every tick while playing. */
+    schedule(): void;
+    stop(): void;
+    /** The film changed: forget every chunk. */
+    reset(): void;
+    dispose(): void;
+    private chunkOf;
+    private load;
+}

package/dist/player/audio.js

@@ -0,0 +1,158 @@
+/** Chunks kept around (about a minute at 5 s each), the most recently used. */
+const KEPT = 12;
+/** Seconds between asking to start and the first sample, so the start is never late. */
+const LEAD = 0.05;
+export class Soundtrack {
+    options;
+    context = null;
+    chunks = new Map();
+    mixing = new Map();
+    playing = null;
+    size;
+    ahead;
+    volume = 1;
+    gain = null;
+    generation = 0;
+    constructor(options) {
+        this.options = options;
+        this.size = Math.max(1, Math.round(options.chunk ?? options.fps * 5));
+        this.ahead = Math.max(1, options.ahead ?? 3);
+    }
+    /** The audio clock in seconds, when it is running (it runs only after a user gesture). */
+    clock() {
+        const ctx = this.context;
+        return ctx && ctx.state === "running" ? ctx.currentTime : null;
+    }
+    /** Creates or resumes the audio context; call it from a click or key press. */
+    wake() {
+        if (!this.context) {
+            this.context = new AudioContext({ sampleRate: 48000, latencyHint: "interactive" });
+            this.gain = this.context.createGain();
+            this.gain.gain.value = this.volume;
+            this.gain.connect(this.context.destination);
+        }
+        if (this.context.state === "suspended")
+            void this.context.resume();
+    }
+    setVolume(volume) {
+        this.volume = Math.max(0, Math.min(1, volume));
+        if (this.gain)
+            this.gain.gain.value = this.volume;
+    }
+    /** Whether the chunk under `frame` is mixed (playback waits for it when there is a clock). */
+    ready(frame) {
+        return this.chunks.has(this.chunkOf(frame));
+    }
+    /** Mixes the chunks from `frame` on that aren't mixed yet. */
+    prepare(frame) {
+        const first = this.chunkOf(frame);
+        for (let k = first; k < first + this.ahead && k * this.size < this.options.length; k++)
+            void this.load(k);
+    }
+    /** Starts sound at `frame`, at audio time `time` (from clock()). */
+    start(frame, time) {
+        this.stop();
+        const ctx = this.context;
+        if (!ctx || ctx.state !== "running")
+            return;
+        this.playing = { frame, time: time + LEAD, sources: [], next: this.chunkOf(frame) };
+        this.schedule();
+    }
+    /** Schedules the chunks that are mixed and due; call it every tick while playing. */
+    schedule() {
+        const p = this.playing, ctx = this.context, gain = this.gain;
+        if (!p || !ctx || !gain)
+            return;
+        this.prepare(p.next * this.size);
+        for (;;) {
+            const buffer = this.chunks.get(p.next);
+            if (!buffer)
+                return;
+            const chunkStart = p.next * this.size;
+            // Seconds after the start frame this chunk begins (negative for the chunk the start is in).
+            const at = (chunkStart - p.frame) / this.options.fps;
+            const source = ctx.createBufferSource();
+            source.buffer = buffer;
+            source.connect(gain);
+            const when = p.time + Math.max(0, at);
+            const offset = Math.max(0, -at);
+            if (offset < buffer.duration)
+                source.start(Math.max(when, ctx.currentTime), offset);
+            p.sources.push(source);
+            p.next++;
+            if (p.next * this.size >= this.options.length)
+                return;
+            // Far enough ahead: the rest is scheduled on later ticks.
+            if (when - ctx.currentTime > (this.size / this.options.fps) * 1.5)
+                return;
+        }
+    }
+    stop() {
+        if (!this.playing)
+            return;
+        for (const s of this.playing.sources) {
+            try {
+                s.stop();
+            }
+            catch { /* never started */ }
+            s.disconnect();
+        }
+        this.playing = null;
+    }
+    /** The film changed: forget every chunk. */
+    reset() {
+        this.stop();
+        this.chunks.clear();
+        this.mixing.clear();
+        this.generation++;
+    }
+    dispose() {
+        this.reset();
+        void this.context?.close();
+        this.context = null;
+    }
+    chunkOf(frame) {
+        return Math.max(0, Math.floor(frame / this.size));
+    }
+    load(k) {
+        const known = this.chunks.get(k);
+        if (known) {
+            // Most recently used goes last, so the oldest is dropped first.
+            this.chunks.delete(k);
+            this.chunks.set(k, known);
+            return Promise.resolve(known);
+        }
+        const pending = this.mixing.get(k);
+        if (pending)
+            return pending;
+        const generation = this.generation;
+        const from = k * this.size, to = Math.min(this.options.length, from + this.size);
+        const job = this.options.mix(from, to).then((mixed) => {
+            this.mixing.delete(k);
+            if (generation !== this.generation)
+                return null;
+            const buffer = new AudioBuffer({ numberOfChannels: 2, length: Math.max(1, mixed.left.length), sampleRate: mixed.sampleRate });
+            buffer.copyToChannel(own(mixed.left), 0);
+            buffer.copyToChannel(own(mixed.right), 1);
+            this.chunks.set(k, buffer);
+            while (this.chunks.size > KEPT) {
+                const oldest = this.chunks.keys().next();
+                if (oldest.done)
+                    break;
+                this.chunks.delete(oldest.value);
+            }
+            return buffer;
+        }, () => {
+            this.mixing.delete(k);
+            return null;
+        });
+        this.mixing.set(k, job);
+        return job;
+    }
+}
+/** copyToChannel wants an ArrayBuffer-backed array. */
+function own(data) {
+    const copy = new Float32Array(data.length);
+    copy.set(data);
+    return copy;
+}

package/dist/player/frames.d.ts

@@ -0,0 +1,34 @@
+export interface Closable {
+    close(): void;
+}
+export interface Cached<T> {
+    readonly value: T;
+    readonly scale: number;
+    readonly bytes: number;
+    /** False when something stood in for part of it (a video's poster for its frames). */
+    readonly exact: boolean;
+}
+export declare class FrameCache<T extends Closable> {
+    private readonly budget;
+    private readonly frames;
+    private total;
+    private focus;
+    constructor(budget: number);
+    /** The best scale `frame` is cached at, or null. */
+    scaleOf(frame: number): number | null;
+    /** True when `frame` is cached at `scale` or better. */
+    has(frame: number, scale?: number): boolean;
+    get(frame: number): Cached<T> | undefined;
+    /** Keeps the better of what is there and what arrived (sharper; exact over stood-in), closing
+     *  the other, then keeps to the budget. */
+    put(frame: number, value: T, scale: number, bytes: number, exact?: boolean): void;
+    /** Where the playhead is: eviction starts furthest from it. */
+    setFocus(frame: number): void;
+    /** The cached frame nearest `frame`, at most `radius` away (the earlier one on a tie). */
+    nearest(frame: number, radius: number): number | null;
+    clear(): void;
+    get bytes(): number;
+    get size(): number;
+    private remove;
+    private trim;
+}

package/dist/player/frames.js

@@ -0,0 +1,83 @@
+// Rendered frames kept for showing again, under a budget of bytes. A frame is kept at the best
+// scale it was rendered at; when the budget is exceeded, the frames furthest from the focus (the
+// playhead) go first, and whatever leaves is closed, so an ImageBitmap's memory is released at once.
+export class FrameCache {
+    budget;
+    frames = new Map();
+    total = 0;
+    focus = 0;
+    constructor(budget) {
+        this.budget = budget;
+    }
+    /** The best scale `frame` is cached at, or null. */
+    scaleOf(frame) {
+        return this.frames.get(frame)?.scale ?? null;
+    }
+    /** True when `frame` is cached at `scale` or better. */
+    has(frame, scale = 0) {
+        const hit = this.frames.get(frame);
+        return hit !== undefined && hit.scale >= scale;
+    }
+    get(frame) {
+        return this.frames.get(frame);
+    }
+    /** Keeps the better of what is there and what arrived (sharper; exact over stood-in), closing
+     *  the other, then keeps to the budget. */
+    put(frame, value, scale, bytes, exact = true) {
+        const old = this.frames.get(frame);
+        if (old && (old.scale > scale || (old.scale === scale && (old.exact || !exact)))) {
+            value.close();
+            return;
+        }
+        if (old)
+            this.remove(frame, old);
+        this.frames.set(frame, { value, scale, bytes, exact });
+        this.total += bytes;
+        this.trim();
+    }
+    /** Where the playhead is: eviction starts furthest from it. */
+    setFocus(frame) {
+        this.focus = frame;
+    }
+    /** The cached frame nearest `frame`, at most `radius` away (the earlier one on a tie). */
+    nearest(frame, radius) {
+        for (let k = 0; k <= radius; k++) {
+            if (this.frames.has(frame - k))
+                return frame - k;
+            if (this.frames.has(frame + k))
+                return frame + k;
+        }
+        return null;
+    }
+    clear() {
+        for (const entry of this.frames.values())
+            entry.value.close();
+        this.frames.clear();
+        this.total = 0;
+    }
+    get bytes() {
+        return this.total;
+    }
+    get size() {
+        return this.frames.size;
+    }
+    remove(frame, entry) {
+        entry.value.close();
+        this.frames.delete(frame);
+        this.total -= entry.bytes;
+    }
+    trim() {
+        if (this.total <= this.budget)
+            return;
+        const byDistance = [...this.frames.keys()].sort((a, b) => Math.abs(b - this.focus) - Math.abs(a - this.focus));
+        for (const frame of byDistance) {
+            if (this.total <= this.budget)
+                break;
+            if (frame === this.focus)
+                continue;
+            const entry = this.frames.get(frame);
+            if (entry)
+                this.remove(frame, entry);
+        }
+    }
+}

package/dist/player/index.d.ts

@@ -0,0 +1,9 @@
+export { createPlayer, type Player, type PlayerOptions, type PlayerEvents, type PlayerEvent, type Readiness, type Shown, type LoadedFilm, type Pixels, type Mix } from "./player.js";
+export { Cancelled, type FrameResult } from "./pool.js";
+export { openSource, buildBase, SourceError, type BuildSource, type OpenedSource } from "./source.js";
+export { FilmNeeds, type Span, type Range } from "./needs.js";
+export { AssetLoader, type AssetFileInfo, type AssetStatus, type AssetProgress, type FetchBytes } from "./assets.js";
+export { FrameCache, type Cached, type Closable } from "./frames.js";
+export { Transport, type PlayState, type TickInput, type TickResult } from "./transport.js";
+export { wantedFrames, bufferedAhead, startBuffer, clockFrame, clampFrame, type Scales, type Want, type Situation } from "./schedule.js";
+export { BUDGETS, type Budgets } from "../budgets.js";