@anvpx/motion-schema 0.0.0-stage → 0.1.0

package/dist/template.js

@@ -0,0 +1,254 @@
+import { z } from "zod";
+import { toJsonPointer } from "./errors.js";
+import { forbiddenKeys, reservedKey } from "./reserved-keys.js";
+import { APPROVALS, EASES, MOVES, SceneEntryBaseSchema, SHOTS, SLUG, SLUG_MESSAGE, TRANSITIONS, } from "./storyboard.js";
+import { toValidationError } from "./validate.js";
+/** Manifest format version; a breaking change bumps it. */
+export const TEMPLATE_VERSION = 1;
+/**
+ * Blueprint scene-prop transforms (`{"$slot": name, "as": ...}`), closed set. `flow-nodes`: labels to
+ * `{id,label}`; `flow-edges`: "A>B" or "A>B|label" to `{from,to,label}`; `flow-chain`: labels to a
+ * consecutive-edge chain.
+ */
+export const SLOT_TRANSFORMS = ["flow-nodes", "flow-edges", "flow-chain"];
+/** Length classes of a pacing document. */
+export const LENGTH_CLASSES = ["short", "standard", "long"];
+const SLOT_NAME = /^[a-z][A-Za-z0-9]*$/;
+const SEMVER = /^\d+\.\d+\.\d+$/;
+const slug = z.string().regex(SLUG, SLUG_MESSAGE);
+const semver = z.string().regex(SEMVER, "must be semver x.y.z");
+const slotName = reservedKey.regex(SLOT_NAME, "must be camelCase (a-z, A-Z, 0-9)");
+/** A path inside the template folder: relative, forward slashes, no `..`. */
+const relativePath = z
+    .string()
+    .min(1)
+    .refine((path) => !path.startsWith("/") &&
+    !path.includes("\\") &&
+    !/^[a-zA-Z]:/.test(path) &&
+    !path.split("/").includes(".."), "must be a relative path inside the template folder");
+const count = z.number().int().nonnegative();
+const ASPECT = /^\d+:\d+$/;
+const slugs = (min, max) => z.array(slug).min(min).max(max);
+/** Fields shared by manifest and blueprint `discover`; caps keep list output skimmable (docs/STORE.md 1.1). */
+const discoverFields = {
+    /** 2-4 sentences, each <= 120 chars: what this is for. */
+    useCases: z.array(z.string().min(1).max(120)).min(2).max(4),
+    audience: slugs(1, 5).optional(),
+    /** WHEN to pick it. */
+    goodFor: z.string().min(1).max(100),
+    /** WHEN NOT to pick it; scoring sinks a match here. */
+    notFor: z.string().min(1).max(100).optional(),
+    tags: slugs(3, 8),
+    tone: slugs(1, 3).optional(),
+    /** Aspect ratios such as `16:9`; platform data lives in packages/schema/data/platforms. */
+    aspects: z.array(z.string().regex(ASPECT, "must look like 16:9")).min(1).max(6).optional(),
+};
+/** Template level `discover`; lengths are derived from its blueprints, never stored. */
+export const ManifestDiscoverSchema = z.strictObject(discoverFields);
+/** Blueprint level `discover`; `lengths` are seconds. */
+export const BlueprintDiscoverSchema = z.strictObject({
+    ...discoverFields,
+    lengths: z
+        .strictObject({ min: z.number().int().positive(), max: z.number().int().positive() })
+        .refine(({ min, max }) => min <= max, "min must be <= max")
+        .optional(),
+});
+const requirement = {
+    required: z.boolean().optional(),
+    optional: z.boolean().optional(),
+};
+const notBoth = (slot) => !(slot.required === true && slot.optional === true);
+const NOT_BOTH = "a slot cannot be both required and optional";
+const TextSlotSchema = z
+    .strictObject({
+    type: z.literal("text"),
+    ...requirement,
+    min: count.optional(),
+    max: count.optional(),
+    default: z.string().optional(),
+})
+    .refine(notBoth, NOT_BOTH);
+const TextListSlotSchema = z
+    .strictObject({
+    type: z.literal("text[]"),
+    ...requirement,
+    min: count.optional(),
+    max: count.optional(),
+    itemMax: count.optional(),
+})
+    .refine(notBoth, NOT_BOTH);
+const NumberSlotSchema = z
+    .strictObject({
+    type: z.literal("number"),
+    ...requirement,
+    min: z.number().optional(),
+    max: z.number().optional(),
+    int: z.boolean().optional(),
+    default: z.number().optional(),
+})
+    .refine(notBoth, NOT_BOTH);
+const EnumSlotSchema = z
+    .strictObject({
+    type: z.literal("enum"),
+    values: z.array(z.string().min(1)).min(1),
+    default: z.string().optional(),
+})
+    .refine((slot) => slot.default === undefined || slot.values.includes(slot.default), "default must be one of values");
+/** One object (`list` absent) or a list of objects (`list: true`, with `min`/`max` item counts). */
+const ObjectSlotSchema = z
+    .strictObject({
+    type: z.literal("object"),
+    fields: z.record(slotName, z.enum(["text", "number"])),
+    ...requirement,
+    list: z.boolean().optional(),
+    min: count.optional(),
+    max: count.optional(),
+})
+    .refine(notBoth, NOT_BOTH)
+    .refine((slot) => Object.keys(slot.fields).length > 0, "fields must not be empty");
+export const SlotSchema = z.discriminatedUnion("type", [
+    TextSlotSchema,
+    TextListSlotSchema,
+    NumberSlotSchema,
+    EnumSlotSchema,
+    ObjectSlotSchema,
+]);
+/** A blueprint scene: a storyboard scene whose props may hold `$slot`/`$spread`/`$item` constructs. */
+export const BlueprintSceneSchema = SceneEntryBaseSchema.extend({
+    /** Include the scene only when this slot is set. */
+    when: slotName.optional(),
+});
+/** One scene per item of a list slot; `$item` inside refers to the current item, ids get `-<n>`. */
+export const BlueprintRepeatSchema = z.strictObject({
+    $repeat: slotName,
+    when: slotName.optional(),
+    scene: BlueprintSceneSchema,
+});
+export const BlueprintDocSchema = z.strictObject({
+    id: slug,
+    purpose: z.string().min(1).max(200),
+    discover: BlueprintDiscoverSchema.optional(),
+    slots: z.record(slotName, SlotSchema),
+    /** A complete slot set; must instantiate with every style (checked by template validation). */
+    example: z.record(slotName, z.unknown()),
+    /** Storyboard meta; `title` may be a `$slot` construct. Defaults to the `title` slot when text. */
+    meta: z
+        .strictObject({
+        title: z.unknown().optional(),
+        lang: z.string().min(2).optional(),
+        /**
+         * Render-gate default the blueprint stamps into generated storyboards (PLAN 7d.3 twin):
+         * "auto" (absent, current behaviour) or "confirm". Additive, optional.
+         */
+        approval: z.enum(APPROVALS).optional(),
+    })
+        .optional(),
+    scenes: z.array(z.union([BlueprintRepeatSchema, BlueprintSceneSchema])).min(1),
+});
+const FileRefSchema = z.strictObject({ id: slug, file: relativePath });
+const ThemeRefSchema = z.strictObject({
+    id: slug,
+    file: relativePath,
+    mode: z.enum(["light", "dark"]),
+    pair: slug.optional(),
+});
+const idsUnique = (items) => new Set(items.map((item) => item.id)).size === items.length;
+export const TemplateManifestSchema = z
+    .strictObject({
+    templateVersion: z.literal(TEMPLATE_VERSION),
+    id: slug,
+    version: semver,
+    title: z.string().min(1),
+    summary: z.string().min(1).max(140),
+    domains: z.array(slug),
+    discover: ManifestDiscoverSchema.optional(),
+    requires: z.strictObject({
+        storyboard: z.number().int().positive(),
+        scenes: z.array(z.string().min(1)),
+    }),
+    themes: z.array(ThemeRefSchema).min(1),
+    styles: z.array(FileRefSchema).min(1),
+    blueprints: z.array(FileRefSchema).min(1),
+    pacing: relativePath,
+    copy: relativePath,
+    license: z.string().min(1),
+})
+    .superRefine((manifest, ctx) => {
+    for (const key of ["themes", "styles", "blueprints"]) {
+        if (!idsUnique(manifest[key])) {
+            ctx.addIssue({ code: "custom", path: [key], message: `duplicate ${key} id` });
+        }
+    }
+    const themes = new Map(manifest.themes.map((theme) => [theme.id, theme]));
+    manifest.themes.forEach((theme, index) => {
+        if (theme.pair === undefined)
+            return;
+        const other = themes.get(theme.pair);
+        if (other?.pair !== theme.id || other.mode === theme.mode) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["themes", index, "pair"],
+                message: `pair "${theme.pair}" must name a theme of the other mode that pairs back`,
+            });
+        }
+    });
+});
+const DirectionSchema = z.strictObject({
+    shot: z.enum(SHOTS).optional(),
+    move: z.enum(MOVES).optional(),
+    ease: z.enum(EASES).optional(),
+    transition: z.enum(TRANSITIONS).optional(),
+});
+const FrameSchema = z.union([
+    z.strictObject({
+        width: z.number().int().positive(),
+        height: z.number().int().positive(),
+        fps: z.number().int().positive(),
+    }),
+    z.strictObject({ platform: slug }),
+]);
+export const StylePresetSchema = z.strictObject({
+    id: slug,
+    theme: slug,
+    frame: FrameSchema.optional(),
+    direction: DirectionSchema.optional(),
+    /** Scene type -> default props; explicit blueprint values win. */
+    props: z.record(reservedKey, z.record(reservedKey, z.unknown())).optional(),
+});
+const seconds = z.number().positive();
+const perLength = z.strictObject({ short: seconds, standard: seconds, long: seconds });
+const range = z.tuple([count, count]).refine(([low, high]) => low <= high, "min must be <= max");
+const target = z.strictObject({ scenes: range, totalSec: range });
+export const PacingDocSchema = z.strictObject({
+    wordsPerSecond: seconds,
+    /** Scene type -> seconds per length class. */
+    sceneSeconds: z.record(reservedKey, perLength),
+    lengths: z.strictObject({ short: target, standard: target, long: target }),
+});
+/** Forbidden keys (prototype-polluting, execution-shaped) first, then the schema; pointer errors. */
+const parseDoc = (schema, input) => {
+    const forbidden = forbiddenKeys(input, []);
+    if (forbidden.length > 0) {
+        return {
+            ok: false,
+            errors: forbidden.map(({ path, message, suggestion }) => suggestion === undefined
+                ? { path: toJsonPointer(path), message }
+                : { path: toJsonPointer(path), message, suggestion }),
+        };
+    }
+    const parsed = schema.safeParse(input);
+    if (parsed.success)
+        return { ok: true, value: parsed.data };
+    return { ok: false, errors: parsed.error.issues.map((issue) => toValidationError(issue, input)) };
+};
+export const parseTemplateManifest = (input) => parseDoc(TemplateManifestSchema, input);
+export const parseBlueprintDoc = (input) => parseDoc(BlueprintDocSchema, input);
+export const parseStylePreset = (input) => parseDoc(StylePresetSchema, input);
+export const parsePacingDoc = (input) => parseDoc(PacingDocSchema, input);
+/** JSON Schemas of the template documents, for editors and constrained decoding. */
+export const templateJsonSchemas = () => ({
+    manifest: z.toJSONSchema(TemplateManifestSchema, { io: "input" }),
+    blueprint: z.toJSONSchema(BlueprintDocSchema, { io: "input" }),
+    style: z.toJSONSchema(StylePresetSchema, { io: "input" }),
+    pacing: z.toJSONSchema(PacingDocSchema, { io: "input" }),
+});

package/dist/theme.d.ts

@@ -0,0 +1,28 @@
+/** Colour keys of a foreground/background pair that must meet WCAG AA text contrast. */
+export interface TextPair {
+    readonly fg: string;
+    readonly bg: string;
+}
+/** Flat JS projection of a DTCG theme; produced by `@anvpx/motion-themes`. */
+export interface ResolvedTheme {
+    readonly name: string;
+    /** Colour key -> hex, e.g. `bg`, `fg`, `accent`, `muted`. */
+    readonly colors: Readonly<Record<string, string>>;
+    /** Categorical chart palette, in order. */
+    readonly chart: readonly string[];
+    /** Font role -> CSS font-family stack. */
+    readonly fonts: Readonly<Record<string, string>>;
+    /** Type scale step -> px. */
+    readonly fontSizes: Readonly<Record<string, number>>;
+    /** Spacing step -> px. */
+    readonly spacing: Readonly<Record<string, number>>;
+    /** Radius step -> px. */
+    readonly radii: Readonly<Record<string, number>>;
+    /** Opacity step (subtle|medium|full) -> 0..1. */
+    readonly opacities: Readonly<Record<string, number>>;
+    /** Motion duration name -> seconds. */
+    readonly durations: Readonly<Record<string, number>>;
+    readonly textPairs: readonly TextPair[];
+    /** Extra custom properties (`--mk-*` name -> CSS value) from optional token groups; absent when the theme sets none. */
+    readonly vars?: Readonly<Record<string, string>>;
+}

package/dist/theme.js

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

package/dist/timing.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+export declare const TIMING_SOURCES: readonly ["authored", "voice"];
+/**
+ * Finite numbers only (zod 4 rejects NaN and Infinity); scenes sorted, non-overlapping, unique slugs.
+ *
+ * Voice (additive, v1 — no version bump): a `voice`-source row may carry per-scene `words`
+ * (aligner timings on the same absolute clock; sorted, non-overlapping) and the manifest may
+ * carry the full `audio` analysis. Both are optional; older manifests stay valid.
+ */
+export declare const TimingManifestSchema: z.ZodObject<{
+    source: z.ZodEnum<{
+        authored: "authored";
+        voice: "voice";
+    }>;
+    scenes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        start: z.ZodNumber;
+        duration: z.ZodNumber;
+        words: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            w: z.ZodString;
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+            confidence: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    audio: z.ZodOptional<z.ZodObject<{
+        words: z.ZodArray<z.ZodObject<{
+            w: z.ZodString;
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+            confidence: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        silences: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+        }, z.core.$strict>>>;
+        peaks: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        model: z.ZodOptional<z.ZodString>;
+        modelRevision: z.ZodOptional<z.ZodString>;
+        modelLicense: z.ZodOptional<z.ZodString>;
+        duration: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type TimingManifest = z.output<typeof TimingManifestSchema>;

package/dist/timing.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { AudioAnalysisSchema, WordTimingsSchema } from "./audio.js";
+import { SLUG, SLUG_MESSAGE } from "./storyboard.js";
+export const TIMING_SOURCES = ["authored", "voice"];
+const checkScenes = (scenes, ctx) => {
+    const seen = new Set();
+    scenes.forEach((scene, index) => {
+        if (seen.has(scene.id)) {
+            ctx.addIssue({
+                code: "custom",
+                path: [index, "id"],
+                message: `duplicate scene id "${scene.id}"`,
+            });
+        }
+        seen.add(scene.id);
+        const prev = scenes[index - 1];
+        if (prev && scene.start < prev.start + prev.duration) {
+            ctx.addIssue({
+                code: "custom",
+                path: [index, "start"],
+                message: `scene "${scene.id}" overlaps "${prev.id}"`,
+            });
+        }
+    });
+};
+/**
+ * Finite numbers only (zod 4 rejects NaN and Infinity); scenes sorted, non-overlapping, unique slugs.
+ *
+ * Voice (additive, v1 — no version bump): a `voice`-source row may carry per-scene `words`
+ * (aligner timings on the same absolute clock; sorted, non-overlapping) and the manifest may
+ * carry the full `audio` analysis. Both are optional; older manifests stay valid.
+ */
+export const TimingManifestSchema = z.strictObject({
+    source: z.enum(TIMING_SOURCES),
+    scenes: z
+        .array(z.strictObject({
+        id: z.string().regex(SLUG, SLUG_MESSAGE),
+        start: z.number().min(0),
+        duration: z.number().positive(),
+        words: WordTimingsSchema.optional(),
+    }))
+        .superRefine(checkScenes),
+    audio: AudioAnalysisSchema.optional(),
+});

package/dist/validate.d.ts

@@ -0,0 +1,5 @@
+import type { z } from "zod";
+import { type Result, type ValidationError } from "./errors.ts";
+import { type Storyboard } from "./storyboard.ts";
+export declare const toValidationError: (issue: z.core.$ZodIssue, input: unknown) => ValidationError;
+export declare const validateStoryboard: (input: unknown) => Result<Storyboard>;

package/dist/validate.js

@@ -0,0 +1,58 @@
+import { toJsonPointer } from "./errors.js";
+import { forbiddenKeys } from "./reserved-keys.js";
+import { StoryboardSchema } from "./storyboard.js";
+import { readVersion, STORYBOARD_VERSION } from "./version.js";
+const valueAt = (root, path) => path.reduce((node, key) => (typeof node === "object" && node !== null ? Reflect.get(node, key) : undefined), root);
+export const toValidationError = (issue, input) => {
+    const path = toJsonPointer(issue.path);
+    if (issue.code === "invalid_value") {
+        const received = JSON.stringify(valueAt(input, issue.path));
+        return {
+            path,
+            message: `${received} invalid`,
+            suggestion: `use one of: ${issue.values.join("|")}`,
+        };
+    }
+    if (issue.code === "unrecognized_keys") {
+        const keys = issue.keys.join(", ");
+        return {
+            path,
+            message: `unknown key(s): ${keys}`,
+            suggestion: `remove ${keys} (check spelling against the catalog)`,
+        };
+    }
+    const suggestion = issue.code === "custom" ? issue.params?.suggestion : undefined;
+    return typeof suggestion === "string"
+        ? { path, message: issue.message, suggestion }
+        : { path, message: issue.message };
+};
+export const validateStoryboard = (input) => {
+    const version = readVersion(input);
+    if (!version.ok)
+        return { ok: false, errors: [version.error] };
+    if (version.version !== STORYBOARD_VERSION) {
+        return {
+            ok: false,
+            errors: [
+                {
+                    path: "/version",
+                    message: `unknown version ${version.version}`,
+                    suggestion: `use "version": ${STORYBOARD_VERSION}`,
+                },
+            ],
+        };
+    }
+    const forbidden = forbiddenKeys(input, []);
+    if (forbidden.length > 0) {
+        return {
+            ok: false,
+            errors: forbidden.map(({ path, message, suggestion }) => suggestion === undefined
+                ? { path: toJsonPointer(path), message }
+                : { path: toJsonPointer(path), message, suggestion }),
+        };
+    }
+    const parsed = StoryboardSchema.safeParse(input);
+    if (parsed.success)
+        return { ok: true, value: parsed.data };
+    return { ok: false, errors: parsed.error.issues.map((issue) => toValidationError(issue, input)) };
+};

package/dist/version.d.ts

@@ -0,0 +1,10 @@
+import type { ValidationError } from "./errors.ts";
+export declare const STORYBOARD_VERSION = 1;
+export type VersionRead = {
+    readonly ok: true;
+    readonly version: number;
+} | {
+    readonly ok: false;
+    readonly error: ValidationError;
+};
+export declare const readVersion: (input: unknown) => VersionRead;

package/dist/version.js

@@ -0,0 +1,19 @@
+export const STORYBOARD_VERSION = 1;
+const isRecord = (input) => typeof input === "object" && input !== null && !Array.isArray(input);
+const reject = (path, message, suggestion) => ({
+    ok: false,
+    error: { path, message, suggestion },
+});
+export const readVersion = (input) => {
+    if (!isRecord(input)) {
+        return reject("", "storyboard must be a JSON object", `start with {"version": ${STORYBOARD_VERSION}, "meta": {...}, "scenes": [...]}`);
+    }
+    const { version } = input;
+    if (version === undefined) {
+        return reject("/version", "version is required", `add "version": ${STORYBOARD_VERSION}`);
+    }
+    if (typeof version !== "number" || !Number.isInteger(version)) {
+        return reject("/version", "version must be an integer", `use "version": ${STORYBOARD_VERSION}`);
+    }
+    return { ok: true, version };
+};

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@anvpx/motion-schema",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Zod contracts and JSON Schema for @anvpx/motion storyboards.",
+  "license": "MIT",
+  "author": "anvpx",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "motion-kit",
+    "schema",
+    "zod",
+    "storyboard",
+    "video"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "data/**/*.json"
+  ],
+  "dependencies": {
+    "zod": "4.6.7"
+  },
+  "scripts": {
+    "snapshot:update": "node scripts/snapshot-update.mjs"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.