@anvpx/motion-schema 0.0.0-stage → 0.1.0

package/dist/platform.d.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { type Result } from "./errors.ts";
+/** Delivery-platform preset: frame, codec, loudness and UI-safe margins (fractions of the frame). */
+export declare const PlatformPresetSchema: z.ZodObject<{
+    id: z.ZodString;
+    aliases: z.ZodArray<z.ZodString>;
+    aspect: z.ZodString;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    maxFps: z.ZodNumber;
+    maxDurationSec: z.ZodOptional<z.ZodNumber>;
+    codec: z.ZodObject<{
+        video: z.ZodString;
+        audio: z.ZodString;
+    }, z.core.$strict>;
+    audio: z.ZodObject<{
+        lufsTarget: z.ZodNumber;
+        truePeakDb: z.ZodNumber;
+    }, z.core.$strict>;
+    safeZones: z.ZodObject<{
+        top: z.ZodNumber;
+        right: z.ZodNumber;
+        bottom: z.ZodNumber;
+        left: z.ZodNumber;
+    }, z.core.$strict>;
+    safe: z.ZodOptional<z.ZodObject<{
+        top: z.ZodNumber;
+        bottom: z.ZodNumber;
+        side: z.ZodNumber;
+    }, z.core.$strict>>;
+    notes: z.ZodOptional<z.ZodString>;
+    source: z.ZodString;
+    verified: z.ZodBoolean;
+}, z.core.$strict>;
+export type PlatformPreset = z.infer<typeof PlatformPresetSchema>;
+/**
+ * PLAN 7f.4: `PlatformTemplate` clashed with the template contract (`TemplateManifest` et al).
+ * Canonical name is now `PlatformPreset` (platform delivery preset, not an authoring template).
+ * The `PlatformTemplate*` names below are deprecated aliases kept for the CLI + existing
+ * imports; remove them only with a major version + migration note. No data change.
+ */
+export declare const PlatformTemplateSchema: z.ZodObject<{
+    id: z.ZodString;
+    aliases: z.ZodArray<z.ZodString>;
+    aspect: z.ZodString;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    maxFps: z.ZodNumber;
+    maxDurationSec: z.ZodOptional<z.ZodNumber>;
+    codec: z.ZodObject<{
+        video: z.ZodString;
+        audio: z.ZodString;
+    }, z.core.$strict>;
+    audio: z.ZodObject<{
+        lufsTarget: z.ZodNumber;
+        truePeakDb: z.ZodNumber;
+    }, z.core.$strict>;
+    safeZones: z.ZodObject<{
+        top: z.ZodNumber;
+        right: z.ZodNumber;
+        bottom: z.ZodNumber;
+        left: z.ZodNumber;
+    }, z.core.$strict>;
+    safe: z.ZodOptional<z.ZodObject<{
+        top: z.ZodNumber;
+        bottom: z.ZodNumber;
+        side: z.ZodNumber;
+    }, z.core.$strict>>;
+    notes: z.ZodOptional<z.ZodString>;
+    source: z.ZodString;
+    verified: z.ZodBoolean;
+}, z.core.$strict>;
+export type PlatformTemplate = PlatformPreset;
+/** Registry-free: validates one preset document; callers decide where it came from. */
+export declare const parsePlatformPreset: (input: unknown) => Result<PlatformPreset>;
+/** @deprecated Use `parsePlatformPreset`; alias kept so old imports stay valid. */
+export declare const parsePlatformTemplate: typeof parsePlatformPreset;

package/dist/platform.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { toJsonPointer } from "./errors.js";
+const fraction = z.number().min(0).max(1);
+/** Delivery-platform preset: frame, codec, loudness and UI-safe margins (fractions of the frame). */
+export const PlatformPresetSchema = z.strictObject({
+    id: z.string().regex(/^[a-z][a-z0-9-]*$/),
+    aliases: z.array(z.string().regex(/^[a-z][a-z0-9-]*$/)),
+    aspect: z.string().regex(/^\d+:\d+$/),
+    width: z.number().int().positive(),
+    height: z.number().int().positive(),
+    maxFps: z.number().int().positive(),
+    maxDurationSec: z.number().positive().optional(),
+    codec: z.strictObject({ video: z.string().min(1), audio: z.string().min(1) }),
+    audio: z.strictObject({ lufsTarget: z.number().max(0), truePeakDb: z.number().max(0) }),
+    safeZones: z.strictObject({
+        top: fraction,
+        right: fraction,
+        bottom: fraction,
+        left: fraction,
+    }),
+    /**
+     * Conservative margins (fractions) that base text must stay outside: `side` applies to left and right.
+     * Common values, not per-platform measurements; `safeZones` holds the platform-specific UI bands.
+     */
+    safe: z.strictObject({ top: fraction, bottom: fraction, side: fraction }).optional(),
+    notes: z.string().optional(),
+    source: z.string().min(1),
+    verified: z.boolean(),
+});
+/**
+ * PLAN 7f.4: `PlatformTemplate` clashed with the template contract (`TemplateManifest` et al).
+ * Canonical name is now `PlatformPreset` (platform delivery preset, not an authoring template).
+ * The `PlatformTemplate*` names below are deprecated aliases kept for the CLI + existing
+ * imports; remove them only with a major version + migration note. No data change.
+ */
+export const PlatformTemplateSchema = PlatformPresetSchema;
+/** Registry-free: validates one preset document; callers decide where it came from. */
+export const parsePlatformPreset = (input) => {
+    const parsed = PlatformPresetSchema.safeParse(input);
+    if (parsed.success)
+        return { ok: true, value: parsed.data };
+    return {
+        ok: false,
+        errors: parsed.error.issues.map((issue) => ({
+            path: toJsonPointer(issue.path),
+            message: issue.message,
+        })),
+    };
+};
+/** @deprecated Use `parsePlatformPreset`; alias kept so old imports stay valid. */
+export const parsePlatformTemplate = parsePlatformPreset;

package/dist/reserved-keys.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+export declare const RESERVED_MESSAGE = "reserved key is not allowed";
+/** Record key schema; zod silently drops an own `__proto__` key, so raw input is also scanned. */
+export declare const reservedKey: z.ZodString;
+type Path = (string | number)[];
+export interface ForbiddenKey {
+    readonly path: Path;
+    readonly message: string;
+    readonly suggestion?: string;
+}
+/** Forbidden keys (prototype-polluting or execution-shaped) anywhere inside a value. */
+export declare const forbiddenKeys: (value: unknown, path: Path) => ForbiddenKey[];
+export {};

package/dist/reserved-keys.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+export const RESERVED_MESSAGE = "reserved key is not allowed";
+const RESERVED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+/** Execution-shaped keys: storyboards are data, never commands. */
+const EXECUTION_KEYS = new Set([
+    "command",
+    "argv",
+    "shell",
+    "filter",
+    "executable",
+    "env",
+]);
+/** Record key schema; zod silently drops an own `__proto__` key, so raw input is also scanned. */
+export const reservedKey = z.string().refine((key) => !RESERVED_KEYS.has(key), RESERVED_MESSAGE);
+const forbiddenAt = (path, key) => {
+    if (RESERVED_KEYS.has(key))
+        return [{ path, message: RESERVED_MESSAGE }];
+    if (EXECUTION_KEYS.has(key)) {
+        return [
+            {
+                path,
+                message: `forbidden key "${key}": storyboards are data only, never commands`,
+                suggestion: `remove "${key}"`,
+            },
+        ];
+    }
+    return [];
+};
+/** Forbidden keys (prototype-polluting or execution-shaped) anywhere inside a value. */
+export const forbiddenKeys = (value, path) => {
+    if (Array.isArray(value)) {
+        return value.flatMap((item, index) => forbiddenKeys(item, [...path, index]));
+    }
+    if (typeof value !== "object" || value === null)
+        return [];
+    return Object.entries(value).flatMap(([key, child]) => [
+        ...forbiddenAt([...path, key], key),
+        ...forbiddenKeys(child, [...path, key]),
+    ]);
+};

package/dist/storyboard.d.ts

@@ -0,0 +1,147 @@
+import { z } from "zod";
+import { STORYBOARD_VERSION } from "./version.ts";
+export { STORYBOARD_VERSION };
+export declare const SHOTS: readonly ["wide", "medium", "close", "overhead"];
+export declare const MOVES: readonly ["static", "push-in", "pull-out", "pan-l", "pan-r", "tilt", "orbit", "reveal"];
+export declare const EASES: readonly ["linear", "in", "out", "in-out", "spring-soft", "spring-snappy"];
+export declare const TRANSITIONS: readonly ["cut", "crossfade", "wipe", "push", "zoom-through"];
+export declare const LAYERS: readonly ["base", "overlay"];
+/** Render-gate policy twin of the sidecar approval (PLAN 7d.3): absent means "auto". */
+export declare const APPROVALS: readonly ["auto", "confirm"];
+export type Approval = (typeof APPROVALS)[number];
+export declare const SLUG: RegExp;
+export declare const SLUG_MESSAGE = "must be a lowercase slug (a-z, 0-9, hyphens)";
+export declare const SceneEntryBaseSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    duration: z.ZodOptional<z.ZodNumber>;
+    narration: z.ZodOptional<z.ZodString>;
+    words: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        w: z.ZodString;
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+        confidence: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
+    props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    shot: z.ZodOptional<z.ZodEnum<{
+        close: "close";
+        medium: "medium";
+        overhead: "overhead";
+        wide: "wide";
+    }>>;
+    move: z.ZodOptional<z.ZodEnum<{
+        orbit: "orbit";
+        "pan-l": "pan-l";
+        "pan-r": "pan-r";
+        "pull-out": "pull-out";
+        "push-in": "push-in";
+        reveal: "reveal";
+        static: "static";
+        tilt: "tilt";
+    }>>;
+    ease: z.ZodOptional<z.ZodEnum<{
+        in: "in";
+        "in-out": "in-out";
+        linear: "linear";
+        out: "out";
+        "spring-snappy": "spring-snappy";
+        "spring-soft": "spring-soft";
+    }>>;
+    transition: z.ZodOptional<z.ZodEnum<{
+        crossfade: "crossfade";
+        cut: "cut";
+        push: "push";
+        wipe: "wipe";
+        "zoom-through": "zoom-through";
+    }>>;
+    focus: z.ZodOptional<z.ZodString>;
+    layer: z.ZodOptional<z.ZodEnum<{
+        base: "base";
+        overlay: "overlay";
+    }>>;
+    over: z.ZodOptional<z.ZodString>;
+    offset: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const StoryboardMetaSchema: z.ZodObject<{
+    title: z.ZodString;
+    fps: z.ZodDefault<z.ZodNumber>;
+    width: z.ZodDefault<z.ZodNumber>;
+    height: z.ZodDefault<z.ZodNumber>;
+    theme: z.ZodDefault<z.ZodString>;
+    lang: z.ZodOptional<z.ZodString>;
+    platform: z.ZodOptional<z.ZodString>;
+    approval: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        confirm: "confirm";
+    }>>;
+}, z.core.$strict>;
+export declare const StoryboardSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    meta: z.ZodObject<{
+        title: z.ZodString;
+        fps: z.ZodDefault<z.ZodNumber>;
+        width: z.ZodDefault<z.ZodNumber>;
+        height: z.ZodDefault<z.ZodNumber>;
+        theme: z.ZodDefault<z.ZodString>;
+        lang: z.ZodOptional<z.ZodString>;
+        platform: z.ZodOptional<z.ZodString>;
+        approval: z.ZodOptional<z.ZodEnum<{
+            auto: "auto";
+            confirm: "confirm";
+        }>>;
+    }, z.core.$strict>;
+    scenes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        duration: z.ZodOptional<z.ZodNumber>;
+        narration: z.ZodOptional<z.ZodString>;
+        words: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            w: z.ZodString;
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+            confidence: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>>;
+        props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        shot: z.ZodOptional<z.ZodEnum<{
+            close: "close";
+            medium: "medium";
+            overhead: "overhead";
+            wide: "wide";
+        }>>;
+        move: z.ZodOptional<z.ZodEnum<{
+            orbit: "orbit";
+            "pan-l": "pan-l";
+            "pan-r": "pan-r";
+            "pull-out": "pull-out";
+            "push-in": "push-in";
+            reveal: "reveal";
+            static: "static";
+            tilt: "tilt";
+        }>>;
+        ease: z.ZodOptional<z.ZodEnum<{
+            in: "in";
+            "in-out": "in-out";
+            linear: "linear";
+            out: "out";
+            "spring-snappy": "spring-snappy";
+            "spring-soft": "spring-soft";
+        }>>;
+        transition: z.ZodOptional<z.ZodEnum<{
+            crossfade: "crossfade";
+            cut: "cut";
+            push: "push";
+            wipe: "wipe";
+            "zoom-through": "zoom-through";
+        }>>;
+        focus: z.ZodOptional<z.ZodString>;
+        layer: z.ZodOptional<z.ZodEnum<{
+            base: "base";
+            overlay: "overlay";
+        }>>;
+        over: z.ZodOptional<z.ZodString>;
+        offset: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type SceneEntry = z.output<typeof SceneEntryBaseSchema>;
+export type StoryboardMeta = z.output<typeof StoryboardMetaSchema>;
+export type Storyboard = z.output<typeof StoryboardSchema>;

package/dist/storyboard.js

@@ -0,0 +1,136 @@
+import { z } from "zod";
+import { WordTimingsSchema } from "./audio.js";
+import { forbiddenKeys, reservedKey } from "./reserved-keys.js";
+import { STORYBOARD_VERSION } from "./version.js";
+export { STORYBOARD_VERSION };
+export const SHOTS = ["wide", "medium", "close", "overhead"];
+export const MOVES = [
+    "static",
+    "push-in",
+    "pull-out",
+    "pan-l",
+    "pan-r",
+    "tilt",
+    "orbit",
+    "reveal",
+];
+export const EASES = ["linear", "in", "out", "in-out", "spring-soft", "spring-snappy"];
+export const TRANSITIONS = ["cut", "crossfade", "wipe", "push", "zoom-through"];
+export const LAYERS = ["base", "overlay"];
+/** Render-gate policy twin of the sidecar approval (PLAN 7d.3): absent means "auto". */
+export const APPROVALS = ["auto", "confirm"];
+export const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+export const SLUG_MESSAGE = "must be a lowercase slug (a-z, 0-9, hyphens)";
+export const SceneEntryBaseSchema = z.strictObject({
+    id: z.string().regex(SLUG, SLUG_MESSAGE),
+    type: z.string().min(1),
+    duration: z.number().positive().optional(),
+    narration: z.string().optional(),
+    /** Voice word timings for the narration (aligner output, same order as spoken). Additive, v1. */
+    words: WordTimingsSchema.optional(),
+    props: z.record(reservedKey, z.unknown()),
+    shot: z.enum(SHOTS).optional(),
+    move: z.enum(MOVES).optional(),
+    ease: z.enum(EASES).optional(),
+    transition: z.enum(TRANSITIONS).optional(),
+    focus: z.string().min(1).optional(),
+    /** "overlay" stacks above the base timeline and does not advance it (default "base"). */
+    layer: z.enum(LAYERS).optional(),
+    /** Overlay only: id of the base scene it is placed over. */
+    over: z.string().regex(SLUG, SLUG_MESSAGE).optional(),
+    /** Overlay only: seconds after the start of the `over` scene (default 0). */
+    offset: z.number().min(0).optional(),
+});
+export const StoryboardMetaSchema = z.strictObject({
+    title: z.string().min(1),
+    fps: z.number().int().positive().default(30),
+    width: z.number().int().positive().default(1920),
+    height: z.number().int().positive().default(1080),
+    theme: z.string().min(1).default("default"),
+    lang: z.string().min(2).optional(),
+    /** Delivery-platform id (packages/schema/data/platforms); lets lint apply that platform's safe margins. */
+    platform: z.string().regex(SLUG, SLUG_MESSAGE).optional(),
+    /**
+     * Render-gate policy (PLAN 7d.3 schema twin of the `.mk approval.json` sidecar):
+     * "auto" renders without a gate, "confirm" requires `mk approve` + `mk render --gated`.
+     * Optional, absent means "auto" (current behaviour); additive, no version bump.
+     */
+    approval: z.enum(APPROVALS).optional(),
+});
+const overlayProblems = (scene) => {
+    if (scene.layer !== "overlay") {
+        return ["over", "offset"]
+            .filter((field) => Reflect.get(scene, field) !== undefined)
+            .map((field) => ({
+            field,
+            message: 'only overlays take over/offset; set layer: "overlay"',
+            suggestion: 'remove it or set layer: "overlay"',
+        }));
+    }
+    const problems = [];
+    if (scene.over === undefined) {
+        problems.push({
+            field: "over",
+            message: "overlay needs over: <base scene id>",
+            suggestion: "set over to the id of the base scene it covers",
+        });
+    }
+    if (scene.duration === undefined) {
+        problems.push({
+            field: "duration",
+            message: "overlay needs its own duration",
+            suggestion: "set duration in seconds (must fit inside the base scene)",
+        });
+    }
+    if (scene.transition !== undefined) {
+        problems.push({
+            field: "transition",
+            message: "overlays do not take a transition",
+            suggestion: "remove transition; overlays fade in and out themselves",
+        });
+    }
+    return problems;
+};
+export const StoryboardSchema = z
+    .strictObject({
+    version: z.literal(STORYBOARD_VERSION),
+    meta: StoryboardMetaSchema,
+    scenes: z.array(SceneEntryBaseSchema).min(1),
+})
+    .superRefine((storyboard, ctx) => {
+    const seen = new Set();
+    storyboard.scenes.forEach((scene, index) => {
+        for (const { path, message, suggestion } of forbiddenKeys(scene.props, [
+            "scenes",
+            index,
+            "props",
+        ])) {
+            ctx.addIssue({ code: "custom", path, message, params: { suggestion } });
+        }
+        if (seen.has(scene.id)) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["scenes", index, "id"],
+                message: `duplicate scene id "${scene.id}"`,
+                params: { suggestion: "give every scene a unique id" },
+            });
+        }
+        seen.add(scene.id);
+        for (const { field, message, suggestion } of overlayProblems(scene)) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["scenes", index, field],
+                message,
+                params: { suggestion },
+            });
+        }
+    });
+    if (storyboard.scenes.every((scene) => scene.layer === "overlay")) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["scenes"],
+            message: "needs at least one base scene",
+            params: { suggestion: "overlays sit over base scenes; add a scene without layer" },
+        });
+    }
+});