@tongue-core/ui 0.1.0-rc.2 → 0.1.0-rc.4

package/README.md

@@ -38,9 +38,21 @@ 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.

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. */
@@ -31,6 +31,10 @@ const SETTLE_MS = 90;
 export function createPlayer(options) {
     const canvas = options.canvas;
     const ctx = canvas.getContext("2d");
+    // The picture keeps the film's shape in whatever box the page gives the canvas: letterboxed,
+    // never stretched. A page that sets its own object-fit keeps it.
+    if (canvas.style.objectFit === "")
+        canvas.style.objectFit = "contain";
     if (!ctx)
         throw new Error("The player needs a canvas with a 2D context.");
     const pool = new WorkerPool({ workerUrl: options.workerUrl, workers: options.workers ?? defaultWorkers() });
@@ -210,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/react/timeline.d.ts

@@ -46,6 +46,7 @@ export declare const Clip: import("react").NamedExoticComponent<Styled & {
 /** A transition: the stretch where two clips overlap. */
 export declare const Transition: import("react").NamedExoticComponent<Styled & {
     readonly transition: TimelineTransition;
+    readonly title?: string;
     readonly children?: ReactNode;
 }>;
 /** The playhead. It moves without React: its frame is a CSS variable on itself, set as reports
@@ -88,6 +89,7 @@ export declare const Timeline: {
     }>;
     Transition: import("react").NamedExoticComponent<Styled & {
         readonly transition: TimelineTransition;
+        readonly title?: string;
         readonly children?: ReactNode;
     }>;
     Playhead: typeof Playhead;

package/dist/react/timeline.js

@@ -169,7 +169,7 @@ export const Clip = memo(function Clip(props) {
 /** A transition: the stretch where two clips overlap. */
 export const Transition = memo(function Transition(props) {
     const t = props.transition;
-    return (_jsx("div", { "data-tl-transition": "", "data-style": t.style, className: props.className, style: { position: "absolute", top: 0, bottom: 0, left: px("--t-start"), width: px("--t-frames"), contain: "strict", "--t-start": t.start, "--t-frames": t.end - t.start, pointerEvents: "none", ...props.style }, children: props.children }));
+    return (_jsx("div", { "data-tl-transition": "", "data-style": t.style, title: props.title, className: props.className, style: { position: "absolute", top: 0, bottom: 0, left: px("--t-start"), width: px("--t-frames"), contain: "strict", "--t-start": t.start, "--t-frames": t.end - t.start, pointerEvents: "none", ...props.style }, children: props.children }));
 });
 /** The playhead. It moves without React: its frame is a CSS variable on itself, set as reports
  *  come in. When it moves out of view (playing on, a jump) the view follows it (`follow`, on by

package/dist/timeline/model.d.ts

@@ -15,6 +15,8 @@ export interface TimelineClip {
 export interface TimelineTransition {
     readonly row: string;
     readonly style: TransitionDoc["style"];
+    /** Everything film.json says about it: a dissolve's noise and edge, a wipe's direction. */
+    readonly doc: TransitionDoc;
     readonly from: string;
     readonly to: string;
     /** Film frames [start, end). */

package/dist/timeline/model.js

@@ -31,7 +31,7 @@ export function timelineModel(doc) {
         const transitions = track.transitions.map((t) => {
             edges.add(t.start);
             edges.add(t.end);
-            return { row: track.id, style: t.style, from: t.from, to: t.to, start: t.start, end: t.end };
+            return { row: track.id, style: t.style, doc: t, from: t.from, to: t.to, start: t.start, end: t.end };
         });
         return { id: track.id, kind: track.kind, clips: rowClips, transitions };
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tongue-core/ui",
-  "version": "0.1.0-rc.2",
+  "version": "0.1.0-rc.4",
   "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.2",
-    "@tongue-core/film": "0.1.0-rc.2",
-    "@tongue-core/project": "0.1.0-rc.2"
+    "@tongue-core/engine": "0.1.0-rc.4",
+    "@tongue-core/film": "0.1.0-rc.4",
+    "@tongue-core/project": "0.1.0-rc.4"
   },
   "peerDependencies": {
     "@effect/atom-react": "^4.0.6",