@tongue-core/ui 0.1.0-rc.1 → 0.1.0-rc.10

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

@@ -38,13 +38,52 @@ player.fit(canvas.clientWidth);                                      // render a
 const bitmap = await player.preview(900, 160);                       // a thumbnail, when the workers are free
 ```
 
+The picture keeps the film's shape in whatever box the page gives the canvas: unless the page
+sets its own `object-fit`, the player sets `contain`, so a box of another shape letterboxes the
+frame instead of stretching it.
+
 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
+writes one). The player fetches them from the build's folder or, given `read` instead of `build`,
+reads them a file at a time from wherever the build is kept (a Git commit, memory, an archive):
+
+```ts
+// Each path as the build gives it: "build.json", "scenes/title.5ebf1e9a05d5.js", "assets/fonts/inter.ttf"…
+await player.load({ read: (path, signal) => commit.bytes(path, signal) });
+```
+
+Either way it reads 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.
 
+Version 2 builds can keep their media outside the build. The player reads each remote file from
+the URL in its manifest, verifies its hash, and bypasses `read` for that file. A Git-backed studio
+therefore needs only code and manifests in Git; originals are never fetched by the browser.
+Remote builds fetch a bounded window of proxy video and segmented audio (15 seconds ahead by
+default). Scenes request their actual video segments when drawn. Old compressed data and decoded
+audio segments are evicted, with stale transfers cancelled after seeks; a queued request the window
+leaves behind is cancelled too, so no decoder waits on a segment nobody will fetch. A video's
+decodes wait for their segments before taking their turn (playback is never held up behind a
+thumbnail on its way), and a jump skips playback's decodes still queued for where it was. `mediaCacheBytes`
+(default 64 MiB) and `mediaAhead` configure the window; files required by active requests remain
+pinned until those requests finish. Decoded video frames have a separate shared byte budget.
+
+```ts
+await player.load({
+  read: (path, signal) => commit.bytes(path, signal),
+  request: (url, signal, headers) => fetch(url, { signal, headers }),
+});
+```
+
+The optional `request` hook supplies authentication or URL refresh. Transient downloads retry
+through the shared media transport. `readiness.failed` reports permanent failures; `player.retry()`
+retries them after the host restores access. `readiness.mediaBytes` reports retained compressed
+data. Failure records also expose `reason`, `status` and `retryable` when known. For streaming
+builds, progress counts describe the current fetch window. Readiness ranges for dynamic scene
+video conservatively report already rendered exact frames, since a scene can choose arbitrary
+source times. Local packaged builds preserve their existing background preloading behavior.
+
 ## A timeline
 
 ```ts

package/dist/player/assets.d.ts

@@ -1,4 +1,12 @@
+import { MediaFailure } from "@tongue-core/project/media";
+export interface AssetFailureInfo {
+    readonly message: string;
+    readonly reason?: MediaFailure["reason"];
+    readonly status?: number;
+    readonly retryable?: boolean;
+}
 export interface AssetFileInfo {
+    readonly url?: string;
     /** Relative to the build's assets folder: fonts/inter.ttf. */
     readonly path: string;
     /** Its size, when the build says (0 when unknown). */
@@ -8,6 +16,8 @@ export interface AssetFileInfo {
 }
 export type AssetStatus = "waiting" | "loading" | "ready" | "failed";
 export interface AssetProgress {
+    /** Counts describe the current fetch window when streaming. */
+    readonly streaming?: boolean;
     readonly files: number;
     readonly ready: number;
     readonly failed: number;
@@ -19,20 +29,37 @@ export type FetchBytes = (path: string, signal: AbortSignal) => Promise<Uint8Arr
 export declare class AssetLoader {
     private readonly fetchBytes;
     private readonly concurrency;
+    private readonly maxBytes;
     private readonly entries;
     private readonly listeners;
     private readonly abort;
     private active;
-    constructor(files: ReadonlyArray<AssetFileInfo>, fetchBytes: FetchBytes, concurrency?: number);
+    private clock;
+    private readonly retained;
+    onEvict: (path: string) => void;
+    /** A request for `path` was withdrawn before it was answered — its transfer stopped, or it never
+     *  started — so whoever waits for the file hears it won't come (and asks again if it still wants it). */
+    onCancel: (path: string) => void;
+    constructor(files: ReadonlyArray<AssetFileInfo>, fetchBytes: FetchBytes, concurrency?: number, maxBytes?: 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;
+    /** Changes the fetch window. Requests outside it are withdrawn, under way or still queued; old data
+     *  is evicted under the byte budget. */
+    retain(paths: Iterable<string>): void;
+    get heldBytes(): number;
+    private evict;
     /** Why a file failed. */
     error(path: string): string | null;
-    progress(): AssetProgress;
+    failure(path: string): AssetFailureInfo;
+    failMissing(path: string): void;
+    failures(): ReadonlyArray<{
+        readonly path: string;
+    } & AssetFailureInfo>;
+    progress(windowOnly?: boolean): 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>;

package/dist/player/assets.js

@@ -3,6 +3,7 @@
 // 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.
+import { MediaFailure } from "@tongue-core/project/media";
 async function sha256(bytes) {
     const copy = new Uint8Array(bytes.length);
     copy.set(bytes);
@@ -12,20 +13,30 @@ async function sha256(bytes) {
 export class AssetLoader {
     fetchBytes;
     concurrency;
+    maxBytes;
     entries = new Map();
     listeners = new Set();
     abort = new AbortController();
     active = 0;
-    constructor(files, fetchBytes, concurrency = 6) {
+    clock = 0;
+    retained = new Set();
+    onEvict = () => { };
+    /** A request for `path` was withdrawn before it was answered — its transfer stopped, or it never
+     *  started — so whoever waits for the file hears it won't come (and asks again if it still wants it). */
+    onCancel = () => { };
+    constructor(files, fetchBytes, concurrency = 6, maxBytes = Infinity) {
         this.fetchBytes = fetchBytes;
         this.concurrency = concurrency;
+        this.maxBytes = maxBytes;
         for (const info of files)
-            this.entries.set(info.path, { info, status: "waiting", priority: Number.POSITIVE_INFINITY, data: null, error: null });
+            this.entries.set(info.path, { info, status: "waiting", priority: Number.POSITIVE_INFINITY, data: null, error: null, abort: null, used: 0, failure: 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)
+                e.used = ++this.clock;
             if (e && priority < e.priority)
                 e.priority = priority;
         }
@@ -37,15 +48,67 @@ export class AssetLoader {
     isReady = (path) => this.entries.get(path)?.status === "ready";
     /** A ready file's bytes. */
     data(path) {
-        return this.entries.get(path)?.data ?? null;
+        const entry = this.entries.get(path);
+        if (entry)
+            entry.used = ++this.clock;
+        return entry?.data ?? null;
+    }
+    /** Changes the fetch window. Requests outside it are withdrawn, under way or still queued; old data
+     *  is evicted under the byte budget. */
+    retain(paths) {
+        this.retained.clear();
+        for (const path of paths)
+            this.retained.add(path);
+        for (const [path, entry] of this.entries) {
+            if (this.retained.has(path))
+                continue;
+            const queued = entry.status === "waiting" && entry.priority < Number.POSITIVE_INFINITY;
+            const transfer = entry.abort !== null && !entry.abort.signal.aborted ? entry.abort : null;
+            entry.priority = Number.POSITIVE_INFINITY;
+            transfer?.abort();
+            if (queued || transfer)
+                this.onCancel(path);
+        }
+        this.evict();
+    }
+    get heldBytes() { let bytes = 0; for (const entry of this.entries.values())
+        bytes += entry.data?.length ?? 0; return bytes; }
+    evict() {
+        let bytes = this.heldBytes;
+        const candidates = [...this.entries.values()].filter((entry) => entry.data && !this.retained.has(entry.info.path)).sort((a, b) => a.used - b.used);
+        for (const entry of candidates) {
+            if (bytes <= this.maxBytes)
+                break;
+            bytes -= entry.data?.length ?? 0;
+            entry.data = null;
+            entry.status = "waiting";
+            entry.priority = Infinity;
+            this.onEvict(entry.info.path);
+            this.changed(entry.info.path);
+        }
     }
     /** Why a file failed. */
     error(path) {
         return this.entries.get(path)?.error ?? null;
     }
-    progress() {
-        let ready = 0, failed = 0, bytes = 0, bytesReady = 0;
+    failure(path) {
+        const entry = this.entries.get(path), failure = entry?.failure;
+        return { message: entry?.error ?? "failed", ...(failure ? { reason: failure.reason, retryable: failure.retryable, ...(failure.status === undefined ? {} : { status: failure.status }) } : {}) };
+    }
+    failMissing(path) {
+        const failure = new MediaFailure({ asset: path, source: "build.json", reason: "invalid", retryable: false, message: `The build does not list required preview file ${path}. Rebuild or repair its prepared-media manifest.` });
+        this.entries.set(path, { info: { path, bytes: 0, hash: null }, status: "failed", priority: Infinity, data: null, error: failure.message, abort: null, used: ++this.clock, failure });
+        this.changed(path);
+    }
+    failures() {
+        return [...this.entries.values()].filter((entry) => entry.status === "failed").map((entry) => ({ path: entry.info.path, ...this.failure(entry.info.path) }));
+    }
+    progress(windowOnly = false) {
+        let ready = 0, failed = 0, bytes = 0, bytesReady = 0, files = 0;
         for (const e of this.entries.values()) {
+            if (windowOnly && !this.retained.has(e.info.path))
+                continue;
+            files++;
             bytes += e.info.bytes;
             if (e.status === "ready") {
                 ready++;
@@ -54,7 +117,7 @@ export class AssetLoader {
             if (e.status === "failed")
                 failed++;
         }
-        return { files: this.entries.size, ready, failed, bytes, bytesReady };
+        return { files, ready, failed, bytes, bytesReady, ...(windowOnly ? { streaming: true } : {}) };
     }
     /** 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. */
@@ -73,9 +136,10 @@ export class AssetLoader {
     /** Files that failed go back in the queue. */
     retry() {
         for (const e of this.entries.values())
-            if (e.status === "failed") {
+            if (e.status === "failed" && e.failure?.reason !== "invalid") {
                 e.status = "waiting";
                 e.error = null;
+                e.failure = null;
             }
         this.pump();
     }
@@ -85,6 +149,8 @@ export class AssetLoader {
     }
     dispose() {
         this.abort.abort();
+        for (const entry of this.entries.values())
+            entry.abort?.abort();
         this.listeners.clear();
     }
     changed(path) {
@@ -115,19 +181,33 @@ export class AssetLoader {
         }
     }
     async load(e) {
+        const abort = new AbortController();
+        e.abort = abort;
         try {
-            const data = await this.fetchBytes(e.info.path, this.abort.signal);
+            const data = await this.fetchBytes(e.info.path, AbortSignal.any([this.abort.signal, abort.signal]));
+            const integrity = (message) => new MediaFailure({ asset: e.info.path, source: e.info.url ?? e.info.path, reason: "integrity", retryable: false, message });
+            if (e.info.bytes > 0 && data.length !== e.info.bytes)
+                throw integrity(`its size differs from the build (${data.length} bytes, expected ${e.info.bytes})`);
             if (e.info.hash !== null && (await sha256(data)) !== e.info.hash)
-                throw new Error("its contents don't match the build (the hash differs)");
+                throw integrity("its contents don't match the build (the hash differs)");
             e.data = data;
             e.status = "ready";
         }
         catch (error) {
             if (this.abort.signal.aborted)
                 return;
+            if (abort.signal.aborted) {
+                e.status = "waiting";
+                return;
+            }
             e.status = "failed";
+            e.failure = error instanceof MediaFailure ? error : null;
             e.error = error instanceof Error ? error.message : String(error);
         }
+        finally {
+            e.abort = null;
+        }
         this.changed(e.info.path);
+        this.evict();
     }
 }

package/dist/player/audio.d.ts

@@ -4,17 +4,45 @@ export interface SoundtrackOptions {
     /** The film's length in frames. */
     readonly length: number;
     /** Mixes frames [from, to). */
-    readonly mix: (from: number, to: number) => Promise<MixResult>;
+    readonly mix: (from: number, to: number, signal: AbortSignal) => Promise<MixResult>;
     /** Frames per chunk (default 5 seconds). */
     readonly chunk?: number;
     /** Chunks kept mixed ahead of the playhead (default 3). */
     readonly ahead?: number;
 }
+/** A chunk to put on the audio clock: when it starts, and how far into it (the chunk playback started in starts part way). */
+export interface DueChunk {
+    readonly chunk: number;
+    readonly when: number;
+    readonly offset: number;
+}
+export interface DueOptions {
+    /** The first chunk not yet on the clock. */
+    readonly next: number;
+    /** Frames per chunk, frames a second, and the film's length in frames. */
+    readonly size: number;
+    readonly fps: number;
+    readonly length: number;
+    /** Playback started at this frame, at this time on the audio clock. */
+    readonly startFrame: number;
+    readonly startTime: number;
+    /** The audio clock now, and how far ahead of it (seconds) sound may be put. */
+    readonly now: number;
+    readonly horizon: number;
+    readonly mixed: (chunk: number) => boolean;
+}
+/**
+ * The chunks to put on the audio clock now, in order from `next`: each one mixed, starting no further
+ * than `horizon` seconds ahead of the clock. It stops at the first chunk still being mixed (it is on
+ * its way) or too far ahead (a later tick takes it), and at the end of the film. Pure.
+ */
+export declare function dueChunks(o: DueOptions): ReadonlyArray<DueChunk>;
 export declare class Soundtrack {
     private readonly options;
     private context;
     private readonly chunks;
     private readonly mixing;
+    private readonly controllers;
     private playing;
     private readonly size;
     private readonly ahead;
@@ -33,7 +61,7 @@ export declare class Soundtrack {
     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. */
+    /** Schedules the chunks that are mixed and due (`dueChunks`); call it every tick while playing. */
     schedule(): void;
     stop(): void;
     /** The film changed: forget every chunk. */

package/dist/player/audio.js

@@ -2,11 +2,32 @@
 const KEPT = 12;
 /** Seconds between asking to start and the first sample, so the start is never late. */
 const LEAD = 0.05;
+/** How far ahead of the audio clock sound is put on it, in chunks: later chunks wait for later ticks
+ *  (and are mixed only as they near). */
+const HORIZON_CHUNKS = 1.5;
+/**
+ * The chunks to put on the audio clock now, in order from `next`: each one mixed, starting no further
+ * than `horizon` seconds ahead of the clock. It stops at the first chunk still being mixed (it is on
+ * its way) or too far ahead (a later tick takes it), and at the end of the film. Pure.
+ */
+export function dueChunks(o) {
+    const due = [];
+    for (let chunk = o.next; chunk * o.size < o.length && o.mixed(chunk); chunk++) {
+        // Seconds after the start frame this chunk begins (negative for the chunk the start is in).
+        const at = (chunk * o.size - o.startFrame) / o.fps;
+        const when = o.startTime + Math.max(0, at);
+        if (when - o.now > o.horizon)
+            break;
+        due.push({ chunk, when, offset: Math.max(0, -at) });
+    }
+    return due;
+}
 export class Soundtrack {
     options;
     context = null;
     chunks = new Map();
     mixing = new Map();
+    controllers = new Map();
     playing = null;
     size;
     ahead;
@@ -58,33 +79,27 @@ export class Soundtrack {
         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. */
+    /** Schedules the chunks that are mixed and due (`dueChunks`); 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);
+        const due = dueChunks({
+            next: p.next, size: this.size, fps: this.options.fps, length: this.options.length, startFrame: p.frame, startTime: p.time,
+            now: ctx.currentTime, horizon: (this.size / this.options.fps) * HORIZON_CHUNKS, mixed: (chunk) => this.chunks.has(chunk),
+        });
+        for (const { chunk, when, offset } of due) {
+            const buffer = this.chunks.get(chunk);
             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;
+            p.next = chunk + 1;
         }
     }
     stop() {
@@ -104,6 +119,9 @@ export class Soundtrack {
         this.stop();
         this.chunks.clear();
         this.mixing.clear();
+        for (const controller of this.controllers.values())
+            controller.abort();
+        this.controllers.clear();
         this.generation++;
     }
     dispose() {
@@ -127,10 +145,13 @@ export class Soundtrack {
             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);
+        const controller = new AbortController();
+        this.controllers.set(k, controller);
+        const job = this.options.mix(from, to, controller.signal).then((mixed) => {
             if (generation !== this.generation)
                 return null;
+            this.mixing.delete(k);
+            this.controllers.delete(k);
             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);
@@ -143,7 +164,10 @@ export class Soundtrack {
             }
             return buffer;
         }, () => {
-            this.mixing.delete(k);
+            if (generation === this.generation) {
+                this.mixing.delete(k);
+                this.controllers.delete(k);
+            }
             return null;
         });
         this.mixing.set(k, job);

package/dist/player/frames.d.ts

@@ -8,11 +8,15 @@ export interface Cached<T> {
     /** False when something stood in for part of it (a video's poster for its frames). */
     readonly exact: boolean;
 }
+/** What eviction keeps: the frames around the focus (paused: someone may step either way), or the
+ *  frames ahead of it (playing: what has been played is the first to go). */
+export type Keep = "around" | "ahead";
 export declare class FrameCache<T extends Closable> {
     private readonly budget;
     private readonly frames;
     private total;
     private focus;
+    private keep;
     constructor(budget: number);
     /** The best scale `frame` is cached at, or null. */
     scaleOf(frame: number): number | null;
@@ -22,13 +26,19 @@ export declare class FrameCache<T extends Closable> {
     /** 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;
+    /** Where the playhead is, and what eviction keeps around it. */
+    setFocus(frame: number, keep?: Keep): void;
+    /** How many frames of `bytes` each the budget holds (at least one: the focus is never evicted). */
+    capacity(bytes: number): number;
     /** 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;
+    exactRanges(): ReadonlyArray<{
+        readonly from: number;
+        readonly to: number;
+    }>;
     private remove;
     private trim;
 }

package/dist/player/frames.js

@@ -1,11 +1,14 @@
 // 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.
+// scale it was rendered at; when the budget is exceeded, frames go by how little they are worth to
+// the focus (the playhead): paused, the furthest from it on either side; playing, every frame
+// behind it first (they won't be shown again), then the furthest ahead. Whatever leaves is closed,
+// so an ImageBitmap's memory is released at once.
 export class FrameCache {
     budget;
     frames = new Map();
     total = 0;
     focus = 0;
+    keep = "around";
     constructor(budget) {
         this.budget = budget;
     }
@@ -35,9 +38,14 @@ export class FrameCache {
         this.total += bytes;
         this.trim();
     }
-    /** Where the playhead is: eviction starts furthest from it. */
-    setFocus(frame) {
+    /** Where the playhead is, and what eviction keeps around it. */
+    setFocus(frame, keep = "around") {
         this.focus = frame;
+        this.keep = keep;
+    }
+    /** How many frames of `bytes` each the budget holds (at least one: the focus is never evicted). */
+    capacity(bytes) {
+        return Math.max(1, Math.floor(this.budget / bytes));
     }
     /** The cached frame nearest `frame`, at most `radius` away (the earlier one on a tie). */
     nearest(frame, radius) {
@@ -61,6 +69,18 @@ export class FrameCache {
     get size() {
         return this.frames.size;
     }
+    exactRanges() {
+        const frames = [...this.frames].filter(([, value]) => value.exact).map(([frame]) => frame).sort((a, b) => a - b);
+        const ranges = [];
+        for (const frame of frames) {
+            const last = ranges[ranges.length - 1];
+            if (last?.to === frame)
+                last.to++;
+            else
+                ranges.push({ from: frame, to: frame + 1 });
+        }
+        return ranges;
+    }
     remove(frame, entry) {
         entry.value.close();
         this.frames.delete(frame);
@@ -69,8 +89,10 @@ export class FrameCache {
     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) {
+        const behind = (frame) => (this.keep === "ahead" && frame < this.focus ? 1 : 0);
+        // Least worth first: playing, every frame behind the focus before any ahead; then the furthest.
+        const byWorth = [...this.frames.keys()].sort((a, b) => behind(b) - behind(a) || Math.abs(b - this.focus) - Math.abs(a - this.focus));
+        for (const frame of byWorth) {
             if (this.total <= this.budget)
                 break;
             if (frame === this.focus)

package/dist/player/index.d.ts

@@ -1,8 +1,8 @@
 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 { openFilm, openSource, openFiles, buildBase, SourceError, type FilmSource, type BuildSource, type FileSource, type OpenedBuild, 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 { AssetLoader, type AssetFileInfo, type AssetStatus, type AssetProgress, type AssetFailureInfo, 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";

package/dist/player/index.js

@@ -1,10 +1,11 @@
 // @tongue-core/ui/player: a film's player, without React or Effect. It opens a build from wherever it is
-// served (build.json, film.json, the scene bundles, then the asset files frames need), draws exact
-// frames with the engine in Web Workers, and plays them with the soundtrack. The worker script is
-// @tongue-core/ui/player/worker; bundle it and pass its URL.
+// served, or reads it a file at a time from wherever it is kept (build.json, film.json, the scene
+// bundles, then the asset files frames need), draws exact frames with the engine in Web Workers, and
+// plays them with the soundtrack. The worker script is @tongue-core/ui/player/worker; bundle it and
+// pass its URL.
 export { createPlayer } from "./player.js";
 export { Cancelled } from "./pool.js";
-export { openSource, buildBase, SourceError } from "./source.js";
+export { openFilm, openSource, openFiles, buildBase, SourceError } from "./source.js";
 export { FilmNeeds } from "./needs.js";
 export { AssetLoader } from "./assets.js";
 export { FrameCache } from "./frames.js";

package/dist/player/needs.d.ts

@@ -20,12 +20,18 @@ export declare class FilmNeeds {
     /** What the soundtrack needs. */
     readonly audio: ReadonlyArray<string>;
     readonly length: number;
+    private readonly audioSegments;
+    private readonly audioClips;
+    private readonly fps;
     private constructor();
     /** A film's needs from its film.json, and the files its build has (which videos have proxies,
      *  and how many segments). */
-    static of(doc: FilmDoc, files?: ReadonlyArray<string>): FilmNeeds;
+    static of(doc: FilmDoc, files?: ReadonlyArray<string>, options?: {
+        readonly demandVideo?: boolean;
+    }): FilmNeeds;
     /** A film whose needs aren't known per clip: every frame needs every file. */
     static everything(paths: ReadonlyArray<string>, length: number): FilmNeeds;
+    audioPathsIn(from: number, to: number): ReadonlyArray<string>;
     /** The spans on screen at a frame, over every track. */
     spansAt(frame: number): ReadonlyArray<Span>;
     /** The spans on screen anywhere in [from, to). */