vivid-editor-core 0.1.0 → 0.3.0

package/dist/ai-orchestrator.d.ts

@@ -12,6 +12,9 @@ import type { Animations, Animation as AnimationCurve, AnimatableProp } from './
 import type { Effect } from './types/effect.js';
 import type { Mask as MaskV2 } from './types/mask.js';
 import type { AudioReactiveModifier } from './types/audioReactive.js';
+import { type SpeedKeyframe, type SpeedRampPresetId } from './speed-ramp.js';
+import { type CueInput } from './subtitles.js';
+import type { SubtitleLayout } from './types/editor.js';
 export interface AddTextCommand {
     type: 'ADD_TEXT';
     payload: TextOverlay;
@@ -81,6 +84,36 @@ export interface SplitClipCommand {
         splitAtMs: number;
     };
 }
+/**
+ * Variable speed inside a clip. Either explicit keyframes (t = ms from the
+ * clip start on the timeline, v = rate) or a preset built for the clip's
+ * duration. `preset: 'none'` / empty keyframes remove the ramp.
+ */
+export interface SetSpeedRampCommand {
+    type: 'SET_SPEED_RAMP';
+    payload: {
+        clipId: string;
+        keyframes?: SpeedKeyframe[] | null;
+        preset?: SpeedRampPresetId | 'none';
+    };
+}
+/** Word-level subtitle state of the project (cues + template + placement). */
+export interface SubtitlesPayload {
+    /** Cues with optional per-word timing; null clears the subtitles. */
+    cues?: CueInput[] | null;
+    /** One of SUBTITLE_TEMPLATE_IDS (outline-reveal, ugc-pop, karaoke-marker, cinematic-fade, neon-cyberpunk, playful-wiggle). */
+    templateId?: string;
+    /** Vertical position 0 (top) – 100 (bottom). */
+    position?: number;
+    /** Overrides on the template style (fontSize, color, highlightColor, …). */
+    styleOverrides?: Record<string, unknown>;
+    /** Canvas-space layout (x, y, scale, maxWidthPct, rotation), normalized 0-1. */
+    layout?: Partial<SubtitleLayout>;
+}
+export interface SetSubtitlesCommand {
+    type: 'SET_SUBTITLES';
+    payload: SubtitlesPayload;
+}
 export interface DuplicateClipCommand {
     type: 'DUPLICATE_CLIP';
     payload: {
@@ -123,7 +156,11 @@ export interface DetachAudioCommand {
  * `audioClipId` — id of an audio clip already in timeline. Must have a
  * cached BeatAnalysis (otherwise the orchestrator returns an error).
  *
- * `beatInterval` — how many beats between cuts. 4 = 1 cut per measure.
+ * `beatInterval` — how many beats (or peaks, with grid 'peaks') between
+ *  cuts. 4 = 1 cut per measure.
+ *
+ * `grid` — 'beats' (default, constant BPM grid) or 'peaks' (detected
+ *  transients from the server analysis; `minStrength` filters weak ones).
  *
  * `mode`:
  *  - "redistribute" (default): take all visual clips, slice them up so
@@ -144,6 +181,15 @@ export interface CutToBeatCommand {
         beatInterval: number;
         mode?: 'redistribute' | 'snap';
         syncClips?: 'all' | string[];
+        /**
+         * Which grid to cut on. 'beats' (default) = the constant BPM grid.
+         * 'peaks' = detected transients (hits, accents) — cuts land on what the
+         * ear actually hears, also on music without a steady tempo or on voice.
+         * Needs `peaks` in the BeatAnalysis (server-side analysis).
+         */
+        grid?: 'beats' | 'peaks';
+        /** grid 'peaks' only: ignore peaks weaker than this (0–1, default 0). */
+        minStrength?: number;
     };
 }
 /** Set keyframe animations on one property of a canvas object or text overlay. */
@@ -202,7 +248,7 @@ export interface SetMaskCommand {
         mask: MaskV2;
     };
 }
-export type AiCommand = AddTextCommand | UpdateTextCommand | RemoveTextCommand | AddClipCommand | UpdateClipCommand | RemoveClipCommand | UpdateCanvasObjectCommand | SetCanvasPresetCommand | AddTrackCommand | SplitClipCommand | DuplicateClipCommand | SetTransitionCommand | SetClipAnimationCommand | SetCinematicLookCommand | DetachAudioCommand | CutToBeatCommand | SetObjectAnimationCommand | SetAnimationsCommand | AddEffectCommand | RemoveEffectCommand | AddAudioReactiveCommand | SetMaskCommand;
+export type AiCommand = AddTextCommand | UpdateTextCommand | RemoveTextCommand | AddClipCommand | UpdateClipCommand | RemoveClipCommand | UpdateCanvasObjectCommand | SetCanvasPresetCommand | AddTrackCommand | SplitClipCommand | SetSpeedRampCommand | SetSubtitlesCommand | DuplicateClipCommand | SetTransitionCommand | SetClipAnimationCommand | SetCinematicLookCommand | DetachAudioCommand | CutToBeatCommand | SetObjectAnimationCommand | SetAnimationsCommand | AddEffectCommand | RemoveEffectCommand | AddAudioReactiveCommand | SetMaskCommand;
 export interface EditorSnapshot {
     timelineClips: TimelineClip[];
     canvasObjects: CanvasObject[];
@@ -230,6 +276,15 @@ export interface OrchestratorActions {
     setClipVolume: (id: string, volume: number) => void;
     setClipOpacity: (id: string, opacity: number) => void;
     setClipSpeed: (id: string, rate: number) => void;
+    setClipSpeedRamp: (id: string, ramp: SpeedKeyframe[] | undefined) => void;
+    /** Subtitle state lives outside the store (editor page / project extras) — optional wiring. */
+    setSubtitles?: (patch: {
+        cues?: import('./types/editor.js').TranscriptionCue[] | null;
+        templateId?: string;
+        position?: number;
+        styleOverrides?: Record<string, unknown>;
+        layout?: Partial<SubtitleLayout>;
+    }) => void;
     setSelectedClipId: (id: string | null) => void;
     splitClip: (splitAtMs: number) => void;
     duplicateClip: (id: string) => void;

package/dist/ai-orchestrator.js

@@ -6,6 +6,8 @@
  * always creates both a TimelineClip AND a CanvasObject).
  */
 import { createTextOverlay } from './text-presets.js';
+import { speedRampPreset } from './speed-ramp.js';
+import { normalizeCues } from './subtitles.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
@@ -68,6 +70,7 @@ export function executeAiCommands(commands, snapshot, actions) {
         'ADD_CLIP', 'UPDATE_CLIP', 'REMOVE_CLIP',
         'UPDATE_CANVAS_OBJECT', 'SET_CANVAS_PRESET',
         'ADD_TRACK', 'SPLIT_CLIP', 'DUPLICATE_CLIP',
+        'SET_SPEED_RAMP', 'SET_SUBTITLES',
         'SET_TRANSITION', 'SET_CLIP_ANIMATION',
         'SET_CINEMATIC_LOOK', 'DETACH_AUDIO',
         'CUT_TO_BEAT',
@@ -306,9 +309,19 @@ export function executeAiCommands(commands, snapshot, actions) {
                     }
                     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.`);
+                        errors.push(`CUT_TO_BEAT: audio "${audioClip.name}" has no beat analysis (status: ${analysis ?? 'unknown'}). In the browser wait a moment after dropping the audio; via the API run POST /api/ai/audio-analysis on the asset first.`);
                         break;
                     }
+                    const grid = cmd.payload.grid ?? 'beats';
+                    let gridMs = analysis.beats;
+                    if (grid === 'peaks') {
+                        if (!analysis.peaks || analysis.peaks.length === 0) {
+                            errors.push(`CUT_TO_BEAT: audio "${audioClip.name}" has no peak analysis — peaks come from the server analysis (POST /api/ai/audio-analysis, mode 'peaks' or 'both'); use grid 'beats' or analyse the asset first.`);
+                            break;
+                        }
+                        const minStrength = Math.max(0, Math.min(1, cmd.payload.minStrength ?? 0));
+                        gridMs = analysis.peaks.filter((p) => p.strength >= minStrength).map((p) => p.ms).sort((a, b) => a - b);
+                    }
                     // Filter visual clips: those participating in the cut.
                     const allVisualClips = snapshot.timelineClips.filter((c) => c.mediaType === 'video' || c.mediaType === 'image');
                     const targetVisuals = syncClipsArg === 'all'
@@ -323,11 +336,11 @@ export function executeAiCommands(commands, snapshot, actions) {
                     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
+                    const beatsAbsolute = gridMs
                         .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}`);
+                        errors.push(`CUT_TO_BEAT: not enough ${grid} (${beatsAbsolute.length}) for beatInterval ${beatInterval}`);
                         break;
                     }
                     // Cut points: every Nth beat, including audio start (first beat) and end.
@@ -591,6 +604,62 @@ export function executeAiCommands(commands, snapshot, actions) {
                     }
                     break;
                 }
+                // ── Speed ramp ────────────────────────────────
+                case 'SET_SPEED_RAMP': {
+                    const { clipId, keyframes, preset } = cmd.payload;
+                    const clip = snapshot.timelineClips.find((c) => c.id === clipId);
+                    if (!clip) {
+                        errors.push(`SET_SPEED_RAMP: clip "${clipId}" not found`);
+                        break;
+                    }
+                    if (clip.mediaType === 'image' || clip.mediaType === 'color') {
+                        errors.push(`SET_SPEED_RAMP: clip "${clipId}" is a ${clip.mediaType}, speed only applies to video/audio`);
+                        break;
+                    }
+                    let ramp;
+                    if (preset && preset !== 'none') {
+                        const p = speedRampPreset(preset);
+                        if (!p) {
+                            errors.push(`SET_SPEED_RAMP: unknown preset "${preset}" (speed-up, slow-down, slow-mo-hit, punch-in, ease-in-out)`);
+                            break;
+                        }
+                        ramp = p.build(clip.durationMs);
+                    }
+                    else if (Array.isArray(keyframes) && keyframes.length > 0) {
+                        ramp = keyframes;
+                    }
+                    actions.setClipSpeedRamp(clipId, ramp);
+                    applied++;
+                    break;
+                }
+                // ── Subtitles ─────────────────────────────────
+                case 'SET_SUBTITLES': {
+                    if (!actions.setSubtitles) {
+                        errors.push('SET_SUBTITLES: not available in this editor context');
+                        break;
+                    }
+                    const { cues, templateId, position, styleOverrides, layout } = cmd.payload;
+                    const patch = {};
+                    if (cues === null)
+                        patch.cues = null;
+                    else if (Array.isArray(cues)) {
+                        const n = normalizeCues(cues);
+                        if (n.warnings.length > 0)
+                            console.warn('[ai-orchestrator] SET_SUBTITLES:', n.warnings.join('; '));
+                        patch.cues = n.cues;
+                    }
+                    if (templateId !== undefined)
+                        patch.templateId = templateId;
+                    if (position !== undefined)
+                        patch.position = Math.max(0, Math.min(100, position));
+                    if (styleOverrides !== undefined)
+                        patch.styleOverrides = styleOverrides;
+                    if (layout !== undefined)
+                        patch.layout = layout;
+                    actions.setSubtitles(patch);
+                    applied++;
+                    break;
+                }
                 case 'SET_MASK': {
                     const { objectId, mask } = cmd.payload;
                     const obj = snapshot.canvasObjects.find((o) => o.id === objectId);

package/dist/headless.d.ts

@@ -8,8 +8,10 @@ import { type AiCommand, type EditorSnapshot, type OrchestratorActions } from '.
 import { type ApplyProjectOptions, type ProjectExtras } from './project.js';
 import { type ProjectFile } from './types/project.js';
 export declare function snapshotOf(state: EditorState): EditorSnapshot;
+/** Subtitle writer over the project extras (the browser keeps this state in the editor page). */
+export declare function subtitleWriter(extras: ProjectExtras): NonNullable<OrchestratorActions['setSubtitles']>;
 /** Same wiring as the browser AI panel (ai-chat-panel.tsx). */
-export declare function actionsOf(state: EditorState): OrchestratorActions;
+export declare function actionsOf(state: EditorState, extras?: ProjectExtras): OrchestratorActions;
 export interface ApplyResult {
     applied: number;
     errors: string[];
@@ -22,7 +24,7 @@ export interface ApplyResult {
     };
 }
 /** One command at a time, fresh snapshot each; consumes ADD_CLIP's canvas patch. */
-export declare function applyCommands(store: EditorStore, commands: AiCommand[]): ApplyResult;
+export declare function applyCommands(store: EditorStore, commands: AiCommand[], extras?: ProjectExtras): ApplyResult;
 export interface HeadlessEditor {
     store: EditorStore;
     /** Subtitle & template state carried through untouched. */

package/dist/headless.js

@@ -9,6 +9,7 @@ import { applyProject, serializeProject, timelineContentMs } from './project.js'
 import { projectSchemaV2 } from './schemas.js';
 import { migrateV1ToV2 } from './migrations/v1ToV2.js';
 import { isV1Project } from './types/project.js';
+import { SUBTITLE_TEMPLATE_IDS } from './types/editor.js';
 export function snapshotOf(state) {
     return {
         timelineClips: state.timelineClips,
@@ -21,8 +22,43 @@ export function snapshotOf(state) {
         audioBeatsByAssetId: state.audioBeatsByAssetId,
     };
 }
+/** Subtitle writer over the project extras (the browser keeps this state in the editor page). */
+export function subtitleWriter(extras) {
+    return (patch) => {
+        if (patch.cues === null) {
+            extras.cues = undefined;
+        }
+        else if (patch.cues) {
+            extras.cues = patch.cues;
+        }
+        if (patch.templateId !== undefined) {
+            if (!SUBTITLE_TEMPLATE_IDS.includes(patch.templateId)) {
+                throw new Error(`unknown subtitle template "${patch.templateId}" — use one of ${SUBTITLE_TEMPLATE_IDS.join(', ')}`);
+            }
+            extras.templateId = patch.templateId;
+            // The template carries its own animation; the page re-derives it from templateId on load.
+            extras.animation = undefined;
+            extras.styleOverrides = patch.styleOverrides ?? {};
+        }
+        else if (patch.styleOverrides !== undefined) {
+            extras.styleOverrides = { ...(extras.styleOverrides ?? {}), ...patch.styleOverrides };
+        }
+        if (!extras.templateId && (extras.cues?.length ?? 0) > 0)
+            extras.templateId = SUBTITLE_TEMPLATE_IDS[0];
+        const prevLayout = extras.subtitleLayout ?? {};
+        if (patch.position !== undefined) {
+            extras.position = patch.position;
+            extras.subtitleLayout = { x: 0.5, scale: 1, rotation: 0, maxWidthPct: 0.85, ...prevLayout, y: patch.position / 100 };
+        }
+        if (patch.layout) {
+            const merged = { x: 0.5, y: (extras.position ?? 50) / 100, scale: 1, rotation: 0, maxWidthPct: 0.85, ...prevLayout, ...(extras.subtitleLayout ?? {}), ...patch.layout };
+            extras.subtitleLayout = merged;
+            extras.position = Math.round(merged.y * 100);
+        }
+    };
+}
 /** Same wiring as the browser AI panel (ai-chat-panel.tsx). */
-export function actionsOf(state) {
+export function actionsOf(state, extras) {
     return {
         addTextOverlay: state.addTextOverlay,
         updateTextOverlay: state.updateTextOverlay,
@@ -33,6 +69,8 @@ export function actionsOf(state) {
         setClipVolume: state.setClipVolume,
         setClipOpacity: state.setClipOpacity,
         setClipSpeed: state.setClipSpeed,
+        setClipSpeedRamp: state.setClipSpeedRamp,
+        setSubtitles: extras ? subtitleWriter(extras) : undefined,
         setSelectedClipId: state.setSelectedClipId,
         splitClip: state.splitClip,
         duplicateClip: state.duplicateClip,
@@ -48,7 +86,7 @@ export function actionsOf(state) {
     };
 }
 /** One command at a time, fresh snapshot each; consumes ADD_CLIP's canvas patch. */
-export function applyCommands(store, commands) {
+export function applyCommands(store, commands, extras) {
     const before = store.getState();
     const seen = {
         clips: new Set(before.timelineClips.map((c) => c.id)),
@@ -61,7 +99,7 @@ export function applyCommands(store, commands) {
     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));
+        const r = executeAiCommands([cmd], snapshotOf(state), actionsOf(state, extras));
         applied += r.applied;
         errors.push(...r.errors);
         // ADD_CLIP with a canvasObject: the orchestrator parks the transform on
@@ -120,7 +158,7 @@ export function openHeadlessProject(raw, opts) {
     return {
         store, extras, missingAssets, migrated,
         snapshot: () => snapshotOf(store.getState()),
-        apply: (commands) => applyCommands(store, commands),
+        apply: (commands) => applyCommands(store, commands, extras),
         toProjectFile: () => serializeProject(store.getState(), extras, file.videoDurationMs && file.videoDurationMs > timelineContentMs(store.getState().timelineClips) ? file.videoDurationMs : undefined),
     };
 }

package/dist/index.d.ts

@@ -8,6 +8,9 @@ export * from './types/project.js';
 export * from './types/beat.js';
 export * from './store.js';
 export * from './timeline-utils.js';
+export * from './speed-ramp.js';
+export * from './text-fill.js';
+export * from './subtitles.js';
 export { TEXT_PRESETS, createTextOverlay, type TextPresetId, type TextPreset } from './text-presets.js';
 export * from './schemas.js';
 export * from './migrations/v1ToV2.js';

package/dist/index.js

@@ -7,6 +7,9 @@ export * from './types/project.js';
 export * from './types/beat.js';
 export * from './store.js';
 export * from './timeline-utils.js';
+export * from './speed-ramp.js';
+export * from './text-fill.js';
+export * from './subtitles.js';
 export { TEXT_PRESETS, createTextOverlay } from './text-presets.js';
 export * from './schemas.js';
 export * from './migrations/v1ToV2.js';

package/dist/speed-ramp.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Speed ramp — variable playback speed inside one clip.
+ *
+ * A ramp is a list of keyframes `{ t, v }`: `t` is the offset in ms from the
+ * clip's start ON THE TIMELINE, `v` the playback rate at that point. Between
+ * keyframes the rate is linear; before the first / after the last it holds.
+ *
+ * The clip's source time at timeline offset `x` is
+ * `sourceOffsetMs + ∫₀ˣ rate(τ) dτ` — because the rate is piecewise linear
+ * the integral is exact (trapezoids), no per-frame accumulation needed, so
+ * preview, export and audio scheduling all agree to the sample.
+ */
+import type { TimelineClip } from './store.js';
+export interface SpeedKeyframe {
+    /** ms from the clip start on the timeline */
+    t: number;
+    /** playback rate (1 = normal, 0.5 = half speed, 2 = double) */
+    v: number;
+}
+export type SpeedRamp = SpeedKeyframe[];
+export declare const SPEED_RAMP_MIN_RATE = 0.1;
+export declare const SPEED_RAMP_MAX_RATE = 8;
+/** Sorted by t, rates clamped, duplicate t collapsed (last wins). Empty → []. */
+export declare function normalizeSpeedRamp(ramp: SpeedRamp | undefined | null): SpeedRamp;
+/** Rate at timeline offset `offsetMs` (holds outside the keyframe range). */
+export declare function rampRateAt(ramp: SpeedRamp, offsetMs: number): number;
+/** Source ms consumed between timeline offsets 0 and `offsetMs` (exact for the piecewise-linear rate). */
+export declare function rampSourceElapsedMs(ramp: SpeedRamp, offsetMs: number): number;
+/** Timeline ms needed to consume `sourceMs` of source under the ramp (bisection, ±0.5 ms). */
+export declare function rampTimelineMsForSource(ramp: SpeedRamp, sourceMs: number): number;
+/** Split a ramp at `atMs`: left keeps its keyframes, right is re-based to 0 starting at the rate of the cut. */
+export declare function splitSpeedRamp(ramp: SpeedRamp, atMs: number): {
+    left: SpeedRamp;
+    right: SpeedRamp;
+};
+/** Re-base a ramp after the clip's start moved by `deltaMs` on the timeline (trim). */
+export declare function shiftSpeedRamp(ramp: SpeedRamp, deltaMs: number): SpeedRamp;
+/** Ramp that plays the whole clip at `rate` — used to fold a constant speed into ramp math. */
+export declare function constantRamp(rate: number): SpeedRamp;
+/** Playback rate of `clip` at timeline offset `offsetMs` from its start. */
+export declare function clipRateAt(clip: Pick<TimelineClip, 'playbackRate' | 'speedRamp'>, offsetMs: number): number;
+/** Source ms consumed by the first `offsetMs` of the clip on the timeline. */
+export declare function clipSourceElapsedMs(clip: Pick<TimelineClip, 'playbackRate' | 'speedRamp'>, offsetMs: number): number;
+/** Absolute source time (ms) of the clip at timeline position `playheadMs`. */
+export declare function clipSourceTimeMs(clip: Pick<TimelineClip, 'startMs' | 'sourceOffsetMs' | 'playbackRate' | 'speedRamp'>, playheadMs: number): number;
+/** Timeline ms the clip needs to consume `sourceMs` of source. */
+export declare function clipTimelineMsForSource(clip: Pick<TimelineClip, 'playbackRate' | 'speedRamp'>, sourceMs: number): number;
+/** Average rate over the clip (what a "speed" badge should show). */
+export declare function clipAverageRate(clip: Pick<TimelineClip, 'durationMs' | 'playbackRate' | 'speedRamp'>): number;
+export type SpeedRampPresetId = 'speed-up' | 'slow-down' | 'slow-mo-hit' | 'punch-in' | 'ease-in-out';
+export interface SpeedRampPreset {
+    id: SpeedRampPresetId;
+    label: string;
+    description: string;
+    /** Keyframes for a clip of `durationMs` on the timeline. */
+    build: (durationMs: number) => SpeedRamp;
+}
+export declare const SPEED_RAMP_PRESETS: SpeedRampPreset[];
+export declare function speedRampPreset(id: string): SpeedRampPreset | undefined;

package/dist/speed-ramp.js

@@ -0,0 +1,158 @@
+/**
+ * Speed ramp — variable playback speed inside one clip.
+ *
+ * A ramp is a list of keyframes `{ t, v }`: `t` is the offset in ms from the
+ * clip's start ON THE TIMELINE, `v` the playback rate at that point. Between
+ * keyframes the rate is linear; before the first / after the last it holds.
+ *
+ * The clip's source time at timeline offset `x` is
+ * `sourceOffsetMs + ∫₀ˣ rate(τ) dτ` — because the rate is piecewise linear
+ * the integral is exact (trapezoids), no per-frame accumulation needed, so
+ * preview, export and audio scheduling all agree to the sample.
+ */
+export const SPEED_RAMP_MIN_RATE = 0.1;
+export const SPEED_RAMP_MAX_RATE = 8;
+/** Sorted by t, rates clamped, duplicate t collapsed (last wins). Empty → []. */
+export function normalizeSpeedRamp(ramp) {
+    if (!ramp || ramp.length === 0)
+        return [];
+    const byT = new Map();
+    for (const k of ramp) {
+        if (!Number.isFinite(k.t) || !Number.isFinite(k.v))
+            continue;
+        byT.set(Math.max(0, Math.round(k.t)), Math.min(SPEED_RAMP_MAX_RATE, Math.max(SPEED_RAMP_MIN_RATE, k.v)));
+    }
+    return [...byT.entries()].sort((a, b) => a[0] - b[0]).map(([t, v]) => ({ t, v }));
+}
+/** Rate at timeline offset `offsetMs` (holds outside the keyframe range). */
+export function rampRateAt(ramp, offsetMs) {
+    if (ramp.length === 0)
+        return 1;
+    if (offsetMs <= ramp[0].t)
+        return ramp[0].v;
+    const last = ramp[ramp.length - 1];
+    if (offsetMs >= last.t)
+        return last.v;
+    for (let i = 1; i < ramp.length; i++) {
+        const a = ramp[i - 1];
+        const b = ramp[i];
+        if (offsetMs <= b.t) {
+            const span = b.t - a.t;
+            return span <= 0 ? b.v : a.v + (b.v - a.v) * (offsetMs - a.t) / span;
+        }
+    }
+    return last.v;
+}
+/** Source ms consumed between timeline offsets 0 and `offsetMs` (exact for the piecewise-linear rate). */
+export function rampSourceElapsedMs(ramp, offsetMs) {
+    if (ramp.length === 0)
+        return offsetMs;
+    if (offsetMs <= 0)
+        return rampRateAt(ramp, 0) * offsetMs;
+    let total = 0;
+    let cursor = 0;
+    // Segment before the first keyframe: constant rate.
+    const first = ramp[0];
+    if (offsetMs <= first.t)
+        return first.v * offsetMs;
+    total += first.v * first.t;
+    cursor = first.t;
+    for (let i = 1; i < ramp.length; i++) {
+        const b = ramp[i];
+        if (b.t <= cursor)
+            continue;
+        const end = Math.min(offsetMs, b.t);
+        if (end > cursor) {
+            const va = rampRateAt(ramp, cursor);
+            const vb = rampRateAt(ramp, end);
+            total += (end - cursor) * (va + vb) / 2;
+            cursor = end;
+        }
+        if (cursor >= offsetMs)
+            return total;
+    }
+    // Past the last keyframe: constant rate.
+    if (offsetMs > cursor)
+        total += ramp[ramp.length - 1].v * (offsetMs - cursor);
+    return total;
+}
+/** Timeline ms needed to consume `sourceMs` of source under the ramp (bisection, ±0.5 ms). */
+export function rampTimelineMsForSource(ramp, sourceMs) {
+    if (sourceMs <= 0)
+        return 0;
+    if (ramp.length === 0)
+        return sourceMs;
+    let lo = 0;
+    let hi = sourceMs / SPEED_RAMP_MIN_RATE;
+    for (let i = 0; i < 60 && hi - lo > 0.5; i++) {
+        const mid = (lo + hi) / 2;
+        if (rampSourceElapsedMs(ramp, mid) < sourceMs)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    return Math.round((lo + hi) / 2);
+}
+/** Split a ramp at `atMs`: left keeps its keyframes, right is re-based to 0 starting at the rate of the cut. */
+export function splitSpeedRamp(ramp, atMs) {
+    const rateAtCut = rampRateAt(ramp, atMs);
+    const left = [...ramp.filter((k) => k.t < atMs), { t: atMs, v: rateAtCut }];
+    const right = [{ t: 0, v: rateAtCut }, ...ramp.filter((k) => k.t > atMs).map((k) => ({ t: k.t - atMs, v: k.v }))];
+    return { left: normalizeSpeedRamp(left), right: normalizeSpeedRamp(right) };
+}
+/** Re-base a ramp after the clip's start moved by `deltaMs` on the timeline (trim). */
+export function shiftSpeedRamp(ramp, deltaMs) {
+    if (ramp.length === 0 || deltaMs === 0)
+        return ramp;
+    const rateAtNewStart = rampRateAt(ramp, deltaMs);
+    return normalizeSpeedRamp([{ t: 0, v: rateAtNewStart }, ...ramp.filter((k) => k.t > deltaMs).map((k) => ({ t: k.t - deltaMs, v: k.v }))]);
+}
+/** Ramp that plays the whole clip at `rate` — used to fold a constant speed into ramp math. */
+export function constantRamp(rate) {
+    return [{ t: 0, v: rate }];
+}
+// ── Clip helpers (constant speed or ramp, one code path) ─────────────────
+/** Playback rate of `clip` at timeline offset `offsetMs` from its start. */
+export function clipRateAt(clip, offsetMs) {
+    if (clip.speedRamp && clip.speedRamp.length > 0)
+        return rampRateAt(clip.speedRamp, offsetMs);
+    return clip.playbackRate ?? 1;
+}
+/** Source ms consumed by the first `offsetMs` of the clip on the timeline. */
+export function clipSourceElapsedMs(clip, offsetMs) {
+    if (clip.speedRamp && clip.speedRamp.length > 0)
+        return rampSourceElapsedMs(clip.speedRamp, offsetMs);
+    return offsetMs * (clip.playbackRate ?? 1);
+}
+/** Absolute source time (ms) of the clip at timeline position `playheadMs`. */
+export function clipSourceTimeMs(clip, playheadMs) {
+    return clip.sourceOffsetMs + clipSourceElapsedMs(clip, playheadMs - clip.startMs);
+}
+/** Timeline ms the clip needs to consume `sourceMs` of source. */
+export function clipTimelineMsForSource(clip, sourceMs) {
+    if (clip.speedRamp && clip.speedRamp.length > 0)
+        return rampTimelineMsForSource(clip.speedRamp, sourceMs);
+    return sourceMs / (clip.playbackRate ?? 1);
+}
+/** Average rate over the clip (what a "speed" badge should show). */
+export function clipAverageRate(clip) {
+    if (!clip.speedRamp || clip.speedRamp.length === 0)
+        return clip.playbackRate ?? 1;
+    return clip.durationMs > 0 ? rampSourceElapsedMs(clip.speedRamp, clip.durationMs) / clip.durationMs : 1;
+}
+export const SPEED_RAMP_PRESETS = [
+    { id: 'speed-up', label: 'Speed up', description: 'Normal → 3× by the end', build: (d) => [{ t: 0, v: 1 }, { t: d, v: 3 }] },
+    { id: 'slow-down', label: 'Slow down', description: 'Normal → 0.3× by the end', build: (d) => [{ t: 0, v: 1 }, { t: d, v: 0.3 }] },
+    { id: 'slow-mo-hit', label: 'Slow-mo hit', description: 'Fast, dips to 0.25× in the middle, fast again', build: (d) => [
+            { t: 0, v: 2 }, { t: d * 0.35, v: 2 }, { t: d * 0.45, v: 0.25 }, { t: d * 0.6, v: 0.25 }, { t: d * 0.7, v: 2 }, { t: d, v: 2 },
+        ] },
+    { id: 'punch-in', label: 'Punch in', description: 'Starts at 0.4×, whips to 3× then settles at 1×', build: (d) => [
+            { t: 0, v: 0.4 }, { t: d * 0.25, v: 3 }, { t: d * 0.5, v: 1 }, { t: d, v: 1 },
+        ] },
+    { id: 'ease-in-out', label: 'Ease in-out', description: 'Slow at both ends, 2× in the middle', build: (d) => [
+            { t: 0, v: 0.5 }, { t: d * 0.4, v: 2 }, { t: d * 0.6, v: 2 }, { t: d, v: 0.5 },
+        ] },
+];
+export function speedRampPreset(id) {
+    return SPEED_RAMP_PRESETS.find((p) => p.id === id);
+}

package/dist/store.d.ts

@@ -8,6 +8,7 @@
  * and defaults to a no-op.
  */
 import { type StoreApi } from 'zustand/vanilla';
+import { type SpeedKeyframe } from './speed-ramp.js';
 import type { TextOverlay } from './types/editor.js';
 import type { Animations } from './types/animation.js';
 import type { Effect } from './types/effect.js';
@@ -107,6 +108,12 @@ export interface TimelineClip {
     opacity?: number;
     /** Playback speed multiplier (default 1.0). Changes visual duration on timeline. */
     playbackRate?: number;
+    /**
+     * Speed ramp: variable rate along the clip (keyframes in ms from the clip
+     * start on the timeline). Takes precedence over playbackRate when set —
+     * see speed-ramp.ts for the source-time math.
+     */
+    speedRamp?: SpeedKeyframe[];
 }
 export type MaskType = 'none' | 'rounded' | 'circle' | 'star' | 'hexagon';
 export type MaskAspectPreset = 'free' | '1:1' | '4:3' | '3:4' | '16:9' | '9:16';
@@ -220,6 +227,8 @@ export interface EditorState {
     detachAudio: (clipId: string) => void;
     setClipOpacity: (clipId: string, opacity: number) => void;
     setClipSpeed: (clipId: string, rate: number) => void;
+    /** Set (or clear with undefined/[]) a speed ramp; the clip keeps its timeline duration unless the source runs out. */
+    setClipSpeedRamp: (clipId: string, ramp: SpeedKeyframe[] | undefined) => void;
     setClipAnimation: (clipId: string, phase: 'in' | 'out', config: ClipAnimationConfig | undefined) => void;
     addTrack: (type: TrackType) => TrackDefinition;
     removeEmptyTracks: () => void;
@@ -253,4 +262,5 @@ export interface EditorState {
     reset: () => void;
 }
 export type EditorStore = StoreApi<EditorState>;
+export declare function uniqueId(prefix: string): string;
 export declare function createEditorStore(deps?: EditorStoreDeps): EditorStore;

package/dist/store.js

@@ -8,6 +8,7 @@
  * and defaults to a no-op.
  */
 import { createStore } from 'zustand/vanilla';
+import { clipRateAt, clipSourceElapsedMs, clipTimelineMsForSource, normalizeSpeedRamp, rampSourceElapsedMs, rampTimelineMsForSource, shiftSpeedRamp, splitSpeedRamp } from './speed-ramp.js';
 import { findFirstGap, findNearestValidPosition } from './timeline-utils.js';
 // Color palettes for dynamic track assignment
 const VISUAL_COLORS = [
@@ -98,6 +99,17 @@ function timelineContentMs(clips) {
 function clamp(v, min, max) {
     return Math.max(min, Math.min(max, v));
 }
+/**
+ * Timestamp-based ids collide when several clips are created in the same
+ * millisecond — which never happens from the UI but always does in a
+ * headless batch (vivid-mcp: ADD_CLIP × 3 in one call). The sequence suffix
+ * keeps them unique; the `clip-`/`obj-` prefixes stay as before.
+ */
+let idSeq = 0;
+export function uniqueId(prefix) {
+    idSeq = (idSeq + 1) % 1_000_000;
+    return `${prefix}-${Date.now()}-${idSeq.toString(36)}`;
+}
 export function createEditorStore(deps = {}) {
     return createStore()((set, get) => ({
         // ── Initial state ──
@@ -246,7 +258,7 @@ export function createEditorStore(deps = {}) {
             const availableMs = MAX_TIMELINE_MS - startMs;
             if (availableMs <= 0)
                 return;
-            const clipId = `clip-${Date.now()}`;
+            const clipId = uniqueId('clip');
             const clip = {
                 id: clipId,
                 assetId: asset.id,
@@ -353,16 +365,19 @@ export function createEditorStore(deps = {}) {
                             sourceOffsetMs: 0,
                         };
                     }
-                    const rate = c.playbackRate ?? 1;
+                    const rateAtStart = clipRateAt(c, 0);
                     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));
+                    // (extending left plays the ramp's opening rate backwards).
+                    const minDelta = Math.max(-c.sourceOffsetMs / rateAtStart, -(c.startMs - prevClipEnd));
                     const actualDelta = clamp(deltaMs, minDelta, maxTrim);
+                    const sourceDelta = actualDelta >= 0 ? clipSourceElapsedMs(c, actualDelta) : actualDelta * rateAtStart;
                     return {
                         ...c,
                         startMs: c.startMs + actualDelta,
                         durationMs: c.durationMs - actualDelta,
-                        sourceOffsetMs: c.sourceOffsetMs + actualDelta * rate,
+                        sourceOffsetMs: c.sourceOffsetMs + sourceDelta,
+                        ...(c.speedRamp && c.speedRamp.length > 0 ? { speedRamp: shiftSpeedRamp(c.speedRamp, actualDelta) } : {}),
                     };
                 }),
             }));
@@ -382,7 +397,9 @@ export function createEditorStore(deps = {}) {
                         const newDuration = clamp(c.durationMs + deltaMs, MIN_CLIP_MS, maxDuration);
                         return { ...c, durationMs: newDuration };
                     }
-                    const maxExtend = c.originalDurationMs - c.sourceOffsetMs - c.durationMs;
+                    // Source left after what the clip already consumes, converted back to timeline ms.
+                    const sourceLeft = c.originalDurationMs - c.sourceOffsetMs - clipSourceElapsedMs(c, c.durationMs);
+                    const maxExtend = sourceLeft <= 0 ? 0 : clipTimelineMsForSource(c, clipSourceElapsedMs(c, c.durationMs) + sourceLeft) - 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 };
@@ -421,11 +438,16 @@ export function createEditorStore(deps = {}) {
                 id: rightId,
                 startMs: splitAtMs,
                 durationMs: clip.durationMs - offsetInClip,
-                sourceOffsetMs: clip.mediaType === 'image' ? 0 : clip.sourceOffsetMs + offsetInClip * (clip.playbackRate ?? 1),
+                sourceOffsetMs: clip.mediaType === 'image' ? 0 : clip.sourceOffsetMs + clipSourceElapsedMs(clip, offsetInClip),
                 isAudioDetached: clip.isAudioDetached,
                 transitionIn: undefined, // cut point — no transition at the split
                 transitionOut: clip.transitionOut,
             };
+            if (clip.speedRamp && clip.speedRamp.length > 0) {
+                const { left, right } = splitSpeedRamp(clip.speedRamp, offsetInClip);
+                leftClip.speedRamp = left;
+                rightClip.speedRamp = right;
+            }
             // 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 };
@@ -454,7 +476,7 @@ export function createEditorStore(deps = {}) {
             if (!clip)
                 return;
             state.pushUndo();
-            const newId = `clip-${Date.now()}`;
+            const newId = uniqueId('clip');
             const newStart = clip.startMs + clip.durationMs; // place right after original
             const newClip = {
                 ...clip,
@@ -464,7 +486,7 @@ export function createEditorStore(deps = {}) {
             // 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, { ...canvasObj, id: uniqueId('obj'), clipId: newId }]
                 : state.canvasObjects;
             set({
                 timelineClips: [...state.timelineClips, newClip],
@@ -530,7 +552,7 @@ export function createEditorStore(deps = {}) {
             }
             if (startMs === null || targetTrackId === null)
                 return;
-            const clipId = `clip-color-${Date.now()}`;
+            const clipId = uniqueId('clip-color');
             const clip = {
                 id: clipId,
                 assetId: `color-${color.replace('#', '')}`,
@@ -587,7 +609,7 @@ export function createEditorStore(deps = {}) {
             // 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 audioClipId = uniqueId('audio-detach');
             const audioClip = {
                 id: audioClipId,
                 assetId: clip.assetId,
@@ -623,18 +645,45 @@ export function createEditorStore(deps = {}) {
             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 sourceDuration = clipSourceElapsedMs(clip, clip.durationMs); // recover source duration (ramp-aware)
             const newDuration = sourceDuration / clampedRate;
             state.pushUndo();
             set((s) => ({
                 timelineClips: s.timelineClips.map((c) => c.id === clipId
-                    ? { ...c, playbackRate: clampedRate, durationMs: newDuration }
+                    ? { ...c, playbackRate: clampedRate, durationMs: newDuration, speedRamp: undefined }
                     : c),
                 redoStack: [],
             }));
         },
+        setClipSpeedRamp: (clipId, ramp) => {
+            const state = get();
+            const clip = state.timelineClips.find((c) => c.id === clipId);
+            if (!clip)
+                return;
+            const normalized = normalizeSpeedRamp(ramp);
+            state.pushUndo();
+            if (normalized.length === 0) {
+                set((s) => ({
+                    timelineClips: s.timelineClips.map((c) => (c.id === clipId ? { ...c, speedRamp: undefined } : c)),
+                    redoStack: [],
+                }));
+                return;
+            }
+            // Keep the timeline duration; if the ramp would run past the end of the
+            // source, shorten the clip to what the source can feed.
+            let durationMs = clip.durationMs;
+            if (clip.mediaType !== 'image' && clip.mediaType !== 'color') {
+                const sourceAvailable = Math.max(0, clip.originalDurationMs - clip.sourceOffsetMs);
+                if (rampSourceElapsedMs(normalized, durationMs) > sourceAvailable) {
+                    durationMs = Math.max(MIN_CLIP_MS, rampTimelineMsForSource(normalized, sourceAvailable));
+                }
+            }
+            set((s) => ({
+                timelineClips: s.timelineClips.map((c) => c.id === clipId ? { ...c, speedRamp: normalized, playbackRate: undefined, durationMs } : c),
+                redoStack: [],
+            }));
+        },
         setClipAnimation: (clipId, phase, config) => {
             set((s) => ({
                 timelineClips: s.timelineClips.map((c) => c.id === clipId

package/dist/subtitles.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Subtitle cues — shared helpers for headless callers (vivid-mcp) that get
+ * words from a transcription and want CapCut-style word-level captions.
+ * The web editor keeps the same shapes in its own state and renders them
+ * with the templates in src/lib/editor/templates.ts.
+ */
+import type { TranscriptionCue, TranscriptionWord } from './types/editor.js';
+export interface CueInput {
+    id?: string;
+    text: string;
+    startMs: number;
+    endMs: number;
+    /** Optional per-word timing; synthesized evenly across the cue when missing. */
+    words?: Array<{
+        word: string;
+        startMs: number;
+        endMs: number;
+        confidence?: number;
+    }>;
+}
+export interface CuesFromWordsOptions {
+    /** Max words per cue (default 4 — short lines read best on 9:16). */
+    maxWords?: number;
+    /** Max cue length in ms (default 2500). */
+    maxDurationMs?: number;
+    /** A silence longer than this starts a new cue (default 600). */
+    maxGapMs?: number;
+}
+/** Words are synthesized evenly across the cue when the input has none. */
+export declare function synthesizeWords(text: string, startMs: number, endMs: number): TranscriptionWord[];
+/** Validate + fill a list of cues: ids, integer ms, sorted, words present. */
+export declare function normalizeCues(input: CueInput[]): {
+    cues: TranscriptionCue[];
+    warnings: string[];
+};
+/** Group raw transcription words into short cues (what the Worker's /transcribe does, reusable on any word list). */
+export declare function cuesFromWords(words: Array<{
+    word: string;
+    startMs: number;
+    endMs: number;
+    confidence?: number;
+}>, opts?: CuesFromWordsOptions): TranscriptionCue[];

package/dist/subtitles.js

@@ -0,0 +1,81 @@
+/**
+ * Subtitle cues — shared helpers for headless callers (vivid-mcp) that get
+ * words from a transcription and want CapCut-style word-level captions.
+ * The web editor keeps the same shapes in its own state and renders them
+ * with the templates in src/lib/editor/templates.ts.
+ */
+/** Words are synthesized evenly across the cue when the input has none. */
+export function synthesizeWords(text, startMs, endMs) {
+    const tokens = text.split(/\s+/).filter(Boolean);
+    if (tokens.length === 0)
+        return [];
+    const span = Math.max(1, endMs - startMs);
+    const per = span / tokens.length;
+    return tokens.map((word, i) => ({
+        word,
+        startMs: Math.round(startMs + i * per),
+        endMs: Math.round(startMs + (i + 1) * per),
+        confidence: 1,
+    }));
+}
+/** Validate + fill a list of cues: ids, integer ms, sorted, words present. */
+export function normalizeCues(input) {
+    const warnings = [];
+    const cues = [];
+    input.forEach((c, i) => {
+        const text = (c.text ?? '').trim();
+        const startMs = Math.round(Number(c.startMs));
+        const endMs = Math.round(Number(c.endMs));
+        if (!text) {
+            warnings.push(`cue ${i + 1}: empty text, skipped`);
+            return;
+        }
+        if (!Number.isFinite(startMs) || !Number.isFinite(endMs) || endMs <= startMs) {
+            warnings.push(`cue ${i + 1}: invalid timing, skipped`);
+            return;
+        }
+        let words;
+        if (c.words && c.words.length > 0) {
+            words = c.words
+                .filter((w) => w.word && Number.isFinite(w.startMs) && Number.isFinite(w.endMs))
+                .map((w) => ({ word: String(w.word), startMs: Math.round(w.startMs), endMs: Math.round(w.endMs), confidence: w.confidence ?? 1 }));
+            if (words.length === 0)
+                words = synthesizeWords(text, startMs, endMs);
+        }
+        else {
+            words = synthesizeWords(text, startMs, endMs);
+        }
+        cues.push({ id: c.id || `cue-${i + 1}-${startMs}`, text, startMs, endMs, words });
+    });
+    cues.sort((a, b) => a.startMs - b.startMs);
+    return { cues, warnings };
+}
+/** Group raw transcription words into short cues (what the Worker's /transcribe does, reusable on any word list). */
+export function cuesFromWords(words, opts = {}) {
+    const maxWords = opts.maxWords ?? 4;
+    const maxDurationMs = opts.maxDurationMs ?? 2500;
+    const maxGapMs = opts.maxGapMs ?? 600;
+    const cues = [];
+    let current = [];
+    const flush = () => {
+        if (current.length === 0)
+            return;
+        const startMs = current[0].startMs;
+        const endMs = current[current.length - 1].endMs;
+        cues.push({ id: `cue-${cues.length + 1}-${startMs}`, text: current.map((w) => w.word).join(' '), startMs, endMs, words: current });
+        current = [];
+    };
+    for (const w of words) {
+        const word = { word: w.word, startMs: Math.round(w.startMs), endMs: Math.round(w.endMs), confidence: w.confidence ?? 1 };
+        if (current.length > 0) {
+            const gap = word.startMs - current[current.length - 1].endMs;
+            const span = word.endMs - current[0].startMs;
+            const endsSentence = /[.!?…]$/.test(current[current.length - 1].word);
+            if (current.length >= maxWords || gap > maxGapMs || span > maxDurationMs || endsSentence)
+                flush();
+        }
+        current.push(word);
+    }
+    flush();
+    return cues;
+}

package/dist/text-fill.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Text fill — gradient (optionally animated) fill for text overlays.
+ *
+ * Both the DOM preview (`background-clip: text`) and the Canvas2D export
+ * (`createLinearGradient`) draw the same thing from these helpers: a gradient
+ * of `colors` at `angle`, tiled 3× so it can scroll seamlessly, offset by a
+ * phase that depends only on the overlay's elapsed time — deterministic, so
+ * preview and export match frame for frame.
+ */
+import type { TextGradientFill, TextOverlay } from './types/editor.js';
+export type TextFillPresetId = 'iridescent' | 'sunset' | 'ocean' | 'gold' | 'candy';
+export interface TextFillPreset {
+    id: TextFillPresetId;
+    label: string;
+    fill: TextGradientFill;
+}
+export declare const TEXT_FILL_PRESETS: TextFillPreset[];
+export declare function textFillPreset(id: string): TextFillPreset | undefined;
+export declare function isGradientFill(fill: TextOverlay['fill']): fill is TextGradientFill;
+/** Colors with the first one repeated at the end so a scrolling gradient wraps seamlessly. */
+export declare function wrappedFillColors(fill: TextGradientFill): string[];
+/**
+ * Scroll phase in [0, 1) at `elapsedMs` since the overlay appeared — the
+ * fraction of one gradient period the pattern has moved. 0 for static fills.
+ */
+export declare function textFillPhase(fill: TextGradientFill, elapsedMs: number): number;
+/**
+ * Gradient geometry for a box `w × h` centred at the origin: the direction
+ * vector of CSS `linear-gradient(angle)` (0deg = up, 90deg = right) and the
+ * half-length that covers the box corners. Used by the Canvas2D export.
+ */
+export declare function gradientAxis(angleDeg: number, w: number, h: number): {
+    dx: number;
+    dy: number;
+    halfLength: number;
+};
+/**
+ * Color stops for a Canvas2D gradient that spans 3 periods (offset -1..2 in
+ * period units) shifted by `phase`, expressed as [offset 0..1, color] over a
+ * gradient line 3× the box length. Callers create the gradient from
+ * (-halfLength*3 … +halfLength*3) on the axis and add these stops.
+ */
+export declare function shiftedGradientStops(fill: TextGradientFill, phase: number): Array<[number, string]>;
+/**
+ * CSS for the DOM preview of a text box `w × h` px: a 3×3 background whose
+ * gradient line carries the same three tiles as the Canvas2D export, centred
+ * on the box and slid toward the gradient start by `phase` periods. Pair it
+ * with `-webkit-background-clip: text; color: transparent`.
+ */
+export declare function textFillCss(fill: TextGradientFill, phase: number, w: number, h: number): {
+    backgroundImage: string;
+    backgroundSize: string;
+    backgroundPosition: string;
+    backgroundRepeat: string;
+};

package/dist/text-fill.js

@@ -0,0 +1,99 @@
+/**
+ * Text fill — gradient (optionally animated) fill for text overlays.
+ *
+ * Both the DOM preview (`background-clip: text`) and the Canvas2D export
+ * (`createLinearGradient`) draw the same thing from these helpers: a gradient
+ * of `colors` at `angle`, tiled 3× so it can scroll seamlessly, offset by a
+ * phase that depends only on the overlay's elapsed time — deterministic, so
+ * preview and export match frame for frame.
+ */
+export const TEXT_FILL_PRESETS = [
+    { id: 'iridescent', label: 'Iridescent', fill: { type: 'gradient', colors: ['#ff6ec4', '#7873f5', '#4ade80', '#facc15', '#ff6ec4'], angle: 100, animate: 'shift', speed: 0.35 } },
+    { id: 'sunset', label: 'Sunset', fill: { type: 'gradient', colors: ['#f97316', '#ec4899', '#8b5cf6', '#f97316'], angle: 90, animate: 'shift', speed: 0.25 } },
+    { id: 'ocean', label: 'Ocean', fill: { type: 'gradient', colors: ['#22d3ee', '#3b82f6', '#a78bfa', '#22d3ee'], angle: 120, animate: 'shift', speed: 0.3 } },
+    { id: 'gold', label: 'Gold', fill: { type: 'gradient', colors: ['#fde68a', '#d97706', '#fef3c7', '#b45309', '#fde68a'], angle: 75, animate: 'shift', speed: 0.5 } },
+    { id: 'candy', label: 'Candy', fill: { type: 'gradient', colors: ['#f472b6', '#fb7185', '#fbbf24', '#f472b6'], angle: 45, animate: 'none' } },
+];
+export function textFillPreset(id) {
+    return TEXT_FILL_PRESETS.find((p) => p.id === id);
+}
+export function isGradientFill(fill) {
+    return !!fill && fill.type === 'gradient' && Array.isArray(fill.colors) && fill.colors.length >= 2;
+}
+/** Colors with the first one repeated at the end so a scrolling gradient wraps seamlessly. */
+export function wrappedFillColors(fill) {
+    const c = fill.colors;
+    return c[0] === c[c.length - 1] ? c : [...c, c[0]];
+}
+/**
+ * Scroll phase in [0, 1) at `elapsedMs` since the overlay appeared — the
+ * fraction of one gradient period the pattern has moved. 0 for static fills.
+ */
+export function textFillPhase(fill, elapsedMs) {
+    if ((fill.animate ?? 'none') !== 'shift')
+        return 0;
+    const cyclesPerSecond = fill.speed ?? 0.35;
+    const phase = (elapsedMs / 1000) * cyclesPerSecond;
+    return phase - Math.floor(phase);
+}
+/**
+ * Gradient geometry for a box `w × h` centred at the origin: the direction
+ * vector of CSS `linear-gradient(angle)` (0deg = up, 90deg = right) and the
+ * half-length that covers the box corners. Used by the Canvas2D export.
+ */
+export function gradientAxis(angleDeg, w, h) {
+    const rad = (angleDeg * Math.PI) / 180;
+    const dx = Math.sin(rad);
+    const dy = -Math.cos(rad);
+    // Same extent CSS uses: the gradient line spans the box's projection.
+    const halfLength = (Math.abs(w * dx) + Math.abs(h * dy)) / 2;
+    return { dx, dy, halfLength };
+}
+/**
+ * Color stops for a Canvas2D gradient that spans 3 periods (offset -1..2 in
+ * period units) shifted by `phase`, expressed as [offset 0..1, color] over a
+ * gradient line 3× the box length. Callers create the gradient from
+ * (-halfLength*3 … +halfLength*3) on the axis and add these stops.
+ */
+export function shiftedGradientStops(fill, phase) {
+    const colors = wrappedFillColors(fill);
+    const n = colors.length - 1;
+    const stops = [];
+    // Three tiles: t = -1, 0, 1 (period units), each tile spans 1/3 of the line.
+    for (let tile = -1; tile <= 1; tile++) {
+        for (let i = 0; i <= n; i++) {
+            const u = tile + i / n - phase; // period units, shifted left as phase grows
+            const offset = (u + 1) / 3; // map [-1, 2] → [0, 1]
+            if (offset < 0 || offset > 1)
+                continue;
+            stops.push([offset, colors[i]]);
+        }
+    }
+    stops.sort((a, b) => a[0] - b[0]);
+    // Ensure ends are covered.
+    if (stops.length === 0 || stops[0][0] > 0)
+        stops.unshift([0, colors[0]]);
+    if (stops[stops.length - 1][0] < 1)
+        stops.push([1, colors[n]]);
+    return stops;
+}
+/**
+ * CSS for the DOM preview of a text box `w × h` px: a 3×3 background whose
+ * gradient line carries the same three tiles as the Canvas2D export, centred
+ * on the box and slid toward the gradient start by `phase` periods. Pair it
+ * with `-webkit-background-clip: text; color: transparent`.
+ */
+export function textFillCss(fill, phase, w, h) {
+    const stops = shiftedGradientStops(fill, 0).map(([o, c]) => `${c} ${(o * 100).toFixed(3)}%`);
+    const { dx, dy, halfLength } = gradientAxis(fill.angle, w, h);
+    const period = halfLength * 2;
+    // Base: centre the 3× image on the box; then slide one period per phase toward the start.
+    const x = -w - phase * period * dx;
+    const y = -h - phase * period * dy;
+    return {
+        backgroundImage: `linear-gradient(${fill.angle}deg, ${stops.join(', ')})`,
+        backgroundSize: '300% 300%',
+        backgroundRepeat: 'no-repeat',
+        backgroundPosition: `${x.toFixed(2)}px ${y.toFixed(2)}px`,
+    };
+}

package/dist/text-presets.d.ts

@@ -1,5 +1,5 @@
 import type { TextOverlay } from './types/editor.js';
-export type TextPresetId = 'title' | 'subtitle' | 'cta' | 'price' | 'lower-third' | 'minimal';
+export type TextPresetId = 'title' | 'subtitle' | 'cta' | 'price' | 'lower-third' | 'minimal' | 'iridescent';
 export interface TextPreset {
     id: TextPresetId;
     name: string;

package/dist/text-presets.js

@@ -163,6 +163,34 @@ export const TEXT_PRESETS = [
             opacity: 1,
         },
     },
+    {
+        id: 'iridescent',
+        name: 'Iridescent',
+        icon: '✦',
+        defaults: {
+            text: 'Shine',
+            fontFamily: "'Archivo Black', sans-serif",
+            fontSize: 64,
+            fontWeight: 400,
+            color: '#FFFFFF',
+            fill: { type: 'gradient', colors: ['#ff6ec4', '#7873f5', '#4ade80', '#facc15', '#ff6ec4'], angle: 100, animate: 'shift', speed: 0.35 },
+            backgroundColor: 'transparent',
+            backgroundOpacity: 0,
+            strokeColor: '#000000',
+            strokeWidth: 0,
+            shadowColor: '#000000',
+            shadowBlur: 12,
+            shadowOffsetX: 0,
+            shadowOffsetY: 4,
+            textTransform: 'uppercase',
+            textAlign: 'center',
+            animation: 'pop',
+            animationDurationMs: 400,
+            padding: 8,
+            borderRadius: 0,
+            opacity: 1,
+        },
+    },
 ];
 /** Default values for a new text overlay */
 export function createTextOverlay(preset) {

package/dist/types/beat.d.ts

@@ -10,7 +10,20 @@ export interface BeatAnalysis {
     /** Downbeats — every 4th beat (1, 5, 9, ...) — in ms */
     downbeats: number[];
     /** Source of the BPM value */
-    source: 'detected' | 'filename-hint' | 'detected+hint-validated' | 'envelope-fallback';
+    source: 'detected' | 'filename-hint' | 'detected+hint-validated' | 'envelope-fallback' | 'server';
     /** Duration of the analyzed audio, in ms */
     analyzedDurationMs: number;
+    /**
+     * Transient peaks (drum hits, accents, word starts) from the server-side
+     * analysis (POST /api/ai/audio-analysis), ms from the start of the source
+     * audio. Strength is 0–1 relative to the loudest onset. Optional: the
+     * browser-only analyzer does not compute them.
+     */
+    peaks?: AudioPeak[];
+    /** 0–1 peakedness of the tempo autocorrelation (server analysis only). */
+    bpmConfidence?: number;
+}
+export interface AudioPeak {
+    ms: number;
+    strength: number;
 }

package/dist/types/editor.d.ts

@@ -17,6 +17,13 @@ export interface TranscriptionResult {
     language: string;
 }
 export type SubtitleAnimation = 'fade' | 'pop' | 'slide' | 'typewriter' | 'word-highlight' | 'word-popup' | 'outline-reveal' | 'ugc-pop' | 'karaoke-marker' | 'cinematic-fade' | 'neon-cyberpunk' | 'playful-wiggle';
+/**
+ * Ids of the word-level subtitle templates shipped by the web editor
+ * (src/lib/editor/templates.ts). Kept here so headless callers (vivid-mcp)
+ * can validate a `templateId` without the browser template table.
+ */
+export declare const SUBTITLE_TEMPLATE_IDS: readonly ["outline-reveal", "ugc-pop", "karaoke-marker", "cinematic-fade", "neon-cyberpunk", "playful-wiggle"];
+export type SubtitleTemplateId = typeof SUBTITLE_TEMPLATE_IDS[number];
 /** Vertical position as percentage from top (0 = top, 100 = bottom) */
 export type SubtitlePosition = number;
 export interface SubtitleStyleConfig {
@@ -60,6 +67,19 @@ export type TextAnimation = 'none' | 'fade-in' | 'fade-out' | 'fade-in-out' | 's
 import type { Animations } from './animation.js';
 import type { Effect } from './effect.js';
 import type { AudioReactiveModifier } from './audioReactive.js';
+/** Gradient fill for a text overlay — replaces `color` for the glyphs when set. */
+export interface TextGradientFill {
+    type: 'gradient';
+    /** 2+ CSS colors. Repeat the first at the end (or let the renderer do it) for a seamless scroll. */
+    colors: string[];
+    /** CSS convention: 0 = bottom→top, 90 = left→right */
+    angle: number;
+    /** 'shift' scrolls the gradient across the text over time; 'none' keeps it static */
+    animate?: 'none' | 'shift';
+    /** gradient periods per second when animated (default 0.35) */
+    speed?: number;
+}
+export type TextFill = TextGradientFill;
 /** Text overlay on the canvas with timing, position, style, and animation */
 export interface TextOverlay {
     id: string;
@@ -76,6 +96,8 @@ export interface TextOverlay {
     fontStyle?: 'normal' | 'italic';
     textDecoration?: 'none' | 'underline' | 'line-through' | 'overline';
     color: string;
+    /** Optional gradient fill for the glyphs (see TextGradientFill); `color` stays as the fallback. */
+    fill?: TextFill;
     backgroundColor: string;
     backgroundOpacity: number;
     strokeColor: string;

package/dist/types/editor.js

@@ -1 +1,6 @@
-export {};
+/**
+ * Ids of the word-level subtitle templates shipped by the web editor
+ * (src/lib/editor/templates.ts). Kept here so headless callers (vivid-mcp)
+ * can validate a `templateId` without the browser template table.
+ */
+export const SUBTITLE_TEMPLATE_IDS = ['outline-reveal', 'ugc-pop', 'karaoke-marker', 'cinematic-fade', 'neon-cyberpunk', 'playful-wiggle'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vivid-editor-core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "VIVID video editor core: project file schema, editor store and AI command orchestrator — shared by the vividai.tv editor and vivid-mcp.",
   "type": "module",
   "main": "dist/index.js",