@anvpx/motion-build 0.0.0-stage → 0.1.0

package/dist/fonts.js

@@ -0,0 +1,112 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { sha256Of } from "./assets.js";
+/** Weights the scenes use for Inter (400 body default; 600/700/800 declared in scene styles). */
+export const FONT_WEIGHTS = [400, 600, 700, 800];
+export const FONTS_STYLESHEET = "fonts/fonts.css";
+const LICENCE = "OFL-1.1";
+/** Latin subset only; order here is the emission order (Inter first keeps default output stable). */
+export const FONT_FAMILIES = {
+    inter: {
+        name: "Inter",
+        weights: FONT_WEIGHTS,
+        sourceUrl: "https://github.com/fontsource/font-files/tree/main/fonts/google/inter",
+        attribution: "Inter, Copyright 2016 The Inter Project Authors (https://github.com/rsms/inter)",
+        licencePath: "fonts/LICENSE.txt",
+    },
+    "space-grotesk": {
+        name: "Space Grotesk",
+        weights: [500, 700],
+        sourceUrl: "https://github.com/fontsource/font-files/tree/main/fonts/google/space-grotesk",
+        attribution: "Space Grotesk, Copyright 2020 The Space Grotesk Project Authors (https://github.com/floriankarsten/space-grotesk)",
+        licencePath: "fonts/LICENSE-space-grotesk.txt",
+    },
+    "jetbrains-mono": {
+        name: "JetBrains Mono",
+        weights: [400, 600],
+        sourceUrl: "https://github.com/fontsource/font-files/tree/main/fonts/google/jetbrains-mono",
+        attribution: "JetBrains Mono, Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)",
+        licencePath: "fonts/LICENSE-jetbrains-mono.txt",
+    },
+    "source-serif-4": {
+        name: "Source Serif 4",
+        weights: [400, 600, 700],
+        sourceUrl: "https://github.com/fontsource/font-files/tree/main/fonts/google/source-serif-4",
+        attribution: "Source Serif 4, Copyright Google Inc. (per the @fontsource/source-serif-4 LICENSE; upstream design: https://github.com/adobe-fonts/source-serif), SIL OFL 1.1",
+        licencePath: "fonts/LICENSE-source-serif-4.txt",
+    },
+};
+const FAMILY_IDS = Object.keys(FONT_FAMILIES);
+const fontFace = (family, id, weight) => [
+    "@font-face {",
+    `  font-family: '${family}';`,
+    "  font-style: normal;",
+    `  font-weight: ${weight};`,
+    "  font-display: block;",
+    `  src: url(${id}-latin-${weight}.woff2) format('woff2');`,
+    "}",
+    "",
+].join("\n");
+const packageDir = (id) => {
+    const specifier = `@fontsource/${id}/LICENSE`;
+    try {
+        // Resolves from the installed @fontsource tree: when this module runs
+        // from @anvpx/motion-build/dist, Node finds build's @fontsource deps;
+        // when bundled into @anvpx/motion/dist, the same call finds core's
+        // @fontsource deps (declared as runtime deps of core). No relative
+        // source-tree path is used, so the lookup survives npm install.
+        return dirname(createRequire(import.meta.url).resolve(specifier));
+    }
+    catch (error) {
+        throw new Error(`cannot resolve "${specifier}" from the installed @fontsource tree ` +
+            `(is @fontsource/${id} installed alongside ${import.meta.url}?): ${error.message}`);
+    }
+};
+const row = (family, path, bytes) => ({
+    path,
+    sourceUrl: family.sourceUrl,
+    licence: LICENCE,
+    attribution: family.attribution,
+    sha256: sha256Of(bytes),
+});
+/** Families whose CSS name appears in a theme's font stacks; Inter (the base face) is always first. */
+export const fontFamiliesFor = (fonts) => {
+    const stacks = Object.values(fonts).join(",").toLowerCase();
+    return FAMILY_IDS.filter((id) => id === "inter" || stacks.includes(FONT_FAMILIES[id].name.toLowerCase()));
+};
+/** Per-file bytes and the total, for the build's size report. */
+export const fontSizeReport = (bundle) => {
+    const files = [...bundle.files]
+        .filter(([path]) => path.endsWith(".woff2"))
+        .map(([path, bytes]) => ({ path, bytes: bytes.byteLength }))
+        .sort((a, b) => (a.path < b.path ? -1 : 1));
+    return { files, totalBytes: files.reduce((sum, file) => sum + file.bytes, 0) };
+};
+/**
+ * Reads the pinned `@fontsource/*` latin subsets so renders never fetch fonts over the network.
+ * Pass only the families a theme uses (see `fontFamiliesFor`); the default is Inter alone.
+ */
+export const bundleFonts = (families = ["inter"]) => {
+    const unknown = families.filter((id) => FONT_FAMILIES[id] === undefined);
+    if (unknown.length > 0)
+        throw new Error(`unknown font family "${unknown.join('", "')}"`);
+    const wanted = FAMILY_IDS.filter((id) => families.includes(id));
+    const files = new Map();
+    const licences = [];
+    const faces = [];
+    for (const id of wanted) {
+        const family = FONT_FAMILIES[id];
+        const dir = packageDir(id);
+        for (const weight of family.weights) {
+            const path = `fonts/${id}-latin-${weight}.woff2`;
+            const bytes = readFileSync(join(dir, "files", `${id}-latin-${weight}-normal.woff2`));
+            files.set(path, bytes);
+            licences.push(row(family, path, bytes));
+            faces.push(fontFace(family.name, id, weight));
+        }
+        files.set(family.licencePath, readFileSync(join(dir, "LICENSE")));
+    }
+    files.set(FONTS_STYLESHEET, Buffer.from(faces.join("\n")));
+    return { files, licences };
+};

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export { CUSTOM_SCENE_TYPE, type CustomSceneFile, type CustomSceneSource, collectIcons, emitCustomScene, type FieldDoc, HELPER_LIMITS, iconGroups, iconLedgerRows, listIcons, type RelativeClosure, type RelativeImportScan, readRelativeClosure, resolveSceneDir, type SceneDirResult, type SceneDoc, scanRelativeImports, scanVendorImports, sceneDocs, sceneWords, searchIconNames, type VendorScan, } from "@anvpx/motion-scenes";
+export { bundledThemeDocs } from "@anvpx/motion-themes";
+export { type AssetCollector, type CopiedAsset, copyAssets, createAssetCollector, normaliseRef, sha256Of, } from "./assets.ts";
+export { type FrozenCopyCheck, frozenCopyProblems, } from "./audio/approval.ts";
+export { AT_TARGET_TOLERANCE_LU, AUDIO_DIR_NAME, type AudioManifestRef, type AudioManifestResult, buildFilterGraph, buildLoudnessMeasureArgs, buildLoudnessNormalizeArgs, buildLoudnessNormalizeFilter, buildMixArgs, buildMusicFilterGraph, buildMusicMixArgs, clipsFromManifest, DEFAULT_MUSIC_VOLUME, frozenClips, frozenMusic, frozenWavFor, isContiguous, LOUDNORM_MEASURE_FILTER, type LoudnessMeasurement, type MixClip, type MixDelivery, type MixDeliveryPlan, type MixRunner, type MixRunResult, type MusicBed, missingClips, missingMusic, mixAtDeliveryLevel, needsNormalization, parseAudioManifest, parseLoudnessMeasurement, resolveMusicVolume, TARGET_LRA, TARGET_LUFS, TARGET_TRUE_PEAK_DB, toDelayMs, wavPathFor, } from "./audio/mix.ts";
+export { type BuildOptions, type BuildResult, buildProject, tryResolveTheme, } from "./build.ts";
+export { type CacheStats, clearCache } from "./cache.ts";
+export { CSP } from "./emit/index-html.ts";
+export { bundleFonts, FONT_FAMILIES, type FontFamilyId } from "./fonts.ts";
+export { type CustomSourceInput, lintCustomSource } from "./lint/custom-source.ts";
+export { type LintFinding, type LintResult, lintStoryboard, type PlatformMarginLookup, type PlatformMargins, } from "./lint/index.ts";
+export { MIN_HOLD_SECONDS } from "./lint/min-hold.ts";
+export { WORDS_PER_SECOND } from "./lint/reading-time.ts";
+export { type BuildManifest, type CompiledAssetView, compiledAssetMismatches, } from "./manifest.ts";
+export { createRenderManifest, type RenderManifest, type RenderManifestInput, renderRenderManifest, } from "./render-manifest.ts";
+export * from "./templates/index.ts";
+export { autoDuration, resolveTimeline, type TimedScene, type Timeline, } from "./timing.ts";
+export { validateStoryboardFull } from "./validate-full.ts";
+export { type FindingLevel, type MediaExpectation, type VerifyFinding, type VerifyInput, type VerifyReport, type VerifyStatus, verifyMedia, } from "./verify.ts";

package/dist/index.js

@@ -0,0 +1,19 @@
+export { CUSTOM_SCENE_TYPE, collectIcons, emitCustomScene, HELPER_LIMITS, iconGroups, iconLedgerRows, listIcons, readRelativeClosure, resolveSceneDir, scanRelativeImports, scanVendorImports, sceneDocs, sceneWords, searchIconNames, } from "@anvpx/motion-scenes";
+export { bundledThemeDocs } from "@anvpx/motion-themes";
+export { copyAssets, createAssetCollector, normaliseRef, sha256Of, } from "./assets.js";
+export { frozenCopyProblems, } from "./audio/approval.js";
+export { AT_TARGET_TOLERANCE_LU, AUDIO_DIR_NAME, buildFilterGraph, buildLoudnessMeasureArgs, buildLoudnessNormalizeArgs, buildLoudnessNormalizeFilter, buildMixArgs, buildMusicFilterGraph, buildMusicMixArgs, clipsFromManifest, DEFAULT_MUSIC_VOLUME, frozenClips, frozenMusic, frozenWavFor, isContiguous, LOUDNORM_MEASURE_FILTER, missingClips, missingMusic, mixAtDeliveryLevel, needsNormalization, parseAudioManifest, parseLoudnessMeasurement, resolveMusicVolume, TARGET_LRA, TARGET_LUFS, TARGET_TRUE_PEAK_DB, toDelayMs, wavPathFor, } from "./audio/mix.js";
+export { buildProject, tryResolveTheme, } from "./build.js";
+export { clearCache } from "./cache.js";
+export { CSP } from "./emit/index-html.js";
+export { bundleFonts, FONT_FAMILIES } from "./fonts.js";
+export { lintCustomSource } from "./lint/custom-source.js";
+export { lintStoryboard, } from "./lint/index.js";
+export { MIN_HOLD_SECONDS } from "./lint/min-hold.js";
+export { WORDS_PER_SECOND } from "./lint/reading-time.js";
+export { compiledAssetMismatches, } from "./manifest.js";
+export { createRenderManifest, renderRenderManifest, } from "./render-manifest.js";
+export * from "./templates/index.js";
+export { autoDuration, resolveTimeline, } from "./timing.js";
+export { validateStoryboardFull } from "./validate-full.js";
+export { verifyMedia, } from "./verify.js";

package/dist/integration/render.integration.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/integration/render.integration.js

@@ -0,0 +1,162 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { afterAll, describe, expect, it } from "vitest";
+import { buildProject } from "../build.js";
+import { resolveTimeline } from "../timing.js";
+import { validateStoryboardFull } from "../validate-full.js";
+import { verifyMedia } from "../verify.js";
+const path = (relative) => fileURLToPath(new URL(relative, import.meta.url));
+const OUT = path("../../dist/.out");
+const PROJECT = `${OUT}/demo`;
+const SNAPSHOTS = `${OUT}/snap`;
+const CLI = path("../../../../node_modules/hyperframes/dist/cli.js");
+const MIN_PNG_BYTES = 10_000;
+const storyboard = JSON.parse(readFileSync(path("../../fixtures/demo.storyboard.json"), "utf8"));
+const hyperframes = (args, cwd = PROJECT) => spawnSync(process.execPath, [CLI, ...args], { cwd, encoding: "utf8" });
+const md5 = (file) => createHash("md5").update(readFileSync(file)).digest("hex");
+const sceneMoments = () => {
+    const valid = validateStoryboardFull(storyboard);
+    if (!valid.ok)
+        throw new Error("fixture invalid");
+    const timeline = resolveTimeline(valid.value);
+    if (!timeline.ok)
+        throw new Error("fixture timeline invalid");
+    return timeline.value.scenes.map((scene) => Math.round((scene.start + scene.duration * 0.6) * 100) / 100);
+};
+const timed = (run) => {
+    const began = performance.now();
+    const value = run();
+    return { value, seconds: Math.round((performance.now() - began) / 100) / 10 };
+};
+describe("real HyperFrames end to end", () => {
+    // HyperFrames writes JSON reports here; they are not source and must not reach `biome check`.
+    afterAll(() => rmSync(`${PROJECT}/.hyperframes`, { recursive: true, force: true }));
+    rmSync(PROJECT, { recursive: true, force: true });
+    rmSync(SNAPSHOTS, { recursive: true, force: true });
+    mkdirSync(OUT, { recursive: true });
+    const built = buildProject({ storyboard, outDir: PROJECT });
+    it("builds the fixture project", () => {
+        expect(built.ok).toBe(true);
+    });
+    it("hyperframes check exits 0", () => {
+        const run = hyperframes(["check", "."]);
+        expect(run.status, run.stdout + run.stderr).toBe(0);
+        expect(run.stdout).toContain("Check passed");
+    });
+    it("snapshots one non-blank frame inside each of the 5 scenes", () => {
+        const moments = sceneMoments();
+        expect(moments).toHaveLength(5);
+        const run = hyperframes([
+            "snapshot",
+            ".",
+            "--at",
+            moments.join(","),
+            "--no-end",
+            "-o",
+            SNAPSHOTS,
+        ]);
+        expect(run.status, run.stdout + run.stderr).toBe(0);
+        for (const [index, moment] of moments.entries()) {
+            const file = `${SNAPSHOTS}/frame-0${index}-at-${moment}s.png`;
+            expect(existsSync(file), file).toBe(true);
+            expect(statSync(file).size, file).toBeGreaterThan(MIN_PNG_BYTES);
+        }
+    });
+    it("two draft renders (15 fps) are byte-identical", () => {
+        const render = (name) => timed(() => hyperframes([
+            "render",
+            ".",
+            "-o",
+            `${OUT}/${name}`,
+            "--fps",
+            "15",
+            "--quality",
+            "draft",
+            "--quiet",
+        ]));
+        const first = render("draft1.mp4");
+        const second = render("draft2.mp4");
+        expect(first.value.status, first.value.stderr).toBe(0);
+        expect(second.value.status, second.value.stderr).toBe(0);
+        const report = {
+            renderSeconds: [first.seconds, second.seconds],
+            md5: [md5(`${OUT}/draft1.mp4`), md5(`${OUT}/draft2.mp4`)],
+        };
+        writeFileSync(`${OUT}/integration-report.json`, `${JSON.stringify(report, null, 2)}\n`);
+        expect(report.md5[0]).toBe(report.md5[1]);
+    });
+    it("verifyMedia PASSes the real 15 fps draft against the resolved timeline", () => {
+        const valid = validateStoryboardFull(storyboard);
+        if (!valid.ok)
+            throw new Error("fixture invalid");
+        const timeline = resolveTimeline(valid.value);
+        if (!timeline.ok)
+            throw new Error("fixture timeline invalid");
+        const probe = spawnSync("ffprobe", ["-v", "error", "-show_streams", "-show_format", "-of", "json", `${OUT}/draft1.mp4`], { encoding: "utf8" });
+        expect(probe.status, probe.stderr).toBe(0);
+        const { width, height } = valid.value.meta;
+        const report = verifyMedia({
+            probe: JSON.parse(probe.stdout),
+            expect: { width, height, fps: 15, duration: timeline.value.total },
+        });
+        expect(report, JSON.stringify(report)).toMatchObject({ status: "PASS" });
+    });
+});
+const OVERLAY_PROJECT = `${OUT}/demo-overlays`;
+const OVERLAY_SNAPSHOTS = `${OUT}/snap-overlays`;
+const BASE_SNAPSHOTS = `${OUT}/snap-base`;
+/** Inside an overlay window of the fixture: lower-third, chapter, bug + countdown, progress. */
+const OVERLAY_MOMENTS = [2.5, 7, 16.5, 24];
+/** Base scene only (signals, no overlay): both builds must match here. */
+const QUIET_MOMENT = 12;
+const overlayStoryboard = JSON.parse(readFileSync(path("../../fixtures/demo-overlays.storyboard.json"), "utf8"));
+const snapshots = (project, outDir, moments) => hyperframes(["snapshot", ".", "--at", moments.join(","), "--no-end", "-o", outDir], project);
+const stillAt = (dir, index, moment) => `${dir}/frame-0${index}-at-${moment}s.png`;
+describe("real HyperFrames end to end with overlays", () => {
+    afterAll(() => rmSync(`${OVERLAY_PROJECT}/.hyperframes`, { recursive: true, force: true }));
+    rmSync(OVERLAY_PROJECT, { recursive: true, force: true });
+    rmSync(OVERLAY_SNAPSHOTS, { recursive: true, force: true });
+    rmSync(BASE_SNAPSHOTS, { recursive: true, force: true });
+    mkdirSync(OUT, { recursive: true });
+    const built = buildProject({ storyboard: overlayStoryboard, outDir: OVERLAY_PROJECT });
+    it("builds the overlay fixture and hyperframes check exits 0", () => {
+        expect(built.ok).toBe(true);
+        const run = hyperframes(["check", "."], OVERLAY_PROJECT);
+        expect(run.status, run.stdout + run.stderr).toBe(0);
+        expect(run.stdout).toContain("Check passed");
+    });
+    it("stills inside overlay windows differ from the base-only build; quiet frames match", () => {
+        const moments = [...OVERLAY_MOMENTS, QUIET_MOMENT];
+        const withOverlays = snapshots(OVERLAY_PROJECT, OVERLAY_SNAPSHOTS, moments);
+        expect(withOverlays.status, withOverlays.stdout + withOverlays.stderr).toBe(0);
+        const baseOnly = snapshots(PROJECT, BASE_SNAPSHOTS, moments);
+        expect(baseOnly.status, baseOnly.stdout + baseOnly.stderr).toBe(0);
+        for (const [index, moment] of moments.entries()) {
+            const file = stillAt(OVERLAY_SNAPSHOTS, index, moment);
+            expect(statSync(file).size, file).toBeGreaterThan(MIN_PNG_BYTES);
+            const same = md5(file) === md5(stillAt(BASE_SNAPSHOTS, index, moment));
+            expect(same, `frame at ${moment}s`).toBe(moment === QUIET_MOMENT);
+        }
+    });
+    it("verifyMedia PASSes a 15 fps draft: overlays do not change the base duration", () => {
+        const out = `${OUT}/draft-overlays.mp4`;
+        const run = hyperframes(["render", ".", "-o", out, "--fps", "15", "--quality", "draft", "--quiet"], OVERLAY_PROJECT);
+        expect(run.status, run.stderr).toBe(0);
+        const valid = validateStoryboardFull(overlayStoryboard);
+        if (!valid.ok)
+            throw new Error("fixture invalid");
+        const timeline = resolveTimeline(valid.value);
+        if (!timeline.ok)
+            throw new Error("fixture timeline invalid");
+        const probe = spawnSync("ffprobe", ["-v", "error", "-show_streams", "-show_format", "-of", "json", out], { encoding: "utf8" });
+        expect(probe.status, probe.stderr).toBe(0);
+        const { width, height } = valid.value.meta;
+        const report = verifyMedia({
+            probe: JSON.parse(probe.stdout),
+            expect: { width, height, fps: 15, duration: timeline.value.total },
+        });
+        expect(report, JSON.stringify(report)).toMatchObject({ status: "PASS" });
+    });
+});

package/dist/lint/custom-source.d.ts

@@ -0,0 +1,12 @@
+import type { LintFinding } from "./types.ts";
+/** Files of an authored (`type: "custom"`) scene, as read by the caller. */
+export interface CustomSourceInput {
+    readonly js: string;
+    readonly css?: string;
+    readonly html?: string;
+}
+/**
+ * Determinism and safety lint for an authored scene: one finding per rule and file,
+ * pointing at the first offending line. Pure, so the CLI can run it before a build.
+ */
+export declare const lintCustomSource: (input: CustomSourceInput, dir: string) => LintFinding[];

package/dist/lint/custom-source.js

@@ -0,0 +1,130 @@
+const PROBES = [
+    {
+        file: "scene.js",
+        pattern: /\bDate\.now\s*\(/,
+        message: "Date.now is a wall clock",
+        suggestion: "derive the value from the t argument",
+    },
+    {
+        file: "scene.js",
+        pattern: /\bperformance\.now\s*\(/,
+        message: "performance.now is a wall clock",
+        suggestion: "derive the value from the t argument",
+    },
+    {
+        file: "scene.js",
+        pattern: /\bnew\s+Date\s*\(\s*\)/,
+        message: "new Date() reads the wall clock",
+        suggestion: "pass an explicit timestamp, or derive from t",
+    },
+    {
+        file: "scene.js",
+        pattern: /\brequestAnimationFrame\s*\(/,
+        message: "requestAnimationFrame drives its own clock",
+        suggestion: "animate from seek(t); the renderer owns the clock",
+    },
+    {
+        file: "scene.js",
+        pattern: /\bMath\.random\s*\(/,
+        message: "Math.random is unseeded",
+        suggestion: "use a seeded generator so every frame repeats",
+    },
+    {
+        file: "scene.js",
+        pattern: /\bset(?:Timeout|Interval)\s*\(/,
+        message: "a timer is not a frame clock",
+        suggestion: "derive the value from t",
+    },
+    {
+        file: "scene.js",
+        pattern: /\bfetch\s*\(|\bXMLHttpRequest\b|\bnew\s+WebSocket\b/,
+        message: "network access is blocked at render",
+        suggestion: "inline the data into props or the scene",
+    },
+    {
+        file: "scene.js",
+        pattern: /\bnew\s+Worker\s*\(/,
+        message: "workers are blocked at render",
+        suggestion: "keep the work on the main thread inside seek(t)",
+    },
+    {
+        file: "scene.js",
+        pattern: /\bwindow\./,
+        message: "window is reserved by the renderer",
+        suggestion: "use the root element and the props you were given",
+    },
+    {
+        file: "style.css",
+        pattern: /(^|[\s;{])animation(?:-name)?\s*:/,
+        message: "a CSS animation runs on the browser clock",
+        suggestion: "set the property from seek(t) instead",
+    },
+    {
+        file: "style.css",
+        pattern: /(^|[\s;{])transition\s*:/,
+        message: "a CSS transition runs on the browser clock",
+        suggestion: "set the property from seek(t) instead",
+    },
+    {
+        file: "style.css",
+        pattern: /@keyframes\b/,
+        message: "@keyframes runs on the browser clock",
+        suggestion: "set the property from seek(t) instead",
+    },
+    {
+        file: "style.css",
+        pattern: /url\(\s*['"]?https?:/i,
+        message: "external stylesheet URL",
+        suggestion: "inline the asset; the render has no network",
+    },
+    {
+        file: "fragment.html",
+        pattern: /<script\b/i,
+        message: "fragment contains a script tag",
+        suggestion: "put code in scene.js",
+    },
+    {
+        file: "fragment.html",
+        pattern: /\son[a-z]+\s*=/i,
+        message: "fragment contains an inline event handler",
+        suggestion: "attach behaviour from scene.js",
+    },
+];
+/** Blanks a span while preserving newlines, so reported line numbers stay true. */
+const blank = (text) => text.replace(/[^\n]/g, " ");
+const stripJs = (source) => source.replace(/\/\*[\s\S]*?\*\//g, blank).replace(/\/\/[^\n]*/g, blank);
+const stripCss = (source) => source.replace(/\/\*[\s\S]*?\*\//g, blank);
+const stripHtml = (source) => source.replace(/<!--[\s\S]*?-->/g, blank);
+const sourceOf = (input, file) => {
+    const raw = file === "scene.js" ? input.js : file === "style.css" ? input.css : input.html;
+    if (raw === undefined)
+        return undefined;
+    // Comments describe the rules ("no window.") and must not trip them.
+    return file === "scene.js" ? stripJs(raw) : file === "style.css" ? stripCss(raw) : stripHtml(raw);
+};
+/** First offending line of one file, as a finding path of `<dir>/<file>:<line>`. */
+const scan = (input, probe, dir) => {
+    const source = sourceOf(input, probe.file);
+    if (source === undefined)
+        return undefined;
+    const lines = source.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+        if (!probe.pattern.test(lines[index] ?? ""))
+            continue;
+        return {
+            severity: "error",
+            path: `${dir}/${probe.file}:${index + 1}`,
+            message: probe.message,
+            suggestion: probe.suggestion,
+        };
+    }
+    return undefined;
+};
+/**
+ * Determinism and safety lint for an authored scene: one finding per rule and file,
+ * pointing at the first offending line. Pure, so the CLI can run it before a build.
+ */
+export const lintCustomSource = (input, dir) => PROBES.flatMap((probe) => {
+    const finding = scan(input, probe, dir);
+    return finding === undefined ? [] : [finding];
+});

package/dist/lint/fixtures.d.ts

@@ -0,0 +1,24 @@
+import type { LintInput } from "./types.ts";
+export interface SceneSpec {
+    readonly id?: string;
+    readonly type?: string;
+    readonly props?: Record<string, unknown>;
+    readonly duration?: number;
+    readonly transition?: string;
+    readonly layer?: "base" | "overlay";
+    readonly over?: string;
+    readonly offset?: number;
+    readonly narration?: string;
+    readonly ease?: string;
+    readonly move?: string;
+    /** Shorthand for `props.caption` (timed speech; craft type rules ignore it). */
+    readonly caption?: string;
+    /** Shorthand for `props.spacing` (explicit author spacing input; off-grid rule checks it). */
+    readonly spacing?: number | string;
+}
+export interface FrameSpec {
+    readonly width: number;
+    readonly height: number;
+}
+/** Builds a LintInput from loose scene specs (test helper); frame defaults to 1920x1080. */
+export declare const lintInput: (specs: readonly SceneSpec[], frame?: FrameSpec) => LintInput;

package/dist/lint/fixtures.js

@@ -0,0 +1,42 @@
+import { sceneWords } from "@anvpx/motion-scenes";
+import { resolveTimeline } from "../timing.js";
+const OPTIONAL_KEYS = [
+    "duration",
+    "transition",
+    "layer",
+    "over",
+    "offset",
+    "narration",
+    "ease",
+    "move",
+];
+const optional = (spec) => Object.fromEntries(OPTIONAL_KEYS.filter((key) => spec[key] !== undefined).map((key) => [key, spec[key]]));
+/** Builds a LintInput from loose scene specs (test helper); frame defaults to 1920x1080. */
+export const lintInput = (specs, frame = { width: 1920, height: 1080 }) => {
+    const storyboard = {
+        version: 1,
+        meta: { title: "T", fps: 30, ...frame, theme: "default" },
+        scenes: specs.map((spec, index) => {
+            const shorthand = {};
+            if (spec.caption !== undefined)
+                shorthand.caption = spec.caption;
+            if (spec.spacing !== undefined)
+                shorthand.spacing = spec.spacing;
+            return {
+                id: spec.id ?? `s${index + 1}`,
+                type: spec.type ?? "title",
+                // Explicit props win over the caption/spacing shorthands.
+                props: { ...shorthand, ...(spec.props ?? { title: "Hello" }) },
+                ...optional(spec),
+            };
+        }),
+    };
+    const timeline = resolveTimeline(storyboard);
+    if (!timeline.ok)
+        throw new Error("fixture timeline must resolve");
+    return {
+        storyboard,
+        timeline: timeline.value,
+        words: storyboard.scenes.map((scene) => sceneWords(scene.props, scene.type)),
+    };
+};

package/dist/lint/flow.d.ts

@@ -0,0 +1,12 @@
+import type { LintRule } from "./types.ts";
+/** Minimum on-screen text size (px) of a node label. */
+export declare const MIN_FLOW_TEXT_PX = 28;
+/** A word wider than its node would be cut mid-word: shorten it or give the nodes room. */
+export declare const flowWordBreakRule: LintRule;
+/**
+ * An edge label that still touches something after placement: a card or another label is an
+ * error, a crossing edge a warning (the label's halo keeps it readable).
+ */
+export declare const flowEdgeLabelRule: LintRule;
+/** Too many or too long nodes force the labels under the legible minimum (or off the card). */
+export declare const flowTextSizeRule: LintRule;

package/dist/lint/flow.js

@@ -0,0 +1,38 @@
+import { inspectFlow } from "@anvpx/motion-scenes";
+/** Minimum on-screen text size (px) of a node label. */
+export const MIN_FLOW_TEXT_PX = 28;
+/** Layout report of every base `flow` scene; scenes whose props are not a flow graph are skipped. */
+const flowScenes = ({ storyboard }) => storyboard.scenes.flatMap((scene, index) => {
+    if (scene.type !== "flow" || scene.layer === "overlay")
+        return [];
+    const report = inspectFlow(scene.props, storyboard.meta);
+    return report === undefined ? [] : [{ index, report }];
+});
+/** A word wider than its node would be cut mid-word: shorten it or give the nodes room. */
+export const flowWordBreakRule = (input) => flowScenes(input).flatMap(({ index, report }) => report.wordBreaks.map((hit) => ({
+    severity: "error",
+    path: `/scenes/${index}/props/nodes/${hit.node}/label`,
+    message: `word "${hit.word}" is wider than node "${hit.id}"; it would break mid-word`,
+    suggestion: 'shorten the word, use fewer nodes or direction "tb"',
+})));
+/**
+ * An edge label that still touches something after placement: a card or another label is an
+ * error, a crossing edge a warning (the label's halo keeps it readable).
+ */
+export const flowEdgeLabelRule = (input) => flowScenes(input).flatMap(({ index, report }) => report.labelOverlaps.map((hit) => ({
+    severity: hit.hard ? "error" : "warning",
+    path: `/scenes/${index}/props/edges/${hit.edge}/label`,
+    message: `edge label overlaps ${hit.with.join(", ")}`,
+    suggestion: "shorten the label, drop it, or use fewer nodes",
+})));
+/** Too many or too long nodes force the labels under the legible minimum (or off the card). */
+export const flowTextSizeRule = (input) => flowScenes(input).flatMap(({ index, report }) => report.crowded || report.font < MIN_FLOW_TEXT_PX
+    ? [
+        {
+            severity: "error",
+            path: `/scenes/${index}/props/nodes`,
+            message: `node text does not fit at ${MIN_FLOW_TEXT_PX}px: too many or too long labels`,
+            suggestion: 'use fewer nodes, shorter labels or direction "tb"',
+        },
+    ]
+    : []);

package/dist/lint/frame.d.ts

@@ -0,0 +1,3 @@
+import type { Storyboard } from "@anvpx/motion-schema";
+/** True for portrait frames (9:16 and any taller-than-wide format). */
+export declare const isPortrait: (meta: Storyboard["meta"]) => boolean;

package/dist/lint/frame.js

@@ -0,0 +1,2 @@
+/** True for portrait frames (9:16 and any taller-than-wide format). */
+export const isPortrait = (meta) => meta.height > meta.width;

package/dist/lint/hook-first.d.ts

@@ -0,0 +1,6 @@
+import type { LintRule } from "./types.ts";
+/**
+ * 9:16 only: the first base scene must open with a title or hook; the base timeline starts at
+ * 0 s, inside the 2 s window. A "social" style tag does not exist in storyboards yet.
+ */
+export declare const hookFirstRule: LintRule;

package/dist/lint/hook-first.js

@@ -0,0 +1,27 @@
+import { isPortrait } from "./frame.js";
+/** Props that carry a hook line in the first scene. */
+const HOOK_KEYS = ["title", "headline", "heading", "text", "value"];
+const hasText = (props) => HOOK_KEYS.some((key) => {
+    const value = props[key];
+    return (typeof value === "string" && value.trim() !== "") || typeof value === "number";
+});
+/**
+ * 9:16 only: the first base scene must open with a title or hook; the base timeline starts at
+ * 0 s, inside the 2 s window. A "social" style tag does not exist in storyboards yet.
+ */
+export const hookFirstRule = ({ storyboard }) => {
+    if (!isPortrait(storyboard.meta))
+        return [];
+    const index = storyboard.scenes.findIndex((scene) => scene.layer !== "overlay");
+    const first = storyboard.scenes[index];
+    if (first === undefined || hasText(first.props))
+        return [];
+    return [
+        {
+            severity: "warning",
+            path: `/scenes/${index}/props`,
+            message: `first scene "${first.id}" has no title or hook text within the first 2s`,
+            suggestion: "open with a title scene or add a title line",
+        },
+    ];
+};