@tongue-core/project 0.0.0-stage → 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

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# @tongue-core/project
 
-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.
+Film projects. A film project is a folder in a fixed shape: `tongue.json`, `film.tsx` (the
+timeline) and one scene per file in `scenes/`. Building one gives **film.json**, the timeline as
+type-safe data that timeline UIs read, and one **bundle** per scene. Renderers, the browser player
+and Workers turn film.json plus the bundles back into the film, and the frames are byte-identical
+to the ones the project's own `film.tsx` gives. [docs/film-json.md](../../docs/film-json.md) is the
+specification.
+
+No Bun, Node or ffmpeg here: the package runs in Bun, browsers and Workers alike (its tsconfig
+leaves out Bun's and Node's types, so a platform API is a type error). Hosts supply what is
+platform-specific: the project's files, and a `ModuleHost` that turns a bundle's code into a module.
+
+```bash
+bun add @tongue-core/project@next effect    # effect (^4.0.6) is a peer: the schemas are yours to run
+```
+The SDK is that host on a machine with files and processes.
+
+## Entry points
+
+| Import | Holds | For |
+|---|---|---|
+| `@tongue-core/project/doc` | the `FilmDoc` schema and types, `decodeFilmDoc` and `filmDocProblems` (does it hold together), `assembleFilm` and `planFilmDoc` (back to a film), `sceneFilmDoc` (one scene alone), `filmDocOf` (a plan as film.json), build.json | timeline UIs, anything that reads or edits film.json |
+| `@tongue-core/project/build` | the project's shape (`roleOf`), the compiler (`compileModule`), bundles, `compileProject` → `loadProject` → `extractFilm` → `writeBuild`, or `buildProject` for all four | whatever builds projects (the SDK, a backend) |
+| `@tongue-core/project/load` | `ModuleHost`, linking bundles, `openBuild` (build.json, film.json and every bundle, hashes checked), `filmFromModules` (bundles a bundler already imported) | renderers, players, Workers |
+| `@tongue-core/project/template` | the template format (`template.json`), `TemplateSource`, `projectFromTemplate` | `tongue init`, apps with template catalogs |
+| `@tongue-core/project/media` | media identities, prepared-media schema, shared HTTP transport and typed failures | SDK acquisition, browser playback, host storage adapters |
+
+`@tongue-core/project` exports all of it.
+
+## Building
+
+```ts
+import { buildProject, type ModuleHost } from "@tongue-core/project/build";
+import { Effect } from "effect";
+
+const host: ModuleHost = { load: (bundle) => import(urlOf(bundle)) };     // however this platform loads a module
+const build = await Effect.runPromise(buildProject(files, host, { tongue: "0.1.0", media }));
+build.doc;     // FilmDoc: the timeline as data
+build.files;   // build.json, film.json, scenes/<id>.<hash>.js
+```
+
+1. **Compile.** Every `.ts`, `.tsx` and `.json` file is checked against the project's shape and
+   compiled with [sucrase](https://github.com/alangpierce/sucrase): TypeScript out, JSX to
+   `@tongue-core/film`'s development runtime (so each element knows its file and line), imports to
+   `require` calls resolved against the project's files.
+2. **Bundle.** Each scene and everything it imports becomes one ES module that imports nothing and
+   exports `link(imports)`. The timeline gets a bundle too; it links the scenes as `scene:<id>`.
+   Bundles are named by their SHA-256, and the same files give the same bytes.
+3. **Load.** The host loads each bundle; `link` runs it against this package's own `@tongue-core/film`
+   (the film package recognises its assets, scenes and nodes by identity, so there must be one
+   copy). The assets each bundle declares are collected as it runs.
+4. **Extract.** The timeline is planned with stable ids and written as film.json: props and the kit
+   by their scenes' `t` schemas, assets by name, every clip with its origin. Then film.json is
+   assembled with the scenes and planned again, and must give film.json back exactly; anything
+   else fails the build (it would be a bug in Tongue).
+
+Hosts that learn media lengths by importing assets (the SDK does, with ffprobe) call
+`compileProject`, `loadProject` and `extractFilm` themselves, importing in between.
+
+## Errors
+
+Every failure is a `Schema.TaggedError` naming its file, line or path, with what to change:
+`LayoutError` (every problem with the project's shape at once), `CompileError`, `LoadError`,
+`TimelineError` (it doesn't plan, or uses what film.json can't hold yet), `DocError` (film.json
+doesn't decode or hold together, with each problem's path) and `TemplateError`.
+
+## Layout
+
+```
+src/
+  doc/        film-doc.ts (the schema), check.ts, assemble.ts, from-plan.ts, plan-doc.ts, build-doc.ts, issues.ts
+  build/      layout.ts (the shape), compile.ts, bundle.ts, compile-project.ts, load-project.ts, extract.ts, write.ts
+  load/       host.ts (ModuleHost, linking), scene.ts, open-build.ts, modules.ts
+  template/   template.ts
+  errors.ts, hash.ts, order.ts
+test/         builds a fixture project (test/fixtures/basic) end to end, document checks, templates
+```

package/dist/build/bundle.d.ts

@@ -0,0 +1,21 @@
+import type { CompiledModule, Link } from "./compile.js";
+export declare const BUNDLE_FORMAT = 1;
+export interface Bundle {
+    /** Where it sits in a build: scenes/<id>.<hash>.js, or film.<hash>.js. */
+    readonly path: string;
+    readonly code: string;
+    /** SHA-256 of `code`, hex. */
+    readonly hash: string;
+    /** The module whose exports `link` returns. */
+    readonly entry: string;
+    /** The project modules in it, sorted. */
+    readonly modules: ReadonlyArray<string>;
+}
+/** The name a link target has inside a bundle (and in `imports`, when it is outside). */
+export declare const linkName: (link: Link) => string;
+/** The bundle of `entry`. `describe` says what it is, for its first line ("scene \"hook\""). */
+export declare function bundleOf(entry: string, modules: ReadonlyMap<string, CompiledModule>, place: {
+    readonly dir: string;
+    readonly stem: string;
+    readonly describe: string;
+}): Promise<Bundle>;

package/dist/build/bundle.js

@@ -0,0 +1,74 @@
+import { sha256 } from "../hash.js";
+import { byText } from "../order.js";
+// A bundle: one module and everything it imports from the project, in one ES module that imports
+// nothing. Its `link(imports)` runs the modules once, CommonJS style, and returns the entry's
+// exports; `imports` supplies what lives outside the bundle (the film runtime, and for a film's
+// timeline its scenes). So a host loads a bundle however it loads modules (a file in Bun, a URL in
+// a browser, a module of a Dynamic Worker) and always links its own one copy of @tongue-core/film.
+export const BUNDLE_FORMAT = 1;
+/** The name a link target has inside a bundle (and in `imports`, when it is outside). */
+export const linkName = (link) => (link.kind === "module" ? link.path : link.kind === "runtime" ? link.name : `scene:${link.id}`);
+/** Every project module `entry` reaches, sorted. */
+function reachable(entry, modules) {
+    const seen = new Set();
+    const visit = (path) => {
+        if (seen.has(path))
+            return;
+        const m = modules.get(path);
+        if (!m)
+            return;
+        seen.add(path);
+        for (const link of m.links.values())
+            if (link.kind === "module")
+                visit(link.path);
+    };
+    visit(entry);
+    return [...seen].sort();
+}
+const LOADER = `  const cache = new Map();
+  const load = (id) => {
+    const done = cache.get(id);
+    if (done) return done.exports;
+    const definition = modules.get(id);
+    if (!definition) {
+      if (Object.prototype.hasOwnProperty.call(imports, id)) return imports[id];
+      throw new Error(\`This bundle needs "\${id}": pass it to link().\`);
+    }
+    const module = { exports: {} };
+    cache.set(id, module);
+    const [links, run] = definition;
+    run.call(undefined, module, module.exports, (specifier) => {
+      const target = links[specifier];
+      if (target === undefined) throw new Error(\`\${id} requires "\${specifier}", which this bundle doesn't link.\`);
+      return load(target);
+    });
+    return module.exports;
+  };`;
+/** The bundle of `entry`. `describe` says what it is, for its first line ("scene \"hook\""). */
+export async function bundleOf(entry, modules, place) {
+    const included = reachable(entry, modules);
+    const outside = [...new Set(included.flatMap((p) => [...(modules.get(p)?.links.values() ?? [])].filter((l) => l.kind !== "module").map(linkName)))].sort();
+    const definitions = included.map((path) => {
+        const m = modules.get(path);
+        const links = Object.fromEntries([...(m?.links ?? new Map())].sort(([a], [b]) => byText(a, b)).map(([specifier, link]) => [specifier, linkName(link)]));
+        return `  [${JSON.stringify(path)}, [${JSON.stringify(links)}, function (module, exports, require) {\n${m?.code ?? ""}\n}]],`;
+    });
+    const others = included.length - 1;
+    const code = [
+        `// Tongue bundle (format ${BUNDLE_FORMAT}): ${place.describe}, from ${entry}${others > 0 ? ` and the ${others} module${others === 1 ? "" : "s"} it imports` : ""}.`,
+        `// It imports nothing. link(imports) runs its modules once and returns ${entry}'s exports;`,
+        `// imports: ${outside.map((o) => JSON.stringify(o)).join(", ")}.`,
+        `export const format = ${BUNDLE_FORMAT};`,
+        `export const entry = ${JSON.stringify(entry)};`,
+        `export function link(imports) {`,
+        `  const modules = new Map([`,
+        ...definitions,
+        `  ]);`,
+        LOADER,
+        `  return load(entry);`,
+        `}`,
+        ``,
+    ].join("\n");
+    const hash = await sha256(code);
+    return { path: `${place.dir}${place.stem}.${hash.slice(0, 12)}.js`, code, hash, entry, modules: included };
+}

package/dist/build/compile-project.d.ts

@@ -0,0 +1,16 @@
+import { Effect } from "effect";
+import { CompileError, LayoutError } from "../errors.js";
+import { type Bundle } from "./bundle.js";
+import { type CompiledModule } from "./compile.js";
+import { ProjectManifest, type ProjectFiles } from "./layout.js";
+export interface CompiledProject {
+    readonly manifest: ProjectManifest;
+    readonly modules: ReadonlyMap<string, CompiledModule>;
+    /** Each scene's bundle, by scene id, in id order. */
+    readonly scenes: ReadonlyMap<string, Bundle>;
+    /** film.tsx's bundle: it links the scene bundles. */
+    readonly film: Bundle;
+    /** SHA-256 of every code file, path and text: what the build was made from. */
+    readonly source: string;
+}
+export declare const compileProject: (files: ProjectFiles) => Effect.Effect<CompiledProject, LayoutError | CompileError, never>;

package/dist/build/compile-project.js

@@ -0,0 +1,63 @@
+import { Effect, Schema } from "effect";
+import { CompileError, LayoutError } from "../errors.js";
+import { bundleOf } from "./bundle.js";
+import { compileModule } from "./compile.js";
+import { sha256 } from "../hash.js";
+import { byText } from "../order.js";
+import { FILM_FILE, isProblem, normalizePath, PROJECT_FILE, ProjectManifest, roleOf } from "./layout.js";
+const decodeManifest = Schema.decodeUnknownEffect(ProjectManifest);
+const layoutError = (problems) => new LayoutError({ problems, message: `The project isn't in the shape of a film project:\n${problems.map((p) => `  ${p.file ? `${p.file}: ` : ""}${p.message}`).join("\n")}` });
+export const compileProject = Effect.fn("compileProject")(function* (files) {
+    const problems = [];
+    const roles = new Map();
+    const texts = new Map();
+    for (const [raw, text] of files) {
+        const path = normalizePath(raw);
+        if (path === null) {
+            problems.push({ file: raw, message: `"${raw}" isn't a path inside the project.` });
+            continue;
+        }
+        const role = roleOf(path);
+        if (isProblem(role)) {
+            problems.push(role);
+            continue;
+        }
+        if (role.kind === "ignored")
+            continue;
+        roles.set(path, role);
+        texts.set(path, text);
+    }
+    if (!roles.has(PROJECT_FILE))
+        problems.push({ file: PROJECT_FILE, message: "There is no tongue.json: a film project starts with one (`tongue init` writes it)." });
+    if (!roles.has(FILM_FILE))
+        problems.push({ file: FILM_FILE, message: "There is no film.tsx: the timeline, whose default export is <Film>." });
+    const sceneIds = [...roles.values()].flatMap((r) => (r.kind === "scene" ? [r.id] : [])).sort();
+    if (sceneIds.length === 0)
+        problems.push({ file: "scenes", message: "There are no scenes: add scenes/<id>.tsx, each exporting scene({ name: \"<id>\", … })." });
+    if (problems.length > 0)
+        return yield* layoutError(problems);
+    const manifestText = texts.get(PROJECT_FILE) ?? "";
+    const manifestJson = yield* Effect.try({ try: () => JSON.parse(manifestText), catch: (e) => new CompileError({ file: PROJECT_FILE, line: null, message: `tongue.json isn't valid JSON: ${e instanceof Error ? e.message : String(e)}` }) });
+    const manifest = yield* decodeManifest(manifestJson).pipe(Effect.mapError((e) => layoutError([{ file: PROJECT_FILE, message: `tongue.json: ${e.message}` }])));
+    const modules = new Map();
+    for (const [path, role] of [...roles].sort(([a], [b]) => byText(a, b))) {
+        if (role.kind === "project")
+            continue;
+        const compiled = yield* Effect.try({
+            try: () => compileModule(path, texts.get(path) ?? "", roles),
+            catch: (e) => (e instanceof CompileError ? e : new CompileError({ file: path, line: null, message: e instanceof Error ? e.message : String(e) })),
+        });
+        problems.push(...compiled.problems);
+        modules.set(path, compiled.module);
+    }
+    if (problems.length > 0)
+        return yield* layoutError(problems);
+    const scenes = new Map();
+    for (const id of sceneIds) {
+        scenes.set(id, yield* Effect.promise(() => bundleOf(`scenes/${id}.tsx`, modules, { dir: "scenes/", stem: id, describe: `scene "${id}"` })));
+    }
+    const film = yield* Effect.promise(() => bundleOf(FILM_FILE, modules, { dir: "", stem: "film", describe: "the timeline" }));
+    const source = yield* Effect.promise(() => sha256([...texts].sort(([a], [b]) => byText(a, b)).map(([path, text]) => `${path}\0${text}`).join("\0")));
+    const compiled = { manifest, modules, scenes, film, source };
+    return compiled;
+});

package/dist/build/compile.d.ts

@@ -0,0 +1,27 @@
+import { type Problem } from "../errors.js";
+import { type FileRole } from "./layout.js";
+/** What the film runtime is linked as: the two modules compiled code imports. */
+export declare const RUNTIME_MODULES: ReadonlyArray<string>;
+/** What an import of a module links to. */
+export type Link = {
+    readonly kind: "module";
+    readonly path: string;
+} | {
+    readonly kind: "runtime";
+    readonly name: string;
+} | {
+    readonly kind: "scene";
+    readonly id: string;
+};
+export interface CompiledModule {
+    readonly path: string;
+    /** The module as a CommonJS function body: `module`, `exports` and `require` are its arguments. */
+    readonly code: string;
+    /** Each specifier it requires, and what that links to. */
+    readonly links: ReadonlyMap<string, Link>;
+}
+/** Compiles one module and resolves its imports; problems with imports come back as Problems. */
+export declare function compileModule(path: string, text: string, roles: ReadonlyMap<string, FileRole>): {
+    readonly module: CompiledModule;
+    readonly problems: ReadonlyArray<Problem>;
+};

package/dist/build/compile.js

@@ -0,0 +1,108 @@
+import { transform } from "sucrase";
+import { CompileError } from "../errors.js";
+import { FILM_FILE } from "./layout.js";
+// Compiling one module: TypeScript and JSX to plain JavaScript, with JSX going to @tongue-core/film's
+// development runtime (so every element knows its file and line) and imports turned into
+// `require` calls the bundle's own loader answers. Each import is resolved here, against the
+// project's files, to what the bundle links: another module, the film runtime, or a scene.
+/** What the film runtime is linked as: the two modules compiled code imports. */
+export const RUNTIME_MODULES = ["@tongue-core/film", "@tongue-core/film/jsx-dev-runtime"];
+const EXTENSIONS = [".tsx", ".ts", ".json"];
+/** The project file a relative import means: exact, then with each extension, then a folder's index. */
+function resolveRelative(from, specifier, files) {
+    const parts = [...from.split("/").slice(0, -1), ...specifier.split("/")];
+    const out = [];
+    for (const part of parts) {
+        if (part === "" || part === ".")
+            continue;
+        if (part === "..") {
+            if (out.length === 0)
+                return null;
+            out.pop();
+        }
+        else
+            out.push(part);
+    }
+    const base = out.join("/");
+    const candidates = [base, ...EXTENSIONS.map((e) => base + e), ...EXTENSIONS.map((e) => `${base}/index${e}`)];
+    // An import written for the compiled name ("./brand.js") still finds "brand.ts".
+    if (base.endsWith(".js"))
+        candidates.push(base.replace(/\.js$/, ".ts"), base.replace(/\.js$/, ".tsx"));
+    return candidates.find((c) => files.has(c)) ?? null;
+}
+// Sucrase writes every import (static, re-export or dynamic) as `require('…')`. A string in the
+// film's own code that looks exactly like one would be read as an import too.
+const REQUIRE = /\brequire\((['"])([^'"\\\n]+)\1\)/g;
+function lineOf(message) {
+    const m = /\((\d+):\d+\)/.exec(message);
+    return m ? Number(m[1]) : null;
+}
+/** Compiles one module and resolves its imports; problems with imports come back as Problems. */
+export function compileModule(path, text, roles) {
+    if (path.endsWith(".json")) {
+        let value;
+        try {
+            value = JSON.parse(text);
+        }
+        catch (e) {
+            throw new CompileError({ file: path, line: null, message: `${path} isn't valid JSON: ${e instanceof Error ? e.message : String(e)}` });
+        }
+        return { module: { path, code: `module.exports = ${JSON.stringify(value)};`, links: new Map() }, problems: [] };
+    }
+    let code;
+    try {
+        code = transform(text, {
+            transforms: path.endsWith(".tsx") ? ["typescript", "jsx", "imports"] : ["typescript", "imports"],
+            jsxRuntime: "automatic",
+            jsxImportSource: "@tongue-core/film",
+            production: false,
+            filePath: path,
+        }).code;
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        throw new CompileError({ file: path, line: lineOf(message), message: `${path} doesn't compile: ${message}` });
+    }
+    const files = new Set(roles.keys());
+    const links = new Map();
+    const problems = [];
+    const fromFilm = path === FILM_FILE;
+    for (const match of code.matchAll(REQUIRE)) {
+        const specifier = match[2] ?? "";
+        if (links.has(specifier))
+            continue;
+        if (RUNTIME_MODULES.includes(specifier)) {
+            links.set(specifier, { kind: "runtime", name: specifier });
+            continue;
+        }
+        if (!specifier.startsWith(".")) {
+            problems.push({ file: path, message: `A film project imports only "@tongue-core/film" and its own files, not "${specifier}".` });
+            continue;
+        }
+        const target = resolveRelative(path, specifier, files);
+        const role = target === null ? undefined : roles.get(target);
+        if (target === null || role === undefined) {
+            problems.push({ file: path, message: `Cannot find "${specifier}" (imported by ${path}).` });
+            continue;
+        }
+        switch (role.kind) {
+            case "scene":
+                if (fromFilm)
+                    links.set(specifier, { kind: "scene", id: role.id });
+                else
+                    problems.push({ file: path, message: `Only film.tsx imports scenes (${path} imports ${target}); share code between scenes through kit/ or lib/.` });
+                break;
+            case "film":
+                problems.push({ file: path, message: `Nothing imports film.tsx (${path} does): it is the timeline, the top of the project.` });
+                break;
+            case "project":
+            case "ignored":
+                problems.push({ file: path, message: `${target} isn't a module a film can import.` });
+                break;
+            case "module":
+                links.set(specifier, { kind: "module", path: target });
+                break;
+        }
+    }
+    return { module: { path, code, links }, problems };
+}

package/dist/build/extract.d.ts

@@ -0,0 +1,242 @@
+import { type Json, type MediaInfo } from "@tongue-core/film";
+import { Effect } from "effect";
+import { TimelineError } from "../errors.js";
+import { type SceneDoc } from "../doc/film-doc.js";
+import type { LoadedScene } from "../load/scene.js";
+import type { LoadedProject } from "./load-project.js";
+export interface ExtractOptions {
+    /** Media lengths, for clips that play a file to its end (what the host's import found). */
+    readonly media?: MediaInfo;
+}
+/** A scene's entry in film.json. */
+export declare function sceneDoc(s: LoadedScene): SceneDoc;
+/** Where two JSON values first differ, as a path (null when they are the same). */
+export declare function firstDifference(a: Json, b: Json, path?: string): string | null;
+export declare const extractFilm: (project: LoadedProject, options?: ExtractOptions | undefined) => Effect.Effect<{
+    readonly format: "tongue.film";
+    readonly version: 1;
+    readonly film: {
+        readonly width: number;
+        readonly height: number;
+        readonly fps: number;
+        readonly background: string;
+        readonly tail: number;
+        readonly length: number;
+    };
+    readonly kit: import("effect/Schema").Json;
+    readonly kitSchema: import("effect/Schema").Json;
+    readonly scenes: readonly {
+        readonly id: string;
+        readonly file: string;
+        readonly bundle: string;
+        readonly hash: string;
+        readonly keys: readonly string[];
+        readonly kit: boolean;
+        readonly assets: readonly {
+            readonly kind: "font" | "image" | "video" | "audio";
+            readonly name: string;
+        }[];
+        readonly props: import("effect/Schema").Json;
+    }[];
+    readonly assets: readonly ({
+        readonly kind: "font";
+        readonly name: string;
+        readonly source: string;
+        readonly sha256?: string | undefined;
+        readonly prepared?: string | undefined;
+        readonly italic?: string | undefined;
+    } | {
+        readonly kind: "image";
+        readonly name: string;
+        readonly source: string;
+        readonly maxSize: number;
+        readonly sha256?: string | undefined;
+        readonly prepared?: string | undefined;
+    } | {
+        readonly kind: "video";
+        readonly name: string;
+        readonly source: string;
+        readonly maxSize: number;
+        readonly sha256?: string | undefined;
+        readonly prepared?: string | undefined;
+    } | {
+        readonly kind: "audio";
+        readonly name: string;
+        readonly source: string;
+        readonly sha256?: string | undefined;
+        readonly prepared?: string | undefined;
+    })[];
+    readonly tracks: readonly {
+        readonly id: string;
+        readonly kind: "audio" | "visual";
+        readonly clips: readonly ({
+            readonly kind: "scene";
+            readonly id: string;
+            readonly props: import("effect/Schema").Json;
+            readonly scene: string;
+            readonly opacity: number;
+            readonly start: number;
+            readonly duration: number;
+            readonly end: number;
+            readonly origin: {
+                readonly file: string;
+                readonly line: number;
+            } | null;
+            readonly blend?: "multiply" | "screen" | "overlay" | "soft-light" | "color-dodge" | "normal" | undefined;
+        } | {
+            readonly in: number;
+            readonly out: number;
+            readonly kind: "video";
+            readonly id: string;
+            readonly opacity: number;
+            readonly start: number;
+            readonly duration: number;
+            readonly end: number;
+            readonly origin: {
+                readonly file: string;
+                readonly line: number;
+            } | null;
+            readonly asset: string;
+            readonly speed: number;
+            readonly reverse: boolean;
+            readonly freeze: boolean;
+            readonly fit: "cover" | "contain";
+            readonly blend?: "multiply" | "screen" | "overlay" | "soft-light" | "color-dodge" | "normal" | undefined;
+        } | {
+            readonly kind: "image";
+            readonly id: string;
+            readonly opacity: number;
+            readonly start: number;
+            readonly duration: number;
+            readonly end: number;
+            readonly origin: {
+                readonly file: string;
+                readonly line: number;
+            } | null;
+            readonly asset: string;
+            readonly fit: "cover" | "contain";
+            readonly blend?: "multiply" | "screen" | "overlay" | "soft-light" | "color-dodge" | "normal" | undefined;
+        } | {
+            readonly in: number;
+            readonly out: number;
+            readonly kind: "audio";
+            readonly id: string;
+            readonly start: number;
+            readonly duration: number;
+            readonly end: number;
+            readonly origin: {
+                readonly file: string;
+                readonly line: number;
+            } | null;
+            readonly asset: string;
+            readonly speed: number;
+            readonly gain: number;
+            readonly fadeIn: number;
+            readonly fadeOut: number;
+            readonly voice?: {
+                readonly words: readonly {
+                    readonly text: string;
+                    readonly start: number;
+                    readonly end: number;
+                }[];
+            } | undefined;
+        })[];
+        readonly transitions: readonly ({
+            readonly from: string;
+            readonly to: string;
+            readonly frames: number;
+            readonly ease: "linear" | "glide" | "settle" | "snap" | "in" | "out" | "swift";
+            readonly start: number;
+            readonly end: number;
+            readonly origin: {
+                readonly file: string;
+                readonly line: number;
+            } | null;
+            readonly style: "fade";
+        } | {
+            readonly direction: "left" | "right" | "up" | "down";
+            readonly from: string;
+            readonly to: string;
+            readonly frames: number;
+            readonly ease: "linear" | "glide" | "settle" | "snap" | "in" | "out" | "swift";
+            readonly start: number;
+            readonly end: number;
+            readonly origin: {
+                readonly file: string;
+                readonly line: number;
+            } | null;
+            readonly style: "wipe" | "push";
+        } | {
+            readonly others: {
+                readonly enter: "iris" | "fade" | "rise" | "pop" | "none" | {
+                    readonly kind: "enter";
+                    readonly from: {
+                        readonly opacity?: number | undefined;
+                        readonly x?: number | undefined;
+                        readonly y?: number | undefined;
+                        readonly scale?: number | undefined;
+                        readonly rotate?: number | undefined;
+                        readonly turn?: number | undefined;
+                        readonly tilt?: number | undefined;
+                        readonly blur?: number | undefined;
+                        readonly brightness?: number | undefined;
+                        readonly iris?: number | undefined;
+                    };
+                    readonly frames?: number | undefined;
+                    readonly ease?: "linear" | "glide" | "settle" | "snap" | "in" | "out" | "swift" | undefined;
+                    readonly spring?: {
+                        readonly stiffness: number;
+                        readonly damping: number;
+                        readonly mass?: number | undefined;
+                    } | undefined;
+                };
+                readonly exit: "fade" | "none" | "drop" | "lift" | "recede" | {
+                    readonly kind: "exit";
+                    readonly to: {
+                        readonly opacity?: number | undefined;
+                        readonly x?: number | undefined;
+                        readonly y?: number | undefined;
+                        readonly scale?: number | undefined;
+                        readonly rotate?: number | undefined;
+                        readonly turn?: number | undefined;
+                        readonly tilt?: number | undefined;
+                        readonly blur?: number | undefined;
+                        readonly brightness?: number | undefined;
+                        readonly iris?: number | undefined;
+                    };
+                    readonly frames?: number | undefined;
+                    readonly ease?: "linear" | "glide" | "settle" | "snap" | "in" | "out" | "swift" | undefined;
+                };
+                readonly stagger: number;
+            };
+            readonly sharedKeys: readonly string[] | null;
+            readonly from: string;
+            readonly to: string;
+            readonly frames: number;
+            readonly ease: "linear" | "glide" | "settle" | "snap" | "in" | "out" | "swift";
+            readonly start: number;
+            readonly end: number;
+            readonly origin: {
+                readonly file: string;
+                readonly line: number;
+            } | null;
+            readonly style: "morph";
+        } | {
+            readonly noise: "cloud" | "ridged";
+            readonly size: number;
+            readonly edge: string | null;
+            readonly from: string;
+            readonly to: string;
+            readonly frames: number;
+            readonly ease: "linear" | "glide" | "settle" | "snap" | "in" | "out" | "swift";
+            readonly start: number;
+            readonly end: number;
+            readonly origin: {
+                readonly file: string;
+                readonly line: number;
+            } | null;
+            readonly style: "dissolve";
+        })[];
+    }[];
+    readonly warnings: readonly string[];
+}, TimelineError | import("../errors.js").DocError, never>;