vivid-editor-core 0.1.0

package/dist/store.js

@@ -0,0 +1,866 @@
+/**
+ * Editor store — the single source of truth for timeline / canvas / text
+ * state and every editing operation (add, split, trim, transitions,
+ * canvas presets, undo…). Runs anywhere: the browser wraps it in a React
+ * hook (vivid-app `src/store/editor.ts`), vivid-mcp drives it headless in
+ * Node. Everything that touches the browser (audio engine, asset manager,
+ * localStorage, rAF, vision analysis) is injected through `EditorStoreDeps`
+ * and defaults to a no-op.
+ */
+import { createStore } from 'zustand/vanilla';
+import { findFirstGap, findNearestValidPosition } from './timeline-utils.js';
+// Color palettes for dynamic track assignment
+const VISUAL_COLORS = [
+    'rgba(245, 101, 69, 0.6)', // vivid orange
+    'rgba(168, 85, 247, 0.6)', // purple
+    'rgba(59, 130, 246, 0.6)', // blue
+    'rgba(236, 72, 153, 0.6)', // pink
+];
+const AUDIO_COLORS = [
+    'rgba(13, 148, 136, 0.5)', // teal
+    'rgba(34, 197, 94, 0.5)', // green
+    'rgba(234, 179, 8, 0.5)', // yellow
+    'rgba(59, 130, 246, 0.5)', // blue
+];
+/** @deprecated Use store `tracks` state instead. Kept for backward compatibility. */
+export const TIMELINE_TRACKS = [
+    { id: 'V1', label: 'V1', type: 'visual', color: VISUAL_COLORS[0] },
+];
+const INITIAL_TRACKS = [
+    { id: 'V1', label: 'V1', type: 'visual', color: VISUAL_COLORS[0] },
+];
+export const CANVAS_PRESETS = [
+    { id: 'landscape', label: '16:9 Landscape', width: 1280, height: 720 },
+    { id: 'landscape-fhd', label: '16:9 Full HD', width: 1920, height: 1080 },
+    { id: 'portrait', label: '9:16 Portrait', width: 720, height: 1280 },
+    { id: 'portrait-fhd', label: '9:16 Vertical HD', width: 1080, height: 1920 },
+    { id: 'square', label: '1:1 Square', width: 1080, height: 1080 },
+    { id: 'social', label: '4:5 Social Feed', width: 864, height: 1080 },
+];
+export const CINEMATIC_LOOKS = [
+    { value: 'none', label: 'None' },
+    { value: 'kodak-portra', label: 'Kodak Portra' },
+    { value: 'noir', label: 'Noir' },
+    { value: 'cyberpunk', label: 'Cyberpunk' },
+    { value: 'kodak-portra-400', label: 'Portra 400' },
+    { value: 'fuji-provia', label: 'Fuji Provia' },
+    { value: 'ilford-hp5', label: 'Ilford HP5' },
+    { value: 'cinestill-800t', label: 'Cinestill 800T' },
+    { value: 'bleach-bypass', label: 'Bleach Bypass' },
+    { value: 'polaroid-vintage', label: 'Polaroid' },
+    { value: 'technicolor', label: 'Technicolor' },
+    { value: 'cross-process', label: 'Cross Process' },
+    { value: 'muted-cinematic', label: 'Muted Cinema' },
+    { value: 'cyberpunk-neon', label: 'Neon Punk' },
+];
+/** CSS filter string for live DOM preview */
+export function getCinematicFilter(look) {
+    switch (look) {
+        case 'kodak-portra': return 'contrast(1.05) sepia(0.15) saturate(1.1)';
+        case 'noir': return 'grayscale(1) contrast(1.2)';
+        case 'cyberpunk': return 'contrast(1.15) saturate(1.4) hue-rotate(-10deg)';
+        case 'kodak-portra-400': return 'contrast(1.05) saturate(1.2) sepia(0.1)';
+        case 'fuji-provia': return 'contrast(1.1) saturate(1.3) hue-rotate(-5deg)';
+        case 'ilford-hp5': return 'grayscale(1) contrast(1.2) brightness(0.9)';
+        case 'cinestill-800t': return 'contrast(1.1) saturate(1.1) hue-rotate(-10deg) brightness(1.05)';
+        case 'bleach-bypass': return 'contrast(1.4) saturate(0.5)';
+        case 'polaroid-vintage': return 'contrast(0.9) saturate(0.8) sepia(0.3) brightness(1.1)';
+        case 'technicolor': return 'contrast(1.2) saturate(1.5)';
+        case 'cross-process': return 'contrast(1.1) saturate(1.2) sepia(0.2) hue-rotate(15deg)';
+        case 'muted-cinematic': return 'contrast(0.95) saturate(0.6)';
+        case 'cyberpunk-neon': return 'contrast(1.2) saturate(1.4) hue-rotate(30deg)';
+        default: return 'none';
+    }
+}
+export const MAX_TIMELINE_MS = 300_000; // 5 minutes
+export const MAX_CROSSFADE_MS = 3000; // max overlap for auto-crossfade (3 s)
+const MIN_CLIP_MS = 100;
+// ─── Zoom Constants ─────────────────────────────────────────
+export const ZOOM_MIN_PX_PER_SEC = 10;
+export const ZOOM_MAX_PX_PER_SEC = 3000;
+export const ZOOM_DEFAULT_PX_PER_SEC = 100;
+// Keep the rendered timeline width below a level where CSS transforms /
+// scroll math start to misbehave. At long durations this caps the max zoom
+// so a 5-minute project can't blow the DOM up to ~900k px at full zoom.
+const SAFE_TIMELINE_WIDTH_PX = 400_000;
+// Effective max zoom for the current timeline length: never exceeds the
+// hard ZOOM_MAX, but shrinks for long timelines so total width stays safe.
+export function maxPxPerSecForDuration(durationMs) {
+    const durationSec = Math.max(1, durationMs / 1000);
+    const widthCapped = Math.floor(SAFE_TIMELINE_WIDTH_PX / durationSec);
+    return Math.max(ZOOM_MIN_PX_PER_SEC, Math.min(ZOOM_MAX_PX_PER_SEC, widthCapped));
+}
+// Total occupied timeline length (end of the last clip), used to derive
+// the duration-aware zoom ceiling.
+function timelineContentMs(clips) {
+    return clips.reduce((max, c) => Math.max(max, c.startMs + c.durationMs), 0);
+}
+function clamp(v, min, max) {
+    return Math.max(min, Math.min(max, v));
+}
+export function createEditorStore(deps = {}) {
+    return createStore()((set, get) => ({
+        // ── Initial state ──
+        projectName: '',
+        playheadMs: 0,
+        isPlaying: false,
+        loopPlayback: (() => {
+            try {
+                return deps.storage?.get('vivid.editor.loopPlayback') === '1';
+            }
+            catch {
+                return false;
+            }
+        })(),
+        assetLibrary: [],
+        selectedAssetIds: new Set(),
+        timelineClips: [],
+        selectedClipId: null,
+        tracks: [...INITIAL_TRACKS],
+        nextVisualNum: 2,
+        nextAudioNum: 1,
+        canvasPreset: CANVAS_PRESETS[0],
+        canvasObjects: [],
+        selectedObjectId: null,
+        snapGuides: [],
+        textOverlays: [],
+        selectedTextId: null,
+        cinematicLook: 'none',
+        pendingReframe: null,
+        maskEditorClipId: null,
+        pxPerSec: ZOOM_DEFAULT_PX_PER_SEC,
+        audioBeatsByAssetId: {},
+        undoStack: [],
+        redoStack: [],
+        // ── Project ──
+        setProjectName: (name) => set({ projectName: name }),
+        // ── Audio beat analysis ──
+        setAudioBeatsStatus: (assetId, value) => set((s) => ({ audioBeatsByAssetId: { ...s.audioBeatsByAssetId, [assetId]: value } })),
+        // ── Bulk timeline replacement ──
+        // Used by AI beat-sync to drop in a freshly computed clip array. Caller
+        // is responsible for pushing undo before invoking.
+        //
+        // If `canvasObjects` is provided, the canvas object array is fully
+        // replaced for visual clips (caller assembles them with the right
+        // transforms). Otherwise existing canvas objects whose clipId no longer
+        // exists are pruned, and surviving ones are kept untouched.
+        replaceTimelineClips: (clips, canvasObjectsArg) => {
+            set((s) => {
+                if (canvasObjectsArg) {
+                    return { timelineClips: clips, canvasObjects: canvasObjectsArg, redoStack: [] };
+                }
+                const remainingClipIds = new Set(clips.map((c) => c.id));
+                const prunedCanvasObjects = s.canvasObjects.filter((obj) => remainingClipIds.has(obj.clipId));
+                return { timelineClips: clips, canvasObjects: prunedCanvasObjects, redoStack: [] };
+            });
+        },
+        // ── Playback ──
+        setPlayheadMs: (ms) => {
+            const clamped = clamp(ms, 0, MAX_TIMELINE_MS);
+            deps.onSeek?.(clamped); // browser: stop audio nodes, sync + re-anchor the playhead engine
+            set({ playheadMs: clamped });
+        },
+        setIsPlaying: (playing) => {
+            deps.onPlayingChange?.(playing);
+            set({ isPlaying: playing });
+        },
+        toggleLoopPlayback: () => set((s) => {
+            const next = !s.loopPlayback;
+            try {
+                deps.storage?.set('vivid.editor.loopPlayback', next ? '1' : '0');
+            }
+            catch { /* ignore quota */ }
+            return { loopPlayback: next };
+        }),
+        // ── Assets ──
+        addAsset: (clip) => {
+            deps.onAssetAdded?.(clip); // browser: AssetManager (triggers background audio analysis if audio)
+            set((s) => ({ assetLibrary: [...s.assetLibrary, clip] }));
+            // Fire-and-forget vision analysis for visual assets without a description
+            if (deps.analyzeAsset && clip.mediaType !== 'audio' && !clip.aiDescription && clip.url) {
+                deps.analyzeAsset(clip).then((result) => {
+                    if (result?.description) {
+                        get().updateAsset(clip.id, { aiDescription: result.description });
+                    }
+                }).catch(() => { });
+            }
+        },
+        removeAsset: (id) => {
+            deps.onAssetRemoved?.(id);
+            set((s) => ({
+                assetLibrary: s.assetLibrary.filter((a) => a.id !== id),
+                selectedAssetIds: (() => { const next = new Set(s.selectedAssetIds); next.delete(id); return next; })(),
+            }));
+        },
+        updateAsset: (id, patch) => {
+            deps.onAssetUpdated?.(id, patch);
+            set((s) => ({
+                assetLibrary: s.assetLibrary.map((a) => a.id === id ? { ...a, ...patch } : a),
+            }));
+        },
+        toggleAssetSelected: (id) => set((s) => {
+            const next = new Set(s.selectedAssetIds);
+            if (next.has(id))
+                next.delete(id);
+            else
+                next.add(id);
+            return { selectedAssetIds: next };
+        }),
+        clearAssetSelection: () => set({ selectedAssetIds: new Set() }),
+        // ── Timeline ──
+        addClipToTimeline: (asset) => {
+            const state = get();
+            state.pushUndo();
+            const isAudio = asset.mediaType === 'audio';
+            const trackType = isAudio ? 'audio' : 'visual';
+            const clipDuration = Math.min(asset.durationMs, MAX_TIMELINE_MS);
+            // Find a track with space, or create one
+            let targetTrackId = null;
+            let startMs = null;
+            // Try existing tracks of the right type in order
+            const candidateTracks = state.tracks.filter((t) => t.type === trackType);
+            // For audio, ensure at least A1 exists
+            if (isAudio && candidateTracks.length === 0) {
+                const newTrack = get().addTrack('audio');
+                targetTrackId = newTrack.id;
+                startMs = findFirstGap(get().timelineClips, targetTrackId, clipDuration, MAX_TIMELINE_MS);
+            }
+            else {
+                for (const track of candidateTracks) {
+                    const gap = findFirstGap(state.timelineClips, track.id, clipDuration, MAX_TIMELINE_MS);
+                    if (gap !== null) {
+                        targetTrackId = track.id;
+                        startMs = gap;
+                        break;
+                    }
+                }
+                // No space on existing tracks → create a new one
+                if (targetTrackId === null) {
+                    const newTrack = get().addTrack(trackType);
+                    targetTrackId = newTrack.id;
+                    startMs = findFirstGap(get().timelineClips, targetTrackId, clipDuration, MAX_TIMELINE_MS);
+                }
+            }
+            if (startMs === null || targetTrackId === null)
+                return;
+            const availableMs = MAX_TIMELINE_MS - startMs;
+            if (availableMs <= 0)
+                return;
+            const clipId = `clip-${Date.now()}`;
+            const clip = {
+                id: clipId,
+                assetId: asset.id,
+                name: asset.name,
+                url: asset.url,
+                startMs,
+                durationMs: Math.min(asset.durationMs, availableMs),
+                originalDurationMs: asset.durationMs,
+                sourceOffsetMs: 0,
+                mediaType: asset.mediaType,
+                trackId: targetTrackId,
+            };
+            // Create canvas object for visual clips
+            // Size to fit the full canvas while preserving aspect ratio (contain, not cover)
+            let objW = 1, objH = 1, objX = 0, objY = 0;
+            if (!isAudio && asset.intrinsicWidth && asset.intrinsicHeight) {
+                const canvasAR = state.canvasPreset.width / state.canvasPreset.height;
+                const mediaAR = asset.intrinsicWidth / asset.intrinsicHeight;
+                if (mediaAR > canvasAR) {
+                    // Media is wider than canvas → fit to width, shrink height
+                    objW = 1;
+                    objH = canvasAR / mediaAR;
+                    objX = 0;
+                    objY = (1 - objH) / 2; // center vertically
+                }
+                else {
+                    // Media is taller than canvas → fit to height, shrink width
+                    objH = 1;
+                    objW = mediaAR / canvasAR;
+                    objX = (1 - objW) / 2; // center horizontally
+                    objY = 0;
+                }
+            }
+            const newCanvasObjects = isAudio ? [] : [{
+                    id: `obj-${clipId}`,
+                    clipId,
+                    x: objX, y: objY, w: objW, h: objH,
+                    rotation: 0,
+                }];
+            set((s) => ({
+                timelineClips: [...s.timelineClips, clip],
+                canvasObjects: [...s.canvasObjects, ...newCanvasObjects],
+                redoStack: [],
+            }));
+            // Audio mirror track is no longer auto-created — only shown when audio is detached
+        },
+        updateClipBounds: (id, updates) => {
+            const state = get();
+            state.pushUndo();
+            set((s) => ({
+                timelineClips: s.timelineClips.map((c) => c.id === id ? { ...c, ...updates } : c),
+                redoStack: [],
+            }));
+        },
+        moveClip: (id, newStartMs, newTrackId, allowOverlap) => {
+            const state = get();
+            const clip = state.timelineClips.find((c) => c.id === id);
+            if (!clip)
+                return;
+            let trackId = newTrackId ?? clip.trackId;
+            // Auto-create track if it doesn't exist yet (drag-to-new-track)
+            if (!state.tracks.some((t) => t.id === trackId)) {
+                const type = trackId.startsWith('V') ? 'visual' : 'audio';
+                const num = parseInt(trackId.replace(/^[VA]/, ''), 10);
+                const colors = type === 'visual' ? VISUAL_COLORS : AUDIO_COLORS;
+                const newTrack = {
+                    id: trackId,
+                    label: trackId,
+                    type,
+                    color: colors[(num - 1) % colors.length],
+                };
+                const nextKey = type === 'visual' ? 'nextVisualNum' : 'nextAudioNum';
+                const currentNext = type === 'visual' ? state.nextVisualNum : state.nextAudioNum;
+                set({ tracks: [...state.tracks, newTrack], [nextKey]: Math.max(currentNext, num + 1) });
+            }
+            // When allowOverlap is set (crossfade), skip collision prevention — place at exact position
+            const validStart = allowOverlap
+                ? clamp(newStartMs, 0, MAX_TIMELINE_MS - clip.durationMs)
+                : findNearestValidPosition(get().timelineClips, id, trackId, newStartMs, clip.durationMs, MAX_TIMELINE_MS);
+            set((s) => ({
+                timelineClips: s.timelineClips.map((c) => c.id === id
+                    ? { ...c, startMs: validStart, trackId }
+                    : c),
+            }));
+            // Clean up empty tracks after move
+            get().removeEmptyTracks();
+        },
+        trimClipStart: (id, deltaMs) => {
+            set((s) => ({
+                timelineClips: s.timelineClips.map((c) => {
+                    if (c.id !== id)
+                        return c;
+                    // Find the previous clip on the same track (left neighbor)
+                    const prevClipEnd = s.timelineClips
+                        .filter((other) => other.id !== id && other.trackId === c.trackId && other.startMs + other.durationMs <= c.startMs)
+                        .reduce((max, other) => Math.max(max, other.startMs + other.durationMs), 0);
+                    if (c.mediaType === 'image' || c.mediaType === 'color') {
+                        const maxShrink = c.durationMs - MIN_CLIP_MS;
+                        const actualDelta = clamp(deltaMs, -(c.startMs - prevClipEnd), maxShrink);
+                        return {
+                            ...c,
+                            startMs: c.startMs + actualDelta,
+                            durationMs: c.durationMs - actualDelta,
+                            sourceOffsetMs: 0,
+                        };
+                    }
+                    const rate = c.playbackRate ?? 1;
+                    const maxTrim = c.durationMs - MIN_CLIP_MS;
+                    // sourceOffsetMs is in source-time, so convert from timeline-delta
+                    const minDelta = Math.max(-c.sourceOffsetMs / rate, -(c.startMs - prevClipEnd));
+                    const actualDelta = clamp(deltaMs, minDelta, maxTrim);
+                    return {
+                        ...c,
+                        startMs: c.startMs + actualDelta,
+                        durationMs: c.durationMs - actualDelta,
+                        sourceOffsetMs: c.sourceOffsetMs + actualDelta * rate,
+                    };
+                }),
+            }));
+        },
+        trimClipEnd: (id, deltaMs) => {
+            set((s) => ({
+                timelineClips: s.timelineClips.map((c) => {
+                    if (c.id !== id)
+                        return c;
+                    // Find the next clip on the same track (right neighbor)
+                    const nextClipStart = s.timelineClips
+                        .filter((other) => other.id !== id && other.trackId === c.trackId && other.startMs >= c.startMs + c.durationMs)
+                        .reduce((min, other) => Math.min(min, other.startMs), MAX_TIMELINE_MS);
+                    const maxDurationByTrack = nextClipStart - c.startMs;
+                    if (c.mediaType === 'image' || c.mediaType === 'color') {
+                        const maxDuration = Math.min(MAX_TIMELINE_MS - c.startMs, maxDurationByTrack);
+                        const newDuration = clamp(c.durationMs + deltaMs, MIN_CLIP_MS, maxDuration);
+                        return { ...c, durationMs: newDuration };
+                    }
+                    const maxExtend = c.originalDurationMs - c.sourceOffsetMs - c.durationMs;
+                    const maxByNeighbor = maxDurationByTrack - c.durationMs;
+                    const newDuration = clamp(c.durationMs + deltaMs, MIN_CLIP_MS, c.durationMs + Math.min(maxExtend, maxByNeighbor));
+                    return { ...c, durationMs: newDuration };
+                }),
+            }));
+        },
+        splitClip: (splitAtMs) => {
+            const state = get();
+            const clips = state.timelineClips;
+            let clipIndex;
+            if (state.selectedClipId) {
+                // Prioritize the selected clip — only split it
+                clipIndex = clips.findIndex((c) => c.id === state.selectedClipId && splitAtMs > c.startMs && splitAtMs < c.startMs + c.durationMs);
+            }
+            else {
+                // No selection — split the first clip that intersects the playhead
+                clipIndex = clips.findIndex((c) => splitAtMs > c.startMs && splitAtMs < c.startMs + c.durationMs);
+            }
+            if (clipIndex === -1)
+                return;
+            state.pushUndo();
+            const clip = clips[clipIndex];
+            const offsetInClip = splitAtMs - clip.startMs;
+            const leftId = `${clip.id}-L`;
+            const rightId = `${clip.id}-R`;
+            const leftClip = {
+                ...clip,
+                id: leftId,
+                durationMs: offsetInClip,
+                isAudioDetached: clip.isAudioDetached,
+                transitionIn: clip.transitionIn,
+                transitionOut: undefined, // cut point — no transition at the split
+            };
+            const rightClip = {
+                ...clip,
+                id: rightId,
+                startMs: splitAtMs,
+                durationMs: clip.durationMs - offsetInClip,
+                sourceOffsetMs: clip.mediaType === 'image' ? 0 : clip.sourceOffsetMs + offsetInClip * (clip.playbackRate ?? 1),
+                isAudioDetached: clip.isAudioDetached,
+                transitionIn: undefined, // cut point — no transition at the split
+                transitionOut: clip.transitionOut,
+            };
+            // Find the original canvas object and duplicate it for both halves
+            const origObj = state.canvasObjects.find((o) => o.clipId === clip.id);
+            const baseObj = origObj ?? { x: 0, y: 0, w: 1, h: 1, rotation: 0 };
+            const leftObj = { ...baseObj, id: `obj-${leftId}`, clipId: leftId };
+            const rightObj = { ...baseObj, id: `obj-${rightId}`, clipId: rightId };
+            set((s) => ({
+                timelineClips: [
+                    ...s.timelineClips.slice(0, clipIndex),
+                    leftClip,
+                    rightClip,
+                    ...s.timelineClips.slice(clipIndex + 1),
+                ],
+                // Replace original canvas object with left + right copies
+                canvasObjects: [
+                    ...s.canvasObjects.filter((o) => o.clipId !== clip.id),
+                    leftObj,
+                    rightObj,
+                ],
+                selectedClipId: leftId,
+                redoStack: [],
+            }));
+        },
+        duplicateClip: (id) => {
+            const state = get();
+            const clip = state.timelineClips.find((c) => c.id === id);
+            if (!clip)
+                return;
+            state.pushUndo();
+            const newId = `clip-${Date.now()}`;
+            const newStart = clip.startMs + clip.durationMs; // place right after original
+            const newClip = {
+                ...clip,
+                id: newId,
+                startMs: newStart,
+            };
+            // Also duplicate canvas object if it's a visual clip
+            const canvasObj = state.canvasObjects.find((o) => o.clipId === id);
+            const newObjs = canvasObj
+                ? [...state.canvasObjects, { ...canvasObj, id: `obj-${Date.now()}`, clipId: newId }]
+                : state.canvasObjects;
+            set({
+                timelineClips: [...state.timelineClips, newClip],
+                canvasObjects: newObjs,
+                selectedClipId: newId,
+            });
+        },
+        deleteSelectedClip: () => {
+            const { selectedClipId, pushUndo } = get();
+            if (!selectedClipId)
+                return;
+            pushUndo();
+            set((s) => {
+                // If we're deleting a detached audio clip, keep the parent video muted
+                // (isAudioDetached stays true so the video doesn't re-play its audio)
+                const updatedClips = s.timelineClips.filter((c) => c.id !== selectedClipId);
+                return {
+                    timelineClips: updatedClips,
+                    canvasObjects: s.canvasObjects.filter((o) => o.clipId !== selectedClipId),
+                    selectedClipId: null,
+                    selectedObjectId: null,
+                    redoStack: [],
+                };
+            });
+            // Clean up empty tracks after deletion
+            get().removeEmptyTracks();
+        },
+        deleteClipById: (id) => {
+            set((s) => ({
+                timelineClips: s.timelineClips.filter((c) => c.id !== id),
+                canvasObjects: s.canvasObjects.filter((o) => o.clipId !== id),
+                selectedClipId: s.selectedClipId === id ? null : s.selectedClipId,
+                selectedObjectId: s.selectedObjectId && s.canvasObjects.find((o) => o.id === s.selectedObjectId)?.clipId === id ? null : s.selectedObjectId,
+                redoStack: [],
+            }));
+            get().removeEmptyTracks();
+        },
+        setSelectedClipId: (id) => {
+            const objId = id ? get().canvasObjects.find((o) => o.clipId === id)?.id ?? null : null;
+            set({ selectedClipId: id, selectedObjectId: objId, selectedTextId: null });
+        },
+        // ── Color Clips ──
+        addColorClip: (color, durationMs) => {
+            const state = get();
+            state.pushUndo();
+            const clipDuration = Math.min(durationMs, MAX_TIMELINE_MS);
+            // Find a visual track with space
+            let targetTrackId = null;
+            let startMs = null;
+            const visualTracks = state.tracks.filter((t) => t.type === 'visual');
+            for (const track of visualTracks) {
+                const gap = findFirstGap(state.timelineClips, track.id, clipDuration, MAX_TIMELINE_MS);
+                if (gap !== null) {
+                    targetTrackId = track.id;
+                    startMs = gap;
+                    break;
+                }
+            }
+            if (targetTrackId === null) {
+                const newTrack = get().addTrack('visual');
+                targetTrackId = newTrack.id;
+                startMs = findFirstGap(get().timelineClips, targetTrackId, clipDuration, MAX_TIMELINE_MS);
+            }
+            if (startMs === null || targetTrackId === null)
+                return;
+            const clipId = `clip-color-${Date.now()}`;
+            const clip = {
+                id: clipId,
+                assetId: `color-${color.replace('#', '')}`,
+                name: `Color ${color}`,
+                url: '',
+                startMs,
+                durationMs: clipDuration,
+                originalDurationMs: clipDuration,
+                sourceOffsetMs: 0,
+                mediaType: 'color',
+                trackId: targetTrackId,
+                color,
+            };
+            // Color clips fill the entire canvas
+            const obj = {
+                id: `obj-${clipId}`,
+                clipId,
+                x: 0, y: 0, w: 1, h: 1,
+                rotation: 0,
+            };
+            set((s) => ({
+                timelineClips: [...s.timelineClips, clip],
+                canvasObjects: [...s.canvasObjects, obj],
+                selectedClipId: clipId,
+                redoStack: [],
+            }));
+        },
+        // ── Transitions ──
+        setClipTransition: (clipId, edge, config) => {
+            const state = get();
+            state.pushUndo();
+            set((s) => ({
+                timelineClips: s.timelineClips.map((c) => c.id === clipId
+                    ? { ...c, [edge === 'in' ? 'transitionIn' : 'transitionOut']: config }
+                    : c),
+                redoStack: [],
+            }));
+        },
+        // ── Audio ──
+        setClipVolume: (clipId, volume) => {
+            const state = get();
+            state.pushUndo();
+            set((s) => ({
+                timelineClips: s.timelineClips.map((c) => c.id === clipId ? { ...c, volume: Math.max(0, Math.min(1, volume)) } : c),
+                redoStack: [],
+            }));
+        },
+        detachAudio: (clipId) => {
+            const state = get();
+            const clip = state.timelineClips.find((c) => c.id === clipId);
+            if (!clip || clip.mediaType !== 'video' || clip.isAudioDetached)
+                return;
+            state.pushUndo();
+            // Ensure an audio track exists for this video's track
+            const audioTrackId = clip.trackId.replace('V', 'A');
+            state.ensureAudioTrack(clip.trackId);
+            const audioClipId = `audio-detach-${Date.now()}`;
+            const audioClip = {
+                id: audioClipId,
+                assetId: clip.assetId,
+                name: `${clip.name} (Audio)`,
+                url: clip.url,
+                startMs: clip.startMs,
+                durationMs: clip.durationMs,
+                originalDurationMs: clip.originalDurationMs,
+                sourceOffsetMs: clip.sourceOffsetMs,
+                mediaType: 'audio',
+                trackId: audioTrackId,
+            };
+            set((s) => ({
+                timelineClips: [
+                    ...s.timelineClips.map((c) => c.id === clipId ? { ...c, isAudioDetached: true } : c),
+                    audioClip,
+                ],
+                redoStack: [],
+            }));
+        },
+        // ── Clip Properties ──
+        setClipOpacity: (clipId, opacity) => {
+            const state = get();
+            state.pushUndo();
+            set((s) => ({
+                timelineClips: s.timelineClips.map((c) => c.id === clipId ? { ...c, opacity: Math.max(0, Math.min(1, opacity)) } : c),
+                redoStack: [],
+            }));
+        },
+        setClipSpeed: (clipId, rate) => {
+            const state = get();
+            const clip = state.timelineClips.find((c) => c.id === clipId);
+            if (!clip)
+                return;
+            const clampedRate = Math.max(0.25, Math.min(4, rate));
+            const prevRate = clip.playbackRate ?? 1;
+            // Adjust visual duration inversely with speed: a 10s clip at 2x shows as 5s
+            const sourceDuration = clip.durationMs * prevRate; // recover source duration
+            const newDuration = sourceDuration / clampedRate;
+            state.pushUndo();
+            set((s) => ({
+                timelineClips: s.timelineClips.map((c) => c.id === clipId
+                    ? { ...c, playbackRate: clampedRate, durationMs: newDuration }
+                    : c),
+                redoStack: [],
+            }));
+        },
+        setClipAnimation: (clipId, phase, config) => {
+            set((s) => ({
+                timelineClips: s.timelineClips.map((c) => c.id === clipId
+                    ? { ...c, [phase === 'in' ? 'animationIn' : 'animationOut']: config }
+                    : c),
+            }));
+        },
+        // ── Tracks ──
+        addTrack: (type) => {
+            const state = get();
+            let track;
+            if (type === 'visual') {
+                const num = state.nextVisualNum;
+                track = { id: `V${num}`, label: `V${num}`, type: 'visual', color: VISUAL_COLORS[(num - 1) % VISUAL_COLORS.length] };
+                set({ tracks: [...state.tracks, track], nextVisualNum: num + 1 });
+            }
+            else {
+                const num = state.nextAudioNum;
+                track = { id: `A${num}`, label: `A${num}`, type: 'audio', color: AUDIO_COLORS[(num - 1) % AUDIO_COLORS.length] };
+                set({ tracks: [...state.tracks, track], nextAudioNum: num + 1 });
+            }
+            return track;
+        },
+        removeEmptyTracks: () => {
+            const state = get();
+            const visualTracks = state.tracks.filter((t) => t.type === 'visual');
+            const audioTracks = state.tracks.filter((t) => t.type === 'audio');
+            const kept = [];
+            // Keep visual tracks that have clips, or the last one (always keep at least 1 visual)
+            const visualWithClips = visualTracks.filter((t) => state.timelineClips.some((c) => c.trackId === t.id));
+            if (visualWithClips.length > 0) {
+                kept.push(...visualWithClips);
+            }
+            else {
+                // Keep first visual track even if empty
+                kept.push(visualTracks[0]);
+            }
+            // Keep audio tracks that have direct audio clips OR have detached audio from a kept visual track
+            for (const at of audioTracks) {
+                const hasDirectClips = state.timelineClips.some((c) => c.trackId === at.id);
+                // Check if a corresponding visual track has video clips with detached audio
+                const vId = at.id.replace('A', 'V');
+                const hasDetachedAudio = kept.some((t) => t.id === vId) &&
+                    state.timelineClips.some((c) => c.trackId === vId && c.mediaType === 'video' && c.isAudioDetached);
+                if (hasDirectClips || hasDetachedAudio) {
+                    kept.push(at);
+                }
+            }
+            if (kept.length !== state.tracks.length) {
+                set({ tracks: kept });
+            }
+        },
+        ensureAudioTrack: (visualTrackId) => {
+            const state = get();
+            const audioId = visualTrackId.replace('V', 'A');
+            const exists = state.tracks.some((t) => t.id === audioId);
+            if (!exists) {
+                const num = parseInt(visualTrackId.replace('V', ''), 10);
+                const track = {
+                    id: audioId,
+                    label: audioId,
+                    type: 'audio',
+                    color: AUDIO_COLORS[(num - 1) % AUDIO_COLORS.length],
+                };
+                // Ensure nextAudioNum stays ahead
+                const nextNum = Math.max(state.nextAudioNum, num + 1);
+                set({ tracks: [...state.tracks, track], nextAudioNum: nextNum });
+            }
+        },
+        // ── Text Overlays ──
+        addTextOverlay: (overlay) => {
+            get().pushUndo();
+            set((s) => ({ textOverlays: [...s.textOverlays, overlay], selectedTextId: overlay.id, redoStack: [] }));
+        },
+        updateTextOverlay: (id, patch) => {
+            set((s) => ({
+                textOverlays: s.textOverlays.map((t) => t.id === id ? { ...t, ...patch } : t),
+            }));
+        },
+        removeTextOverlay: (id) => {
+            get().pushUndo();
+            set((s) => ({
+                textOverlays: s.textOverlays.filter((t) => t.id !== id),
+                selectedTextId: s.selectedTextId === id ? null : s.selectedTextId,
+                redoStack: [],
+            }));
+            // Nudge playhead by 0ms to force canvas redraw (clears ghost of deleted overlay)
+            const ms = get().playheadMs;
+            set({ playheadMs: ms + 0.001 });
+            (deps.nextFrame ?? ((cb) => cb()))(() => set({ playheadMs: ms }));
+        },
+        setSelectedTextId: (id) => set({ selectedTextId: id, selectedObjectId: null, selectedClipId: null }),
+        // ── Canvas ──
+        setCanvasPreset: (preset) => {
+            const state = get();
+            state.pushUndo();
+            // Reset all canvas objects to full-canvas bounding box.
+            // Since we use drawCover (object-fit: cover), the media will fill
+            // the box and crop overflow — no letterboxing.
+            const updatedObjects = state.canvasObjects.map((obj) => ({
+                ...obj, x: 0, y: 0, w: 1, h: 1,
+            }));
+            // Text overlays use normalized x/y (0-1) which auto-adapt.
+            // fontSize is in preview pixels — stays the same since preview container doesn't change.
+            // If the timeline has clips, offer AI reframe
+            const shouldOfferReframe = state.timelineClips.length > 0
+                && (preset.width !== state.canvasPreset.width || preset.height !== state.canvasPreset.height);
+            set({
+                canvasPreset: preset,
+                canvasObjects: updatedObjects,
+                redoStack: [],
+                pendingReframe: shouldOfferReframe ? preset : null,
+            });
+        },
+        updateCanvasObject: (id, patch) => {
+            set((s) => ({
+                canvasObjects: s.canvasObjects.map((o) => o.id === id ? { ...o, ...patch } : o),
+            }));
+        },
+        setSelectedObjectId: (id) => {
+            const clipId = id ? get().canvasObjects.find((o) => o.id === id)?.clipId ?? null : null;
+            set({ selectedObjectId: id, selectedClipId: clipId, selectedTextId: null });
+        },
+        setSnapGuides: (guides) => set({ snapGuides: guides }),
+        // ── Cinematic Look ──
+        setCinematicLook: (look) => set({ cinematicLook: look }),
+        // ── AI Reframe ──
+        dismissReframe: () => set({ pendingReframe: null }),
+        // ── Mask Editor ──
+        openMaskEditor: (clipId) => set({ maskEditorClipId: clipId }),
+        closeMaskEditor: () => set({ maskEditorClipId: null }),
+        // ── Zoom ──
+        setPxPerSec: (pxPerSec) => set((s) => ({
+            pxPerSec: clamp(pxPerSec, ZOOM_MIN_PX_PER_SEC, maxPxPerSecForDuration(timelineContentMs(s.timelineClips))),
+        })),
+        zoomIn: () => set((s) => ({
+            pxPerSec: clamp(Math.round(s.pxPerSec * 1.5), ZOOM_MIN_PX_PER_SEC, maxPxPerSecForDuration(timelineContentMs(s.timelineClips))),
+        })),
+        zoomOut: () => set((s) => ({
+            pxPerSec: clamp(Math.round(s.pxPerSec / 1.5), ZOOM_MIN_PX_PER_SEC, maxPxPerSecForDuration(timelineContentMs(s.timelineClips))),
+        })),
+        // ── Undo/Redo ──
+        pushUndo: () => {
+            const { timelineClips, canvasObjects, tracks, textOverlays } = get();
+            set((s) => ({
+                undoStack: [...s.undoStack.slice(-49), { timelineClips, canvasObjects, tracks, textOverlays }],
+            }));
+        },
+        undo: () => {
+            const { undoStack, timelineClips, canvasObjects, tracks, textOverlays } = get();
+            if (undoStack.length === 0)
+                return;
+            const prev = undoStack[undoStack.length - 1];
+            set({
+                undoStack: undoStack.slice(0, -1),
+                redoStack: [...get().redoStack, { timelineClips, canvasObjects, tracks, textOverlays }],
+                timelineClips: prev.timelineClips,
+                canvasObjects: prev.canvasObjects,
+                tracks: prev.tracks,
+                textOverlays: prev.textOverlays,
+            });
+        },
+        redo: () => {
+            const { redoStack, timelineClips, canvasObjects, tracks, textOverlays } = get();
+            if (redoStack.length === 0)
+                return;
+            const next = redoStack[redoStack.length - 1];
+            set({
+                redoStack: redoStack.slice(0, -1),
+                undoStack: [...get().undoStack, { timelineClips, canvasObjects, tracks, textOverlays }],
+                timelineClips: next.timelineClips,
+                canvasObjects: next.canvasObjects,
+                tracks: next.tracks,
+                textOverlays: next.textOverlays,
+            });
+        },
+        // ── Hydrate (AI Video Generator) ──
+        hydrateTimeline: (data) => {
+            // Push undo so the entire AI generation can be undone with Ctrl+Z
+            const { timelineClips, canvasObjects, tracks, textOverlays } = get();
+            set((s) => ({
+                undoStack: [...s.undoStack.slice(-49), { timelineClips, canvasObjects, tracks, textOverlays }],
+            }));
+            // Apply cinematic look if provided by the AI
+            if (data.cinematicLook) {
+                set({ cinematicLook: data.cinematicLook });
+            }
+            // Compute next track numbering from the incoming tracks
+            const vNums = data.tracks.filter((t) => t.type === 'visual').map((t) => parseInt(t.id.replace('V', ''), 10)).filter((n) => !isNaN(n));
+            const aNums = data.tracks.filter((t) => t.type === 'audio').map((t) => parseInt(t.id.replace('A', ''), 10)).filter((n) => !isNaN(n));
+            set({
+                tracks: data.tracks,
+                timelineClips: data.timelineClips,
+                canvasObjects: data.canvasObjects,
+                textOverlays: data.textOverlays,
+                selectedClipId: null,
+                selectedObjectId: null,
+                selectedTextId: null,
+                redoStack: [],
+                nextVisualNum: (vNums.length > 0 ? Math.max(...vNums) : 0) + 1,
+                nextAudioNum: (aNums.length > 0 ? Math.max(...aNums) : 0) + 1,
+            });
+        },
+        // ── Reset ──
+        reset: () => set({
+            projectName: '',
+            playheadMs: 0,
+            isPlaying: false,
+            assetLibrary: [],
+            selectedAssetIds: new Set(),
+            timelineClips: [],
+            selectedClipId: null,
+            tracks: [...INITIAL_TRACKS],
+            nextVisualNum: 2,
+            nextAudioNum: 1,
+            canvasObjects: [],
+            selectedObjectId: null,
+            snapGuides: [],
+            textOverlays: [],
+            selectedTextId: null,
+            cinematicLook: 'none',
+            pendingReframe: null,
+            maskEditorClipId: null,
+            pxPerSec: ZOOM_DEFAULT_PX_PER_SEC,
+            undoStack: [],
+            redoStack: [],
+        }),
+    }));
+}