vivid-editor-core 0.1.0

package/dist/headless.js

@@ -0,0 +1,126 @@
+/**
+ * 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 { createEditorStore } from './store.js';
+import { executeAiCommands } from './ai-orchestrator.js';
+import { applyProject, serializeProject, timelineContentMs } from './project.js';
+import { projectSchemaV2 } from './schemas.js';
+import { migrateV1ToV2 } from './migrations/v1ToV2.js';
+import { isV1Project } from './types/project.js';
+export function snapshotOf(state) {
+    return {
+        timelineClips: state.timelineClips,
+        canvasObjects: state.canvasObjects,
+        tracks: state.tracks,
+        textOverlays: state.textOverlays,
+        assetLibrary: state.assetLibrary,
+        canvasPreset: state.canvasPreset,
+        videoDurationMs: Math.max(timelineContentMs(state.timelineClips), 5000),
+        audioBeatsByAssetId: state.audioBeatsByAssetId,
+    };
+}
+/** Same wiring as the browser AI panel (ai-chat-panel.tsx). */
+export function actionsOf(state) {
+    return {
+        addTextOverlay: state.addTextOverlay,
+        updateTextOverlay: state.updateTextOverlay,
+        removeTextOverlay: state.removeTextOverlay,
+        addClipToTimeline: state.addClipToTimeline,
+        updateClipBounds: state.updateClipBounds,
+        deleteClipById: state.deleteClipById,
+        setClipVolume: state.setClipVolume,
+        setClipOpacity: state.setClipOpacity,
+        setClipSpeed: state.setClipSpeed,
+        setSelectedClipId: state.setSelectedClipId,
+        splitClip: state.splitClip,
+        duplicateClip: state.duplicateClip,
+        setClipTransition: state.setClipTransition,
+        setClipAnimation: state.setClipAnimation,
+        detachAudio: state.detachAudio,
+        updateCanvasObject: state.updateCanvasObject,
+        setCanvasPreset: state.setCanvasPreset,
+        setCinematicLook: state.setCinematicLook,
+        addTrack: state.addTrack,
+        replaceTimelineClips: state.replaceTimelineClips,
+        pushUndo: state.pushUndo,
+    };
+}
+/** One command at a time, fresh snapshot each; consumes ADD_CLIP's canvas patch. */
+export function applyCommands(store, commands) {
+    const before = store.getState();
+    const seen = {
+        clips: new Set(before.timelineClips.map((c) => c.id)),
+        objects: new Set(before.canvasObjects.map((o) => o.id)),
+        texts: new Set(before.textOverlays.map((t) => t.id)),
+        tracks: new Set(before.tracks.map((t) => t.id)),
+    };
+    let applied = 0;
+    const errors = [];
+    for (const cmd of commands) {
+        const state = store.getState();
+        const objectsBefore = new Set(state.canvasObjects.map((o) => o.id));
+        const r = executeAiCommands([cmd], snapshotOf(state), actionsOf(state));
+        applied += r.applied;
+        errors.push(...r.errors);
+        // ADD_CLIP with a canvasObject: the orchestrator parks the transform on
+        // the command (the browser never consumed it); apply it to the object
+        // the clip just created.
+        const patch = cmd._pendingCanvasPatch;
+        if (patch) {
+            const after = store.getState();
+            const fresh = after.canvasObjects.filter((o) => !objectsBefore.has(o.id)).at(-1);
+            if (fresh)
+                after.updateCanvasObject(fresh.id, patch);
+        }
+    }
+    const after = store.getState();
+    return {
+        applied, errors,
+        created: {
+            clips: after.timelineClips.filter((c) => !seen.clips.has(c.id)).map((c) => c.id),
+            canvasObjects: after.canvasObjects.filter((o) => !seen.objects.has(o.id)).map((o) => o.id),
+            textOverlays: after.textOverlays.filter((t) => !seen.texts.has(t.id)).map((t) => t.id),
+            tracks: after.tracks.filter((t) => !seen.tracks.has(t.id)).map((t) => t.id),
+        },
+    };
+}
+/** Parse + validate (+ migrate v1) a project JSON as loaded from R2. */
+export function parseProjectFile(raw) {
+    let candidate = raw;
+    let migrated = false;
+    if (isV1Project(raw)) {
+        candidate = migrateV1ToV2(raw);
+        migrated = true;
+    }
+    const parsed = projectSchemaV2.safeParse(candidate);
+    if (!parsed.success) {
+        throw new Error(`Invalid project file: ${parsed.error.issues.slice(0, 3).map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`);
+    }
+    return { file: parsed.data, migrated };
+}
+/** Empty project with sensible defaults (V1 track, first canvas preset). */
+export function emptyProjectFile(name, canvasPreset) {
+    const store = createEditorStore();
+    const s = store.getState();
+    return {
+        version: 2, schemaVersion: 2, projectName: name, videoDurationMs: 0,
+        canvasPreset: canvasPreset ?? s.canvasPreset, tracks: s.tracks, timelineClips: [], canvasObjects: [], textOverlays: [], assets: [],
+    };
+}
+export function openHeadlessProject(raw, opts) {
+    const { file, migrated } = parseProjectFile(raw);
+    const store = createEditorStore();
+    const { missingAssets } = applyProject(store, file, opts);
+    const extras = {
+        cues: file.cues, templateId: file.templateId, styleOverrides: file.styleOverrides,
+        animation: file.animation, position: file.position, subtitleLayout: file.subtitleLayout,
+    };
+    return {
+        store, extras, missingAssets, migrated,
+        snapshot: () => snapshotOf(store.getState()),
+        apply: (commands) => applyCommands(store, commands),
+        toProjectFile: () => serializeProject(store.getState(), extras, file.videoDurationMs && file.videoDurationMs > timelineContentMs(store.getState().timelineClips) ? file.videoDurationMs : undefined),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export * from './types/editor.js';
+export * from './types/animation.js';
+export * from './types/effect.js';
+export type { Mask, Mask as MaskV2, MaskType as MaskV2Type } from './types/mask.js';
+export * from './types/audioReactive.js';
+export * from './types/easing.js';
+export * from './types/project.js';
+export * from './types/beat.js';
+export * from './store.js';
+export * from './timeline-utils.js';
+export { TEXT_PRESETS, createTextOverlay, type TextPresetId, type TextPreset } from './text-presets.js';
+export * from './schemas.js';
+export * from './migrations/v1ToV2.js';
+export * from './ai-command-schemas.js';
+export * from './ai-orchestrator.js';
+export * from './project.js';
+export * from './headless.js';

package/dist/index.js

@@ -0,0 +1,16 @@
+export * from './types/editor.js'; // note: its generic `TextPreset` is shadowed by text-presets' typed one below
+export * from './types/animation.js';
+export * from './types/effect.js';
+export * from './types/audioReactive.js';
+export * from './types/easing.js';
+export * from './types/project.js';
+export * from './types/beat.js';
+export * from './store.js';
+export * from './timeline-utils.js';
+export { TEXT_PRESETS, createTextOverlay } from './text-presets.js';
+export * from './schemas.js';
+export * from './migrations/v1ToV2.js';
+export * from './ai-command-schemas.js';
+export * from './ai-orchestrator.js';
+export * from './project.js';
+export * from './headless.js';

package/dist/migrations/v1ToV2.d.ts

@@ -0,0 +1,19 @@
+/**
+ * V1 → V2 project file migration.
+ *
+ * The V1 project file already has `version: 2` (ad-hoc, predates the v2 spec).
+ * V2 uses `schemaVersion: 2` as a separate marker. A project is V1 if
+ * `schemaVersion` is missing or < 2.
+ *
+ * Migration is a pure function. Side-effects (R2 backup, network) live in
+ * projectLoader.ts.
+ *
+ * Per spec §10:
+ * - CanvasObject: x/y/w/h/rotation unchanged (already fractions + degrees).
+ *   opacity stays on TimelineClip (no-op for canvas objects).
+ * - TextOverlay: legacy `animation` + `animationDurationMs` → `animations.{prop}`
+ *   keyframes using the overlay's own startMs/endMs timestamps.
+ * - Legacy fields are deleted post-migration.
+ */
+import type { ProjectFile } from '../types/project.js';
+export declare function migrateV1ToV2(p: Record<string, unknown>): ProjectFile;

package/dist/migrations/v1ToV2.js

@@ -0,0 +1,126 @@
+/**
+ * V1 → V2 project file migration.
+ *
+ * The V1 project file already has `version: 2` (ad-hoc, predates the v2 spec).
+ * V2 uses `schemaVersion: 2` as a separate marker. A project is V1 if
+ * `schemaVersion` is missing or < 2.
+ *
+ * Migration is a pure function. Side-effects (R2 backup, network) live in
+ * projectLoader.ts.
+ *
+ * Per spec §10:
+ * - CanvasObject: x/y/w/h/rotation unchanged (already fractions + degrees).
+ *   opacity stays on TimelineClip (no-op for canvas objects).
+ * - TextOverlay: legacy `animation` + `animationDurationMs` → `animations.{prop}`
+ *   keyframes using the overlay's own startMs/endMs timestamps.
+ * - Legacy fields are deleted post-migration.
+ */
+export function migrateV1ToV2(p) {
+    const canvasObjects = Array.isArray(p.canvasObjects)
+        ? p.canvasObjects.map(migrateCanvasObject)
+        : [];
+    const textOverlays = Array.isArray(p.textOverlays)
+        ? p.textOverlays.map(migrateTextOverlay)
+        : [];
+    // Pass everything else through unchanged. V2 is a superset of V1 shape.
+    return {
+        ...p,
+        schemaVersion: 2,
+        canvasObjects,
+        textOverlays,
+    };
+}
+function migrateCanvasObject(obj) {
+    // V1 coordinates are already fractions, rotation is already degrees, opacity
+    // lives on TimelineClip. Nothing to convert in V1→V2 terms; just pass through.
+    // New v2 fields (animations/effects/maskV2/audioReactive) default to undefined.
+    return { ...obj };
+}
+function migrateTextOverlay(textV1) {
+    const text = { ...textV1 };
+    const legacyType = textV1.animation;
+    const dur = textV1.animationDurationMs;
+    if (legacyType && legacyType !== 'none' && typeof dur === 'number' && dur > 0) {
+        const startMs = textV1.startMs;
+        const endMs = textV1.endMs;
+        const baseOpacity = typeof textV1.opacity === 'number' ? textV1.opacity : 1;
+        const baseX = typeof textV1.x === 'number' ? textV1.x : 0.5;
+        const baseY = typeof textV1.y === 'number' ? textV1.y : 0.5;
+        const baseScale = typeof textV1.scale === 'number' ? textV1.scale : 1;
+        const animations = { ...(text.animations ?? {}) };
+        switch (legacyType) {
+            case 'fade-in':
+                animations.opacity = twoKfAnim(startMs, 0, startMs + dur, baseOpacity, 'easeOutCubic');
+                break;
+            case 'fade-out':
+                animations.opacity = twoKfAnim(endMs - dur, baseOpacity, endMs, 0, 'easeInCubic');
+                break;
+            case 'fade-in-out':
+                animations.opacity = {
+                    keyframes: [
+                        { t: startMs, v: 0, easing: 'easeOutCubic' },
+                        { t: startMs + dur, v: baseOpacity, easing: 'linear' },
+                        { t: Math.max(startMs + dur, endMs - dur), v: baseOpacity, easing: 'easeInCubic' },
+                        { t: endMs, v: 0 },
+                    ],
+                };
+                break;
+            case 'slide-up':
+                animations.y = twoKfAnim(startMs, baseY + 0.15, startMs + dur, baseY, 'easeOutQuart');
+                animations.opacity = twoKfAnim(startMs, 0, startMs + dur, baseOpacity, 'easeOutCubic');
+                break;
+            case 'slide-down':
+                animations.y = twoKfAnim(startMs, baseY - 0.15, startMs + dur, baseY, 'easeOutQuart');
+                animations.opacity = twoKfAnim(startMs, 0, startMs + dur, baseOpacity, 'easeOutCubic');
+                break;
+            case 'slide-left':
+                animations.x = twoKfAnim(startMs, baseX + 0.2, startMs + dur, baseX, 'easeOutQuart');
+                animations.opacity = twoKfAnim(startMs, 0, startMs + dur, baseOpacity, 'easeOutCubic');
+                break;
+            case 'slide-right':
+                animations.x = twoKfAnim(startMs, baseX - 0.2, startMs + dur, baseX, 'easeOutQuart');
+                animations.opacity = twoKfAnim(startMs, 0, startMs + dur, baseOpacity, 'easeOutCubic');
+                break;
+            case 'pop':
+            case 'scale-up':
+                animations.scale = twoKfAnim(startMs, 0, startMs + dur, baseScale, 'easeOutBack');
+                animations.opacity = twoKfAnim(startMs, 0, startMs + dur, baseOpacity, 'easeOutCubic');
+                break;
+            case 'bounce':
+                animations.scale = {
+                    keyframes: [
+                        { t: startMs, v: 0, easing: 'easeOutBack' },
+                        { t: startMs + dur * 0.7, v: baseScale * 1.1, easing: 'easeInOutCubic' },
+                        { t: startMs + dur, v: baseScale },
+                    ],
+                };
+                animations.opacity = twoKfAnim(startMs, 0, startMs + dur * 0.4, baseOpacity, 'easeOutCubic');
+                break;
+            case 'blur-in':
+                animations.blur = twoKfAnim(startMs, 20, startMs + dur, 0, 'easeOutCubic');
+                animations.opacity = twoKfAnim(startMs, 0, startMs + dur, baseOpacity, 'easeOutCubic');
+                break;
+            case 'typewriter':
+                // Typewriter is a text-rendering effect, not a numeric animation.
+                // Keep the legacy field in place — the renderer handles it inline
+                // until a proper per-character keyframe system exists (post-v2).
+                // Skip migration for this case.
+                return text;
+        }
+        text.animations = animations;
+        // Strip legacy fields post-migration. Cast via unknown because the base
+        // TextOverlay type has these as required.
+        const mutable = text;
+        delete mutable.animation;
+        delete mutable.animationDurationMs;
+    }
+    return text;
+}
+function twoKfAnim(tA, vA, tB, vB, easingA) {
+    return {
+        keyframes: [
+            { t: tA, v: vA, easing: easingA },
+            { t: tB, v: vB },
+        ],
+    };
+}

package/dist/project.d.ts

@@ -0,0 +1,34 @@
+/**
+ * ProjectFile v2 ⇄ editor store.
+ *
+ * Mirrors what the browser editor does on Save / Load (vivid-app
+ * `editor-inner.tsx`): assets are stored by `serverAssetId` (the VIVID asset
+ * id), clip URLs are dropped on save and resolved again on load. Subtitle
+ * state (cues, template…) lives outside the store and travels as `extras`.
+ */
+import type { EditorState, EditorStore, AssetClip, TimelineClip, TrackDefinition } from './store.js';
+import type { ProjectFile } from './types/project.js';
+export declare const DEFAULT_TRACKS: TrackDefinition[];
+export type ProjectExtras = Pick<ProjectFile, 'cues' | 'templateId' | 'styleOverrides' | 'animation' | 'position' | 'subtitleLayout'>;
+/** End of the last clip on the timeline, in ms. */
+export declare function timelineContentMs(clips: TimelineClip[]): number;
+/**
+ * Store → ProjectFile. Assets without a `serverAssetId` are skipped (the
+ * browser uploads them first; a headless client must pass server-backed
+ * assets only).
+ */
+export declare function serializeProject(state: EditorState, extras?: ProjectExtras, videoDurationMs?: number): ProjectFile;
+export interface ApplyProjectOptions {
+    /** URL for a server asset (browser: blob URL after download; headless: the API download URL). */
+    resolveUrl: (serverAssetId: string, asset: Partial<AssetClip> & {
+        id: string;
+    }) => string | null;
+}
+/**
+ * ProjectFile → store (replaces timeline state, resets selection + undo).
+ * Returns the local ids of assets whose URL could not be resolved; their
+ * clips are dropped like the browser does.
+ */
+export declare function applyProject(store: EditorStore, file: ProjectFile, opts: ApplyProjectOptions): {
+    missingAssets: string[];
+};

package/dist/project.js

@@ -0,0 +1,100 @@
+/**
+ * ProjectFile v2 ⇄ editor store.
+ *
+ * Mirrors what the browser editor does on Save / Load (vivid-app
+ * `editor-inner.tsx`): assets are stored by `serverAssetId` (the VIVID asset
+ * id), clip URLs are dropped on save and resolved again on load. Subtitle
+ * state (cues, template…) lives outside the store and travels as `extras`.
+ */
+export const DEFAULT_TRACKS = [
+    { id: 'V1', label: 'V1', type: 'visual', color: 'rgba(245, 101, 69, 0.6)' },
+];
+/** End of the last clip on the timeline, in ms. */
+export function timelineContentMs(clips) {
+    return clips.reduce((max, c) => Math.max(max, c.startMs + c.durationMs), 0);
+}
+/**
+ * Store → ProjectFile. Assets without a `serverAssetId` are skipped (the
+ * browser uploads them first; a headless client must pass server-backed
+ * assets only).
+ */
+export function serializeProject(state, extras = {}, videoDurationMs) {
+    const assets = state.assetLibrary
+        .filter((a) => a.serverAssetId)
+        .map((a) => ({
+        id: a.id,
+        name: a.name,
+        durationMs: a.durationMs,
+        mediaType: a.mediaType,
+        intrinsicWidth: a.intrinsicWidth,
+        intrinsicHeight: a.intrinsicHeight,
+        serverAssetId: a.serverAssetId,
+        source: a.source,
+        ...(a.bpm && { bpm: a.bpm }),
+    }));
+    return {
+        version: 2,
+        schemaVersion: 2,
+        ...extras,
+        videoDurationMs: videoDurationMs ?? timelineContentMs(state.timelineClips),
+        assets,
+        timelineClips: state.timelineClips.map((c) => ({ ...c, url: undefined })),
+        canvasObjects: state.canvasObjects,
+        tracks: state.tracks,
+        canvasPreset: state.canvasPreset,
+        textOverlays: state.textOverlays,
+        projectName: state.projectName,
+    };
+}
+/**
+ * ProjectFile → store (replaces timeline state, resets selection + undo).
+ * Returns the local ids of assets whose URL could not be resolved; their
+ * clips are dropped like the browser does.
+ */
+export function applyProject(store, file, opts) {
+    const missing = [];
+    const urlByLocalId = {};
+    const assets = [];
+    for (const sa of file.assets ?? []) {
+        const serverId = sa.serverAssetId;
+        const url = serverId ? opts.resolveUrl(serverId, sa) : null;
+        if (!url) {
+            missing.push(sa.id);
+            continue;
+        }
+        urlByLocalId[sa.id] = url;
+        assets.push({
+            id: sa.id,
+            name: sa.name ?? sa.id,
+            url,
+            durationMs: sa.durationMs ?? 0,
+            file: null,
+            mediaType: sa.mediaType ?? 'video',
+            intrinsicWidth: sa.intrinsicWidth,
+            intrinsicHeight: sa.intrinsicHeight,
+            serverAssetId: serverId,
+            source: sa.source,
+            ...(sa.bpm && { bpm: sa.bpm }),
+        });
+    }
+    const clips = (file.timelineClips ?? [])
+        .filter((c) => c.mediaType === 'color' || urlByLocalId[c.assetId])
+        .map((c) => ({ ...c, url: c.mediaType === 'color' ? '' : (urlByLocalId[c.assetId] ?? '') }));
+    store.setState({
+        assetLibrary: assets,
+        timelineClips: clips,
+        canvasObjects: (file.canvasObjects ?? []),
+        tracks: file.tracks?.length ? file.tracks : [...DEFAULT_TRACKS],
+        textOverlays: (file.textOverlays ?? []),
+        selectedClipId: null,
+        selectedObjectId: null,
+        selectedTextId: null,
+        playheadMs: 0,
+        isPlaying: false,
+        undoStack: [],
+        redoStack: [],
+        ...(file.canvasPreset ? { canvasPreset: file.canvasPreset } : {}),
+        ...(typeof file.projectName === 'string' ? { projectName: file.projectName } : {}),
+    });
+    return { missingAssets: missing };
+}