@anvpx/motion-build 0.0.0-stage → 0.1.0

package/dist/templates/validate.d.ts

@@ -0,0 +1,17 @@
+import { type ValidationError } from "@anvpx/motion-schema";
+import type { LintFinding } from "../lint/index.ts";
+import type { LoadedTemplate, PlatformLookup } from "./types.ts";
+export declare const WCAG_AA_TEXT = 4.5;
+/** Rough token estimate: 4 characters per token. */
+export declare const COPY_TOKEN_LIMIT = 300;
+export interface ValidateOptions {
+    readonly platforms?: PlatformLookup;
+    /** Built-in templates must carry a fully populated `discover`; elsewhere it only warns. */
+    readonly builtIn?: boolean;
+}
+export interface TemplateReport {
+    readonly errors: readonly ValidationError[];
+    readonly warnings: readonly LintFinding[];
+}
+/** The author/CI gate: contracts, themes (AA contrast), styles, blueprints and their examples. */
+export declare const validateTemplate: (template: LoadedTemplate, options?: ValidateOptions) => TemplateReport;

package/dist/templates/validate.js

@@ -0,0 +1,203 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { sceneTypes } from "@anvpx/motion-scenes";
+import { SLOT_TRANSFORMS, STORYBOARD_VERSION, } from "@anvpx/motion-schema";
+import { chartContrastIssues, chartCvdIssues, contrastRatio, isStrictChart, resolveTheme, spacingIssues, THEME_NAMES, } from "@anvpx/motion-themes";
+import { discoverFindings } from "./discover-check.js";
+import { slotReferences } from "./expand.js";
+import { instantiate } from "./instantiate.js";
+export const WCAG_AA_TEXT = 4.5;
+/** Rough token estimate: 4 characters per token. */
+export const COPY_TOKEN_LIMIT = 300;
+const err = (path, message, suggestion) => suggestion === undefined ? { path, message } : { path, message, suggestion };
+const reference = resolveTheme("default");
+const sameKeys = (group, actual, expected) => {
+    const missing = Object.keys(expected).filter((key) => !Object.hasOwn(actual, key));
+    return missing.length === 0 ? [] : [`${group} missing: ${missing.join(", ")}`];
+};
+const themeErrors = (theme) => {
+    if (THEME_NAMES.includes(theme.id)) {
+        return [
+            err(theme.file, `theme id "${theme.id}" collides with a built-in theme`, "rename it <template>-<name>"),
+        ];
+    }
+    let resolved;
+    try {
+        resolved = resolveTheme(theme.id, { [theme.id]: theme.doc });
+    }
+    catch (error) {
+        return [err(theme.file, error.message)];
+    }
+    const incomplete = [
+        ...sameKeys("colors", resolved.colors, reference.colors),
+        ...sameKeys("fonts", resolved.fonts, reference.fonts),
+        ...sameKeys("fontSizes", resolved.fontSizes, reference.fontSizes),
+        ...sameKeys("spacing", resolved.spacing, reference.spacing),
+        ...sameKeys("radii", resolved.radii, reference.radii),
+        ...sameKeys("opacities", resolved.opacities, reference.opacities),
+        ...sameKeys("durations", resolved.durations, reference.durations),
+        ...(resolved.chart.length < reference.chart.length ? ["chart needs 8 colours"] : []),
+    ].map((message) => err(theme.file, message));
+    const contrast = resolved.textPairs.flatMap(({ fg, bg }) => {
+        const foreground = resolved.colors[fg];
+        const background = resolved.colors[bg];
+        if (foreground === undefined || background === undefined) {
+            return [err(theme.file, `text pair ${fg}/${bg} names an unknown colour`)];
+        }
+        const ratio = contrastRatio(foreground, background);
+        return ratio >= WCAG_AA_TEXT
+            ? []
+            : [err(theme.file, `${fg} on ${bg} is ${ratio.toFixed(2)}:1, AA needs ${WCAG_AA_TEXT}:1`)];
+    });
+    const strict = isStrictChart(theme.doc);
+    const chart = strict ? [...chartContrastIssues(resolved), ...chartCvdIssues(resolved)] : [];
+    return [
+        ...incomplete,
+        ...contrast,
+        ...chart.map((issue) => err(theme.file, issue.message, "raise the chart foreground/background contrast")),
+    ];
+};
+/** Theme findings that never block: spacing off the 4 px grid; chart marks under 3:1 unless the theme is strict. */
+const themeWarnings = (theme) => {
+    let resolved;
+    try {
+        resolved = resolveTheme(theme.id, { [theme.id]: theme.doc });
+    }
+    catch {
+        return [];
+    }
+    const issues = [
+        ...spacingIssues(resolved),
+        ...(isStrictChart(theme.doc) ? [] : chartContrastIssues(resolved)),
+    ];
+    return issues.map((issue) => ({
+        severity: "warning",
+        path: theme.file,
+        message: issue.message,
+    }));
+};
+const manifestErrors = (template) => {
+    const { requires } = template.manifest;
+    const known = new Set(sceneTypes);
+    const missing = requires.scenes.filter((type) => !known.has(type));
+    return [
+        ...(requires.storyboard === STORYBOARD_VERSION
+            ? []
+            : [err("template.json#/requires/storyboard", `needs storyboard ${requires.storyboard}`)]),
+        ...(missing.length === 0
+            ? []
+            : [
+                err("template.json#/requires/scenes", `scene type(s) not available: ${missing.join(", ")}`, "update motion-kit or remove them from requires"),
+            ]),
+    ];
+};
+const styleErrors = (template, platforms) => [...template.styles.values()].flatMap((style) => {
+    const file = `styles/${style.id}.json`;
+    const theme = template.themes.has(style.theme)
+        ? []
+        : [
+            err(`${file}#/theme`, `unknown theme "${style.theme}"`, `use one of: ${[...template.themes.keys()].join("|")}`),
+        ];
+    const frame = style.frame;
+    const platform = frame !== undefined && "platform" in frame && platforms?.(frame.platform) === undefined
+        ? [err(`${file}#/frame/platform`, `unknown platform "${frame.platform}"`)]
+        : [];
+    const types = Object.keys(style.props ?? {})
+        .filter((type) => !sceneTypes.includes(type))
+        .map((type) => err(`${file}#/props/${type}`, `unknown scene type "${type}"`));
+    return [...theme, ...platform, ...types];
+});
+const blueprintErrors = (blueprint, template) => {
+    const file = `blueprints/${blueprint.id}.json`;
+    const refs = slotReferences(blueprint).flatMap((ref) => {
+        const def = blueprint.slots[ref.name];
+        if (def === undefined)
+            return [err(`${file}#${ref.path}`, `unknown slot "${ref.name}"`)];
+        const isList = def.type === "text[]" || (def.type === "object" && def.list === true);
+        return ref.list && !isList
+            ? [err(`${file}#${ref.path}`, `$repeat needs a list slot; "${ref.name}" is ${def.type}`)]
+            : [];
+    });
+    const transforms = JSON.stringify(blueprint).matchAll(/"as":"([^"]*)"/g);
+    const unknownAs = [...transforms]
+        .filter((match) => !SLOT_TRANSFORMS.includes(match[1] ?? ""))
+        .map((match) => err(file, `unknown transform "${match[1]}"`, `use one of: ${SLOT_TRANSFORMS.join("|")}`));
+    const styleSlot = blueprint.slots.style;
+    const badStyles = styleSlot?.type === "enum"
+        ? styleSlot.values
+            .filter((id) => !template.styles.has(id))
+            .map((id) => err(`${file}#/slots/style`, `style "${id}" is not in the template`))
+        : [];
+    const unpaced = blueprint.scenes
+        .map((entry) => ("$repeat" in entry ? entry.scene : entry))
+        .filter((scene) => scene.duration === undefined && scene.layer !== "overlay")
+        .filter((scene) => template.pacing.sceneSeconds[scene.type] === undefined)
+        .map((scene) => err(`${file}#/scenes`, `pacing.json has no seconds for "${scene.type}"`));
+    return [...refs, ...unknownAs, ...badStyles, ...unpaced];
+};
+const exampleRun = (template, blueprint, variant, platforms) => {
+    const { style, platform } = variant;
+    const result = instantiate(template, blueprint.id, blueprint.example, {
+        style,
+        ...(platform === undefined ? {} : { platform }),
+        ...(platforms === undefined ? {} : { platforms }),
+    });
+    const tag = platform === undefined ? "" : `, ${platform}`;
+    const where = `blueprints/${blueprint.id}.json#example (style ${style}${tag})`;
+    if (!result.ok) {
+        return {
+            errors: result.errors.map((e) => ({ ...e, path: `${where}${e.path}` })),
+            warnings: [],
+        };
+    }
+    return {
+        errors: [],
+        warnings: result.value.warnings.map((w) => ({ ...w, path: `${where}${w.path}` })),
+    };
+};
+/** The example must instantiate for every style, and for every platform of a `platform` slot. */
+const exampleErrors = (template, blueprint, platforms) => {
+    const slot = blueprint.slots.platform;
+    const platformIds = slot?.type === "enum" ? slot.values : [undefined];
+    const runs = [...template.styles.keys()].flatMap((style) => platformIds.map((platform) => exampleRun(template, blueprint, platform === undefined ? { style } : { style, platform }, platforms)));
+    return {
+        errors: runs.flatMap((run) => run.errors),
+        warnings: runs.flatMap((run) => run.warnings),
+    };
+};
+const COPY_CHARS_PER_TOKEN = 4;
+const copyErrors = (template) => {
+    const tokens = Math.ceil(template.copy.length / COPY_CHARS_PER_TOKEN);
+    return tokens <= COPY_TOKEN_LIMIT
+        ? []
+        : [
+            err(template.manifest.copy, `~${tokens} tokens, max ${COPY_TOKEN_LIMIT}`, "cut the copy guide"),
+        ];
+};
+const licenceErrors = (template) => existsSync(join(template.dir, "assets")) && !existsSync(join(template.dir, "licences.json"))
+    ? [
+        err("licences.json", "template ships assets but has no licences.json", "add a ledger row per asset"),
+    ]
+    : [];
+/** The author/CI gate: contracts, themes (AA contrast), styles, blueprints and their examples. */
+export const validateTemplate = (template, options = {}) => {
+    const { platforms } = options;
+    const discover = discoverFindings(template, options.builtIn === true);
+    const examples = [...template.blueprints.values()].map((blueprint) => exampleErrors(template, blueprint, platforms));
+    const errors = [
+        ...manifestErrors(template),
+        ...[...template.themes.values()].flatMap(themeErrors),
+        ...styleErrors(template, platforms),
+        ...[...template.blueprints.values()].flatMap((blueprint) => blueprintErrors(blueprint, template)),
+        ...examples.flatMap((example) => example.errors),
+        ...copyErrors(template),
+        ...licenceErrors(template),
+        ...discover.errors,
+    ];
+    const warnings = [
+        ...examples.flatMap((example) => example.warnings),
+        ...[...template.themes.values()].flatMap(themeWarnings),
+        ...discover.warnings,
+    ];
+    return { errors, warnings };
+};

package/dist/timing.d.ts

@@ -0,0 +1,38 @@
+import type { Result, SceneEntry, Storyboard, TimingManifest } from "@anvpx/motion-schema";
+export declare const MIN_AUTO_SECONDS = 3;
+export declare const TRANSITION_SECONDS = 0.5;
+export declare const IMPLEMENTED_TRANSITIONS: readonly string[];
+export type ResolvedTransition = "cut" | "crossfade" | "push" | "wipe" | "zoom-through";
+export interface TimedScene {
+    readonly id: string;
+    /** Position in the storyboard's `scenes` array (overlays occupy slots too). */
+    readonly index: number;
+    readonly start: number;
+    readonly duration: number;
+    /** Transition into this scene (the first scene has none). */
+    readonly transition: ResolvedTransition;
+    /** Seconds this scene overlaps the previous one. */
+    readonly overlap: number;
+}
+/** An overlay placed on the final timeline; it never advances the base timeline. */
+export interface TimedOverlay {
+    readonly id: string;
+    readonly index: number;
+    /** Id of the base scene it covers (may be unknown; lint reports that). */
+    readonly over: string;
+    /** Absolute start, seconds. */
+    readonly start: number;
+    readonly duration: number;
+    /** Absolute end, seconds. */
+    readonly end: number;
+}
+export interface Timeline {
+    /** Base scenes in order; the TimingManifest overlap rule applies to these only. */
+    readonly scenes: readonly TimedScene[];
+    readonly overlays: readonly TimedOverlay[];
+    readonly total: number;
+}
+export declare const autoDuration: (words: number) => number;
+export declare const isOverlay: (entry: SceneEntry) => boolean;
+/** Authored durations, optionally overridden per base scene id by a voice TimingManifest. */
+export declare const resolveTimeline: (storyboard: Storyboard, manifest?: TimingManifest) => Result<Timeline>;

package/dist/timing.js

@@ -0,0 +1,88 @@
+import { sceneWords } from "@anvpx/motion-scenes";
+export const MIN_AUTO_SECONDS = 3;
+export const TRANSITION_SECONDS = 0.5;
+export const IMPLEMENTED_TRANSITIONS = [
+    "cut",
+    "crossfade",
+    "push",
+    "wipe",
+    "zoom-through",
+];
+const round3 = (value) => Math.round(value * 1000) / 1000;
+export const autoDuration = (words) => Math.max(MIN_AUTO_SECONDS, Math.ceil(words / 3 + 1.5));
+export const isOverlay = (entry) => entry.layer === "overlay";
+const durationOf = (entry, voice) => round3(voice.get(entry.id) ?? entry.duration ?? autoDuration(sceneWords(entry.props, entry.type)));
+const overlapOf = (entry, prev, own) => entry.transition === "crossfade" ||
+    entry.transition === "push" ||
+    entry.transition === "wipe" ||
+    entry.transition === "zoom-through"
+    ? Math.min(TRANSITION_SECONDS, prev / 2, own / 2)
+    : 0;
+const manifestErrors = (storyboard, manifest) => {
+    const kinds = new Map(storyboard.scenes.map((scene) => [scene.id, isOverlay(scene)]));
+    return manifest.scenes.flatMap((row, index) => {
+        const path = `/timing/scenes/${index}/id`;
+        const overlay = kinds.get(row.id);
+        if (overlay === undefined) {
+            return [
+                {
+                    path,
+                    message: `scene "${row.id}" is not in the storyboard`,
+                    suggestion: "regenerate timing for this storyboard",
+                },
+            ];
+        }
+        return overlay
+            ? [
+                {
+                    path,
+                    message: `scene "${row.id}" is an overlay; voice timing covers base scenes only`,
+                    suggestion: "remove it from the timing manifest",
+                },
+            ]
+            : [];
+    });
+};
+const placeBase = (entries, voice) => {
+    const scenes = [];
+    let cursor = 0;
+    entries.forEach(({ entry, index }, position) => {
+        const duration = durationOf(entry, voice);
+        const prev = scenes[position - 1]?.duration ?? 0;
+        const overlap = round3(position === 0 ? 0 : overlapOf(entry, prev, duration));
+        const start = round3(cursor - overlap);
+        const transition = overlap > 0
+            ? entry.transition === "push" ||
+                entry.transition === "wipe" ||
+                entry.transition === "zoom-through"
+                ? entry.transition
+                : "crossfade"
+            : "cut";
+        scenes.push({ id: entry.id, index, start, duration, transition, overlap });
+        cursor = round3(start + duration);
+    });
+    return { scenes, total: cursor };
+};
+const placeOverlays = (entries, bases) => {
+    const starts = new Map(bases.map((scene) => [scene.id, scene.start]));
+    return entries.map(({ entry, index }) => {
+        const over = entry.over ?? "";
+        const duration = round3(entry.duration ?? MIN_AUTO_SECONDS);
+        const start = round3((starts.get(over) ?? 0) + (entry.offset ?? 0));
+        return { id: entry.id, index, over, start, duration, end: round3(start + duration) };
+    });
+};
+const place = (storyboard, voice) => {
+    const indexed = storyboard.scenes.map((entry, index) => ({ entry, index }));
+    const base = placeBase(indexed.filter(({ entry }) => !isOverlay(entry)), voice);
+    const overlays = placeOverlays(indexed.filter(({ entry }) => isOverlay(entry)), base.scenes);
+    return { scenes: base.scenes, overlays, total: base.total };
+};
+/** Authored durations, optionally overridden per base scene id by a voice TimingManifest. */
+export const resolveTimeline = (storyboard, manifest) => {
+    const errors = manifest ? manifestErrors(storyboard, manifest) : [];
+    if (errors.length > 0)
+        return { ok: false, errors };
+    const voice = new Map((manifest?.scenes ?? []).map((row) => [row.id, row.duration]));
+    return { ok: true, value: place(storyboard, voice) };
+};

package/dist/validate-full.d.ts

@@ -0,0 +1,3 @@
+import { type Result, type Storyboard } from "@anvpx/motion-schema";
+/** Schema validation plus every scene's own configSchema; errors are terse and fixable. */
+export declare const validateStoryboardFull: (input: unknown) => Result<Storyboard>;

package/dist/validate-full.js

@@ -0,0 +1,132 @@
+import { CUSTOM_SCENE_TYPE, getScene, sceneRegistry, sceneTypes } from "@anvpx/motion-scenes";
+import { toJsonPointer, validateStoryboard, } from "@anvpx/motion-schema";
+const WORD_LIMIT = /^scene has \d+ words/;
+const valueAt = (root, path) => path.reduce((node, key) => (typeof node === "object" && node !== null ? Reflect.get(node, key) : undefined), root);
+const withSuggestion = (base, suggestion) => suggestion === undefined ? base : { ...base, suggestion };
+const describeIssue = (issue, props) => {
+    if (issue.code === "invalid_value") {
+        const received = JSON.stringify(valueAt(props, issue.path));
+        return { message: `${received} invalid`, suggestion: `use one of: ${issue.values.join("|")}` };
+    }
+    if (issue.code === "unrecognized_keys") {
+        const keys = issue.keys.join(", ");
+        return {
+            message: `unknown key(s): ${keys}`,
+            suggestion: `remove ${keys} (check spelling against the catalog)`,
+        };
+    }
+    if (WORD_LIMIT.test(issue.message)) {
+        return { message: issue.message, suggestion: "shorten the text or split into two scenes" };
+    }
+    return { message: issue.message };
+};
+const propErrors = (entry, index) => {
+    const parsed = getScene(entry.type).configSchema.safeParse(entry.props);
+    if (parsed.success)
+        return [];
+    return parsed.error.issues.map((issue) => {
+        const { message, suggestion } = describeIssue(issue, entry.props);
+        const path = toJsonPointer(["scenes", index, "props", ...issue.path]);
+        return withSuggestion({ path, message }, suggestion);
+    });
+};
+const overlayTypes = () => [...sceneRegistry.values()].filter((plugin) => plugin.layer === "overlay").map((p) => p.type);
+/** An overlay entry needs an overlay plugin and the other way round. */
+const layerErrors = (entry, index) => {
+    const overlayPlugin = getScene(entry.type).layer === "overlay";
+    if (entry.layer === "overlay" && !overlayPlugin) {
+        return [
+            {
+                path: `/scenes/${index}/type`,
+                message: `scene type "${entry.type}" is not an overlay`,
+                suggestion: `use one of: ${overlayTypes().join("|")}`,
+            },
+        ];
+    }
+    if (entry.layer !== "overlay" && overlayPlugin) {
+        return [
+            {
+                path: `/scenes/${index}/layer`,
+                message: `scene type "${entry.type}" is overlay-only`,
+                suggestion: 'set layer: "overlay", over and duration',
+            },
+        ];
+    }
+    return [];
+};
+const ABSOLUTE_DIR = /^(?:[a-zA-Z]:|[\\/]|~)/;
+const ESCAPING_DIR = /(^|[\\/])\.\.([\\/]|$)/;
+/** `custom` takes exactly one prop: a relative directory holding the scene's three files. */
+const customErrors = (entry, index) => {
+    const props = entry.props;
+    const unknown = Object.keys(props).filter((key) => key !== "dir");
+    if (unknown.length > 0) {
+        return [
+            {
+                path: toJsonPointer(["scenes", index, "props"]),
+                message: `unknown key(s): ${unknown.join(", ")}`,
+                suggestion: "custom scenes take only props.dir",
+            },
+        ];
+    }
+    const dir = props.dir;
+    if (typeof dir !== "string" || dir.trim() === "") {
+        return [
+            {
+                path: toJsonPointer(["scenes", index, "props", "dir"]),
+                message: "custom scene needs a directory",
+                suggestion: 'set props: { "dir": "scenes/<name>" }',
+            },
+        ];
+    }
+    if (ABSOLUTE_DIR.test(dir)) {
+        return [
+            {
+                path: toJsonPointer(["scenes", index, "props", "dir"]),
+                message: "props.dir must be relative",
+                suggestion: "use a path inside the storyboard's directory",
+            },
+        ];
+    }
+    if (ESCAPING_DIR.test(dir)) {
+        return [
+            {
+                path: toJsonPointer(["scenes", index, "props", "dir"]),
+                message: "props.dir escapes the storyboard directory",
+                suggestion: "keep the scene beside the storyboard",
+            },
+        ];
+    }
+    return [];
+};
+const sceneErrors = (entry, index) => {
+    if (entry.type === CUSTOM_SCENE_TYPE) {
+        if (entry.layer === "overlay") {
+            return [
+                {
+                    path: `/scenes/${index}/layer`,
+                    message: `scene type "${entry.type}" is not an overlay`,
+                    suggestion: `use one of: ${overlayTypes().join("|")}`,
+                },
+            ];
+        }
+        return customErrors(entry, index);
+    }
+    return sceneRegistry.has(entry.type)
+        ? [...layerErrors(entry, index), ...propErrors(entry, index)]
+        : [
+            {
+                path: `/scenes/${index}/type`,
+                message: `unknown scene type "${entry.type}"`,
+                suggestion: `use one of: ${sceneTypes.join("|")}|custom (authored: mk scene new)`,
+            },
+        ];
+};
+/** Schema validation plus every scene's own configSchema; errors are terse and fixable. */
+export const validateStoryboardFull = (input) => {
+    const base = validateStoryboard(input);
+    if (!base.ok)
+        return base;
+    const errors = base.value.scenes.flatMap(sceneErrors);
+    return errors.length > 0 ? { ok: false, errors } : base;
+};

package/dist/verify.d.ts

@@ -0,0 +1,32 @@
+import type { PlatformTemplate } from "@anvpx/motion-schema";
+export type FindingLevel = "fatal" | "warn" | "info";
+export type VerifyStatus = "PASS" | "WARN" | "FAIL" | "UNKNOWN";
+export interface VerifyFinding {
+    readonly code: string;
+    readonly level: FindingLevel;
+    /** At most 25 words. */
+    readonly message: string;
+    readonly path?: string;
+}
+export interface VerifyReport {
+    readonly status: VerifyStatus;
+    readonly findings: readonly VerifyFinding[];
+}
+/** What the rendered file should look like; every field is optional. */
+export interface MediaExpectation {
+    readonly width?: number;
+    readonly height?: number;
+    readonly fps?: number;
+    /** Seconds. */
+    readonly duration?: number;
+    /** true: an audio stream is required; false: none is expected; absent: not checked. */
+    readonly audio?: boolean;
+}
+export interface VerifyInput {
+    /** Parsed `ffprobe -show_streams -show_format -of json` output. */
+    readonly probe: unknown;
+    readonly expect?: MediaExpectation;
+    readonly platform?: PlatformTemplate;
+}
+/** Pure QC over probe JSON: measures and reports; the caller decides what to do with the status. */
+export declare function verifyMedia(input: VerifyInput): VerifyReport;