vivid-editor-core 0.1.0

package/README.md

@@ -0,0 +1,19 @@
+# vivid-editor-core
+
+The core of the [VIVID](https://vividai.tv) video editor, shared between the web editor and [vivid-mcp](https://github.com/loopotv/vivid-mcp):
+
+- **Project file v2** — Zod schema (`projectSchemaV2`), types (`ProjectFile`), v1→v2 migration.
+- **Editor store** — `createEditorStore(deps)`: a vanilla zustand store holding tracks, clips, canvas objects, text overlays, undo/redo and every editing action (add, split, trim, speed, transitions, canvas presets, masks…). Browser side effects are injected and default to no-ops, so it runs in Node.
+- **AI commands** — the typed `AiCommand` union, Zod validators and `executeAiCommands`, the orchestrator the VIVID Art Director uses.
+- **Headless editor** — `openHeadlessProject(json, { resolveUrl })` → `apply(commands)` → `toProjectFile()`.
+
+```ts
+import { openHeadlessProject, emptyProjectFile } from 'vivid-editor-core'
+
+const ed = openHeadlessProject(projectJson, { resolveUrl: (assetId) => `https://vivid-api.vividoai.workers.dev/api/assets/${assetId}/download` })
+ed.store.getState().addAsset({ id: 'a1', name: 'hero.mp4', url: '…', durationMs: 10000, file: null, mediaType: 'video', serverAssetId: '…' })
+ed.apply([{ type: 'ADD_CLIP', payload: { assetId: 'a1' } }, { type: 'ADD_TEXT', payload: { text: 'Hello', startMs: 0, endMs: 3000 } }])
+const file = ed.toProjectFile() // save via POST /api/ai/save-editor-project
+```
+
+Peer dependencies: `zod`, `zustand`. Source lives in `vivid-app/packages/editor-core`; the app consumes it from source via alias, vivid-mcp from npm.

package/dist/ai-command-schemas.d.ts

@@ -0,0 +1,486 @@
+/**
+ * M6 — Zod schemas for AI Art Director command validation.
+ *
+ * Every JSON object returned by the LLM is parsed through these schemas
+ * before being passed to executeAiCommands(). safeParse() → readable error
+ * message shown in the chat UI, never a silent drop.
+ *
+ * Schema reuses the v2 type primitives from src/io/schemas.ts but is kept
+ * separate to avoid coupling the load/save path to the LLM path.
+ */
+import { z } from 'zod';
+/** Set keyframe animations on a canvas object or text overlay property. */
+export declare const SetObjectAnimationSchema: z.ZodObject<{
+    type: z.ZodLiteral<"SET_OBJECT_ANIMATION">;
+    payload: z.ZodObject<{
+        objectId: z.ZodString;
+        objectType: z.ZodEnum<{
+            canvas: "canvas";
+            text: "text";
+        }>;
+        property: z.ZodEnum<{
+            x: "x";
+            y: "y";
+            scale: "scale";
+            rotation: "rotation";
+            opacity: "opacity";
+            blur: "blur";
+            brightness: "brightness";
+            contrast: "contrast";
+            saturation: "saturation";
+            maskProgress: "maskProgress";
+        }>;
+        animation: z.ZodObject<{
+            keyframes: z.ZodArray<z.ZodObject<{
+                t: z.ZodNumber;
+                v: z.ZodNumber;
+                easing: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+                    linear: "linear";
+                    easeInQuad: "easeInQuad";
+                    easeOutQuad: "easeOutQuad";
+                    easeInOutQuad: "easeInOutQuad";
+                    easeInCubic: "easeInCubic";
+                    easeOutCubic: "easeOutCubic";
+                    easeInOutCubic: "easeInOutCubic";
+                    easeInBack: "easeInBack";
+                    easeOutBack: "easeOutBack";
+                    easeInOutBack: "easeInOutBack";
+                    easeInElastic: "easeInElastic";
+                    easeOutElastic: "easeOutElastic";
+                    easeInOutElastic: "easeInOutElastic";
+                    easeInBounce: "easeInBounce";
+                    easeOutBounce: "easeOutBounce";
+                    easeInOutBounce: "easeInOutBounce";
+                }>, z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>, z.ZodObject<{
+                    type: z.ZodLiteral<"spring">;
+                    stiffness: z.ZodNumber;
+                    damping: z.ZodNumber;
+                    mass: z.ZodNumber;
+                }, z.core.$strip>]>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** Add or replace an effect on a canvas object or text overlay. */
+export declare const AddEffectSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ADD_EFFECT">;
+    payload: z.ZodObject<{
+        objectId: z.ZodString;
+        objectType: z.ZodEnum<{
+            canvas: "canvas";
+            text: "text";
+        }>;
+        effect: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"blur">;
+            amount: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"vignette">;
+            intensity: z.ZodNumber;
+            size: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"colorGrade">;
+            brightness: z.ZodOptional<z.ZodNumber>;
+            contrast: z.ZodOptional<z.ZodNumber>;
+            saturation: z.ZodOptional<z.ZodNumber>;
+            hue: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"grain">;
+            intensity: z.ZodNumber;
+            size: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"glitch">;
+            intensity: z.ZodNumber;
+            blockSize: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"chromaticAberration">;
+            offset: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"pixelate">;
+            blockSize: z.ZodNumber;
+        }, z.core.$strip>], "type">;
+        replace: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** Remove an effect by type from a canvas object or text overlay. */
+export declare const RemoveEffectSchema: z.ZodObject<{
+    type: z.ZodLiteral<"REMOVE_EFFECT">;
+    payload: z.ZodObject<{
+        objectId: z.ZodString;
+        objectType: z.ZodEnum<{
+            canvas: "canvas";
+            text: "text";
+        }>;
+        effectType: z.ZodEnum<{
+            blur: "blur";
+            vignette: "vignette";
+            colorGrade: "colorGrade";
+            grain: "grain";
+            glitch: "glitch";
+            chromaticAberration: "chromaticAberration";
+            pixelate: "pixelate";
+        }>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** Add an audio-reactive modifier to a canvas object. */
+export declare const AddAudioReactiveSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ADD_AUDIO_REACTIVE">;
+    payload: z.ZodObject<{
+        objectId: z.ZodString;
+        objectType: z.ZodEnum<{
+            canvas: "canvas";
+            text: "text";
+        }>;
+        modifier: z.ZodObject<{
+            property: z.ZodEnum<{
+                x: "x";
+                y: "y";
+                scale: "scale";
+                rotation: "rotation";
+                opacity: "opacity";
+                blur: "blur";
+                brightness: "brightness";
+                contrast: "contrast";
+                saturation: "saturation";
+                maskProgress: "maskProgress";
+            }>;
+            feature: z.ZodEnum<{
+                rms: "rms";
+                low: "low";
+                mid: "mid";
+                high: "high";
+                beat: "beat";
+            }>;
+            assetId: z.ZodString;
+            factor: z.ZodNumber;
+            mode: z.ZodEnum<{
+                add: "add";
+                multiply: "multiply";
+            }>;
+            smoothing: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** Set the v2 mask on a canvas object. */
+export declare const SetMaskSchema: z.ZodObject<{
+    type: z.ZodLiteral<"SET_MASK">;
+    payload: z.ZodObject<{
+        objectId: z.ZodString;
+        mask: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"none">;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"rect">;
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            w: z.ZodNumber;
+            h: z.ZodNumber;
+            feather: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"circle">;
+            cx: z.ZodNumber;
+            cy: z.ZodNumber;
+            r: z.ZodNumber;
+            feather: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"reveal">;
+            direction: z.ZodEnum<{
+                ltr: "ltr";
+                rtl: "rtl";
+                ttb: "ttb";
+                btt: "btt";
+            }>;
+            progress: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"clipPath">;
+            svgPath: z.ZodString;
+        }, z.core.$strip>], "type">;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** Set all animations on an object at once (replaces existing). */
+export declare const SetAnimationsSchema: z.ZodObject<{
+    type: z.ZodLiteral<"SET_ANIMATIONS">;
+    payload: z.ZodObject<{
+        objectId: z.ZodString;
+        objectType: z.ZodEnum<{
+            canvas: "canvas";
+            text: "text";
+        }>;
+        animations: z.ZodRecord<z.ZodEnum<{
+            x: "x";
+            y: "y";
+            scale: "scale";
+            rotation: "rotation";
+            opacity: "opacity";
+            blur: "blur";
+            brightness: "brightness";
+            contrast: "contrast";
+            saturation: "saturation";
+            maskProgress: "maskProgress";
+        }>, z.ZodObject<{
+            keyframes: z.ZodArray<z.ZodObject<{
+                t: z.ZodNumber;
+                v: z.ZodNumber;
+                easing: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+                    linear: "linear";
+                    easeInQuad: "easeInQuad";
+                    easeOutQuad: "easeOutQuad";
+                    easeInOutQuad: "easeInOutQuad";
+                    easeInCubic: "easeInCubic";
+                    easeOutCubic: "easeOutCubic";
+                    easeInOutCubic: "easeInOutCubic";
+                    easeInBack: "easeInBack";
+                    easeOutBack: "easeOutBack";
+                    easeInOutBack: "easeInOutBack";
+                    easeInElastic: "easeInElastic";
+                    easeOutElastic: "easeOutElastic";
+                    easeInOutElastic: "easeInOutElastic";
+                    easeInBounce: "easeInBounce";
+                    easeOutBounce: "easeOutBounce";
+                    easeInOutBounce: "easeInOutBounce";
+                }>, z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>, z.ZodObject<{
+                    type: z.ZodLiteral<"spring">;
+                    stiffness: z.ZodNumber;
+                    damping: z.ZodNumber;
+                    mass: z.ZodNumber;
+                }, z.core.$strip>]>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** The full union of v2 AI commands — used by the LLM response validator. */
+export declare const AiCommandV2Schema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"SET_OBJECT_ANIMATION">;
+    payload: z.ZodObject<{
+        objectId: z.ZodString;
+        objectType: z.ZodEnum<{
+            canvas: "canvas";
+            text: "text";
+        }>;
+        property: z.ZodEnum<{
+            x: "x";
+            y: "y";
+            scale: "scale";
+            rotation: "rotation";
+            opacity: "opacity";
+            blur: "blur";
+            brightness: "brightness";
+            contrast: "contrast";
+            saturation: "saturation";
+            maskProgress: "maskProgress";
+        }>;
+        animation: z.ZodObject<{
+            keyframes: z.ZodArray<z.ZodObject<{
+                t: z.ZodNumber;
+                v: z.ZodNumber;
+                easing: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+                    linear: "linear";
+                    easeInQuad: "easeInQuad";
+                    easeOutQuad: "easeOutQuad";
+                    easeInOutQuad: "easeInOutQuad";
+                    easeInCubic: "easeInCubic";
+                    easeOutCubic: "easeOutCubic";
+                    easeInOutCubic: "easeInOutCubic";
+                    easeInBack: "easeInBack";
+                    easeOutBack: "easeOutBack";
+                    easeInOutBack: "easeInOutBack";
+                    easeInElastic: "easeInElastic";
+                    easeOutElastic: "easeOutElastic";
+                    easeInOutElastic: "easeInOutElastic";
+                    easeInBounce: "easeInBounce";
+                    easeOutBounce: "easeOutBounce";
+                    easeInOutBounce: "easeInOutBounce";
+                }>, z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>, z.ZodObject<{
+                    type: z.ZodLiteral<"spring">;
+                    stiffness: z.ZodNumber;
+                    damping: z.ZodNumber;
+                    mass: z.ZodNumber;
+                }, z.core.$strip>]>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ADD_EFFECT">;
+    payload: z.ZodObject<{
+        objectId: z.ZodString;
+        objectType: z.ZodEnum<{
+            canvas: "canvas";
+            text: "text";
+        }>;
+        effect: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"blur">;
+            amount: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"vignette">;
+            intensity: z.ZodNumber;
+            size: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"colorGrade">;
+            brightness: z.ZodOptional<z.ZodNumber>;
+            contrast: z.ZodOptional<z.ZodNumber>;
+            saturation: z.ZodOptional<z.ZodNumber>;
+            hue: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"grain">;
+            intensity: z.ZodNumber;
+            size: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"glitch">;
+            intensity: z.ZodNumber;
+            blockSize: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"chromaticAberration">;
+            offset: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"pixelate">;
+            blockSize: z.ZodNumber;
+        }, z.core.$strip>], "type">;
+        replace: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"REMOVE_EFFECT">;
+    payload: z.ZodObject<{
+        objectId: z.ZodString;
+        objectType: z.ZodEnum<{
+            canvas: "canvas";
+            text: "text";
+        }>;
+        effectType: z.ZodEnum<{
+            blur: "blur";
+            vignette: "vignette";
+            colorGrade: "colorGrade";
+            grain: "grain";
+            glitch: "glitch";
+            chromaticAberration: "chromaticAberration";
+            pixelate: "pixelate";
+        }>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ADD_AUDIO_REACTIVE">;
+    payload: z.ZodObject<{
+        objectId: z.ZodString;
+        objectType: z.ZodEnum<{
+            canvas: "canvas";
+            text: "text";
+        }>;
+        modifier: z.ZodObject<{
+            property: z.ZodEnum<{
+                x: "x";
+                y: "y";
+                scale: "scale";
+                rotation: "rotation";
+                opacity: "opacity";
+                blur: "blur";
+                brightness: "brightness";
+                contrast: "contrast";
+                saturation: "saturation";
+                maskProgress: "maskProgress";
+            }>;
+            feature: z.ZodEnum<{
+                rms: "rms";
+                low: "low";
+                mid: "mid";
+                high: "high";
+                beat: "beat";
+            }>;
+            assetId: z.ZodString;
+            factor: z.ZodNumber;
+            mode: z.ZodEnum<{
+                add: "add";
+                multiply: "multiply";
+            }>;
+            smoothing: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"SET_MASK">;
+    payload: z.ZodObject<{
+        objectId: z.ZodString;
+        mask: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"none">;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"rect">;
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            w: z.ZodNumber;
+            h: z.ZodNumber;
+            feather: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"circle">;
+            cx: z.ZodNumber;
+            cy: z.ZodNumber;
+            r: z.ZodNumber;
+            feather: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"reveal">;
+            direction: z.ZodEnum<{
+                ltr: "ltr";
+                rtl: "rtl";
+                ttb: "ttb";
+                btt: "btt";
+            }>;
+            progress: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"clipPath">;
+            svgPath: z.ZodString;
+        }, z.core.$strip>], "type">;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"SET_ANIMATIONS">;
+    payload: z.ZodObject<{
+        objectId: z.ZodString;
+        objectType: z.ZodEnum<{
+            canvas: "canvas";
+            text: "text";
+        }>;
+        animations: z.ZodRecord<z.ZodEnum<{
+            x: "x";
+            y: "y";
+            scale: "scale";
+            rotation: "rotation";
+            opacity: "opacity";
+            blur: "blur";
+            brightness: "brightness";
+            contrast: "contrast";
+            saturation: "saturation";
+            maskProgress: "maskProgress";
+        }>, z.ZodObject<{
+            keyframes: z.ZodArray<z.ZodObject<{
+                t: z.ZodNumber;
+                v: z.ZodNumber;
+                easing: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+                    linear: "linear";
+                    easeInQuad: "easeInQuad";
+                    easeOutQuad: "easeOutQuad";
+                    easeInOutQuad: "easeInOutQuad";
+                    easeInCubic: "easeInCubic";
+                    easeOutCubic: "easeOutCubic";
+                    easeInOutCubic: "easeInOutCubic";
+                    easeInBack: "easeInBack";
+                    easeOutBack: "easeOutBack";
+                    easeInOutBack: "easeInOutBack";
+                    easeInElastic: "easeInElastic";
+                    easeOutElastic: "easeOutElastic";
+                    easeInOutElastic: "easeInOutElastic";
+                    easeInBounce: "easeInBounce";
+                    easeOutBounce: "easeOutBounce";
+                    easeInOutBounce: "easeInOutBounce";
+                }>, z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>, z.ZodObject<{
+                    type: z.ZodLiteral<"spring">;
+                    stiffness: z.ZodNumber;
+                    damping: z.ZodNumber;
+                    mass: z.ZodNumber;
+                }, z.core.$strip>]>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>], "type">;
+export type AiCommandV2 = z.infer<typeof AiCommandV2Schema>;
+/**
+ * Parse and validate a raw LLM JSON response as an array of v2 AI commands.
+ *
+ * Returns { commands, errors } where errors is a human-readable list.
+ * Never throws — all parse errors are collected and returned.
+ */
+export declare function parseLlmCommands(raw: unknown): {
+    commands: AiCommandV2[];
+    errors: string[];
+};

package/dist/ai-command-schemas.js

@@ -0,0 +1,182 @@
+/**
+ * M6 — Zod schemas for AI Art Director command validation.
+ *
+ * Every JSON object returned by the LLM is parsed through these schemas
+ * before being passed to executeAiCommands(). safeParse() → readable error
+ * message shown in the chat UI, never a silent drop.
+ *
+ * Schema reuses the v2 type primitives from src/io/schemas.ts but is kept
+ * separate to avoid coupling the load/save path to the LLM path.
+ */
+import { z } from 'zod';
+// ── Primitive schemas (mirrors src/io/schemas.ts, kept local for isolation) ──
+const EASING_PRESET = z.enum([
+    'linear',
+    'easeInQuad', 'easeOutQuad', 'easeInOutQuad',
+    'easeInCubic', 'easeOutCubic', 'easeInOutCubic',
+    'easeInBack', 'easeOutBack', 'easeInOutBack',
+    'easeInElastic', 'easeOutElastic', 'easeInOutElastic',
+    'easeInBounce', 'easeOutBounce', 'easeInOutBounce',
+]);
+const BEZIER_EASING = z.tuple([z.number(), z.number(), z.number(), z.number()]);
+const SPRING_CONFIG = z.object({
+    type: z.literal('spring'),
+    stiffness: z.number().positive(),
+    damping: z.number().min(0),
+    mass: z.number().positive(),
+});
+const EASING = z.union([EASING_PRESET, BEZIER_EASING, SPRING_CONFIG]);
+const KEYFRAME = z.object({
+    t: z.number().min(0),
+    v: z.number(),
+    easing: EASING.optional(),
+});
+const ANIMATION = z.object({
+    keyframes: z.array(KEYFRAME).min(1),
+});
+const ANIMATABLE_PROP = z.enum([
+    'x', 'y', 'scale', 'rotation', 'opacity',
+    'blur', 'brightness', 'contrast', 'saturation', 'maskProgress',
+]);
+const ANIMATIONS = z.record(ANIMATABLE_PROP, ANIMATION);
+const EFFECT = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('blur'), amount: z.number().min(0).max(40) }),
+    z.object({ type: z.literal('vignette'), intensity: z.number().min(0).max(1), size: z.number().min(0).max(1) }),
+    z.object({
+        type: z.literal('colorGrade'),
+        brightness: z.number().optional(),
+        contrast: z.number().optional(),
+        saturation: z.number().optional(),
+        hue: z.number().optional(),
+    }),
+    z.object({ type: z.literal('grain'), intensity: z.number().min(0).max(1), size: z.number().min(0.5).max(3) }),
+    z.object({ type: z.literal('glitch'), intensity: z.number().min(0).max(1), blockSize: z.number().min(4).max(64) }),
+    z.object({ type: z.literal('chromaticAberration'), offset: z.number().min(0).max(20) }),
+    z.object({ type: z.literal('pixelate'), blockSize: z.number().min(2).max(64) }),
+]);
+const MASK_V2 = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('none') }),
+    z.object({
+        type: z.literal('rect'),
+        x: z.number().min(0).max(1), y: z.number().min(0).max(1),
+        w: z.number().min(0).max(1), h: z.number().min(0).max(1),
+        feather: z.number().optional(),
+    }),
+    z.object({
+        type: z.literal('circle'),
+        cx: z.number().min(0).max(1), cy: z.number().min(0).max(1),
+        r: z.number().min(0).max(1),
+        feather: z.number().optional(),
+    }),
+    z.object({
+        type: z.literal('reveal'),
+        direction: z.enum(['ltr', 'rtl', 'ttb', 'btt']),
+        progress: z.number().min(0).max(1),
+    }),
+    z.object({ type: z.literal('clipPath'), svgPath: z.string().min(1) }),
+]);
+const AUDIO_REACTIVE = z.object({
+    property: ANIMATABLE_PROP,
+    feature: z.enum(['rms', 'low', 'mid', 'high', 'beat']),
+    assetId: z.string(),
+    factor: z.number(),
+    mode: z.enum(['add', 'multiply']),
+    smoothing: z.number().min(0).max(1).optional(),
+});
+// ── Command schemas ───────────────────────────────────────────────────────────
+/** Set keyframe animations on a canvas object or text overlay property. */
+export const SetObjectAnimationSchema = z.object({
+    type: z.literal('SET_OBJECT_ANIMATION'),
+    payload: z.object({
+        objectId: z.string(),
+        /** 'canvas' for CanvasObject, 'text' for TextOverlay */
+        objectType: z.enum(['canvas', 'text']),
+        property: ANIMATABLE_PROP,
+        animation: ANIMATION,
+    }),
+});
+/** Add or replace an effect on a canvas object or text overlay. */
+export const AddEffectSchema = z.object({
+    type: z.literal('ADD_EFFECT'),
+    payload: z.object({
+        objectId: z.string(),
+        objectType: z.enum(['canvas', 'text']),
+        effect: EFFECT,
+        /** If true, replace any existing effect of the same type */
+        replace: z.boolean().optional(),
+    }),
+});
+/** Remove an effect by type from a canvas object or text overlay. */
+export const RemoveEffectSchema = z.object({
+    type: z.literal('REMOVE_EFFECT'),
+    payload: z.object({
+        objectId: z.string(),
+        objectType: z.enum(['canvas', 'text']),
+        effectType: z.enum(['blur', 'vignette', 'colorGrade', 'grain', 'glitch', 'chromaticAberration', 'pixelate']),
+    }),
+});
+/** Add an audio-reactive modifier to a canvas object. */
+export const AddAudioReactiveSchema = z.object({
+    type: z.literal('ADD_AUDIO_REACTIVE'),
+    payload: z.object({
+        objectId: z.string(),
+        objectType: z.enum(['canvas', 'text']),
+        modifier: AUDIO_REACTIVE,
+    }),
+});
+/** Set the v2 mask on a canvas object. */
+export const SetMaskSchema = z.object({
+    type: z.literal('SET_MASK'),
+    payload: z.object({
+        objectId: z.string(),
+        mask: MASK_V2,
+    }),
+});
+/** Set all animations on an object at once (replaces existing). */
+export const SetAnimationsSchema = z.object({
+    type: z.literal('SET_ANIMATIONS'),
+    payload: z.object({
+        objectId: z.string(),
+        objectType: z.enum(['canvas', 'text']),
+        animations: ANIMATIONS,
+    }),
+});
+/** The full union of v2 AI commands — used by the LLM response validator. */
+export const AiCommandV2Schema = z.discriminatedUnion('type', [
+    SetObjectAnimationSchema,
+    AddEffectSchema,
+    RemoveEffectSchema,
+    AddAudioReactiveSchema,
+    SetMaskSchema,
+    SetAnimationsSchema,
+]);
+/**
+ * Parse and validate a raw LLM JSON response as an array of v2 AI commands.
+ *
+ * Returns { commands, errors } where errors is a human-readable list.
+ * Never throws — all parse errors are collected and returned.
+ */
+export function parseLlmCommands(raw) {
+    if (!Array.isArray(raw)) {
+        return {
+            commands: [],
+            errors: ['La risposta del modello non è un array di comandi valido.'],
+        };
+    }
+    const commands = [];
+    const errors = [];
+    for (let i = 0; i < raw.length; i++) {
+        const result = AiCommandV2Schema.safeParse(raw[i]);
+        if (result.success) {
+            commands.push(result.data);
+        }
+        else {
+            const issues = result.error.issues
+                .slice(0, 3)
+                .map((iss) => `${iss.path.join('.')}: ${iss.message}`)
+                .join('; ');
+            errors.push(`Comando #${i + 1} non valido — ${issues}`);
+        }
+    }
+    return { commands, errors };
+}