vivid-editor-core 0.1.0

package/dist/ai-orchestrator.js

@@ -0,0 +1,617 @@
+/**
+ * AI Art Director — State Orchestrator
+ *
+ * Processes structured AI commands against the editor Zustand store.
+ * Each command maps to one or more store mutations (e.g. adding a visual clip
+ * always creates both a TimelineClip AND a CanvasObject).
+ */
+import { createTextOverlay } from './text-presets.js';
+/**
+ * Take whatever the LLM produced for an ADD_TEXT payload and:
+ *  - clamp x/y to [0, 1] so the overlay can't land off-canvas
+ *  - clamp opacity / scale / rotation to sensible ranges
+ *  - guarantee 0 < (endMs - startMs) so the overlay is visible for some time
+ *  - fill in every required field via createTextOverlay's defaults
+ *
+ * Returns { overlay, warnings[] } so the orchestrator can log what
+ * had to be patched up.
+ */
+function normalizeAiTextOverlay(raw, projectDurationMs) {
+    const warnings = [];
+    const patch = { ...raw };
+    const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));
+    if (typeof patch.x === 'number' && (patch.x < 0 || patch.x > 1)) {
+        warnings.push(`x=${patch.x} clamped to [0,1]`);
+        patch.x = clamp(patch.x, 0, 1);
+    }
+    if (typeof patch.y === 'number' && (patch.y < 0 || patch.y > 1)) {
+        warnings.push(`y=${patch.y} clamped to [0,1]`);
+        patch.y = clamp(patch.y, 0, 1);
+    }
+    if (typeof patch.opacity === 'number')
+        patch.opacity = clamp(patch.opacity, 0, 1);
+    if (typeof patch.scale === 'number')
+        patch.scale = clamp(patch.scale, 0.1, 10);
+    // Timing — guarantee start < end and both inside project range.
+    const start = typeof patch.startMs === 'number' && patch.startMs >= 0 ? patch.startMs : 0;
+    let end = typeof patch.endMs === 'number' && patch.endMs > 0 ? patch.endMs : start + 3000;
+    if (end <= start) {
+        warnings.push(`endMs (${end}) <= startMs (${start}); extending by 3 s`);
+        end = start + 3000;
+    }
+    if (projectDurationMs > 0 && start >= projectDurationMs) {
+        warnings.push(`startMs (${start}) past project end; clamping`);
+        patch.startMs = Math.max(0, projectDurationMs - 3000);
+        patch.endMs = projectDurationMs;
+    }
+    else {
+        patch.startMs = start;
+        patch.endMs = projectDurationMs > 0 ? Math.min(end, projectDurationMs) : end;
+    }
+    return { overlay: createTextOverlay(patch), warnings };
+}
+/**
+ * Execute an array of AI commands against the editor store.
+ *
+ * Pushes a single undo checkpoint before processing all commands,
+ * so the entire AI action can be undone in one Ctrl+Z.
+ */
+export function executeAiCommands(commands, snapshot, actions) {
+    const errors = [];
+    let applied = 0;
+    // Single undo checkpoint for the whole batch
+    actions.pushUndo();
+    // Whitelist of valid command types — used to detect when the LLM
+    // hallucinates a value (e.g. "fade-in") into the `type` field.
+    const VALID_TYPES = new Set([
+        'ADD_TEXT', 'UPDATE_TEXT', 'REMOVE_TEXT',
+        'ADD_CLIP', 'UPDATE_CLIP', 'REMOVE_CLIP',
+        'UPDATE_CANVAS_OBJECT', 'SET_CANVAS_PRESET',
+        'ADD_TRACK', 'SPLIT_CLIP', 'DUPLICATE_CLIP',
+        'SET_TRANSITION', 'SET_CLIP_ANIMATION',
+        'SET_CINEMATIC_LOOK', 'DETACH_AUDIO',
+        'CUT_TO_BEAT',
+        // V2
+        'SET_OBJECT_ANIMATION', 'SET_ANIMATIONS',
+        'ADD_EFFECT', 'REMOVE_EFFECT',
+        'ADD_AUDIO_REACTIVE', 'SET_MASK',
+    ]);
+    for (const cmd of commands) {
+        // Defensive: every command must be { type, payload }. The LLM
+        // sometimes flattens the envelope or puts a value into `type`.
+        if (!cmd || typeof cmd !== 'object' || !('type' in cmd)) {
+            errors.push(`Malformed command: ${JSON.stringify(cmd)}`);
+            continue;
+        }
+        if (!VALID_TYPES.has(cmd.type)) {
+            errors.push(`Unknown command type: ${cmd.type}`);
+            continue;
+        }
+        if (!('payload' in cmd) || cmd.payload == null || typeof cmd.payload !== 'object') {
+            errors.push(`${cmd.type}: missing or invalid payload`);
+            continue;
+        }
+        try {
+            switch (cmd.type) {
+                // ── Text Overlays ──────────────────────────────
+                case 'ADD_TEXT': {
+                    // The LLM commonly emits partial / out-of-bounds payloads
+                    // (missing fontFamily, x>1, endMs<startMs). Normalize so
+                    // the overlay is always renderable rather than silently
+                    // adding an invisible row to the array.
+                    const raw = cmd.payload;
+                    if (!raw.text || typeof raw.text !== 'string') {
+                        errors.push('ADD_TEXT: payload missing required "text" field');
+                        break;
+                    }
+                    const { overlay, warnings } = normalizeAiTextOverlay({ ...raw, text: raw.text }, snapshot.videoDurationMs);
+                    if (warnings.length > 0) {
+                        console.warn('[ai-orchestrator] ADD_TEXT normalized:', warnings.join('; '));
+                    }
+                    actions.addTextOverlay(overlay);
+                    applied++;
+                    break;
+                }
+                case 'UPDATE_TEXT': {
+                    const { id, ...patch } = cmd.payload;
+                    const exists = snapshot.textOverlays.some((t) => t.id === id);
+                    if (!exists) {
+                        errors.push(`UPDATE_TEXT: text overlay "${id}" not found`);
+                        break;
+                    }
+                    actions.updateTextOverlay(id, patch);
+                    applied++;
+                    break;
+                }
+                case 'REMOVE_TEXT': {
+                    actions.removeTextOverlay(cmd.payload.id);
+                    applied++;
+                    break;
+                }
+                // ── Timeline Clips (dual update) ───────────────
+                case 'ADD_CLIP': {
+                    const { assetId, canvasObject } = cmd.payload;
+                    const asset = snapshot.assetLibrary.find((a) => a.id === assetId);
+                    if (!asset) {
+                        errors.push(`ADD_CLIP: asset "${assetId}" not found in library`);
+                        break;
+                    }
+                    // addClipToTimeline handles both TimelineClip + CanvasObject creation
+                    actions.addClipToTimeline(asset);
+                    // If the AI specified custom canvas transform, apply it to the newly created object
+                    if (canvasObject) {
+                        // The store creates canvas objects with id `obj-clip-{timestamp}`
+                        // We need to find the newest canvas object for this asset
+                        // Since addClipToTimeline is sync, we read from the snapshot's length
+                        // to know the new object was appended. We'll apply after a microtask.
+                        // For now, we'll use a post-execution patch approach.
+                        const patchFields = canvasObject;
+                        cmd._pendingCanvasPatch = patchFields;
+                    }
+                    applied++;
+                    break;
+                }
+                case 'UPDATE_CLIP': {
+                    const { id, volume, opacity, playbackRate, ...bounds } = cmd.payload;
+                    const clip = snapshot.timelineClips.find((c) => c.id === id);
+                    if (!clip) {
+                        errors.push(`UPDATE_CLIP: clip "${id}" not found`);
+                        break;
+                    }
+                    if (Object.keys(bounds).length > 0) {
+                        actions.updateClipBounds(id, bounds);
+                    }
+                    if (volume !== undefined)
+                        actions.setClipVolume(id, volume);
+                    if (opacity !== undefined)
+                        actions.setClipOpacity(id, opacity);
+                    if (playbackRate !== undefined)
+                        actions.setClipSpeed(id, playbackRate);
+                    applied++;
+                    break;
+                }
+                case 'REMOVE_CLIP': {
+                    actions.deleteClipById(cmd.payload.id);
+                    applied++;
+                    break;
+                }
+                // ── Canvas Objects ──────────────────────────────
+                case 'UPDATE_CANVAS_OBJECT': {
+                    const { id, ...patch } = cmd.payload;
+                    const exists = snapshot.canvasObjects.some((o) => o.id === id);
+                    if (!exists) {
+                        errors.push(`UPDATE_CANVAS_OBJECT: object "${id}" not found`);
+                        break;
+                    }
+                    actions.updateCanvasObject(id, patch);
+                    applied++;
+                    break;
+                }
+                // ── Canvas Preset ──────────────────────────────
+                case 'SET_CANVAS_PRESET': {
+                    actions.setCanvasPreset(cmd.payload);
+                    applied++;
+                    break;
+                }
+                // ── Tracks ─────────────────────────────────────
+                case 'ADD_TRACK': {
+                    actions.addTrack(cmd.payload.type);
+                    applied++;
+                    break;
+                }
+                // ── Split Clip ─────────────────────────────────
+                case 'SPLIT_CLIP': {
+                    const { clipId, splitAtMs } = cmd.payload;
+                    const clip = snapshot.timelineClips.find((c) => c.id === clipId);
+                    if (!clip) {
+                        errors.push(`SPLIT_CLIP: clip "${clipId}" not found`);
+                        break;
+                    }
+                    // The LLM regularly emits splitAtMs values that are off by
+                    // a few ms or expressed relative to the clip start instead
+                    // of absolute. Rather than dropping the command silently,
+                    // clamp inside [startMs+1, startMs+durationMs-1] and warn.
+                    const clipEnd = clip.startMs + clip.durationMs;
+                    let safeSplit = splitAtMs;
+                    if (safeSplit <= clip.startMs || safeSplit >= clipEnd) {
+                        // Heuristic: if the value is small (looks like an offset
+                        // into the clip), interpret as relative; otherwise clamp.
+                        const relativeGuess = clip.startMs + splitAtMs;
+                        if (splitAtMs > 0 &&
+                            splitAtMs < clip.durationMs &&
+                            relativeGuess > clip.startMs &&
+                            relativeGuess < clipEnd) {
+                            safeSplit = relativeGuess;
+                            errors.push(`SPLIT_CLIP: splitAtMs ${splitAtMs} interpreted as offset into clip → ${safeSplit}`);
+                        }
+                        else {
+                            safeSplit = Math.round((clip.startMs + clipEnd) / 2);
+                            errors.push(`SPLIT_CLIP: splitAtMs ${splitAtMs} out of clip bounds [${clip.startMs}, ${clipEnd}]; cut at midpoint ${safeSplit} instead`);
+                        }
+                    }
+                    actions.setSelectedClipId(clipId);
+                    actions.splitClip(safeSplit);
+                    applied++;
+                    break;
+                }
+                // ── Duplicate Clip ─────────────────────────────
+                case 'DUPLICATE_CLIP': {
+                    const clip = snapshot.timelineClips.find((c) => c.id === cmd.payload.id);
+                    if (!clip) {
+                        errors.push(`DUPLICATE_CLIP: clip "${cmd.payload.id}" not found`);
+                        break;
+                    }
+                    actions.duplicateClip(cmd.payload.id);
+                    applied++;
+                    break;
+                }
+                // ── Transitions ────────────────────────────────
+                case 'SET_TRANSITION': {
+                    const { clipId, edge, type, durationMs } = cmd.payload;
+                    const clip = snapshot.timelineClips.find((c) => c.id === clipId);
+                    if (!clip) {
+                        errors.push(`SET_TRANSITION: clip "${clipId}" not found`);
+                        break;
+                    }
+                    actions.setClipTransition(clipId, edge, { type, durationMs });
+                    applied++;
+                    break;
+                }
+                // ── Clip Animations ────────────────────────────
+                case 'SET_CLIP_ANIMATION': {
+                    const { clipId, phase, type, durationMs } = cmd.payload;
+                    const clip = snapshot.timelineClips.find((c) => c.id === clipId);
+                    if (!clip) {
+                        errors.push(`SET_CLIP_ANIMATION: clip "${clipId}" not found`);
+                        break;
+                    }
+                    actions.setClipAnimation(clipId, phase, { type, durationMs });
+                    applied++;
+                    break;
+                }
+                // ── Cinematic Look ─────────────────────────────
+                case 'SET_CINEMATIC_LOOK': {
+                    actions.setCinematicLook(cmd.payload.look);
+                    applied++;
+                    break;
+                }
+                // ── Detach Audio ───────────────────────────────
+                case 'DETACH_AUDIO': {
+                    const clip = snapshot.timelineClips.find((c) => c.id === cmd.payload.clipId);
+                    if (!clip) {
+                        errors.push(`DETACH_AUDIO: clip "${cmd.payload.clipId}" not found`);
+                        break;
+                    }
+                    if (clip.mediaType !== 'video') {
+                        errors.push(`DETACH_AUDIO: clip "${cmd.payload.clipId}" is not a video`);
+                        break;
+                    }
+                    actions.detachAudio(cmd.payload.clipId);
+                    applied++;
+                    break;
+                }
+                // ── Cut-to-beat (rhythmic editing) ──────────────
+                case 'CUT_TO_BEAT': {
+                    const { audioClipId, beatInterval } = cmd.payload;
+                    const mode = cmd.payload.mode ?? 'redistribute';
+                    const syncClipsArg = cmd.payload.syncClips ?? 'all';
+                    if (typeof beatInterval !== 'number' || beatInterval < 1 || beatInterval > 32) {
+                        errors.push(`CUT_TO_BEAT: invalid beatInterval ${beatInterval} (expected 1-32)`);
+                        break;
+                    }
+                    const audioClip = snapshot.timelineClips.find((c) => c.id === audioClipId);
+                    if (!audioClip || audioClip.mediaType !== 'audio') {
+                        errors.push(`CUT_TO_BEAT: audio clip "${audioClipId}" not found in timeline`);
+                        break;
+                    }
+                    const analysis = snapshot.audioBeatsByAssetId?.[audioClip.assetId];
+                    if (!analysis || analysis === 'analyzing' || analysis === 'failed') {
+                        errors.push(`CUT_TO_BEAT: audio "${audioClip.name}" has no beat analysis (status: ${analysis ?? 'unknown'}). Wait a moment after dropping audio for analysis to complete.`);
+                        break;
+                    }
+                    // Filter visual clips: those participating in the cut.
+                    const allVisualClips = snapshot.timelineClips.filter((c) => c.mediaType === 'video' || c.mediaType === 'image');
+                    const targetVisuals = syncClipsArg === 'all'
+                        ? allVisualClips
+                        : allVisualClips.filter((c) => syncClipsArg.includes(c.id));
+                    if (targetVisuals.length === 0) {
+                        errors.push('CUT_TO_BEAT: no visual clips to sync');
+                        break;
+                    }
+                    // Audio's absolute beat positions on the project timeline.
+                    const audioStart = audioClip.startMs;
+                    const audioEnd = audioClip.startMs + audioClip.durationMs;
+                    // Beats from analysis are offsets from start of source audio.
+                    // sourceOffsetMs accounts for trims at audio's head.
+                    const beatsAbsolute = analysis.beats
+                        .map((bMs) => audioStart + (bMs - audioClip.sourceOffsetMs))
+                        .filter((t) => t >= audioStart && t <= audioEnd);
+                    if (beatsAbsolute.length < beatInterval + 1) {
+                        errors.push(`CUT_TO_BEAT: not enough beats (${beatsAbsolute.length}) for beatInterval ${beatInterval}`);
+                        break;
+                    }
+                    // Cut points: every Nth beat, including audio start (first beat) and end.
+                    const cutPoints = [];
+                    for (let i = 0; i < beatsAbsolute.length; i += beatInterval) {
+                        cutPoints.push(beatsAbsolute[i]);
+                    }
+                    // Always end at audio end so the last segment fills the music.
+                    if (cutPoints[cutPoints.length - 1] < audioEnd - 50)
+                        cutPoints.push(audioEnd);
+                    if (mode === 'redistribute') {
+                        const tape = [];
+                        let totalSourceMs = 0;
+                        for (const c of targetVisuals) {
+                            tape.push({ sourceClip: c, offsetMs: c.sourceOffsetMs, durationMs: c.durationMs });
+                            totalSourceMs += c.durationMs;
+                        }
+                        if (totalSourceMs <= 0) {
+                            errors.push('CUT_TO_BEAT: total visual duration is zero');
+                            break;
+                        }
+                        const newClips = [];
+                        const newCanvasObjects = [];
+                        const trackId = targetVisuals[0].trackId;
+                        const now = Date.now();
+                        // Walk the tape with a moving cursor; for each cut interval,
+                        // peel off a segment of the tape equal to (next - current).
+                        let tapeIdx = 0;
+                        let tapeCursorInSegment = 0;
+                        for (let i = 0; i < cutPoints.length - 1; i++) {
+                            const segmentMs = cutPoints[i + 1] - cutPoints[i];
+                            if (segmentMs <= 0)
+                                continue;
+                            // The piece we lay down references the current tape segment,
+                            // possibly clipping its tail if the tape segment is shorter
+                            // than the beat interval (then we step to next tape segment).
+                            let remaining = segmentMs;
+                            let placed = false;
+                            while (remaining > 0 && tapeIdx < tape.length) {
+                                const seg = tape[tapeIdx];
+                                const available = seg.durationMs - tapeCursorInSegment;
+                                if (available <= 0) {
+                                    tapeIdx++;
+                                    tapeCursorInSegment = 0;
+                                    continue;
+                                }
+                                const take = Math.min(available, remaining);
+                                if (!placed) {
+                                    // First piece of this beat segment — emit a clip starting at cutPoints[i].
+                                    const newId = `clip-cb-${now}-${i}`;
+                                    newClips.push({
+                                        id: newId,
+                                        assetId: seg.sourceClip.assetId,
+                                        name: seg.sourceClip.name,
+                                        url: seg.sourceClip.url,
+                                        startMs: cutPoints[i],
+                                        durationMs: take,
+                                        originalDurationMs: seg.sourceClip.originalDurationMs,
+                                        sourceOffsetMs: seg.offsetMs + tapeCursorInSegment,
+                                        mediaType: seg.sourceClip.mediaType,
+                                        trackId,
+                                    });
+                                    newCanvasObjects.push({
+                                        id: `obj-${newId}`,
+                                        clipId: newId,
+                                        x: 0, y: 0, w: 1, h: 1,
+                                        rotation: 0,
+                                    });
+                                    placed = true;
+                                }
+                                else {
+                                    // Subsequent piece within the same beat — extend the
+                                    // previous clip's duration if and only if it's the same
+                                    // source asset; otherwise start a fresh clip nested in
+                                    // the same beat. For simplicity, we only support a
+                                    // single asset per beat segment (truncate trailing tape
+                                    // and snap to next beat).
+                                    break;
+                                }
+                                tapeCursorInSegment += take;
+                                remaining -= take;
+                                if (tapeCursorInSegment >= seg.durationMs) {
+                                    tapeIdx++;
+                                    tapeCursorInSegment = 0;
+                                }
+                            }
+                            if (tapeIdx >= tape.length)
+                                break; // tape exhausted, stop emitting
+                        }
+                        // Preserve audio + non-target clips intact.
+                        const preservedClips = snapshot.timelineClips.filter((c) => c.mediaType === 'audio' || c.mediaType === 'color' ||
+                            (syncClipsArg !== 'all' && !syncClipsArg.includes(c.id) && (c.mediaType === 'video' || c.mediaType === 'image')));
+                        // Preserve canvas objects whose clip is in preservedClips.
+                        const preservedClipIds = new Set(preservedClips.map((c) => c.id));
+                        const preservedCanvasObjects = snapshot.canvasObjects.filter((o) => preservedClipIds.has(o.clipId));
+                        actions.replaceTimelineClips([...preservedClips, ...newClips], [...preservedCanvasObjects, ...newCanvasObjects]);
+                        applied++;
+                    }
+                    else {
+                        // mode === 'snap' — leave clips, just nudge edges to nearest beat.
+                        const snapToNearestBeat = (t) => {
+                            if (beatsAbsolute.length === 0)
+                                return t;
+                            let best = beatsAbsolute[0];
+                            let bestDist = Math.abs(t - best);
+                            for (let i = 1; i < beatsAbsolute.length; i++) {
+                                const d = Math.abs(t - beatsAbsolute[i]);
+                                if (d < bestDist) {
+                                    best = beatsAbsolute[i];
+                                    bestDist = d;
+                                }
+                                else if (beatsAbsolute[i] > t + bestDist)
+                                    break;
+                            }
+                            return best;
+                        };
+                        const updatedClips = snapshot.timelineClips.map((c) => {
+                            if (c.mediaType !== 'video' && c.mediaType !== 'image')
+                                return c;
+                            if (syncClipsArg !== 'all' && !syncClipsArg.includes(c.id))
+                                return c;
+                            const newStart = snapToNearestBeat(c.startMs);
+                            const newEnd = snapToNearestBeat(c.startMs + c.durationMs);
+                            const newDur = Math.max(100, newEnd - newStart);
+                            return { ...c, startMs: newStart, durationMs: newDur };
+                        });
+                        actions.replaceTimelineClips(updatedClips);
+                        applied++;
+                    }
+                    break;
+                }
+                // ── V2: motion design / effects / masks / audio reactivity ──
+                // These mutate the optional v2 fields (animations, effects, maskV2,
+                // audioReactive) on CanvasObject / TextOverlay. The render path
+                // (render.ts) already reads these fields — wiring just needed the
+                // orchestrator handlers, which had been left as dead code in M6.
+                case 'SET_OBJECT_ANIMATION': {
+                    const { objectId, objectType, property, animation } = cmd.payload;
+                    if (objectType === 'canvas') {
+                        const obj = snapshot.canvasObjects.find((o) => o.id === objectId);
+                        if (!obj) {
+                            errors.push(`SET_OBJECT_ANIMATION: canvas object "${objectId}" not found`);
+                            break;
+                        }
+                        // Merge into existing animations rather than replace — lets the
+                        // AI add multiple per-property curves in successive commands.
+                        const merged = { ...(obj.animations ?? {}), [property]: animation };
+                        actions.updateCanvasObject(objectId, { animations: merged });
+                        applied++;
+                    }
+                    else {
+                        const txt = snapshot.textOverlays.find((t) => t.id === objectId);
+                        if (!txt) {
+                            errors.push(`SET_OBJECT_ANIMATION: text overlay "${objectId}" not found`);
+                            break;
+                        }
+                        const merged = { ...(txt.animations ?? {}), [property]: animation };
+                        actions.updateTextOverlay(objectId, { animations: merged });
+                        applied++;
+                    }
+                    break;
+                }
+                case 'SET_ANIMATIONS': {
+                    const { objectId, objectType, animations } = cmd.payload;
+                    if (objectType === 'canvas') {
+                        if (!snapshot.canvasObjects.some((o) => o.id === objectId)) {
+                            errors.push(`SET_ANIMATIONS: canvas object "${objectId}" not found`);
+                            break;
+                        }
+                        actions.updateCanvasObject(objectId, { animations });
+                        applied++;
+                    }
+                    else {
+                        if (!snapshot.textOverlays.some((t) => t.id === objectId)) {
+                            errors.push(`SET_ANIMATIONS: text overlay "${objectId}" not found`);
+                            break;
+                        }
+                        actions.updateTextOverlay(objectId, { animations });
+                        applied++;
+                    }
+                    break;
+                }
+                case 'ADD_EFFECT': {
+                    const { objectId, objectType, effect, replace } = cmd.payload;
+                    if (objectType === 'canvas') {
+                        const obj = snapshot.canvasObjects.find((o) => o.id === objectId);
+                        if (!obj) {
+                            errors.push(`ADD_EFFECT: canvas object "${objectId}" not found`);
+                            break;
+                        }
+                        const existing = obj.effects ?? [];
+                        const next = replace
+                            ? [...existing.filter((e) => e.type !== effect.type), effect]
+                            : [...existing, effect];
+                        actions.updateCanvasObject(objectId, { effects: next });
+                        applied++;
+                    }
+                    else {
+                        const txt = snapshot.textOverlays.find((t) => t.id === objectId);
+                        if (!txt) {
+                            errors.push(`ADD_EFFECT: text overlay "${objectId}" not found`);
+                            break;
+                        }
+                        const existing = txt.effects ?? [];
+                        const next = replace
+                            ? [...existing.filter((e) => e.type !== effect.type), effect]
+                            : [...existing, effect];
+                        actions.updateTextOverlay(objectId, { effects: next });
+                        applied++;
+                    }
+                    break;
+                }
+                case 'REMOVE_EFFECT': {
+                    const { objectId, objectType, effectType } = cmd.payload;
+                    if (objectType === 'canvas') {
+                        const obj = snapshot.canvasObjects.find((o) => o.id === objectId);
+                        if (!obj) {
+                            errors.push(`REMOVE_EFFECT: canvas object "${objectId}" not found`);
+                            break;
+                        }
+                        const filtered = (obj.effects ?? []).filter((e) => e.type !== effectType);
+                        actions.updateCanvasObject(objectId, { effects: filtered });
+                        applied++;
+                    }
+                    else {
+                        const txt = snapshot.textOverlays.find((t) => t.id === objectId);
+                        if (!txt) {
+                            errors.push(`REMOVE_EFFECT: text overlay "${objectId}" not found`);
+                            break;
+                        }
+                        const filtered = (txt.effects ?? []).filter((e) => e.type !== effectType);
+                        actions.updateTextOverlay(objectId, { effects: filtered });
+                        applied++;
+                    }
+                    break;
+                }
+                case 'ADD_AUDIO_REACTIVE': {
+                    const { objectId, objectType, modifier } = cmd.payload;
+                    if (objectType === 'canvas') {
+                        const obj = snapshot.canvasObjects.find((o) => o.id === objectId);
+                        if (!obj) {
+                            errors.push(`ADD_AUDIO_REACTIVE: canvas object "${objectId}" not found`);
+                            break;
+                        }
+                        // Replace any existing modifier on the same property — having
+                        // two reactive curves on the same property would be undefined
+                        // behavior at the sampler level.
+                        const existing = (obj.audioReactive ?? []).filter((m) => m.property !== modifier.property);
+                        actions.updateCanvasObject(objectId, { audioReactive: [...existing, modifier] });
+                        applied++;
+                    }
+                    else {
+                        const txt = snapshot.textOverlays.find((t) => t.id === objectId);
+                        if (!txt) {
+                            errors.push(`ADD_AUDIO_REACTIVE: text overlay "${objectId}" not found`);
+                            break;
+                        }
+                        const existing = (txt.audioReactive ?? []).filter((m) => m.property !== modifier.property);
+                        actions.updateTextOverlay(objectId, { audioReactive: [...existing, modifier] });
+                        applied++;
+                    }
+                    break;
+                }
+                case 'SET_MASK': {
+                    const { objectId, mask } = cmd.payload;
+                    const obj = snapshot.canvasObjects.find((o) => o.id === objectId);
+                    if (!obj) {
+                        errors.push(`SET_MASK: canvas object "${objectId}" not found`);
+                        break;
+                    }
+                    actions.updateCanvasObject(objectId, { maskV2: mask });
+                    applied++;
+                    break;
+                }
+                default: {
+                    // Should be unreachable — VALID_TYPES check above filters out
+                    // unknown types before reaching the switch.
+                    errors.push(`Unhandled known command type: ${cmd.type}`);
+                }
+            }
+        }
+        catch (err) {
+            errors.push(`${cmd.type}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return { applied, errors };
+}

package/dist/headless.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Headless editor — open a ProjectFile, apply AiCommands with the SAME
+ * store + orchestrator the browser uses, serialize back. This is what
+ * vivid-mcp runs in Node; nothing here touches the DOM.
+ */
+import { type EditorStore, type EditorState } from './store.js';
+import { type AiCommand, type EditorSnapshot, type OrchestratorActions } from './ai-orchestrator.js';
+import { type ApplyProjectOptions, type ProjectExtras } from './project.js';
+import { type ProjectFile } from './types/project.js';
+export declare function snapshotOf(state: EditorState): EditorSnapshot;
+/** Same wiring as the browser AI panel (ai-chat-panel.tsx). */
+export declare function actionsOf(state: EditorState): OrchestratorActions;
+export interface ApplyResult {
+    applied: number;
+    errors: string[];
+    /** Ids created by this batch, in order (clips + their canvas objects, texts, tracks). */
+    created: {
+        clips: string[];
+        canvasObjects: string[];
+        textOverlays: string[];
+        tracks: string[];
+    };
+}
+/** One command at a time, fresh snapshot each; consumes ADD_CLIP's canvas patch. */
+export declare function applyCommands(store: EditorStore, commands: AiCommand[]): ApplyResult;
+export interface HeadlessEditor {
+    store: EditorStore;
+    /** Subtitle & template state carried through untouched. */
+    extras: ProjectExtras;
+    /** Local asset ids whose server asset could not be resolved on open. */
+    missingAssets: string[];
+    /** True when the file was a v1 project migrated in memory. */
+    migrated: boolean;
+    snapshot(): EditorSnapshot;
+    /**
+     * Apply commands through the shared orchestrator. Unlike the browser
+     * panel (one snapshot per batch) each command sees the state left by the
+     * previous one, so a batch can ADD_CLIP and then UPDATE_CLIP the new clip
+     * via the ids reported in `created`.
+     */
+    apply(commands: AiCommand[]): ApplyResult;
+    toProjectFile(): ProjectFile;
+}
+/** Parse + validate (+ migrate v1) a project JSON as loaded from R2. */
+export declare function parseProjectFile(raw: unknown): {
+    file: ProjectFile;
+    migrated: boolean;
+};
+/** Empty project with sensible defaults (V1 track, first canvas preset). */
+export declare function emptyProjectFile(name: string, canvasPreset?: ProjectFile['canvasPreset']): ProjectFile;
+export declare function openHeadlessProject(raw: unknown, opts: ApplyProjectOptions): HeadlessEditor;