@anvpx/motion-build 0.0.0-stage → 0.1.1

package/dist/audio/music.js

@@ -0,0 +1,134 @@
+import { DEFAULT_MUSIC_VOLUME as SCHEMA_DEFAULT_MUSIC_VOLUME } from "@anvpx/motion-schema";
+/**
+ * Pinned music-bed mix constants (T-AU-01a, current-only).
+ *
+ * Single measurement source: the qc-lufs pack proof.
+ * LUFS target comes from the verified `youtube` platform policy
+ * (`lufsTarget: -14`, `truePeakDb: -1`, `verified: true`); the ducked bed
+ * depth is the static schema level `DEFAULT_MUSIC_VOLUME = 0.5`, measured
+ * on this machine as `20*log10(0.5) = -6.0206 dB`, before the frozen
+ * sidechain stage. Tolerances mirror the `qc-lufs` measurement seam
+ * (`LOUDNESS_TOLERANCE_LU = 1`, `TRUE_PEAK_TOLERANCE_DB = 0.5`).
+ * Nothing here runs ffmpeg; measurement stays in the verify chain (LC-04).
+ */
+/** Ducked bed level, re-exported from the schema single source. */
+export const DEFAULT_MUSIC_VOLUME = SCHEMA_DEFAULT_MUSIC_VOLUME;
+/** Pinned integrated-loudness target for the mixed output (qc-lufs). */
+export const MIX_LUFS_TARGET = -14;
+/** Pinned true-peak ceiling for the mixed output (qc-lufs). */
+export const MIX_TRUE_PEAK_DBTP = -1;
+/** Accepted drift for integrated loudness vs the pinned target. */
+export const MIX_LOUDNESS_TOLERANCE_LU = 1;
+/** Accepted excess for true peak above the pinned ceiling. */
+export const MIX_TRUE_PEAK_TOLERANCE_DB = 0.5;
+/** Static bed gain of the default ducked level, dB (measured receipt). */
+export const DUCKING_DB = -6.0206;
+/** Frozen sidechain stage (pinned by mix.test.ts, qc-lufs §Ducking dB). */
+export const SIDECHAIN_THRESHOLD = 0.03;
+export const SIDECHAIN_RATIO = 4;
+export const SIDECHAIN_ATTACK_MS = 200;
+export const SIDECHAIN_RELEASE_MS = 500;
+/** Only CC0 beds are supported (licence gate, current-only). */
+export const MUSIC_LICENCE = "CC0-1.0";
+/** sha256 of zero bytes: a silent/empty wav can never qualify as a bed. */
+export const EMPTY_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+const SHA256_HEX = /^[0-9a-f]{64}$/i;
+/** Static gain of a bed level in dB; refuses nonsense (fail closed). */
+export const musicGainDb = (volume) => {
+    if (!Number.isFinite(volume) || volume <= 0) {
+        throw new Error(`invalid music volume ${volume}: must be finite and > 0`);
+    }
+    return 20 * Math.log10(volume);
+};
+/** True when a level sits at the pinned ducking depth within 0.001 dB. */
+export const isPinnedDuckingDepth = (volume) => {
+    if (!Number.isFinite(volume) || volume <= 0 || volume > 1)
+        return false;
+    return Math.abs(musicGainDb(volume) - DUCKING_DB) < 0.001;
+};
+const PHASE_EPSILON = 1e-9;
+/**
+ * Seamless-loop phase math: how many bed repeats cover `totalDuration`
+ * seconds and where the trim lands in the bed cycle. `phaseError` is the
+ * fractional cycle cut by the trim (0 = trim lands on the loop boundary,
+ * seamless); `loops` is `ceil(total / bed)`. Refuses nonsense (fail closed).
+ */
+export const seamlessLoopFor = (bedDuration, totalDuration) => {
+    if (!Number.isFinite(bedDuration) || bedDuration <= 0) {
+        throw new Error(`invalid bed duration ${bedDuration}: must be finite and > 0`);
+    }
+    if (!Number.isFinite(totalDuration) || totalDuration <= 0) {
+        throw new Error(`invalid total duration ${totalDuration}: must be finite and > 0`);
+    }
+    const loops = Math.ceil(totalDuration / bedDuration);
+    const remainder = totalDuration % bedDuration;
+    const phaseError = remainder < PHASE_EPSILON || bedDuration - remainder < PHASE_EPSILON
+        ? 0
+        : remainder / bedDuration;
+    return {
+        loops,
+        trimDuration: totalDuration,
+        phaseError,
+        isSeamless: phaseError === 0,
+    };
+};
+const isLocalWavRef = (ref) => ref.length > 0 &&
+    !ref.includes("\\") &&
+    !ref.startsWith("/") &&
+    !ref.startsWith("../") &&
+    !ref.includes("/../") &&
+    !/^[a-zA-Z]:[\\/]/.test(ref) &&
+    ref.endsWith(".wav") &&
+    !ref.includes("..");
+/**
+ * Fail-closed identity check (current-only): malformed identity fields,
+ * a missing/unreadable bed digest, a mutated bed sha, or a drifted licence
+ * receipt each yield a problem. Empty means the frozen bytes match the
+ * identity. An ABA restore (mutate then restore the source) still passes
+ * only when the frozen copy consumed by the mix matches — the check reads
+ * the frozen digest, never the mutable source.
+ */
+export const verifyMusicIdentity = (identity, actualBedSha256, actualLicenceSha256) => {
+    const problems = [];
+    if (!isLocalWavRef(identity.relativePath)) {
+        problems.push(`music bed "${identity.relativePath}" must be a project-local .wav`);
+    }
+    if (!SHA256_HEX.test(identity.sha256)) {
+        problems.push("music bed sha256 must be 64 hex characters");
+    }
+    if (!Number.isFinite(identity.volume) || identity.volume <= 0 || identity.volume > 1) {
+        problems.push("music bed volume must be within (0, 1]");
+    }
+    if (identity.licenceEvidenceSha256 !== null && !SHA256_HEX.test(identity.licenceEvidenceSha256)) {
+        problems.push("music licence evidence sha256 must be 64 hex characters or null");
+    }
+    if (actualBedSha256 === undefined) {
+        problems.push(`music bed wav unreadable: ${identity.relativePath}`);
+    }
+    else if (actualBedSha256 !== identity.sha256) {
+        problems.push(`music bed sha256 differs for "${identity.relativePath}"`);
+    }
+    if (identity.licenceEvidenceSha256 !== null &&
+        actualLicenceSha256 !== identity.licenceEvidenceSha256) {
+        problems.push(`music licence evidence sha256 differs for "${identity.relativePath}"`);
+    }
+    return problems;
+};
+/**
+ * Judges one integrated-loudness + true-peak measurement against the pinned
+ * qc-lufs constants. Mirrors the verify-chain tolerances; measurement itself
+ * stays in the CLI verify seam (LC-04).
+ */
+export const assessMixLoudness = (integratedLufs, truePeakDb) => {
+    const problems = [];
+    if (!Number.isFinite(integratedLufs) || !Number.isFinite(truePeakDb)) {
+        return { ok: false, problems: ["loudness measurement is non-finite"] };
+    }
+    if (Math.abs(integratedLufs - MIX_LUFS_TARGET) > MIX_LOUDNESS_TOLERANCE_LU) {
+        problems.push(`integrated ${integratedLufs} LUFS differs from pinned target ${MIX_LUFS_TARGET} LUFS by more than ${MIX_LOUDNESS_TOLERANCE_LU} LU`);
+    }
+    if (truePeakDb - MIX_TRUE_PEAK_DBTP > MIX_TRUE_PEAK_TOLERANCE_DB) {
+        problems.push(`true peak ${truePeakDb} dBTP exceeds pinned ceiling ${MIX_TRUE_PEAK_DBTP} dBTP`);
+    }
+    return { ok: problems.length === 0, problems };
+};

package/dist/audio/preview.d.ts

@@ -0,0 +1,31 @@
+import { type MixClip, type MusicBed } from "./mix.ts";
+import type { MusicIdentity } from "./music.ts";
+/**
+ * T-AU-01b preview authority (current-only, pure).
+ *
+ * The audible preview mixes the exact final bytes with the exact final
+ * params: the same frozen layout (`frozenClips`/`frozenMusic`) and the same
+ * ducked `buildMusicMixArgs` graph as the final render (no second pipeline).
+ * Any bed/volume/receipt change after preview makes the preview stale
+ * (`isPreviewCurrent` false → re-preview + re-approve). Mutated, silent, or
+ * missing frozen bytes fail closed; no machine identity enters paths.
+ */
+/** Frozen preview inputs in the final frozen layout (role- and ordinal-scoped names). */
+export declare const freezePreviewInputs: (clips: readonly MixClip[], music: MusicBed | undefined, frozenDir: string) => {
+    clips: MixClip[];
+    music: MusicBed | undefined;
+};
+/**
+ * Preview mix argv with the same normalized params as the final render.
+ * Same wrapper, same graph: preview and final diverge only in the out path.
+ */
+export declare const buildPreviewMixArgs: (videoIn: string, clips: readonly MixClip[], music: MusicBed, out: string) => string[];
+/** Narration-only preview argv, same as the final narration mix. */
+export declare const buildPreviewNarrationArgs: (videoIn: string, clips: readonly MixClip[], out: string) => string[];
+/** True only when the previewed bed identity still matches the current one. */
+export declare const isPreviewCurrent: (previewed: MusicIdentity, current: MusicIdentity) => boolean;
+/**
+ * Fail closed on preview inputs: mutated/silent/missing frozen bytes or
+ * machine-identity paths yield problems (never an audible approval).
+ */
+export declare const verifyPreviewInputs: (identity: MusicIdentity, frozenBedSha256: string | undefined, frozenLicenceSha256: string | null | undefined) => string[];

package/dist/audio/preview.js

@@ -0,0 +1,31 @@
+import { needsReapproval, verifyFrozenApproval } from "./approval.js";
+import { buildMixArgs, buildMusicMixArgs, frozenClips, frozenMusic, } from "./mix.js";
+/**
+ * T-AU-01b preview authority (current-only, pure).
+ *
+ * The audible preview mixes the exact final bytes with the exact final
+ * params: the same frozen layout (`frozenClips`/`frozenMusic`) and the same
+ * ducked `buildMusicMixArgs` graph as the final render (no second pipeline).
+ * Any bed/volume/receipt change after preview makes the preview stale
+ * (`isPreviewCurrent` false → re-preview + re-approve). Mutated, silent, or
+ * missing frozen bytes fail closed; no machine identity enters paths.
+ */
+/** Frozen preview inputs in the final frozen layout (role- and ordinal-scoped names). */
+export const freezePreviewInputs = (clips, music, frozenDir) => ({
+    clips: frozenClips(clips, frozenDir),
+    music: music === undefined ? undefined : frozenMusic(music, frozenDir),
+});
+/**
+ * Preview mix argv with the same normalized params as the final render.
+ * Same wrapper, same graph: preview and final diverge only in the out path.
+ */
+export const buildPreviewMixArgs = (videoIn, clips, music, out) => buildMusicMixArgs(videoIn, clips, music, out);
+/** Narration-only preview argv, same as the final narration mix. */
+export const buildPreviewNarrationArgs = (videoIn, clips, out) => buildMixArgs(videoIn, clips, out);
+/** True only when the previewed bed identity still matches the current one. */
+export const isPreviewCurrent = (previewed, current) => needsReapproval(previewed, current).length === 0;
+/**
+ * Fail closed on preview inputs: mutated/silent/missing frozen bytes or
+ * machine-identity paths yield problems (never an audible approval).
+ */
+export const verifyPreviewInputs = (identity, frozenBedSha256, frozenLicenceSha256) => verifyFrozenApproval(identity, frozenBedSha256, frozenLicenceSha256);

package/dist/build.d.ts

@@ -0,0 +1,65 @@
+import { type CustomSceneSource } from "@anvpx/motion-scenes";
+import type { AssetLedger, AssetRow, ResolvedTheme, TimingManifest, ValidationError } from "@anvpx/motion-schema";
+import { type AudioManifestRef } from "./audio/mix.ts";
+import { type CacheStats } from "./cache.ts";
+import { type LintFinding, type PlatformMarginLookup } from "./lint/index.ts";
+import { type BuildManifest } from "./manifest.ts";
+export interface BuildOptions {
+    /** Parsed storyboard JSON (validated here). */
+    readonly storyboard: unknown;
+    readonly outDir: string;
+    readonly assetsDir?: string;
+    readonly ledger?: AssetLedger;
+    /** Voice timing; overrides scene durations by id. */
+    readonly timing?: TimingManifest;
+    /**
+     * Opt-in narration mixdown input: the voice TimingManifest plus the directory
+     * holding its `<scene-id>.wav` files. Absent means a silent build (no behavior
+     * change). Present but unmixable (no scenes, missing wav) fails the build
+     * closed — before the slow emit — instead of rendering silent video.
+     */
+    readonly audioManifest?: AudioManifestRef;
+    /** Project theme documents by name (vendored DTCG files), resolved beside the built-in themes. */
+    readonly themes?: Readonly<Record<string, unknown>>;
+    /** Enables the per-scene incremental cache stored in this directory. */
+    readonly cacheDir?: string;
+    /**
+     * Opt-in workspace-level sharing for the disk cache (see `DiskCacheOptions.sharedDir`).
+     * Absent means per-storyboard only; never enabled by default.
+     */
+    readonly sharedCacheDir?: string;
+    /**
+     * Run the lint rules (default true). Only for derived storyboards that are not authored work,
+     * such as preview clips whose scenes are cut short; schema and timing validation always run.
+     */
+    readonly lint?: boolean;
+    /**
+     * Platform margins by id (`meta.platform`): scene padding is raised to the platform UI bands and the
+     * `safe-zone-9x16` lint runs. Without it a platform tag changes nothing.
+     */
+    readonly platforms?: PlatformMarginLookup;
+    /**
+     * Authored scene sources, keyed by scene id, already read from disk by the caller.
+     * `build` stays pure: it never resolves `props.dir` itself. A `custom` entry without
+     * a source here fails the build instead of emitting an empty scene.
+     */
+    readonly customScenes?: Readonly<Record<string, CustomSceneSource>>;
+}
+export type BuildResult = {
+    readonly ok: true;
+    readonly outDir: string;
+    readonly files: readonly string[];
+    readonly manifest: BuildManifest;
+    /** Licence rows for every font, inlined icon and copied image; also written to `licences.json`. */
+    readonly licences: readonly AssetRow[];
+    readonly warnings: readonly LintFinding[];
+    /** Present only for cached builds; never written to the manifest. */
+    readonly cache?: CacheStats;
+} | {
+    readonly ok: false;
+    readonly errors: readonly ValidationError[];
+};
+/** A theme by name, or undefined when it is unknown (callers that only lint skip theme rules). */
+export declare const tryResolveTheme: (name: string, docs?: BuildOptions["themes"]) => ResolvedTheme | undefined;
+/** storyboard -> validate -> theme -> timing -> lint -> assets -> emit -> HyperFrames project. */
+export declare const buildProject: (options: BuildOptions) => BuildResult;

package/dist/build.js

@@ -0,0 +1,260 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CUSTOM_SCENE_TYPE, collectIcons, emitCustomScene, getScene, iconLedgerRows, LUCIDE_LICENCE_TEXT, runtimeFiles, sceneWords, } from "@anvpx/motion-scenes";
+import { canonicalJson } from "@anvpx/motion-schema";
+import { bundledThemeDocs, resolveGrades, resolveTheme, toCssVars, toGradeCssVars, } from "@anvpx/motion-themes";
+import { copyAssets, createAssetCollector, sha256Of } from "./assets.js";
+import { clipsFromManifest, missingClips } from "./audio/mix.js";
+import { createCachePlan, emitCached } from "./cache.js";
+import { renderBoot } from "./emit/boot.js";
+import { assertInertFragment } from "./emit/fragment-guard.js";
+import { renderIndexHtml } from "./emit/index-html.js";
+import { renderImportMap, vendorFiles, vendorLibs } from "./emit/vendor.js";
+import { bundleFonts, fontFamiliesFor } from "./fonts.js";
+import { lintStoryboard, } from "./lint/index.js";
+import { createManifest, renderManifest, } from "./manifest.js";
+import { GRADE_REVIEW_PATH, renderGradeReview } from "./review/review.js";
+import { resolveTimeline } from "./timing.js";
+import { validateStoryboardFull } from "./validate-full.js";
+import { readVersions } from "./versions.js";
+const fail = (path, message) => ({
+    ok: false,
+    errors: [{ path, message }],
+});
+const messageOf = (error) => error instanceof Error ? error.message : String(error);
+const themeOf = (name, docs) => {
+    try {
+        return { ok: true, value: resolveTheme(name, { ...bundledThemeDocs(), ...docs }) };
+    }
+    catch (error) {
+        return fail("/meta/theme", messageOf(error));
+    }
+};
+/** A theme by name, or undefined when it is unknown (callers that only lint skip theme rules). */
+export const tryResolveTheme = (name, docs) => {
+    const found = themeOf(name, docs);
+    return found.ok ? found.value : undefined;
+};
+/** Base scenes in order, then overlays in declared order (later in the page = higher z-order). */
+const placementsOf = (timeline) => [
+    ...timeline.scenes.map((placed, position) => ({
+        placed,
+        final: position === timeline.scenes.length - 1,
+    })),
+    ...timeline.overlays.map((overlay) => ({
+        placed: { ...overlay, overlap: 0 },
+        final: overlay.end >= timeline.total,
+    })),
+];
+const insetsOf = (board, platforms) => {
+    const { platform } = board.meta;
+    const insets = platform === undefined ? undefined : platforms?.(platform)?.safeZones;
+    return insets === undefined ? {} : { insets };
+};
+const contextOf = (board, placed, total, theme, assets, platforms) => ({
+    theme,
+    ...insetsOf(board, platforms),
+    fps: board.meta.fps,
+    width: board.meta.width,
+    height: board.meta.height,
+    duration: placed.duration,
+    timeline: { start: placed.start, total },
+    assetResolver: assets.resolver,
+});
+/** Runs an emit and appends the icon names it drew to `icons`. */
+const drawn = (icons, run) => {
+    const result = collectIcons(run);
+    icons.push(...result.icons);
+    return result.value;
+};
+const emitScene = (entry, { placed, final }, ctx, plan, customScenes) => {
+    const source = entry.type === CUSTOM_SCENE_TYPE ? customScenes?.[entry.id] : undefined;
+    if (entry.type === CUSTOM_SCENE_TYPE && source === undefined) {
+        return fail(`/scenes/${placed.index}`, `custom scene "${entry.id}" has no source; keep its directory beside the storyboard and set props.dir`);
+    }
+    try {
+        const icons = [];
+        const emit = (context) => source === undefined
+            ? getScene(entry.type).emit(entry, context)
+            : emitCustomScene(entry, context, source);
+        // Authored bytes are not in the cache key, so a cached hit could serve a stale scene.
+        const scenePlan = source === undefined ? plan : undefined;
+        const files = scenePlan
+            ? emitCached(scenePlan, entry, ctx, emit, (names) => icons.push(...names))
+            : drawn(icons, () => emit(ctx));
+        const config = {
+            ...(entry.ease === undefined ? {} : { ease: entry.ease }),
+            ...(entry.move === undefined ? {} : { move: entry.move }),
+            ...(entry.focus === undefined ? {} : { focus: entry.focus }),
+        };
+        const fragment = files.get(`scenes/${entry.id}/fragment.html`) ?? "";
+        assertInertFragment(entry.id, fragment);
+        const { id, start, duration, index } = placed;
+        return {
+            ok: true,
+            value: {
+                page: { id, start, duration, index, fragment },
+                boot: { timed: placed, final, config },
+                files,
+                icons,
+                vendor: source === undefined ? (getScene(entry.type).vendor ?? []) : (source.vendor ?? []),
+            },
+        };
+    }
+    catch (error) {
+        return fail(`/scenes/${placed.index}`, messageOf(error));
+    }
+};
+const emitAll = (board, timeline, theme, assets, plan, platforms, customScenes) => {
+    const emitted = [];
+    const errors = [];
+    for (const placement of placementsOf(timeline)) {
+        const entry = board.scenes[placement.placed.index];
+        if (!entry)
+            continue;
+        const ctx = contextOf(board, placement.placed, timeline.total, theme, assets, platforms);
+        const result = emitScene(entry, placement, ctx, plan, customScenes);
+        if (result.ok)
+            emitted.push(result.value);
+        else
+            errors.push(...result.errors);
+    }
+    return errors.length > 0 ? { ok: false, errors } : { ok: true, value: emitted };
+};
+const assemble = (board, timeline, theme, emitted, assetFiles, fonts) => {
+    const files = new Map();
+    const themeCss = toCssVars(theme);
+    const grades = resolveGrades();
+    const gradeCss = toGradeCssVars(grades);
+    const libs = vendorLibs(emitted.flatMap((scene) => scene.vendor));
+    files.set("index.html", renderIndexHtml({
+        meta: board.meta,
+        total: timeline.total,
+        themeCss,
+        scenes: emitted.map((scene) => scene.page),
+        importMap: renderImportMap(libs),
+    }));
+    files.set("boot.js", renderBoot(emitted.map((scene) => scene.boot), board.meta.fps));
+    for (const [path, text] of runtimeFiles())
+        files.set(path, text);
+    for (const [path, bytes] of vendorFiles(libs))
+        files.set(path, bytes);
+    for (const scene of emitted)
+        for (const [path, text] of scene.files)
+            files.set(path, text);
+    for (const [path, bytes] of assetFiles)
+        files.set(path, bytes);
+    for (const [path, bytes] of fonts)
+        files.set(path, bytes);
+    files.set(GRADE_REVIEW_PATH, renderGradeReview({ themeName: theme.name, themeCss, gradeCss, grades }));
+    return files;
+};
+const writeFiles = (outDir, files) => {
+    for (const [path, data] of files) {
+        const target = join(outDir, path);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, data);
+    }
+};
+const toErrors = (findings) => findings.map(({ path, message, suggestion }) => suggestion === undefined ? { path, message } : { path, message, suggestion });
+const runLint = (options, board, timeline, theme) => {
+    if (options.lint === false)
+        return { errors: [], warnings: [] };
+    const words = board.scenes.map((scene) => sceneWords(scene.props, scene.type));
+    return lintStoryboard({
+        storyboard: board,
+        timeline,
+        words,
+        theme,
+        ...(options.platforms === undefined ? {} : { platforms: options.platforms }),
+    });
+};
+const cachePlanOf = (cacheDir, theme, assetsDir, sharedCacheDir) => {
+    if (cacheDir === undefined)
+        return undefined;
+    return createCachePlan(cacheDir, theme, assetsDir, sharedCacheDir === undefined ? undefined : { sharedDir: sharedCacheDir });
+};
+/** Fail-closed gate for the opt-in narration mixdown; absent means silent. */
+const checkAudioManifest = (ref) => {
+    if (ref === undefined)
+        return { ok: true, value: undefined };
+    const clips = clipsFromManifest(ref.manifest, ref.audioDir);
+    if (clips.length === 0)
+        return fail("/audio", "audio manifest has no scenes; nothing to mix");
+    const missing = missingClips(clips, (path) => existsSync(path));
+    const first = missing[0];
+    if (first !== undefined) {
+        return fail(`/audio/${first.id}`, `missing narration wav for scene "${first.id}": ${first.wav}`);
+    }
+    return { ok: true, value: undefined };
+};
+const compile = (options) => {
+    const valid = validateStoryboardFull(options.storyboard);
+    if (!valid.ok)
+        return valid;
+    const board = valid.value;
+    const theme = themeOf(board.meta.theme, options.themes);
+    if (!theme.ok)
+        return theme;
+    const timeline = resolveTimeline(board, options.timing);
+    if (!timeline.ok)
+        return timeline;
+    const audio = checkAudioManifest(options.audioManifest);
+    if (!audio.ok)
+        return audio;
+    const lint = runLint(options, board, timeline.value, theme.value);
+    if (lint.errors.length > 0)
+        return { ok: false, errors: toErrors(lint.errors) };
+    const assets = createAssetCollector(options.assetsDir !== undefined);
+    const plan = cachePlanOf(options.cacheDir, theme.value, options.assetsDir, options.sharedCacheDir);
+    const emitted = emitAll(board, timeline.value, theme.value, assets, plan, options.platforms, options.customScenes);
+    if (!emitted.ok)
+        return emitted;
+    const copied = copyAssets(assets.refs(), options.assetsDir, options.ledger);
+    if (!copied.ok)
+        return copied;
+    const assetFiles = new Map(copied.assets.map((asset) => [asset.path, asset.bytes]));
+    const fonts = bundleFonts(fontFamiliesFor(theme.value.fonts));
+    const icons = [...new Set(emitted.value.flatMap((scene) => scene.icons))].sort();
+    const licences = [...fonts.licences, ...iconLedgerRows(icons), ...copied.licences];
+    const files = assemble(board, timeline.value, theme.value, emitted.value, assetFiles, fonts.files);
+    if (icons.length > 0)
+        files.set("LICENSE-lucide.txt", LUCIDE_LICENCE_TEXT);
+    files.set("licences.json", `${JSON.stringify(licences, null, 2)}
+`);
+    const manifest = createManifest(JSON.stringify(board), files, readVersions(), {
+        themeHash: sha256Of(canonicalJson(theme.value)),
+        ledgerSha256: options.ledger === undefined ? null : sha256Of(canonicalJson(options.ledger)),
+        sceneTypes: board.scenes.map((scene) => scene.type),
+        icons,
+        overlays: timeline.value.overlays.map(({ id, over, start, end }) => ({ id, over, start, end })),
+    });
+    files.set("manifest.json", renderManifest(manifest));
+    return {
+        ok: true,
+        value: {
+            files,
+            manifest,
+            licences,
+            warnings: lint.warnings,
+            ...(plan ? { cache: plan.stats } : {}),
+        },
+    };
+};
+/** storyboard -> validate -> theme -> timing -> lint -> assets -> emit -> HyperFrames project. */
+export const buildProject = (options) => {
+    const compiled = compile(options);
+    if (!compiled.ok)
+        return compiled;
+    const { files, manifest, licences, warnings, cache } = compiled.value;
+    writeFiles(options.outDir, files);
+    return {
+        ok: true,
+        outDir: options.outDir,
+        files: [...files.keys()].sort(),
+        manifest,
+        licences,
+        warnings,
+        ...(cache ? { cache } : {}),
+    };
+};

package/dist/cache.d.ts

@@ -0,0 +1,59 @@
+import type { EmitContext, ResolvedTheme, SceneEntry } from "@anvpx/motion-schema";
+/** Everything outside the scene itself that can change what a plugin emits. */
+export interface CacheSalt {
+    readonly themeHash: string;
+    readonly packages: Readonly<Record<string, string>>;
+    readonly hyperframes: string;
+    readonly nodeMajor: string;
+    /** Hash of the scenes package source: editing a plugin without a version bump invalidates. */
+    readonly scenesSource: string;
+}
+export interface CacheStats {
+    hits: number;
+    misses: number;
+}
+type Placement = Pick<EmitContext, "fps" | "width" | "height" | "duration" | "timeline" | "insets">;
+/** Emitted per-scene files plus the asset refs and icon names the plugin requested. */
+export interface CachedScene {
+    readonly files: Map<string, string>;
+    readonly refs: readonly string[];
+    readonly icons: readonly string[];
+}
+type HashAsset = (ref: string) => string;
+export interface SceneCache {
+    load(base: string, hash: HashAsset, prefix: string): CachedScene | undefined;
+    save(base: string, refs: readonly string[], hash: HashAsset, files: ReadonlyMap<string, string>, icons: readonly string[]): void;
+}
+export interface CachePlan {
+    readonly cache: SceneCache;
+    readonly salt: CacheSalt;
+    readonly hashAsset: HashAsset;
+    readonly stats: CacheStats;
+}
+/** Key of a scene before its assets are known: type, config (incl. overlay `over`/window), placement, salt. */
+export declare const baseKey: (entry: SceneEntry, ctx: Placement, salt: CacheSalt) => string;
+/** Final key: the base key plus the content hash of every asset the scene references. */
+export declare const fullKey: (base: string, assets: Readonly<Record<string, string>>) => string;
+/** Opt-in workspace-level sharing for the disk cache. Absent means per-storyboard only. */
+export interface DiskCacheOptions {
+    /** Directory of content-addressed entries shared across storyboards; best-effort on failure. */
+    readonly sharedDir?: string;
+    /** Largest single shared entry file accepted on read; a larger file is a miss. */
+    readonly maxSharedEntryBytes?: number;
+}
+/**
+ * Disk-backed cache; every failure degrades to a miss or a skipped store, never an error.
+ * With `sharedDir` set, entries are content-addressed (same salt plus config plus asset
+ * hashes yields the same keys), so two storyboards sharing a scene share its entries: load
+ * falls back to the shared dir and promotes hits locally, save writes through to both.
+ */
+export declare const createDiskCache: (dir: string, opts?: DiskCacheOptions) => SceneCache;
+/** Deletes cache files only (hex-named `.json`/`.refs` and their tmp files); returns how many. */
+export declare const clearCache: (dir: string) => number;
+export declare const createCachePlan: (dir: string, theme: ResolvedTheme, assetsDir: string | undefined, opts?: DiskCacheOptions) => CachePlan;
+/**
+ * Replays a cached scene (re-registering its asset refs) or emits and stores it. The icon names the
+ * scene drew go to `onIcons` either way, so a cache hit still reaches the licence ledger.
+ */
+export declare const emitCached: (plan: CachePlan, entry: SceneEntry, ctx: EmitContext, emit: (ctx: EmitContext) => Map<string, string>, onIcons?: (icons: readonly string[]) => void) => Map<string, string>;
+export {};