@anvpx/motion-cli 0.0.0-stage → 0.1.1

package/dist/state/command.js

@@ -0,0 +1,128 @@
+import { resolve } from "node:path";
+import { parseFlags, requireStoryboard, textFlag, usageError, } from "../args.js";
+import { EXIT } from "../exit-codes.js";
+import { deriveState, gatherEvidence } from "./evidence.js";
+const USAGE = `mk state <storyboard.json> [--out <dir>] [--render <dir>] [--assets <dir>] [--ledger <assets.json>] [--audio <manifest>] [--music <bed.wav>] [--music-volume <n>] [--music-license <file>] [--json]
+
+Report the highest project state the artifacts prove; read-only, never writes.
+  --out <dir>       preview pack base (default <storyboard dir>/out)
+  --render <dir>  render output dir (default <storyboard dir>/out/project); one manifest per dir
+  --assets <dir>    the --assets used with \`mk preview\`/\`mk approve\`
+  --ledger <file>   the --ledger used with \`mk preview\`/\`mk approve\`
+  --audio <manifest>  the --audio used with \`mk preview\`/\`mk approve\`
+  --music <bed.wav>   the --music used with \`mk preview\`/\`mk approve\`
+  --music-volume <n>  the --music-volume used with \`mk preview\`/\`mk approve\`
+  --music-license <file>  the --music-license used with \`mk preview\`/\`mk approve\`
+  --json            one compact line {state, next, missing, problems, evidence}
+Exit 0 consistent; 1 an artifact claims more than the evidence; 2 usage, invalid storyboard or unreadable inputs.
+`;
+const FLAGS = {
+    out: { type: "string" },
+    render: { type: "string" },
+    assets: { type: "string" },
+    ledger: { type: "string" },
+    audio: { type: "string" },
+    music: { type: "string" },
+    "music-volume": { type: "string" },
+    "music-license": { type: "string" },
+    json: { type: "boolean" },
+};
+const MAX_PROBLEM_LINES = 3;
+/** The state word, the one missing artifact, then at most three problem lines. */
+function formatText(report) {
+    const lines = [report.state];
+    if (report.next !== null)
+        lines.push(`missing: ${report.next}`);
+    for (const problem of report.problems.slice(0, MAX_PROBLEM_LINES)) {
+        lines.push(`problem: ${problem.code} ${problem.message}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function isExit(value) {
+    return typeof value === "object" && value !== null && value.kind === "exit";
+}
+/** `--music-volume` as a number in (0, 1], or the usage exit. */
+function musicVolumeOf(flags, io) {
+    const raw = textFlag(flags, "music-volume");
+    if (raw === undefined)
+        return {};
+    const volume = Number(raw);
+    if (!Number.isFinite(volume) || volume <= 0 || volume > 1) {
+        return usageError("state", USAGE, "--music-volume must be within (0, 1]", io);
+    }
+    return { volume };
+}
+/** `--music` needs `--audio`; its volume/license need `--music`. */
+function musicDependency(flags, io) {
+    const music = textFlag(flags, "music");
+    if (music === undefined) {
+        return textFlag(flags, "music-volume") === undefined &&
+            textFlag(flags, "music-license") === undefined
+            ? undefined
+            : usageError("state", USAGE, "--music-volume/--music-license need --music", io);
+    }
+    return textFlag(flags, "audio") === undefined
+        ? usageError("state", USAGE, "--music needs --audio", io)
+        : undefined;
+}
+/** The same approval input scope `mk approve` used; without it vendored assets cannot resolve. */
+function approvalOptions(flags, io) {
+    const volume = musicVolumeOf(flags, io);
+    if (isExit(volume))
+        return volume;
+    const dependency = musicDependency(flags, io);
+    if (dependency !== undefined)
+        return dependency;
+    const assets = textFlag(flags, "assets");
+    const ledger = textFlag(flags, "ledger");
+    const audio = textFlag(flags, "audio");
+    const music = textFlag(flags, "music");
+    const license = textFlag(flags, "music-license");
+    const options = {};
+    if (assets !== undefined)
+        options.assetsDir = resolve(assets);
+    if (ledger !== undefined)
+        options.ledgerPath = ledger;
+    if (audio !== undefined)
+        options.audioManifest = audio;
+    if (music !== undefined)
+        options.music = music;
+    if (volume.volume !== undefined)
+        options.musicVolume = volume.volume;
+    if (license !== undefined)
+        options.musicLicense = license;
+    return options;
+}
+/** Unreadable inputs are undecidable (exit 2); a render overclaim is a contradiction (exit 1). */
+function exitFor(report) {
+    if (report.problems.some((problem) => problem.code === "inputs-unreadable"))
+        return EXIT.USAGE;
+    return report.problems.length > 0 ? EXIT.ERROR : EXIT.OK;
+}
+export const stateCommand = {
+    name: "state",
+    summary: "report the highest project state the artifacts prove; flags overclaims",
+    async run(args, io) {
+        const parsed = parseFlags("state", USAGE, args, FLAGS, io);
+        if (parsed.kind === "exit")
+            return parsed.code;
+        const storyboard = requireStoryboard("state", USAGE, parsed.positionals, io);
+        if (isExit(storyboard))
+            return storyboard.code;
+        const approval = approvalOptions(parsed.flags, io);
+        if (isExit(approval))
+            return approval.code;
+        const gathered = await gatherEvidence(io, storyboard, {
+            out: textFlag(parsed.flags, "out"),
+            render: textFlag(parsed.flags, "render"),
+            approval,
+        });
+        if (!gathered.ok) {
+            io.stderr(`mk state: ${gathered.message.trimEnd()}\n`);
+            return EXIT.USAGE;
+        }
+        const report = deriveState(gathered.facts);
+        io.stdout(parsed.flags.json === true ? `${JSON.stringify(report)}\n` : formatText(report));
+        return exitFor(report);
+    },
+};

package/dist/state/evidence.d.ts

@@ -0,0 +1,71 @@
+import { type ApprovalState } from "../approval/approval.ts";
+import type { ApprovalBuildOptions } from "../approval/hash.ts";
+import type { Io } from "../types.ts";
+/** The highest state a project has current evidence for. */
+export type ProjectState = "storyboard" | "previewed" | "approved" | "rendered" | "verified";
+/** The next missing artifact, one word. */
+export type NextState = "preview" | "approval" | "render" | "verify";
+export type Presence = "missing" | "stale" | "current";
+export type ApprovalEvidence = ApprovalState["state"];
+export type VerifyEvidence = "PASS" | "not-run" | "unknown";
+export type ProblemCode = "render-output-missing" | "render-output-mismatch" | "render-unapproved" | "verify-claim-unsupported" | "inputs-unreadable";
+export interface Problem {
+    readonly code: ProblemCode;
+    readonly message: string;
+}
+export interface Evidence {
+    readonly storyboard: string;
+    readonly preview: Presence;
+    readonly approval: ApprovalEvidence;
+    readonly render: Presence;
+    readonly verify: VerifyEvidence;
+}
+export interface StateReport {
+    readonly state: ProjectState;
+    readonly next: NextState | null;
+    readonly missing: readonly NextState[];
+    readonly problems: readonly Problem[];
+    readonly evidence: Evidence;
+}
+/** A render manifest we understand: recorded output plus what is actually on disk. */
+export interface RenderFacts {
+    readonly file: string;
+    readonly recordedSha256: string;
+    readonly diskSha256?: string;
+    /** `storyboardSha256` of the build manifest; absent when it is missing or unparsable. */
+    readonly buildStoryboardSha256?: string;
+    readonly verify: string;
+}
+/** Already-read facts; `deriveState` is pure so every combination is testable without files. */
+export interface EvidenceFacts {
+    readonly storyboardSha256: string;
+    /** The hash a build would record: `sha256(JSON.stringify(board))`, so whitespace is not identity. */
+    readonly storyboardCanonicalSha256: string;
+    /** The approval hash the current inputs resolve to; absent when they cannot be read. */
+    readonly currentHash?: string;
+    /** `inputManifestSha256` recorded by the preview pack. */
+    readonly previewSha256?: string;
+    readonly approval: ApprovalEvidence;
+    readonly render?: RenderFacts;
+    /** Short, path-free reason the approval inputs could not be resolved. */
+    readonly unreadable?: string;
+}
+/** Derives the state, the next missing artifact and every overclaim from already-read facts. */
+export declare function deriveState(facts: EvidenceFacts): StateReport;
+export interface StateOptions {
+    /** Preview pack base; default `<storyboard dir>/out`. */
+    readonly out?: string;
+    /** Render output dir; default `<out>/project`. */
+    readonly render?: string;
+    /** The same approval input scope `mk approve` used (`--assets`, `--ledger`, audio, music). */
+    readonly approval?: ApprovalBuildOptions;
+}
+export type GatherResult = {
+    readonly ok: true;
+    readonly facts: EvidenceFacts;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** Reads every artifact once; validation failures and unreadable inputs are exit-2 values. */
+export declare function gatherEvidence(io: Io, storyboard: string, options?: StateOptions): Promise<GatherResult>;

package/dist/state/evidence.js

@@ -0,0 +1,243 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { validateStoryboardFull } from "@anvpx/motion-build";
+import { approvalState } from "../approval/approval.js";
+import { defaultOut, previewManifestPath } from "../preview/manifest.js";
+import { checkStoryboard } from "../storyboard/check.js";
+import { readJsonFile } from "../storyboard/load.js";
+import { formatFindings } from "../storyboard/report.js";
+import { RENDER_MANIFEST } from "../workflow/provenance.js";
+/** `<render>/manifest.json`: the build manifest, the only artifact that names its storyboard. */
+const BUILD_MANIFEST = "manifest.json";
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+const NEXT = {
+    storyboard: "preview",
+    previewed: "approval",
+    approved: "render",
+    rendered: "verify",
+    verified: null,
+};
+const previewEvidence = (facts) => {
+    if (facts.previewSha256 === undefined || facts.currentHash === undefined)
+        return "missing";
+    return facts.previewSha256 === facts.currentHash ? "current" : "stale";
+};
+/** Current only when the output holds AND the build manifest attributes it to this storyboard. */
+const renderEvidence = (render, canonical) => {
+    if (render === undefined)
+        return "missing";
+    if (render.diskSha256 !== render.recordedSha256)
+        return "stale";
+    return render.buildStoryboardSha256 === canonical ? "current" : "stale";
+};
+const verifyEvidence = (render, supported) => {
+    if (render === undefined)
+        return "unknown";
+    if (render.verify === "PASS")
+        return supported ? "PASS" : "unknown";
+    return render.verify === "not-run" ? "not-run" : "unknown";
+};
+const renderProblems = (facts, supported) => {
+    const render = facts.render;
+    if (render === undefined)
+        return [];
+    const problems = [];
+    if (render.diskSha256 === undefined) {
+        problems.push({
+            code: "render-output-missing",
+            message: `${render.file} is recorded but not in the render dir`,
+        });
+    }
+    else if (render.diskSha256 !== render.recordedSha256) {
+        problems.push({
+            code: "render-output-mismatch",
+            message: `${render.file} sha256 differs from the render manifest`,
+        });
+    }
+    // Unreadable approval inputs leave the approval state unknown, not "not approved".
+    if (facts.unreadable !== undefined)
+        return problems;
+    if (facts.approval !== "approved") {
+        problems.push({
+            code: "render-unapproved",
+            message: "a render manifest exists without a current approval",
+        });
+    }
+    if (render.verify === "PASS" && !supported) {
+        problems.push({
+            code: "verify-claim-unsupported",
+            message: "verify PASS is recorded but the render evidence does not hold",
+        });
+    }
+    return problems;
+};
+const stateOf = (facts, preview, render, verify) => {
+    const approved = facts.approval === "approved";
+    if (approved && render === "current")
+        return verify === "PASS" ? "verified" : "rendered";
+    if (approved)
+        return "approved";
+    return preview === "current" ? "previewed" : "storyboard";
+};
+/** Derives the state, the next missing artifact and every overclaim from already-read facts. */
+export function deriveState(facts) {
+    const preview = previewEvidence(facts);
+    const render = renderEvidence(facts.render, facts.storyboardCanonicalSha256);
+    const supported = render === "current" && facts.approval === "approved";
+    const verify = verifyEvidence(facts.render, supported);
+    const problems = renderProblems(facts, supported);
+    if (facts.unreadable !== undefined) {
+        problems.push({ code: "inputs-unreadable", message: facts.unreadable });
+    }
+    const state = stateOf(facts, preview, render, verify);
+    const next = NEXT[state];
+    return {
+        state,
+        next,
+        missing: next === null ? [] : [next],
+        problems,
+        evidence: {
+            storyboard: facts.storyboardSha256,
+            preview,
+            approval: facts.approval,
+            render,
+            verify,
+        },
+    };
+}
+const HEX64 = /^[a-f0-9]{64}$/;
+const BASENAME = /^[^\\/]+$/;
+const ABSOLUTE = /(?:[A-Za-z]:)?[\\/][^\s:;,"']+/g;
+/** Keeps an error reason short and machine-independent: no absolute paths. */
+const sanitize = (text) => {
+    const line = text.split("\n")[0] ?? "";
+    return line.replace(ABSOLUTE, "<path>").slice(0, 120);
+};
+const recordedPreviewSha = (value) => {
+    const row = value;
+    if (typeof row !== "object" || row === null)
+        return undefined;
+    const sha = row.inputManifestSha256;
+    return typeof sha === "string" && HEX64.test(sha) ? sha : undefined;
+};
+/** The storyboard a build manifest compiled. Unknown or older shapes are "cannot attribute". */
+const recordedBuildSha = (value) => {
+    const row = value;
+    if (typeof row !== "object" || row === null)
+        return undefined;
+    const sha = row.storyboardSha256;
+    return typeof sha === "string" && HEX64.test(sha) ? sha : undefined;
+};
+/** Present and parsed, absent, or present but unreadable (which exits 2, never "missing"). */
+async function readEvidenceJson(host, path, label) {
+    const loaded = await readJsonFile(path, host);
+    if (loaded.ok)
+        return { kind: "value", value: loaded.value };
+    if (loaded.kind === "syntax" || !(await host.exists(path)))
+        return { kind: "missing" };
+    return { kind: "unreadable", message: `${label} is unreadable` };
+}
+/** A render manifest shape we understand; unknown or older shapes are simply not evidence. */
+async function parseRender(host, dir, value, buildStoryboardSha256) {
+    const row = value;
+    if (typeof row !== "object" || row === null || row.schema !== 1)
+        return undefined;
+    const output = row.output;
+    if (typeof output !== "object" || output === null)
+        return undefined;
+    const file = output.file;
+    const sha = output.sha256;
+    if (typeof file !== "string" || !BASENAME.test(file) || file === "." || file === "..") {
+        return undefined;
+    }
+    if (typeof sha !== "string" || !HEX64.test(sha))
+        return undefined;
+    return {
+        file,
+        recordedSha256: sha,
+        diskSha256: await host.sha256File(join(dir, file)),
+        ...(buildStoryboardSha256 === undefined ? {} : { buildStoryboardSha256 }),
+        verify: typeof row.verify === "string" ? row.verify : "unknown",
+    };
+}
+/** Tolerant by design: an absent or unparsable build manifest means "cannot attribute", not an error. */
+async function readBuildStoryboardSha(host, dir) {
+    const loaded = await readJsonFile(join(dir, BUILD_MANIFEST), host);
+    return loaded.ok ? recordedBuildSha(loaded.value) : undefined;
+}
+const SAME_APPROVAL_FLAGS = "pass the same --assets/--ledger/--audio/--music flags used with `mk approve`";
+async function readApproval(io, storyboard, options) {
+    try {
+        const state = await approvalState(io.host, storyboard, options);
+        return { approval: state.state, currentHash: state.hash };
+    }
+    catch (error) {
+        return {
+            approval: "missing",
+            unreadable: `approval inputs cannot be read: ${sanitize(error.message)}; ${SAME_APPROVAL_FLAGS}`,
+        };
+    }
+}
+async function loadStoryboard(io, storyboard) {
+    const loaded = await readJsonFile(storyboard, io.host);
+    if (!loaded.ok)
+        return { ok: false, message: loaded.message };
+    const report = checkStoryboard(loaded.value);
+    if (report.errors.length > 0) {
+        const findings = formatFindings(report.errors.slice(0, 3));
+        return { ok: false, message: `storyboard is invalid; run \`mk validate\`.\n${findings}` };
+    }
+    const board = validateStoryboardFull(loaded.value);
+    // checkStoryboard ran the same validator; this turns the impossible into a typed refusal.
+    if (!board.ok)
+        return { ok: false, message: "storyboard is invalid; run `mk validate`." };
+    const fileSha256 = await io.host.sha256File(storyboard);
+    if (fileSha256 === undefined)
+        return { ok: false, message: `cannot read ${storyboard}` };
+    // A build hashes `JSON.stringify(board)`: canonical, so whitespace and key order are not identity.
+    return { ok: true, sha256: fileSha256, canonicalSha256: sha256(JSON.stringify(board.value)) };
+}
+async function readPreview(io, storyboard, options) {
+    const out = options.out ?? defaultOut(storyboard);
+    const preview = await readEvidenceJson(io.host, previewManifestPath(out, storyboard), "preview manifest");
+    if (preview.kind === "unreadable")
+        return { ok: false, message: preview.message };
+    const sha256 = preview.kind === "value" ? recordedPreviewSha(preview.value) : undefined;
+    return sha256 === undefined ? { ok: true } : { ok: true, sha256 };
+}
+async function readRender(io, storyboard, options) {
+    const dir = options.render ?? join(defaultOut(storyboard), "project");
+    const json = await readEvidenceJson(io.host, join(dir, RENDER_MANIFEST), "render manifest");
+    if (json.kind === "unreadable")
+        return { ok: false, message: json.message };
+    if (json.kind !== "value")
+        return { ok: true };
+    const buildSha = await readBuildStoryboardSha(io.host, dir);
+    const facts = await parseRender(io.host, dir, json.value, buildSha);
+    return facts === undefined ? { ok: true } : { ok: true, facts };
+}
+/** Reads every artifact once; validation failures and unreadable inputs are exit-2 values. */
+export async function gatherEvidence(io, storyboard, options = {}) {
+    const board = await loadStoryboard(io, storyboard);
+    if (!board.ok)
+        return board;
+    const approval = await readApproval(io, storyboard, options.approval ?? {});
+    const preview = await readPreview(io, storyboard, options);
+    if (!preview.ok)
+        return preview;
+    const render = await readRender(io, storyboard, options);
+    if (!render.ok)
+        return render;
+    return {
+        ok: true,
+        facts: {
+            storyboardSha256: board.sha256,
+            storyboardCanonicalSha256: board.canonicalSha256,
+            approval: approval.approval,
+            ...(approval.currentHash === undefined ? {} : { currentHash: approval.currentHash }),
+            ...(approval.unreadable === undefined ? {} : { unreadable: approval.unreadable }),
+            ...(preview.sha256 === undefined ? {} : { previewSha256: preview.sha256 }),
+            ...(render.facts === undefined ? {} : { render: render.facts }),
+        },
+    };
+}

package/dist/storyboard/check.d.ts

@@ -0,0 +1,21 @@
+import { type LintFinding, type PlatformMarginLookup } from "@anvpx/motion-build";
+export type Finding = LintFinding;
+export interface CheckReport {
+    errors: Finding[];
+    warnings: Finding[];
+    /** Total duration in seconds; present once the storyboard validates. */
+    total?: number;
+    /** Frame size and rate; present once the storyboard validates. */
+    meta?: {
+        width: number;
+        height: number;
+        fps: number;
+    };
+}
+/** A finding about the document itself (path "" is the JSON root). */
+export declare const rootError: (message: string) => Finding;
+/** Schema + per-scene validation, timing resolution and lint (unless `lint: false`), with no side effects. */
+export declare function checkStoryboard(value: unknown, options?: {
+    lint?: boolean;
+    platforms?: PlatformMarginLookup;
+}): CheckReport;

package/dist/storyboard/check.js

@@ -0,0 +1,39 @@
+import { bundledThemeDocs, lintStoryboard, resolveTimeline, sceneWords, tryResolveTheme, validateStoryboardFull, } from "@anvpx/motion-build";
+const asFinding = (error) => ({ severity: "error", ...error });
+/** A finding about the document itself (path "" is the JSON root). */
+export const rootError = (message) => ({ severity: "error", path: "", message });
+const failure = (errors) => ({
+    errors: errors.map(asFinding),
+    warnings: [],
+});
+const themeInput = (name) => {
+    const theme = tryResolveTheme(name, bundledThemeDocs());
+    return theme === undefined ? {} : { theme };
+};
+/** Schema + per-scene validation, timing resolution and lint (unless `lint: false`), with no side effects. */
+export function checkStoryboard(value, options = {}) {
+    const valid = validateStoryboardFull(value);
+    if (!valid.ok)
+        return failure(valid.errors);
+    const board = valid.value;
+    const timeline = resolveTimeline(board);
+    if (!timeline.ok)
+        return failure(timeline.errors);
+    const words = board.scenes.map((scene) => sceneWords(scene.props, scene.type));
+    const lint = options.lint === false
+        ? { errors: [], warnings: [] }
+        : lintStoryboard({
+            storyboard: board,
+            timeline: timeline.value,
+            words,
+            ...themeInput(board.meta.theme),
+            ...(options.platforms === undefined ? {} : { platforms: options.platforms }),
+        });
+    const { width, height, fps } = board.meta;
+    return {
+        errors: [...lint.errors],
+        warnings: [...lint.warnings],
+        total: timeline.value.total,
+        meta: { width, height, fps },
+    };
+}

package/dist/storyboard/containment.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Real-path containment for authored scenes.
+ *
+ * `props.dir` is checked textually by `resolveSceneDir`, but a symlink or NTFS
+ * junction points outside the project while still looking local. Loading such a
+ * scene would read outside files, and hashing it would record them as local
+ * approval inputs. Every path that reaches an authored scene therefore gets a
+ * real-path check; the check fails closed when a real path exists and leaves the
+ * allowed root.
+ *
+ * Fake/off-disk hosts have no realpath: an unresolvable path is treated as "not
+ * escaped" and left to the existing existence checks, because there is nothing
+ * for the real filesystem to resolve.
+ */
+/** True when `target` is strictly inside `root` (not equal, not a sibling prefix). */
+export declare const insideReal: (root: string, target: string) => boolean;
+export interface SceneContainment {
+    /** False when the scene directory itself resolves outside the storyboard directory. */
+    readonly dirInside: boolean;
+    /** Scene-relative files whose real path leaves the scene directory. */
+    readonly escapedFiles: readonly string[];
+}
+/** Real-path containment for a scene directory plus the files it is about to read. */
+export declare const sceneContainment: (storyboardDir: string, sceneDir: string, files: readonly string[]) => SceneContainment;

package/dist/storyboard/containment.js

@@ -0,0 +1,43 @@
+import { realpathSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+/**
+ * Real-path containment for authored scenes.
+ *
+ * `props.dir` is checked textually by `resolveSceneDir`, but a symlink or NTFS
+ * junction points outside the project while still looking local. Loading such a
+ * scene would read outside files, and hashing it would record them as local
+ * approval inputs. Every path that reaches an authored scene therefore gets a
+ * real-path check; the check fails closed when a real path exists and leaves the
+ * allowed root.
+ *
+ * Fake/off-disk hosts have no realpath: an unresolvable path is treated as "not
+ * escaped" and left to the existing existence checks, because there is nothing
+ * for the real filesystem to resolve.
+ */
+/** True when `target` is strictly inside `root` (not equal, not a sibling prefix). */
+export const insideReal = (root, target) => {
+    const rel = relative(root, target);
+    return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+};
+const realPath = (path) => {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Real-path containment for a scene directory plus the files it is about to read. */
+export const sceneContainment = (storyboardDir, sceneDir, files) => {
+    const rootReal = realPath(storyboardDir);
+    const dirReal = realPath(sceneDir);
+    if (rootReal === undefined || dirReal === undefined) {
+        return { dirInside: true, escapedFiles: [] };
+    }
+    const dirInside = insideReal(rootReal, dirReal);
+    const escapedFiles = files.filter((file) => {
+        const fileReal = realPath(join(sceneDir, file));
+        return fileReal !== undefined && !insideReal(dirReal, fileReal);
+    });
+    return { dirInside, escapedFiles };
+};

package/dist/storyboard/custom.d.ts

@@ -0,0 +1,15 @@
+import { type CustomSceneSource, type LintFinding } from "@anvpx/motion-build";
+import type { Host } from "../types.ts";
+/** True when the storyboard references an authored scene; cheap, no disk access. */
+export declare const hasCustomScenes: (board: unknown) => boolean;
+export interface CustomReadResult {
+    /** Authored scene sources by scene id; only the entries that read cleanly. */
+    readonly sources: Readonly<Record<string, CustomSceneSource>>;
+    readonly findings: readonly LintFinding[];
+}
+/**
+ * Reads every authored scene beside the storyboard, refuses directories that escape it
+ * (textually or through a symlink/junction), and runs the determinism lint. The build
+ * stays pure: this is the only place that touches disk.
+ */
+export declare function readCustomScenes(board: unknown, storyboardPath: string, host: Host): Promise<CustomReadResult>;