@anvpx/motion-build 0.0.0-stage → 0.1.1

package/dist/templates/discover-check.d.ts

@@ -0,0 +1,11 @@
+import type { ValidationError } from "@anvpx/motion-schema";
+import type { LintFinding } from "../lint/index.ts";
+import type { LoadedTemplate } from "./types.ts";
+/**
+ * `discover` on the manifest and every blueprint: an error in built-in templates (fully populated),
+ * a warning elsewhere (optional for user and project templates).
+ */
+export declare const discoverFindings: (template: LoadedTemplate, builtIn: boolean) => {
+    errors: ValidationError[];
+    warnings: LintFinding[];
+};

package/dist/templates/discover-check.js

@@ -0,0 +1,36 @@
+/** Fields a built-in `discover` must carry beyond the schema minimum. */
+const MANIFEST_REQUIRED = ["audience", "notFor", "tone", "aspects"];
+const BLUEPRINT_REQUIRED = [...MANIFEST_REQUIRED, "lengths"];
+const missingFields = (discover, required) => required.filter((field) => discover[field] === undefined);
+const targetsOf = (template) => [
+    {
+        path: "template.json#/discover",
+        discover: template.manifest.discover,
+        required: MANIFEST_REQUIRED,
+    },
+    ...[...template.blueprints.values()].map((blueprint) => ({
+        path: `blueprints/${blueprint.id}.json#/discover`,
+        discover: blueprint.discover,
+        required: BLUEPRINT_REQUIRED,
+    })),
+];
+const problemOf = ({ discover, required }) => {
+    if (discover === undefined)
+        return "missing discover";
+    const missing = missingFields(discover, required);
+    return missing.length === 0 ? undefined : `discover missing: ${missing.join(", ")}`;
+};
+/**
+ * `discover` on the manifest and every blueprint: an error in built-in templates (fully populated),
+ * a warning elsewhere (optional for user and project templates).
+ */
+export const discoverFindings = (template, builtIn) => {
+    const found = targetsOf(template).flatMap((target) => {
+        const message = problemOf(target);
+        return message === undefined ? [] : [{ path: target.path, message }];
+    });
+    const suggestion = "add the discover fields; mk template list --for reads them";
+    return builtIn
+        ? { errors: found.map((f) => ({ ...f, suggestion })), warnings: [] }
+        : { errors: [], warnings: found.map((f) => ({ severity: "warning", ...f, suggestion })) };
+};

package/dist/templates/discover.d.ts

@@ -0,0 +1,37 @@
+import { type ValidationError } from "@anvpx/motion-schema";
+/** A directory that may hold templates; earlier roots win. */
+export interface TemplateRoot {
+    readonly path: string;
+    /** Label shown in listings, e.g. `project`, `user`, `built-in`. */
+    readonly source: string;
+}
+export interface TemplateCandidate {
+    readonly id: string;
+    readonly version: string;
+    readonly dir: string;
+    readonly source: string;
+    readonly rootIndex: number;
+}
+export interface ShadowedTemplate extends TemplateCandidate {
+    readonly reason: "root" | "version";
+    /** `dir` of the candidate that won. */
+    readonly by: string;
+}
+export interface Discovery {
+    /** Winners, one per id, sorted by id. */
+    readonly templates: readonly TemplateCandidate[];
+    readonly shadowed: readonly ShadowedTemplate[];
+    /** Manifests that exist but do not parse; never silent. */
+    readonly problems: readonly ValidationError[];
+}
+export interface RootsInput {
+    readonly projectDir: string;
+    /** Value of `MK_TEMPLATES_PATH` (list separated by the platform path delimiter). */
+    readonly envPath?: string | undefined;
+    readonly homeDir: string;
+    readonly builtInDir: string;
+}
+/** Search roots, highest precedence first: project, env path, user, built-in. */
+export declare const templateRoots: (input: RootsInput) => TemplateRoot[];
+/** Finds templates under the roots; the highest-precedence root wins, then the highest semver. */
+export declare const discoverTemplates: (roots: readonly TemplateRoot[]) => Discovery;

package/dist/templates/discover.js

@@ -0,0 +1,63 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { parseTemplateManifest } from "@anvpx/motion-schema";
+import { MANIFEST_FILE } from "./load.js";
+import { compareSemver } from "./semver.js";
+/** Search roots, highest precedence first: project, env path, user, built-in. */
+export const templateRoots = (input) => [
+    { path: join(input.projectDir, "templates"), source: "project" },
+    ...(input.envPath ?? "")
+        .split(delimiter)
+        .filter((path) => path !== "")
+        .map((path) => ({ path, source: "env" })),
+    { path: join(input.homeDir, ".motion-kit", "templates"), source: "user" },
+    { path: input.builtInDir, source: "built-in" },
+];
+const subdirs = (dir) => {
+    try {
+        return readdirSync(dir)
+            .sort()
+            .filter((name) => statSync(join(dir, name)).isDirectory())
+            .map((name) => join(dir, name));
+    }
+    catch {
+        return [];
+    }
+};
+/** `<root>/<id>/template.json` or the versioned layout `<root>/<id>/<version>/template.json`. */
+const manifestDirs = (root) => subdirs(root).flatMap((dir) => existsSync(join(dir, MANIFEST_FILE))
+    ? [dir]
+    : subdirs(dir).filter((child) => existsSync(join(child, MANIFEST_FILE))));
+const readCandidate = (dir, root, rootIndex) => {
+    const file = join(dir, MANIFEST_FILE);
+    try {
+        const parsed = parseTemplateManifest(JSON.parse(readFileSync(file, "utf8")));
+        if (!parsed.ok) {
+            const [first] = parsed.errors;
+            return { path: file, message: `${first?.path ?? ""} ${first?.message ?? "invalid"}`.trim() };
+        }
+        const { id, version } = parsed.value;
+        return { id, version, dir, source: root.source, rootIndex };
+    }
+    catch (error) {
+        return { path: file, message: `unreadable: ${error.message}` };
+    }
+};
+const isCandidate = (item) => "id" in item;
+const precedence = (a, b) => a.rootIndex - b.rootIndex || compareSemver(b.version, a.version) || a.dir.localeCompare(b.dir);
+/** Finds templates under the roots; the highest-precedence root wins, then the highest semver. */
+export const discoverTemplates = (roots) => {
+    const found = roots.flatMap((root, index) => manifestDirs(root.path).map((dir) => readCandidate(dir, root, index)));
+    const candidates = found.filter(isCandidate);
+    const problems = found.filter((item) => !isCandidate(item));
+    const ordered = [...candidates].sort((a, b) => a.id.localeCompare(b.id) || precedence(a, b));
+    const winners = ordered.filter((candidate, index) => candidate.id !== ordered[index - 1]?.id);
+    const shadowed = ordered.flatMap((candidate) => {
+        const winner = winners.find((item) => item.id === candidate.id);
+        if (winner === undefined || winner === candidate)
+            return [];
+        const reason = candidate.rootIndex === winner.rootIndex ? "version" : "root";
+        return [{ ...candidate, reason, by: winner.dir }];
+    });
+    return { templates: winners, shadowed, problems };
+};

package/dist/templates/expand.d.ts

@@ -0,0 +1,17 @@
+import { type BlueprintDoc, type BlueprintScene, type Result } from "@anvpx/motion-schema";
+import { type SlotValues } from "./slots.ts";
+type Scene = Omit<BlueprintScene, "when">;
+export interface Expanded {
+    readonly meta: Record<string, unknown>;
+    readonly scenes: readonly Scene[];
+}
+/** Expands `$slot`/`$spread`/`$item`/`when`/`$repeat` into plain storyboard scenes and meta. */
+export declare const expandBlueprint: (blueprint: BlueprintDoc, slots: SlotValues) => Result<Expanded>;
+/** Every slot name a blueprint refers to, with where; used by template validation. */
+export interface SlotReference {
+    readonly name: string;
+    readonly path: string;
+    readonly list: boolean;
+}
+export declare const slotReferences: (blueprint: BlueprintDoc) => SlotReference[];
+export {};

package/dist/templates/expand.js

@@ -0,0 +1,184 @@
+import { SLOT_TRANSFORMS, toJsonPointer, } from "@anvpx/motion-schema";
+import { isSet } from "./slots.js";
+const ABSENT = Symbol("absent");
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const fail = (scope, path, message, suggestion) => {
+    const base = { path: toJsonPointer(path), message };
+    scope.errors.push(suggestion === undefined ? base : { ...base, suggestion });
+    return ABSENT;
+};
+const slugify = (label) => label
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "node";
+const labelsOf = (value) => Array.isArray(value) ? value.map((item) => String(item)) : [];
+const flowNodes = (value, scope, path) => {
+    const labels = labelsOf(value);
+    const ids = labels.map(slugify);
+    const dup = ids.find((id, index) => ids.indexOf(id) !== index);
+    if (dup !== undefined) {
+        return fail(scope, path, `two labels both become node id "${dup}"`, "make the labels distinct");
+    }
+    return labels.map((label, index) => ({ id: ids[index], label }));
+};
+const EDGE = /^([^>]+)>([^|]+)(?:\|(.+))?$/;
+const flowEdges = (value, scope, path) => labelsOf(value).flatMap((text, index) => {
+    const match = EDGE.exec(text);
+    if (match === null) {
+        fail(scope, [...path, index], `"${text}" is not an edge`, 'write "From>To" or "From>To|label"');
+        return [];
+    }
+    const [, from = "", to = "", label] = match;
+    const edge = { from: slugify(from.trim()), to: slugify(to.trim()) };
+    return [label === undefined ? edge : { ...edge, label: label.trim() }];
+});
+const flowChain = (value) => {
+    const ids = labelsOf(value).map(slugify);
+    return ids.slice(1).map((to, index) => ({ from: ids[index], to }));
+};
+const transform = (name, value, scope, path) => {
+    if (name === "flow-nodes")
+        return flowNodes(value, scope, path);
+    if (name === "flow-edges")
+        return flowEdges(value, scope, path);
+    if (name === "flow-chain")
+        return flowChain(value);
+    return fail(scope, path, `unknown transform "${name}"`, `use one of: ${SLOT_TRANSFORMS.join("|")}`);
+};
+const slotRef = (node, scope, path) => {
+    const extra = Object.keys(node).filter((key) => !["$slot", "as", "orElse"].includes(key));
+    if (extra.length > 0)
+        return fail(scope, path, `$slot takes only as/orElse, got ${extra.join(", ")}`);
+    const name = String(node.$slot);
+    if (!scope.known.has(name)) {
+        return fail(scope, path, `unknown slot "${name}"`, `use one of: ${[...scope.known].join("|")}`);
+    }
+    const value = scope.slots[name];
+    if (!isSet(value)) {
+        return node.orElse === undefined ? ABSENT : walk(node.orElse, scope, [...path, "orElse"]);
+    }
+    return typeof node.as === "string" ? transform(node.as, value, scope, path) : value;
+};
+const itemRef = (node, scope, path) => {
+    if (scope.item === undefined)
+        return fail(scope, path, "$item is only valid inside $repeat");
+    const field = node.$item;
+    if (field === ".")
+        return scope.item.value;
+    if (field === "#")
+        return scope.item.index + 1;
+    if (typeof field === "string" && isRecord(scope.item.value) && field in scope.item.value) {
+        return scope.item.value[field];
+    }
+    return fail(scope, path, `item has no field "${String(field)}"`, 'use "." for the whole item, "#" for its 1-based position');
+};
+const objectOf = (node, scope, path) => {
+    const spread = node.$spread === undefined ? ABSENT : spreadOf(String(node.$spread), scope, path);
+    const own = Object.entries(node)
+        .filter(([key]) => key !== "$spread")
+        .map(([key, child]) => [key, walk(child, scope, [...path, key])])
+        .filter(([, value]) => value !== ABSENT);
+    return { ...(spread === ABSENT ? {} : spread), ...Object.fromEntries(own) };
+};
+const spreadOf = (name, scope, path) => {
+    if (!scope.known.has(name))
+        return fail(scope, path, `unknown slot "${name}"`);
+    const value = scope.slots[name];
+    if (value === undefined)
+        return ABSENT;
+    return isRecord(value) ? value : fail(scope, path, `$spread slot "${name}" is not an object`);
+};
+const walk = (node, scope, path) => {
+    if (Array.isArray(node)) {
+        return node
+            .map((child, index) => walk(child, scope, [...path, index]))
+            .filter((child) => child !== ABSENT);
+    }
+    if (!isRecord(node))
+        return node;
+    if ("$slot" in node)
+        return slotRef(node, scope, path);
+    if ("$item" in node)
+        return itemRef(node, scope, path);
+    return objectOf(node, scope, path);
+};
+const isRepeat = (entry) => "$repeat" in entry;
+const sceneOf = (scene, scope, path, suffix) => {
+    const { when: _when, props, id, ...rest } = scene;
+    const expanded = walk(props, scope, [...path, "props"]);
+    return { ...rest, id: `${id}${suffix}`, props: isRecord(expanded) ? expanded : {} };
+};
+const passes = (when, scope, path) => {
+    if (when === undefined)
+        return true;
+    if (!scope.known.has(when)) {
+        fail(scope, [...path, "when"], `unknown slot "${when}"`);
+        return false;
+    }
+    return isSet(scope.slots[when]);
+};
+const repeated = (entry, scope, path) => {
+    if (!passes(entry.when, scope, path))
+        return [];
+    if (!scope.known.has(entry.$repeat)) {
+        fail(scope, [...path, "$repeat"], `unknown slot "${entry.$repeat}"`);
+        return [];
+    }
+    const items = scope.slots[entry.$repeat];
+    if (!Array.isArray(items))
+        return [];
+    return items.map((value, index) => sceneOf(entry.scene, { ...scope, item: { value, index } }, [...path, "scene"], `-${index + 1}`));
+};
+/** Expands `$slot`/`$spread`/`$item`/`when`/`$repeat` into plain storyboard scenes and meta. */
+export const expandBlueprint = (blueprint, slots) => {
+    const errors = [];
+    const scope = { slots, known: new Set(Object.keys(blueprint.slots)), errors };
+    const scenes = blueprint.scenes.flatMap((entry, index) => {
+        const path = ["scenes", index];
+        if (isRepeat(entry))
+            return repeated(entry, scope, path);
+        return passes(entry.when, scope, path) ? [sceneOf(entry, scope, path, "")] : [];
+    });
+    const rawMeta = walk(blueprint.meta ?? {}, scope, ["meta"]);
+    const meta = isRecord(rawMeta) ? rawMeta : {};
+    return errors.length > 0 ? { ok: false, errors } : { ok: true, value: { meta, scenes } };
+};
+const refsIn = (node, path, out) => {
+    if (Array.isArray(node)) {
+        for (const [index, child] of node.entries())
+            refsIn(child, [...path, index], out);
+    }
+    if (!isRecord(node))
+        return;
+    for (const key of ["$slot", "$spread"]) {
+        if (typeof node[key] === "string") {
+            out.push({ name: node[key], path: toJsonPointer([...path, key]), list: false });
+        }
+    }
+    for (const [key, child] of Object.entries(node))
+        refsIn(child, [...path, key], out);
+};
+export const slotReferences = (blueprint) => {
+    const out = [];
+    refsIn(blueprint.meta, ["meta"], out);
+    blueprint.scenes.forEach((entry, index) => {
+        const path = ["scenes", index];
+        if (entry.when !== undefined) {
+            out.push({ name: entry.when, path: toJsonPointer([...path, "when"]), list: false });
+        }
+        if (isRepeat(entry)) {
+            out.push({ name: entry.$repeat, path: toJsonPointer([...path, "$repeat"]), list: true });
+            refsIn(entry.scene.props, [...path, "scene", "props"], out);
+            if (entry.scene.when !== undefined) {
+                out.push({
+                    name: entry.scene.when,
+                    path: toJsonPointer([...path, "scene", "when"]),
+                    list: false,
+                });
+            }
+            return;
+        }
+        refsIn(entry.props, [...path, "props"], out);
+    });
+    return out;
+};

package/dist/templates/fixtures.d.ts

@@ -0,0 +1,4 @@
+/** Test helpers: write small valid template folders. */
+export declare const put: (dir: string, file: string, content: unknown) => void;
+export declare const manifestOf: (id: string, version: string) => Record<string, unknown>;
+export declare const writeTemplate: (root: string, id: string, version: string, folder?: string) => string;

package/dist/templates/fixtures.js

@@ -0,0 +1,63 @@
+import { copyFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Test helpers: write small valid template folders. */
+export const put = (dir, file, content) => {
+    const path = join(dir, file);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, typeof content === "string" ? content : JSON.stringify(content, null, 2));
+};
+const TOKENS = fileURLToPath(new URL("../../../themes/src/tokens/", import.meta.url));
+const copyTheme = (dir, file, token) => {
+    mkdirSync(join(dir, "themes"), { recursive: true });
+    copyFileSync(join(TOKENS, `${token}.json`), join(dir, file));
+};
+export const manifestOf = (id, version) => ({
+    templateVersion: 1,
+    id,
+    version,
+    title: `Template ${id}`,
+    summary: "A test template.",
+    domains: ["test"],
+    requires: { storyboard: 1, scenes: ["title", "bullets"] },
+    themes: [
+        { id: `${id}-light`, file: "themes/light.json", mode: "light", pair: `${id}-dark` },
+        { id: `${id}-dark`, file: "themes/dark.json", mode: "dark", pair: `${id}-light` },
+    ],
+    styles: [{ id: "calm", file: "styles/calm.json" }],
+    blueprints: [{ id: "basic", file: "blueprints/basic.json" }],
+    pacing: "pacing.json",
+    copy: "copy.md",
+    license: "Apache-2.0",
+});
+const range = { scenes: [1, 6], totalSec: [4, 60] };
+export const writeTemplate = (root, id, version, folder = id) => {
+    const dir = join(root, folder);
+    put(dir, "template.json", manifestOf(id, version));
+    copyTheme(dir, "themes/light.json", "default");
+    copyTheme(dir, "themes/dark.json", "dark");
+    put(dir, "styles/calm.json", { id: "calm", theme: `${id}-light` });
+    put(dir, "blueprints/basic.json", {
+        id: "basic",
+        purpose: "Title plus bullets.",
+        slots: {
+            title: { type: "text", max: 40, required: true },
+            points: { type: "text[]", min: 2, max: 4, itemMax: 40 },
+        },
+        example: { title: "Hello", points: ["One", "Two"] },
+        scenes: [
+            { id: "intro", type: "title", props: { title: { $slot: "title" } } },
+            { when: "points", id: "list", type: "bullets", props: { items: { $slot: "points" } } },
+        ],
+    });
+    put(dir, "pacing.json", {
+        wordsPerSecond: 2.5,
+        sceneSeconds: {
+            title: { short: 3, standard: 4, long: 5 },
+            bullets: { short: 4, standard: 6, long: 8 },
+        },
+        lengths: { short: range, standard: range, long: range },
+    });
+    put(dir, "copy.md", "Be brief.\n");
+    return dir;
+};

package/dist/templates/index.d.ts

@@ -0,0 +1,8 @@
+export { type Discovery, discoverTemplates, type RootsInput, type ShadowedTemplate, type TemplateCandidate, type TemplateRoot, templateRoots, } from "./discover.ts";
+export { type Instantiated, type InstantiateOptions, instantiate, type VendoredTheme, } from "./instantiate.ts";
+export { type LoadOptions, loadTemplate, resolveThemeFile, SHARED_PREFIX } from "./load.ts";
+export type { LengthClass } from "./pacing.ts";
+export { type BlueprintEntry, DEFAULT_STOPWORDS, entriesOf, filterEntries, type Hit, rankEntries, type SearchFilters, templateLengths, tokenize, WEIGHTS, } from "./search.ts";
+export { compareSemver } from "./semver.ts";
+export type { LoadedTemplate, PlatformFrame, PlatformLookup, ThemeFile } from "./types.ts";
+export { type TemplateReport, type ValidateOptions, validateTemplate } from "./validate.ts";

package/dist/templates/index.js

@@ -0,0 +1,6 @@
+export { discoverTemplates, templateRoots, } from "./discover.js";
+export { instantiate, } from "./instantiate.js";
+export { loadTemplate, resolveThemeFile, SHARED_PREFIX } from "./load.js";
+export { DEFAULT_STOPWORDS, entriesOf, filterEntries, rankEntries, templateLengths, tokenize, WEIGHTS, } from "./search.js";
+export { compareSemver } from "./semver.js";
+export { validateTemplate } from "./validate.js";

package/dist/templates/instantiate.d.ts

@@ -0,0 +1,43 @@
+import { type Result, type Storyboard } from "@anvpx/motion-schema";
+import { type LintFinding } from "../lint/index.ts";
+import { type LengthClass } from "./pacing.ts";
+import type { LoadedTemplate, PlatformLookup } from "./types.ts";
+export interface InstantiateOptions {
+    /** Style id; overrides the `style` slot. Default: slot default, else the first style. */
+    readonly style?: string;
+    /** Length class; overrides the `length` slot. Default: slot default, else `standard`. */
+    readonly length?: LengthClass;
+    /** Theme id from the template; overrides the style's theme (e.g. its dark pair). */
+    readonly theme?: string;
+    /** Platform id; overrides the `platform` slot (only for blueprints that declare it). */
+    readonly platform?: string;
+    readonly platforms?: PlatformLookup;
+}
+/** A theme file the project must carry to build without the template installed. */
+export interface VendoredTheme {
+    readonly id: string;
+    /** Path relative to the project, `themes/<id>.json`. */
+    readonly file: string;
+    readonly text: string;
+}
+export interface Instantiated {
+    readonly storyboard: Storyboard;
+    /** Canonical JSON of the storyboard: same inputs give the same bytes. */
+    readonly text: string;
+    readonly sceneCount: number;
+    readonly totalSec: number;
+    readonly warnings: readonly LintFinding[];
+    readonly themes: readonly VendoredTheme[];
+    readonly provenance: {
+        readonly template: string;
+        readonly blueprint: string;
+        readonly style: string;
+        readonly length: LengthClass;
+        readonly slotsSha256: string;
+    };
+}
+/**
+ * blueprint + slots + style + length -> a plain, fully validated storyboard.
+ * Pipeline: slots -> expand -> style -> pacing -> storyboard validation -> lint.
+ */
+export declare const instantiate: (template: LoadedTemplate, blueprintId: string, slots: unknown, options?: InstantiateOptions) => Result<Instantiated>;

package/dist/templates/instantiate.js

@@ -0,0 +1,160 @@
+import { sceneWords } from "@anvpx/motion-scenes";
+import { canonicalJson, LENGTH_CLASSES, } from "@anvpx/motion-schema";
+import { resolveTheme } from "@anvpx/motion-themes";
+import { sha256Of } from "../assets.js";
+import { lintStoryboard } from "../lint/index.js";
+import { resolveTimeline } from "../timing.js";
+import { validateStoryboardFull } from "../validate-full.js";
+import { expandBlueprint } from "./expand.js";
+import { applyPacing, pacingWarnings } from "./pacing.js";
+import { resolveSlots } from "./slots.js";
+import { applyStyle } from "./style.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const bad = (path, message, suggestion) => ({
+    ok: false,
+    errors: [suggestion === undefined ? { path, message } : { path, message, suggestion }],
+});
+const isLength = (value) => LENGTH_CLASSES.some((length) => length === value);
+const enumDefault = (blueprint, name) => {
+    const def = blueprint.slots[name];
+    return def?.type === "enum" ? def.default : undefined;
+};
+const asText = (value) => typeof value === "string" ? value : undefined;
+/** `style` and `length` steer the engine; they are slots only when the blueprint declares them. */
+const controls = (template, blueprint, input, options) => ({
+    style: options.style ??
+        asText(input.style) ??
+        enumDefault(blueprint, "style") ??
+        template.manifest.styles[0]?.id ??
+        "",
+    length: options.length ?? input.length ?? enumDefault(blueprint, "length") ?? "standard",
+    ...(Object.hasOwn(blueprint.slots, "platform")
+        ? {
+            platform: options.platform ?? asText(input.platform) ?? enumDefault(blueprint, "platform") ?? "",
+        }
+        : {}),
+});
+const slotInput = (blueprint, input, chosen) => {
+    const { style: _style, length: _length, platform: _platform, ...rest } = input;
+    return {
+        ...rest,
+        ...(chosen.platform === undefined ? {} : { platform: chosen.platform }),
+        ...(Object.hasOwn(blueprint.slots, "style") ? { style: chosen.style } : {}),
+        ...(Object.hasOwn(blueprint.slots, "length") ? { length: chosen.length } : {}),
+    };
+};
+const toErrors = (findings) => findings.map(({ path, message, suggestion }) => suggestion === undefined ? { path, message } : { path, message, suggestion });
+/** The template theme resolved for lint; an unresolvable one is reported by template validation. */
+const themeInput = (theme) => {
+    try {
+        return { theme: resolveTheme(theme.id, { [theme.id]: theme.doc }) };
+    }
+    catch {
+        return {};
+    }
+};
+const checkBoard = (board, theme, platforms) => {
+    const timeline = resolveTimeline(board);
+    if (!timeline.ok)
+        return timeline;
+    const words = board.scenes.map((scene) => sceneWords(scene.props, scene.type));
+    const lint = lintStoryboard({
+        storyboard: board,
+        timeline: timeline.value,
+        words,
+        ...themeInput(theme),
+        ...(platforms === undefined ? {} : { platforms }),
+    });
+    if (lint.errors.length > 0)
+        return { ok: false, errors: toErrors(lint.errors) };
+    return { ok: true, value: { timeline: timeline.value, warnings: [...lint.warnings] } };
+};
+const metaOf = (expanded, slots, theme, frame, platform) => ({
+    title: expanded.title ?? slots.title,
+    ...frame,
+    theme,
+    ...(platform === undefined ? {} : { platform }),
+    ...(expanded.lang === undefined ? {} : { lang: expanded.lang }),
+});
+const listOf = (keys) => `use one of: ${[...keys].join("|")}`;
+/** Picks blueprint, style, length and theme; every miss names the known ids. */
+const choose = (template, blueprintId, slots, options) => {
+    const blueprint = template.blueprints.get(blueprintId);
+    if (blueprint === undefined) {
+        return bad("/blueprint", `unknown blueprint "${blueprintId}"`, listOf(template.blueprints.keys()));
+    }
+    if (slots !== undefined && !isRecord(slots))
+        return bad("/slots", "slots must be an object");
+    const input = slots ?? {};
+    const chosen = controls(template, blueprint, input, options);
+    const style = template.styles.get(chosen.style);
+    if (style === undefined) {
+        return bad("/slots/style", `unknown style "${chosen.style}"`, listOf(template.styles.keys()));
+    }
+    if (!isLength(chosen.length)) {
+        return bad("/slots/length", `unknown length "${String(chosen.length)}"`, listOf(LENGTH_CLASSES));
+    }
+    const themeId = options.theme ?? style.theme;
+    const theme = template.themes.get(themeId);
+    if (theme === undefined) {
+        const path = options.theme === undefined ? `styles/${style.id}.json#/theme` : "/theme";
+        return bad(path, `theme "${themeId}" is not in the template`, listOf(template.themes.keys()));
+    }
+    return { ok: true, value: { blueprint, input, chosen, style, length: chosen.length, theme } };
+};
+/**
+ * blueprint + slots + style + length -> a plain, fully validated storyboard.
+ * Pipeline: slots -> expand -> style -> pacing -> storyboard validation -> lint.
+ */
+export const instantiate = (template, blueprintId, slots, options = {}) => {
+    const choice = choose(template, blueprintId, slots, options);
+    if (!choice.ok)
+        return choice;
+    const { blueprint, input, chosen, style, length, theme } = choice.value;
+    const resolved = resolveSlots(blueprint.slots, slotInput(blueprint, input, chosen));
+    if (!resolved.ok)
+        return resolved;
+    const expanded = expandBlueprint(blueprint, resolved.value);
+    if (!expanded.ok)
+        return expanded;
+    const styled = applyStyle(expanded.value.scenes, style, options.platforms, chosen.platform);
+    if (!styled.ok)
+        return styled;
+    const paced = applyPacing(styled.value.scenes, template.pacing, length);
+    if (!paced.ok)
+        return paced;
+    const draft = {
+        version: 1,
+        meta: metaOf(expanded.value.meta, resolved.value, theme.id, styled.value.frame, chosen.platform),
+        scenes: paced.value,
+    };
+    const valid = validateStoryboardFull(draft);
+    if (!valid.ok)
+        return valid;
+    const checked = checkBoard(valid.value, theme, options.platforms);
+    if (!checked.ok)
+        return checked;
+    const { timeline, warnings } = checked.value;
+    const sceneCount = valid.value.scenes.length;
+    return {
+        ok: true,
+        value: {
+            storyboard: valid.value,
+            text: canonicalJson(valid.value),
+            sceneCount,
+            totalSec: timeline.total,
+            warnings: [
+                ...warnings,
+                ...pacingWarnings(template.pacing, length, sceneCount, timeline.total),
+            ],
+            themes: [{ id: theme.id, file: `themes/${theme.id}.json`, text: theme.text }],
+            provenance: {
+                template: `${template.manifest.id}@${template.manifest.version}`,
+                blueprint: blueprint.id,
+                style: style.id,
+                length,
+                slotsSha256: sha256Of(canonicalJson(resolved.value)),
+            },
+        },
+    };
+};

package/dist/templates/load.d.ts

@@ -0,0 +1,16 @@
+import { type Result } from "@anvpx/motion-schema";
+import type { LoadedTemplate } from "./types.ts";
+export declare const MANIFEST_FILE = "template.json";
+/** A theme `file` starting with this prefix is read from the shared themes folder. */
+export declare const SHARED_PREFIX = "@shared/";
+export interface LoadOptions {
+    /** Folder holding `@shared/<name>` theme files (supplied by the caller; `build` never imports templates). */
+    readonly sharedThemesDir?: string | undefined;
+}
+/** Where a theme ref is read from: the template folder, or (for `@shared/<name>`) the shared folder. */
+export declare const resolveThemeFile: (file: string, sharedThemesDir: string | undefined) => Result<{
+    shared: boolean;
+    file: string;
+}>;
+/** Reads a template folder: manifest, themes, styles, blueprints, pacing and copy guide. */
+export declare const loadTemplate: (dir: string, options?: LoadOptions) => Result<LoadedTemplate>;