@tongue-core/ui 0.1.0-rc.3 → 0.1.0-rc.5

package/README.md

@@ -43,8 +43,16 @@ sets its own `object-fit`, the player sets `contain`, so a box of another shape
 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.

package/dist/player/index.d.ts

@@ -1,6 +1,6 @@
 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 { FrameCache, type Cached, type Closable } from "./frames.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/player.d.ts

@@ -3,7 +3,7 @@ import type { BuildDoc, FilmDoc } from "@tongue-core/project/doc";
 import { type AssetProgress } from "./assets.js";
 import { type Range } from "./needs.js";
 import { type Scales } from "./schedule.js";
-import { type BuildSource } from "./source.js";
+import { type FilmSource } from "./source.js";
 import { type PlayState } from "./transport.js";
 export interface PlayerOptions {
     /** Where frames are drawn. Its pixel size follows the film's size at the still scale. */
@@ -72,8 +72,9 @@ export interface Mix {
     readonly right: Float32Array;
 }
 export interface Player {
-    /** Loads a build (again, after a rebuild: the playhead and range are kept, unchanged files aren't fetched again). */
-    load(source: BuildSource): Promise<LoadedFilm>;
+    /** Loads a build, served as files (`{ build }`) or read a file at a time (`{ read }`); again after a
+     *  rebuild or for another version: the playhead and range are kept, unchanged files aren't read again. */
+    load(source: FilmSource): Promise<LoadedFilm>;
     /** Loads the current build again. */
     reload(): Promise<LoadedFilm>;
     seek(frame: number): void;

package/dist/player/player.js

@@ -5,7 +5,7 @@ import { FrameCache } from "./frames.js";
 import { FilmNeeds } from "./needs.js";
 import { Cancelled, WorkerPool } from "./pool.js";
 import { bufferedAhead, clampFrame, startBuffer, wantedFrames } from "./schedule.js";
-import { openSource } from "./source.js";
+import { openFilm } from "./source.js";
 import { Transport } from "./transport.js";
 /** Which workers use a file: audio the soundtrack's, proxy segments the video worker, a video's
  *  facts both (frames lay out with them; the decoder reads its proxy from them), the rest frames. */
@@ -214,7 +214,7 @@ export function createPlayer(options) {
     async function load(source) {
         const mine = ++generation;
         lastSource = source;
-        const opened = await openSource(source, typeof location !== "undefined" ? location.href : "http://localhost/");
+        const opened = await openFilm(source, typeof location !== "undefined" ? location.href : "http://localhost/");
         if (mine !== generation)
             throw new Cancelled();
         const doc = opened.doc;

package/dist/player/source.d.ts

@@ -1,14 +1,25 @@
 import { type BuildDoc, type FilmDoc } from "@tongue-core/project/doc";
 import type { AssetFileInfo, FetchBytes } from "./assets.js";
+/** A build served as files: its folder's URL. */
 export interface BuildSource {
     /** The build's folder (where build.json is), absolute or relative to the page. */
     readonly build: string | URL;
     /** Another manifest in the build, such as one scene on its own. Default build.json. */
     readonly manifest?: string;
 }
+/** A build read a file at a time, from wherever it is kept: a Git commit, memory, an archive. */
+export interface FileSource {
+    /** One file of the build, by its path in the build as build.json and film.json give it:
+     *  `build.json`, `film.json`, `scenes/title.5ebf1e9a05d5.js`, `assets/fonts/inter.ttf`.
+     *  Rejects when the file can't be read. */
+    readonly read: (path: string, signal?: AbortSignal) => Promise<Uint8Array>;
+    /** Another manifest in the build, such as one scene on its own. Default build.json. */
+    readonly manifest?: string;
+}
+/** What a player loads: a build served as files, or one read a file at a time. */
+export type FilmSource = BuildSource | FileSource;
 /** A build, opened: its documents, its text files for the workers, and its asset files. */
-export interface OpenedSource {
-    readonly base: URL;
+export interface OpenedBuild {
     readonly manifest: string;
     readonly build: BuildDoc;
     readonly doc: FilmDoc;
@@ -19,10 +30,18 @@ export interface OpenedSource {
     /** Reads one imported asset file by its path in the assets folder. */
     readonly fetchAsset: FetchBytes;
 }
+/** A build served as files, opened: also the folder it is served from. */
+export interface OpenedSource extends OpenedBuild {
+    readonly base: URL;
+}
 export declare class SourceError extends Error {
     readonly name = "SourceError";
 }
 /** The folder URL of a build, ending in a slash so paths resolve inside it. */
 export declare function buildBase(build: string | URL, page: string): URL;
-/** Opens a build: its manifest and film.json, then every scene bundle at once. */
+/** Opens a build served as files: every path resolved against its folder's URL. */
 export declare function openSource(source: BuildSource, page: string, signal?: AbortSignal): Promise<OpenedSource>;
+/** Opens a build read a file at a time; an asset file is read at its path in the assets folder. */
+export declare function openFiles(source: FileSource, signal?: AbortSignal): Promise<OpenedBuild>;
+/** Opens either kind of source; a served build's folder is resolved against `page`. */
+export declare function openFilm(source: FilmSource, page: string, signal?: AbortSignal): Promise<OpenedBuild>;

package/dist/player/source.js

@@ -13,27 +13,55 @@ export function buildBase(build, page) {
 /** Fetches with revalidation: a server answers 304 for what hasn't changed, so a rebuild is seen at once. */
 async function fetchOk(url, signal) {
     const response = await fetch(url, { cache: "no-cache", signal }).catch((e) => {
-        throw new SourceError(`${url.href} couldn't be fetched: ${e instanceof Error ? e.message : String(e)}`);
+        throw new SourceError(`${url.href} couldn't be fetched: ${message(e)}`);
     });
     if (!response.ok)
         throw new SourceError(`${url.href}: ${response.status} ${response.statusText}`);
     return response;
 }
-const failure = (e) => new SourceError(e instanceof Error ? e.message : String(e));
+const message = (e) => (e instanceof Error ? e.message : String(e));
+const failure = (e) => new SourceError(message(e));
 /** Opens a build: its manifest and film.json, then every scene bundle at once. */
-export async function openSource(source, page, signal) {
-    const base = buildBase(source.build, page);
-    const manifest = source.manifest ?? "build.json";
-    const text = async (path) => (await fetchOk(new URL(path, base), signal)).text();
-    const buildText = await text(manifest);
+async function open(manifest, reader) {
+    const buildText = await reader.text(manifest);
     const build = await Effect.runPromise(parseBuildDoc(buildText)).catch((e) => { throw failure(e); });
-    const filmText = await text(build.film);
+    const filmText = await reader.text(build.film);
     const doc = await Effect.runPromise(parseFilmDoc(filmText)).catch((e) => { throw failure(e); });
-    const bundles = await Promise.all(doc.scenes.map(async (scene) => [scene.bundle, await text(scene.bundle)]));
+    const bundles = await Promise.all(doc.scenes.map(async (scene) => [scene.bundle, await reader.text(scene.bundle)]));
     const files = { [manifest]: buildText, [build.film]: filmText };
     for (const [path, code] of bundles)
         files[path] = code;
-    const assetsBase = buildBase(build.assets.dir, base.href);
-    const fetchAsset = async (path, abort) => new Uint8Array(await (await fetchOk(new URL(path, assetsBase), abort)).arrayBuffer());
-    return { base, manifest, build, doc, files, assets: build.assets.files, fetchAsset };
+    return { manifest, build, doc, files, assets: build.assets.files, fetchAsset: reader.assets(build.assets.dir) };
+}
+/** Opens a build served as files: every path resolved against its folder's URL. */
+export async function openSource(source, page, signal) {
+    const base = buildBase(source.build, page);
+    const opened = await open(source.manifest ?? "build.json", {
+        text: async (path) => (await fetchOk(new URL(path, base), signal)).text(),
+        assets: (dir) => {
+            const assetsBase = buildBase(dir, base.href);
+            return async (path, abort) => new Uint8Array(await (await fetchOk(new URL(path, assetsBase), abort)).arrayBuffer());
+        },
+    });
+    return { ...opened, base };
+}
+/** A file in one of the build's folders: "assets" and "fonts/inter.ttf" → "assets/fonts/inter.ttf". */
+function inFolder(dir, path) {
+    const folder = dir.replace(/\/+$/, "");
+    return folder === "" || folder === "." ? path : `${folder}/${path}`;
+}
+/** Opens a build read a file at a time; an asset file is read at its path in the assets folder. */
+export async function openFiles(source, signal) {
+    const bytes = (path, abort) => source.read(path, abort).catch((e) => {
+        throw new SourceError(`${path} couldn't be read: ${message(e)}`);
+    });
+    const utf8 = new TextDecoder();
+    return open(source.manifest ?? "build.json", {
+        text: async (path) => utf8.decode(await bytes(path, signal)),
+        assets: (dir) => (path, abort) => bytes(inFolder(dir, path), abort),
+    });
+}
+/** Opens either kind of source; a served build's folder is resolved against `page`. */
+export function openFilm(source, page, signal) {
+    return "read" in source ? openFiles(source, signal) : openSource(source, page, signal);
 }

package/dist/timeline/index.d.ts

@@ -6,4 +6,5 @@ export { ruler, stepFor, minorFor, rulerLabel, timecode, LABEL_SPACING, MINOR_SP
 export { reduceSelection, emptySelection, type Selection, type SelectionAction } from "./selection.js";
 export { rowItems, rowTransitions, clipInRun, octaveOf, sameRowItems, MIN_CLIP_PX, type RowItem } from "./items.js";
 export { filmstrip, PreviewCache, type PreviewSource, type StripFrame } from "./previews.js";
+export { narration, wordAt, wordsIn, lastStartedBy, type NarrationWord } from "./narration.js";
 export { BUDGETS, type Budgets } from "../budgets.js";

package/dist/timeline/index.js

@@ -10,4 +10,5 @@ export { ruler, stepFor, minorFor, rulerLabel, timecode, LABEL_SPACING, MINOR_SP
 export { reduceSelection, emptySelection } from "./selection.js";
 export { rowItems, rowTransitions, clipInRun, octaveOf, sameRowItems, MIN_CLIP_PX } from "./items.js";
 export { filmstrip, PreviewCache } from "./previews.js";
+export { narration, wordAt, wordsIn, lastStartedBy } from "./narration.js";
 export { BUDGETS } from "../budgets.js";

package/dist/timeline/narration.d.ts

@@ -0,0 +1,18 @@
+import type { FilmDoc } from "@tongue-core/project/doc";
+export interface NarrationWord {
+    readonly text: string;
+    /** Film frames [start, end). */
+    readonly start: number;
+    readonly end: number;
+    /** The clip it is said in, and its row. */
+    readonly clip: string;
+    readonly row: string;
+}
+/** Every word of the film's narration on the film's clock, by start. Empty for a film with none. */
+export declare function narration(doc: FilmDoc): ReadonlyArray<NarrationWord>;
+/** The index of the last word that has started by `frame`; -1 before the first. */
+export declare function lastStartedBy(words: ReadonlyArray<NarrationWord>, frame: number): number;
+/** The word being said at `frame` (its start reached, its end not), or null between words. */
+export declare function wordAt(words: ReadonlyArray<NarrationWord>, frame: number): NarrationWord | null;
+/** The words said in `[from, to)`, in order. */
+export declare const wordsIn: (words: ReadonlyArray<NarrationWord>, from: number, to: number) => ReadonlyArray<NarrationWord>;

package/dist/timeline/narration.js

@@ -0,0 +1,42 @@
+/** Every word of the film's narration on the film's clock, by start. Empty for a film with none. */
+export function narration(doc) {
+    const out = [];
+    for (const track of doc.tracks) {
+        for (const clip of track.clips) {
+            if (clip.kind !== "audio" || clip.voice === undefined)
+                continue;
+            for (const word of clip.voice.words) {
+                const start = clip.start + word.start / clip.speed;
+                const end = clip.start + word.end / clip.speed;
+                if (start >= clip.end)
+                    continue;
+                out.push({ text: word.text, start, end: Math.min(end, clip.end), clip: clip.id, row: track.id });
+            }
+        }
+    }
+    return out.sort((a, b) => a.start - b.start || a.end - b.end);
+}
+/** The index of the last word that has started by `frame`; -1 before the first. */
+export function lastStartedBy(words, frame) {
+    let low = 0;
+    let high = words.length - 1;
+    let found = -1;
+    while (low <= high) {
+        const mid = (low + high) >>> 1;
+        if ((words[mid]?.start ?? Number.POSITIVE_INFINITY) <= frame) {
+            found = mid;
+            low = mid + 1;
+        }
+        else
+            high = mid - 1;
+    }
+    return found;
+}
+/** The word being said at `frame` (its start reached, its end not), or null between words. */
+export function wordAt(words, frame) {
+    const index = lastStartedBy(words, frame);
+    const word = words[index];
+    return word !== undefined && frame < word.end ? word : null;
+}
+/** The words said in `[from, to)`, in order. */
+export const wordsIn = (words, from, to) => words.filter((word) => word.end > from && word.start < to);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tongue-core/ui",
-  "version": "0.1.0-rc.3",
+  "version": "0.1.0-rc.5",
   "description": "The pieces of a film's interface: the player, the timeline's state and geometry, and unstyled React primitives. Build your own studio from them.",
   "type": "module",
   "license": "MIT",
@@ -36,9 +36,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@tongue-core/engine": "0.1.0-rc.3",
-    "@tongue-core/film": "0.1.0-rc.3",
-    "@tongue-core/project": "0.1.0-rc.3"
+    "@tongue-core/engine": "0.1.0-rc.5",
+    "@tongue-core/film": "0.1.0-rc.5",
+    "@tongue-core/project": "0.1.0-rc.5"
   },
   "peerDependencies": {
     "@effect/atom-react": "^4.0.6",