@tongue-core/sdk 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,156 @@
-# Temporary Holding Version
+# @tongue-core/sdk
 
-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.
+Everything you do with a Tongue film, as a library: import its assets, plan and check it, draw
+frames, render video, open it in the studio, and list what the machine can render with. The
+`tongue` CLI is a thin shell over this package, so anything the CLI does an application can do
+here, with the same results. Built with Effect v4 (orchestration only: the per-frame path is plain
+TypeScript); a Promise facade is included for applications that don't use Effect.
+
+```bash
+bun add @tongue-core/sdk@next      # Bun ≥ 1.3; ffmpeg and ffprobe on the PATH
+```
+
+## Promise API
+
+```ts
+import { createTongue } from "@tongue-core/sdk";
+
+const tongue = createTongue();
+await tongue.init("my-film", { template: "social-post" });            // a film project from a template
+const { build } = await tongue.build("my-film");                       // my-film/dist: film.json, build.json, bundles
+await tongue.stills("my-film", { frames: [0, 30], outDir: "out/hook", scene: { id: "hook" } });   // one scene alone
+const { text, summary } = await tongue.info("src/film.tsx");          // the timeline, as text and JSON
+const report = await tongue.check("src/film.tsx");                    // { ok, problems, warnings }: never rejects for a broken film
+await tongue.sheet("src/film.tsx", { frames: [0, 90, 300], outDir: "out/look" });
+const video = await tongue.render("src/film.tsx", { out: "out/film.mp4", from: 90, to: 300, scale: 0.5 });
+const machine = await tongue.backends();                               // rasters and encoders that work here
+```
+
+Failures reject with the SDK's tagged errors (below).
+
+## Effect API
+
+```ts
+import { BunServices } from "@effect/platform-bun";
+import { openFilm, renderVideo } from "@tongue-core/sdk";
+import { Effect } from "effect";
+
+const program = Effect.gen(function* () {
+  const film = yield* openFilm("src/film.tsx");          // load, import assets, plan
+  return yield* renderVideo(film, { out: "out/film.mp4", encoder: "auto", raster: "auto" });
+});
+await Effect.runPromise(program.pipe(Effect.provide(BunServices.layer)));
+```
+
+| Function | Does |
+|---|---|
+| `initProject(dir, { template, name })` | a film project in a new or empty folder, from a built-in template or a template folder |
+| `listTemplates()` / `readTemplate(nameOrPath)` | the built-in templates, or one by name or path |
+| `buildFilm(project, { out })` | builds a film project into `out` (default `dist/`): build.json, film.json, a bundle per scene |
+| `openFilm(path, { scene })` | a film ready to render: a project is built (into `.tongue/builds/<id>`, named by its content) and planned from film.json, a film module is imported and planned; assets imported (cached by size, mtime and options) either way. `scene: { id, props }` opens one scene of a project on its own |
+| `describeFilm(film)` | the plan as text (for agents to read) and as a JSON summary |
+| `checkFilm(path)` | problems and warnings as data |
+| `renderStills(film, { frames, scale, outDir })` / `renderSheet(…)` | PNGs drawn by the wasm raster (the player's), or tiled into one labelled sheet |
+| `renderVideo(film, options)` | an MP4 with sound: the whole film or `[from, to)`, at any scale; `onStart` once the request is checked and the raster and encoder are chosen, `onProgress` while it draws. A frame that throws fails the render with `Frame <n>: <message>` |
+| `listBackends()` | every raster and encoder, each tried for real |
+| `studioServer(path, { port, remote })` | the studio on a project (rebuilt and reloaded on every edit) or on a build served anywhere |
+
+## Films and projects
+
+A **film project** is a folder with a `tongue.json` ([docs/film-json.md](../../docs/film-json.md)):
+`film.tsx`, `scenes/`, `kit/`, `lib/`, `assets.ts`, `assets/`. It needs nothing installed: the SDK
+reads its files, compiles and bundles it with `@tongue-core/project`, loads the bundles with its own
+`@tongue-core/film`, imports the assets they declare (ffprobe gives media lengths), extracts film.json
+and writes the build. Everything renders from the build: in this process, in the render workers
+(they open build.json and the bundles), and in the studio (`tongue studio` serves the build; the
+browser fetches it). `.tongue/types/film` links to the SDK's `@tongue-core/film`, which the
+project's `tsconfig.json` points editors at.
+
+A **film module** (the way films were written before projects) is a `film.tsx` in a folder with a
+`package.json`. The SDK bundles it with Bun (into `.tongue/modules/`, JSX compiled for Tongue) against
+its own `@tongue-core/film`, the copy the engine reads, as it links a project's bundles, then plans
+it. The folder may install `@tongue-core/film` too, for its editor's types
+(`"jsx": "react-jsx", "jsxImportSource": "@tongue-core/film"` in its tsconfig); that copy isn't the one
+that runs.
+
+Either way, asset paths are relative to the root, Tongue writes `.tongue/` there (imported assets,
+builds, render work) and renders to `out/`.
+
+A film's assets are what its modules declare (`font()`, `image()`, `audio()`, `video()`) while
+the SDK loads it, plus the media its clips play; `<Film assets={[…]}>` replaces the declared ones.
+Importing turns them into what the engine reads: TrueType fonts, QOI images, WAV audio, video facts
+and a poster frame.
+
+## How a video renders
+
+```
+coordinator ──segments──▶ worker 1: frames ─▶ raster ─▶ encoder ─▶ seg-0000.mp4
+            ◀─progress──  worker 2 …                              seg-0001.mp4
+            soundtrack:   sounds + audio clips ─▶ mix ─▶ AAC        audio.m4a
+            join:         concat + audio ─(stream copy)─▶ film.mp4, frame count probed
+```
+
+- **Workers** are processes (`src/render/worker.ts`), one per physical core by default. Each loads
+  the film and its raster once and renders every segment it is sent into that segment's own
+  encoder, so the JIT stays warm and glyphs and images stay uploaded.
+- **Segments** are one to two seconds of frames, shrinking towards the end so the last ones finish
+  together. Each is a closed-GOP encode; the join copies streams without re-encoding.
+- **Video clips** are decoded by ffmpeg in order, frame after frame, and restarted on jumps.
+- **The soundtrack** is mixed in its own process while the workers draw (`soundtrack-process.ts`).
+
+Rasters (who draws) and encoders (who encodes) are chosen by name, because the choice is made here
+but runs inside the workers:
+
+| Raster | |
+|---|---|
+| `native` | the Rust raster built for x86-64-v3 (`@tongue-core/raster-linux-x64`); byte-identical to wasm, 2–3× faster |
+| `wasm` | the engine's embedded WebAssembly raster, the browser player's; runs anywhere |
+| `gpu` | EGL + GLES 3.1; within a few levels of the CPU rasters, never chosen by `auto` |
+
+Encoders: `x264` (veryfast, crf 14), `vaapi-hevc` / `vaapi-h264` (constant QP 18 / 16, with
+CPU-conversion variants), and `nvenc-*` / `qsv-*` (written from vendor documentation, untested).
+`auto` takes the first that works of nvenc-hevc, vaapi-hevc, vaapi-hevc-cpuconv, qsv-hevc, x264.
+
+On this machine (16 threads, AMD GPU) the 35.5 s demo renders at 1080p with sound in about 12 s
+(≈ 87 fps) with `native` + `vaapi-hevc`.
+
+## Errors
+
+Every failure is a `Schema.TaggedError` with a message that says what to change. `exitCodeOf`
+gives the CLI's exit code.
+
+| Error | When | Exit |
+|---|---|---|
+| `FilmFailure` | the module is missing, throws, isn't a `<Film>`, or its timeline doesn't plan | 2 |
+| `AssetFailure` | an asset's file is missing or unreadable | 2 |
+| `InvalidRequest` | a frame outside the film, a bad range or scale | 2 |
+| `ToolFailure` | ffmpeg or ffprobe is missing or failed | 3 |
+| `BackendUnavailable` | the raster or encoder asked for doesn't work here | 3 |
+| `RenderFailure` | a worker died or a frame failed | 3 |
+| `LayoutError`, `CompileError`, `LoadError`, `TimelineError`, `DocError`, `TemplateError` | a film project doesn't build (from `@tongue-core/project`: each names its file, line or path) | 2 |
+
+## Environment
+
+| Variable | |
+|---|---|
+| `TONGUE_FFMPEG`, `TONGUE_FFPROBE` | the tools' paths (default: `ffmpeg`, `ffprobe` on the PATH) |
+| `TONGUE_NATIVE_RASTER`, `TONGUE_GPU_RASTER` | a raster library to use instead of `@tongue-core/raster-linux-x64`'s |
+| `TONGUE_VAAPI_DEVICE` | the render node for VAAPI and Quick Sync (default `/dev/dri/renderD128`) |
+
+## Layout
+
+```
+src/
+  index.ts, client.ts     the Effect API and the Promise facade
+  project.ts              projects, openFilm and buildFilm
+  build/build.ts          building a film project on this machine: its files, a module host, the build folder, editor types
+  init.ts                 init from templates
+  check.ts, backends.ts   checkFilm, listBackends
+  import/                 asset import: fonts, images, audio, video (ffprobe, posters)
+  render/                 stills, the video pipeline, its worker and soundtrack processes, video decoding
+  encode/encoders.ts      the ffmpeg encoders and how each is tried
+  raster/                 the native and GPU raster bindings (index.ts) and the registry (rasters.ts)
+  studio/server.ts        the studio's server: the app bundled, a project's build served and rebuilt
+test/                     unit tests, end-to-end ones on fixtures/tiny (a film with text, video and sound), and
+                          projects from every template (project.test.ts: film.json draws the same frames as film.tsx)
+```

package/dist/backends.d.ts

@@ -0,0 +1,24 @@
+import { Effect } from "effect";
+import { type EncoderName } from "./encode/encoders.js";
+import { type RasterName } from "./raster/rasters.js";
+export interface BackendsReport {
+    readonly rasters: ReadonlyArray<{
+        readonly name: RasterName;
+        readonly available: boolean;
+        readonly exact: boolean;
+        readonly summary: string;
+    }>;
+    readonly encoders: ReadonlyArray<{
+        readonly name: EncoderName;
+        readonly available: boolean;
+        readonly hardware: boolean;
+        readonly tested: boolean;
+        readonly summary: string;
+    }>;
+    /** What `auto` picks here. */
+    readonly auto: {
+        readonly raster: RasterName;
+        readonly encoder: EncoderName | null;
+    };
+}
+export declare const listBackends: () => Effect.Effect<BackendsReport, import("effect/Config").ConfigError, never>;

package/dist/backends.js

@@ -0,0 +1,17 @@
+import { Effect } from "effect";
+import { AUTO_ENCODERS, DEFAULT_SETTINGS, ENCODER_NAMES, ENCODER_SUMMARIES, encoderSpec, encoderWorks } from "./encode/encoders.js";
+import { autoRaster, RASTERS } from "./raster/rasters.js";
+import { ffmpegPath } from "./tools.js";
+export const listBackends = Effect.fn("listBackends")(function* () {
+    const ffmpeg = yield* ffmpegPath;
+    const encoders = yield* Effect.forEach(ENCODER_NAMES, (name) => Effect.promise(async () => {
+        const spec = encoderSpec(name, DEFAULT_SETTINGS, 30);
+        return { name, available: await encoderWorks(ffmpeg, spec), hardware: spec.hardware, tested: spec.tested, summary: ENCODER_SUMMARIES[name] };
+    }), { concurrency: "unbounded" });
+    const report = {
+        rasters: RASTERS.map((r) => ({ name: r.name, available: r.available(), exact: r.exact, summary: r.summary })),
+        encoders,
+        auto: { raster: autoRaster().name, encoder: AUTO_ENCODERS.find((n) => encoders.some((e) => e.name === n && e.available)) ?? null },
+    };
+    return report;
+});

package/dist/build/build.d.ts

@@ -0,0 +1,48 @@
+import type { Asset, MediaInfo, SceneDefinition } from "@tongue-core/film";
+import { type Build, type ModuleHost, type ProjectFiles } from "@tongue-core/project";
+import { Effect, FileSystem, type PlatformError } from "effect";
+import { type ImportReport } from "../import/importer.js";
+import type { Project } from "../project.js";
+/** A project's code and data: every .ts, .tsx and .json file outside hidden folders and the ones
+ *  tools write. */
+export declare const readProjectFiles: (root: string) => Effect.Effect<ProjectFiles, PlatformError.PlatformError, FileSystem.FileSystem>;
+/** Loads bundles by writing each to `dir` (named by its hash, so written once) and importing it. */
+export declare const fileModuleHost: (dir: string) => ModuleHost;
+/** Points the project's `.tongue/types/film` at this SDK's @tongue-core/film (tsconfig.json reads it). */
+export declare const linkFilmTypes: (root: string) => Effect.Effect<void, PlatformError.PlatformError, FileSystem.FileSystem>;
+export interface BuiltProject {
+    readonly build: Build;
+    /** Where the build was written. */
+    readonly dir: string;
+    readonly imported: ImportReport;
+    /** The scenes the bundles export, by id: what film.json is assembled with. */
+    readonly scenes: ReadonlyMap<string, SceneDefinition>;
+    readonly media: MediaInfo;
+}
+/** The imported files a film's assets are (a video is its facts, its poster and its proxy's
+ *  segments), with their sizes and hashes: what build.json lists. */
+export declare const importedFiles: (project: Project, assets: readonly Asset[]) => Effect.Effect<{
+    readonly path: string;
+    readonly bytes: number;
+    readonly hash: string;
+}[], PlatformError.PlatformError, FileSystem.FileSystem>;
+/** How a written build reaches its assets: copies of the files (a build to publish), or a link to
+ *  the project's imported assets (a build for Tongue's own use). */
+export type AssetPlacement = {
+    readonly kind: "copy";
+    readonly from: string;
+} | {
+    readonly kind: "link";
+    readonly to: string;
+};
+/** Writes a build to `dir`, replacing the build that was there (old bundles and assets included). */
+export declare const writeBuildFiles: (dir: string, build: Build, assets: AssetPlacement) => Effect.Effect<void, PlatformError.PlatformError, FileSystem.FileSystem>;
+/** Keeps a build in `.tongue/builds/<id>`, named by its content and never rewritten, so renders
+ *  reading one build are never disturbed by the next. Written to a temporary folder first and moved
+ *  into place, so a build folder is either whole or not there. */
+export declare const keepBuild: (project: Project, build: Build) => Effect.Effect<string, PlatformError.PlatformError, FileSystem.FileSystem>;
+/** Builds a film project into `dir` (what `tongue build` does: dist/ by default), replacing what
+ *  was there, with copies of its imported assets: a folder any static host can serve. */
+export declare const buildFilmProject: (project: Project, dir: string) => Effect.Effect<BuiltProject, import("../errors.js").AssetFailure | import("../errors.js").ToolFailure | import("@tongue-core/project").LayoutError | import("@tongue-core/project").CompileError | import("@tongue-core/project").LoadError | import("@tongue-core/project").TimelineError | import("@tongue-core/project").DocError | import("effect/Config").ConfigError | PlatformError.PlatformError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | FileSystem.FileSystem | import("effect/Path").Path>;
+/** Builds a film project for Tongue's own use (stills, renders, dev): kept in .tongue/builds. */
+export declare const buildForWork: (project: Project) => Effect.Effect<BuiltProject, import("../errors.js").AssetFailure | import("../errors.js").ToolFailure | import("@tongue-core/project").LayoutError | import("@tongue-core/project").CompileError | import("@tongue-core/project").LoadError | import("@tongue-core/project").TimelineError | import("@tongue-core/project").DocError | import("effect/Config").ConfigError | PlatformError.PlatformError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | FileSystem.FileSystem | import("effect/Path").Path>;

package/dist/build/build.js

@@ -0,0 +1,162 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { createHash } from "node:crypto";
+import { dirname, join, relative, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { importedFiles as filesOf, videoProxyDir } from "@tongue-core/engine";
+import { compileProject, extractFilm, IGNORED_DIRS, loadProject, sha256, TYPES_LINK, writeBuild, } from "@tongue-core/project";
+import { Effect, FileSystem } from "effect";
+import { importAssets } from "../import/importer.js";
+import { sdkVersion } from "../version.js";
+// Building a film project on this machine: read its code, compile and bundle it, run the bundles,
+// import the assets they declare (media lengths go into film.json), extract film.json and write
+// the build, with the imported asset files listed in build.json (and copied beside it, or linked,
+// so a build folder is everything a player needs). Everything but the files and the module
+// loading is @tongue-core/project's.
+/** A project's code and data: every .ts, .tsx and .json file outside hidden folders and the ones
+ *  tools write. */
+export const readProjectFiles = Effect.fn("readProjectFiles")(function* (root) {
+    const fs = yield* FileSystem.FileSystem;
+    const files = new Map();
+    const walk = (dir) => Effect.gen(function* () {
+        for (const name of (yield* fs.readDirectory(dir)).sort()) {
+            const path = join(dir, name);
+            const info = yield* fs.stat(path);
+            if (info.type === "Directory") {
+                // What tools write, and anything hidden (.git, .vscode): never the film's.
+                if (!IGNORED_DIRS.has(name) && !name.startsWith("."))
+                    yield* walk(path);
+            }
+            else if (/\.(ts|tsx|json)$/.test(name)) {
+                files.set(relative(root, path).split(sep).join("/"), yield* fs.readFileString(path));
+            }
+        }
+    });
+    yield* walk(root);
+    const out = files;
+    return out;
+});
+/** Loads bundles by writing each to `dir` (named by its hash, so written once) and importing it. */
+export const fileModuleHost = (dir) => ({
+    load: async (bundle) => {
+        const file = join(dir, bundle.path);
+        if (!(await Bun.file(file).exists()))
+            await Bun.write(file, bundle.code);
+        const module = await import(__rewriteRelativeImportExtension(pathToFileURL(file).href));
+        return module;
+    },
+});
+/** The folder of the @tongue-core/film this SDK uses: what a project's editor types come from. */
+const filmPackage = dirname(dirname(fileURLToPath(import.meta.resolve("@tongue-core/film"))));
+/** Points the project's `.tongue/types/film` at this SDK's @tongue-core/film (tsconfig.json reads it). */
+export const linkFilmTypes = Effect.fn("linkFilmTypes")(function* (root) {
+    const fs = yield* FileSystem.FileSystem;
+    const link = join(root, TYPES_LINK);
+    const current = yield* fs.readLink(link).pipe(Effect.orElseSucceed(() => null));
+    if (current === filmPackage)
+        return;
+    yield* fs.remove(link, { force: true });
+    yield* fs.makeDirectory(dirname(link), { recursive: true });
+    yield* fs.symlink(filmPackage, link);
+});
+/** The imported files a film's assets are (a video is its facts, its poster and its proxy's
+ *  segments), with their sizes and hashes: what build.json lists. */
+export const importedFiles = Effect.fn("importedFiles")(function* (project, assets) {
+    const fs = yield* FileSystem.FileSystem;
+    const proxies = yield* Effect.forEach(assets.filter((a) => a.kind === "video"), (a) => {
+        const dir = videoProxyDir(a);
+        return fs.readDirectory(join(project.assetsDir, dir)).pipe(Effect.map((names) => names.filter((n) => n.endsWith(".mp4")).sort().map((n) => `${dir}${n}`)), Effect.orElseSucceed(() => []));
+    });
+    const paths = [...new Set([...assets.flatMap(filesOf), ...proxies.flat()])];
+    return yield* Effect.forEach(paths, (path) => Effect.map(fs.readFile(join(project.assetsDir, path)), (bytes) => ({
+        path,
+        bytes: bytes.length,
+        hash: createHash("sha256").update(bytes).digest("hex"),
+    })), { concurrency: 8 });
+});
+/** Writes a build to `dir`, replacing the build that was there (old bundles and assets included). */
+export const writeBuildFiles = Effect.fn("writeBuildFiles")(function* (dir, build, assets) {
+    const fs = yield* FileSystem.FileSystem;
+    yield* fs.makeDirectory(dir, { recursive: true });
+    for (const name of yield* fs.readDirectory(dir)) {
+        if (name === "scenes" || name === build.manifest.assets.dir || name.endsWith(".json"))
+            yield* fs.remove(join(dir, name), { recursive: true });
+    }
+    for (const file of build.files) {
+        const path = join(dir, file.path);
+        yield* fs.makeDirectory(dirname(path), { recursive: true });
+        yield* fs.writeFileString(path, file.text);
+    }
+    const assetsDir = join(dir, build.manifest.assets.dir);
+    if (assets.kind === "link") {
+        yield* fs.symlink(assets.to, assetsDir);
+        return;
+    }
+    for (const file of build.manifest.assets.files) {
+        const path = join(assetsDir, file.path);
+        yield* fs.makeDirectory(dirname(path), { recursive: true });
+        yield* fs.copyFile(join(assets.from, file.path), path);
+    }
+});
+/** Builds kept in .tongue/builds: the newest this many, older ones removed. */
+const KEPT_BUILDS = 8;
+/** Keeps a build in `.tongue/builds/<id>`, named by its content and never rewritten, so renders
+ *  reading one build are never disturbed by the next. Written to a temporary folder first and moved
+ *  into place, so a build folder is either whole or not there. */
+export const keepBuild = Effect.fn("keepBuild")(function* (project, build) {
+    const fs = yield* FileSystem.FileSystem;
+    const builds = join(project.workDir, "builds");
+    const id = (yield* Effect.promise(() => sha256(build.files.map((f) => `${f.path}\0${f.text}`).join("\0")))).slice(0, 16);
+    const dir = join(builds, id);
+    if (yield* fs.exists(join(dir, "build.json")))
+        return dir;
+    yield* fs.makeDirectory(builds, { recursive: true });
+    const temp = yield* fs.makeTempDirectory({ directory: builds, prefix: ".writing-" });
+    yield* writeBuildFiles(temp, build, { kind: "link", to: project.assetsDir });
+    // Another process may have kept the same build meanwhile: its copy is the same bytes.
+    yield* fs.rename(temp, dir).pipe(Effect.catch(() => fs.remove(temp, { recursive: true })));
+    yield* pruneBuilds(builds, dir);
+    return dir;
+});
+/** Removes all but the newest builds (never `keep`); a build in use elsewhere is old enough to go
+ *  only after KEPT_BUILDS newer ones. */
+const pruneBuilds = Effect.fn("pruneBuilds")(function* (builds, keep) {
+    const fs = yield* FileSystem.FileSystem;
+    const dated = yield* Effect.forEach(yield* fs.readDirectory(builds), (name) => fs.stat(join(builds, name)).pipe(Effect.map((info) => ({ dir: join(builds, name), at: info.mtime._tag === "Some" ? info.mtime.value.getTime() : 0, temp: name.startsWith(".") }))));
+    const old = dated.filter((b) => !b.temp && b.dir !== keep).sort((a, b) => b.at - a.at).slice(KEPT_BUILDS - 1);
+    for (const b of old)
+        yield* fs.remove(b.dir, { recursive: true, force: true });
+});
+/** A film project built in memory: compiled, its bundles run, its assets imported (their lengths
+ *  go into film.json), film.json extracted. */
+const buildInMemory = Effect.fn("buildInMemory")(function* (project) {
+    const files = yield* readProjectFiles(project.root);
+    const compiled = yield* compileProject(files);
+    const loaded = yield* loadProject(compiled, fileModuleHost(join(project.workDir, "modules")));
+    const imported = yield* importAssets(project, loaded.assets);
+    const media = { duration: (asset) => imported.durations.get(`${asset.kind}:${asset.name}`) ?? null };
+    const doc = yield* extractFilm(loaded, { media });
+    const build = writeBuild(compiled, doc, { tongue: yield* sdkVersion, assets: yield* importedFiles(project, loaded.assets) });
+    yield* linkFilmTypes(project.root);
+    return { build, imported, scenes: new Map(loaded.scenes.map((s) => [s.id, s.scene])), media };
+});
+/** Builds a film project into `dir` (what `tongue build` does: dist/ by default), replacing what
+ *  was there, with copies of its imported assets: a folder any static host can serve. */
+export const buildFilmProject = Effect.fn("buildFilmProject")(function* (project, dir) {
+    const built = yield* buildInMemory(project);
+    yield* writeBuildFiles(dir, built.build, { kind: "copy", from: project.assetsDir });
+    const out = { ...built, dir };
+    return out;
+});
+/** Builds a film project for Tongue's own use (stills, renders, dev): kept in .tongue/builds. */
+export const buildForWork = Effect.fn("buildForWork")(function* (project) {
+    const built = yield* buildInMemory(project);
+    const out = { ...built, dir: yield* keepBuild(project, built.build) };
+    return out;
+});

package/dist/check.d.ts

@@ -0,0 +1,18 @@
+import type { PlanSummary } from "@tongue-core/film";
+import { Effect } from "effect";
+export interface CheckProblem {
+    /** layout, compile, load, timeline, doc (film.json), asset. */
+    readonly kind: string;
+    readonly file: string | null;
+    readonly message: string;
+}
+export interface CheckReport {
+    readonly ok: boolean;
+    /** What stops the film from rendering, with what to change. */
+    readonly problems: ReadonlyArray<CheckProblem>;
+    /** What will render, but probably not as intended. */
+    readonly warnings: ReadonlyArray<string>;
+    readonly summary: PlanSummary | null;
+    readonly text: string | null;
+}
+export declare const checkFilm: (path: string) => Effect.Effect<CheckReport, import("./errors.js").InvalidRequest | import("./errors.js").ToolFailure | import("effect/Config").ConfigError | import("effect/PlatformError").PlatformError, import("effect/process/ChildProcessSpawner").ChildProcessSpawner | import("effect/FileSystem").FileSystem | import("effect/Path").Path>;

package/dist/check.js

@@ -0,0 +1,17 @@
+import { Effect } from "effect";
+import { describeFilm, openFilm } from "./project.js";
+const failed = (problems) => ({ ok: false, problems, warnings: [], summary: null, text: null });
+export const checkFilm = Effect.fn("checkFilm")(function* (path) {
+    return yield* openFilm(path).pipe(Effect.map((film) => {
+        const { text, summary } = describeFilm(film);
+        return { ok: true, problems: [], warnings: film.plan.warnings, summary, text };
+    }), Effect.catchTags({
+        FilmFailure: (e) => Effect.succeed(failed([{ kind: e.phase === "load" ? "load" : "timeline", file: e.film, message: e.message }])),
+        AssetFailure: (e) => Effect.succeed(failed([{ kind: "asset", file: null, message: e.message }])),
+        LayoutError: (e) => Effect.succeed(failed(e.problems.map((p) => ({ kind: "layout", file: p.file, message: p.message })))),
+        CompileError: (e) => Effect.succeed(failed([{ kind: "compile", file: e.line === null ? e.file : `${e.file}:${e.line}`, message: e.message }])),
+        LoadError: (e) => Effect.succeed(failed([{ kind: "load", file: e.file, message: e.message }])),
+        TimelineError: (e) => Effect.succeed(failed([{ kind: "timeline", file: null, message: e.message }])),
+        DocError: (e) => Effect.succeed(failed([{ kind: "doc", file: "film.json", message: e.message }])),
+    }));
+});

package/dist/client.d.ts

@@ -0,0 +1,43 @@
+import { type InitOptions } from "./init.js";
+import { type OpenOptions } from "./project.js";
+import { type VideoOptions } from "./render/pipeline.js";
+import { type StillsOptions } from "./render/stills.js";
+export declare function createTongue(): {
+    /** Makes a film project in a new or empty folder from a template. */
+    init: (dir: string, options?: InitOptions) => Promise<import("./init.js").InitReport>;
+    /** The templates that come with Tongue. */
+    templates: () => Promise<readonly {
+        readonly width: number;
+        readonly height: number;
+        readonly name: string;
+        readonly fps: number;
+        readonly title: string;
+        readonly description: string;
+        readonly tags?: readonly string[] | undefined;
+    }[]>;
+    /** Builds a film project: build.json, film.json and a bundle per scene, in its dist folder. */
+    build: (project: string, options?: {
+        readonly out?: string;
+    }) => Promise<import("./index.js").BuiltProject>;
+    /** Imports the film's assets and plans it; resolves to its timeline as text and JSON. */
+    info: (film: string) => Promise<{
+        readonly text: string;
+        readonly summary: import("@tongue-core/film").PlanSummary;
+    }>;
+    /** Problems and warnings as data: never rejects for a broken film. */
+    check: (film: string) => Promise<import("./check.js").CheckReport>;
+    /** Frames as PNG files. */
+    stills: (film: string, options: StillsOptions & OpenOptions) => Promise<import("./index.js").Still[]>;
+    /** Frames tiled into one labelled image. */
+    sheet: (film: string, options: StillsOptions & OpenOptions & {
+        readonly columns?: number;
+    }) => Promise<{
+        stills: import("./index.js").Still[];
+        sheet: string;
+    }>;
+    /** The film (or a range of it, or one scene of a project) as an MP4. */
+    render: (film: string, options: VideoOptions & OpenOptions) => Promise<import("./index.js").VideoResult>;
+    /** The rasters and encoders this machine can use. */
+    backends: () => Promise<import("./backends.js").BackendsReport>;
+};
+export type Tongue = ReturnType<typeof createTongue>;

package/dist/client.js

@@ -0,0 +1,38 @@
+import { BunServices } from "@effect/platform-bun";
+import { Cause, Effect, Exit } from "effect";
+import { listBackends } from "./backends.js";
+import { checkFilm } from "./check.js";
+import { initProject, listTemplates } from "./init.js";
+import { buildFilm, describeFilm, openFilm } from "./project.js";
+import { renderVideo } from "./render/pipeline.js";
+import { renderSheet, renderStills } from "./render/stills.js";
+// The SDK as plain Promises, for applications that don't use Effect. Each call runs the same Effect
+// program the CLI runs; a failure rejects with the SDK's tagged error (FilmFailure, ToolFailure…).
+const run = async (effect) => {
+    const exit = await Effect.runPromiseExit(effect.pipe(Effect.provide(BunServices.layer)));
+    if (Exit.isSuccess(exit))
+        return exit.value;
+    throw Cause.squash(exit.cause);
+};
+export function createTongue() {
+    return {
+        /** Makes a film project in a new or empty folder from a template. */
+        init: (dir, options) => run(initProject(dir, options)),
+        /** The templates that come with Tongue. */
+        templates: () => run(listTemplates()),
+        /** Builds a film project: build.json, film.json and a bundle per scene, in its dist folder. */
+        build: (project, options) => run(buildFilm(project, options)),
+        /** Imports the film's assets and plans it; resolves to its timeline as text and JSON. */
+        info: (film) => run(openFilm(film).pipe(Effect.map(describeFilm))),
+        /** Problems and warnings as data: never rejects for a broken film. */
+        check: (film) => run(checkFilm(film)),
+        /** Frames as PNG files. */
+        stills: (film, options) => run(openFilm(film, options).pipe(Effect.flatMap((f) => renderStills(f, options)))),
+        /** Frames tiled into one labelled image. */
+        sheet: (film, options) => run(openFilm(film, options).pipe(Effect.flatMap((f) => renderSheet(f, options)))),
+        /** The film (or a range of it, or one scene of a project) as an MP4. */
+        render: (film, options) => run(openFilm(film, options).pipe(Effect.flatMap((f) => renderVideo(f, options)))),
+        /** The rasters and encoders this machine can use. */
+        backends: () => run(listBackends()),
+    };
+}

package/dist/encode/encoders.d.ts

@@ -0,0 +1,68 @@
+export type VideoCodec = "h264" | "hevc";
+export interface EncodeTarget {
+    readonly width: number;
+    readonly height: number;
+    readonly fps: number;
+    /** The video-only file to write; audio is muxed in afterwards. */
+    readonly out: string;
+}
+/** An open encode. A frame's buffer may be reused once the next `write` has resolved. */
+export interface Encoder {
+    write(frame: Uint8Array): Promise<void>;
+    finish(): Promise<void>;
+}
+export interface EncoderSpec {
+    /** With its settings: "x264 veryfast crf 14", "vaapi-hevc qp 18". */
+    readonly name: string;
+    readonly codec: VideoCodec;
+    readonly hardware: boolean;
+    /** False for settings written from vendor documentation and never run on a machine of ours. */
+    readonly tested: boolean;
+    /** Options before the raw input (hardware devices). */
+    readonly device: ReadonlyArray<string>;
+    /** The filter from the raw input to what the encoder takes (uploads to the GPU). */
+    readonly filter: string | null;
+    readonly encode: ReadonlyArray<string>;
+    /** AMD's HEVC encoder pads the picture and writes no conformance window, or a wrong one, so 1080
+     *  rows decode as 1088 and 540 columns as 572: the window is set again when muxing. */
+    readonly fixCrop: boolean;
+}
+/** Where ffmpeg and ffprobe are. */
+export interface Tools {
+    readonly ffmpeg: string;
+    readonly ffprobe: string;
+}
+export declare class EncoderError extends Error {
+    readonly name = "EncoderError";
+}
+/** Opens an encode: frames go to ffmpeg's stdin, one in flight while the next is drawn. */
+export declare function openEncoder(tools: Tools, spec: EncoderSpec, target: EncodeTarget): Encoder;
+/** Whether this machine can run an encoder: a 0.2 s encode of a test pattern through its arguments,
+ *  at the size it will encode (hardware encoders have a smallest size; VAAPI's is about 130×128). */
+export declare function encoderWorks(ffmpeg: string, spec: EncoderSpec, size?: {
+    readonly width: number;
+    readonly height: number;
+}): Promise<boolean>;
+export interface EncoderSettings {
+    /** x264: preset and constant rate factor. */
+    readonly preset: string;
+    readonly crf: number;
+    /** x264: threads per encoder (two keeps x264 efficient when many encoders share the machine). */
+    readonly threads: number;
+    /** Hardware: constant QP (lower is better and bigger); null takes each codec's default. */
+    readonly qp: number | null;
+    /** Frames between keyframes (default: two seconds). */
+    readonly gop: number | null;
+    /** x264: extra settings, `key=value:key=value`. */
+    readonly x264Params: string;
+}
+export declare const DEFAULT_SETTINGS: EncoderSettings;
+export declare const X264_PRESETS: ReadonlyArray<string>;
+export type EncoderName = "x264" | "vaapi-hevc" | "vaapi-h264" | "vaapi-hevc-cpuconv" | "vaapi-h264-cpuconv" | "nvenc-hevc" | "nvenc-h264" | "qsv-hevc" | "qsv-h264";
+export declare const ENCODER_NAMES: ReadonlyArray<EncoderName>;
+export declare const isEncoderName: (v: string) => v is EncoderName;
+/** What "auto" tries, in order: a GPU's encoder when one works, else x264. */
+export declare const AUTO_ENCODERS: ReadonlyArray<EncoderName>;
+export declare const ENCODER_SUMMARIES: Readonly<Record<EncoderName, string>>;
+/** The encoder `name` with `settings`. Throws EncoderError for settings that can't work. */
+export declare function encoderSpec(name: EncoderName, settings: EncoderSettings, fps: number): EncoderSpec;