@elah/core 0.1.0

package/dist/editor/TimelineEngine.d.ts

@@ -0,0 +1,65 @@
+import type { Clip, EngineEvent, EngineEventPayload, Project, TimelineConfig, Track, TrackKind, Transition, TransitionKind, TransitionEasing, TransitionDirection } from '../types';
+import { type CreateTrackOptions } from '../track/track';
+import { type CreateClipOptions } from '../elements/base';
+type Listener<E extends EngineEvent> = (payload: EngineEventPayload[E]) => void;
+export declare class TimelineEngine {
+    private project;
+    private undoStack;
+    private redoStack;
+    private readonly maxHistorySize;
+    private readonly defaultTrackHeight;
+    private batchDepth;
+    private batchPrev;
+    private batchDescription;
+    private interactionPrev;
+    private listeners;
+    constructor(config: TimelineConfig);
+    getProject(): Project;
+    getTrack(trackId: string): Track | undefined;
+    getClipsOnTrack(trackId: string): Clip[];
+    findClip(clipId: string): {
+        clip: Clip;
+        trackId: string;
+    } | null;
+    getTotalFrames(): number;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    setStage(width: number, height: number): void;
+    addTrack(kind: TrackKind, options?: Partial<CreateTrackOptions>): Track;
+    removeTrack(trackId: string): void;
+    updateTrack(trackId: string, updates: Partial<Track>): void;
+    reorderTracks(orderedIds: string[]): void;
+    addClip(options: CreateClipOptions): Clip;
+    removeClip(clipId: string, trackId: string): void;
+    updateClip(clipId: string, trackId: string, updates: Partial<Clip>): void;
+    previewClip(clipId: string, trackId: string, updates: Partial<Clip>): void;
+    commitInteraction(description?: string): void;
+    cancelInteraction(): void;
+    moveClip(clipId: string, fromTrackId: string, toTrackId: string, startFrame: number): void;
+    trimClip(clipId: string, trackId: string, startFrame: number, durationFrames: number): void;
+    splitClip(clipId: string, trackId: string, atFrame: number): [string, string] | null;
+    cloneClip(clipId: string, trackId: string, startFrame: number): string | null;
+    addTransition(options: {
+        fromClipId: string;
+        toClipId: string;
+        trackId: string;
+        kind: TransitionKind;
+        durationFrames: number;
+        easing?: TransitionEasing;
+        direction?: TransitionDirection;
+        offsetFrames?: number;
+    }): Transition | null;
+    removeTransition(transitionId: string): void;
+    updateTransition(transitionId: string, patch: Partial<Pick<Transition, 'kind' | 'durationFrames' | 'easing' | 'direction'>> & {
+        offsetFrames?: number;
+    }): void;
+    loadProject(project: Project): void;
+    batch(recipe: () => void, description?: string): void;
+    undo(): boolean;
+    redo(): boolean;
+    on<E extends EngineEvent>(event: E, listener: Listener<E>): void;
+    off<E extends EngineEvent>(event: E, listener: Listener<E>): void;
+    private commit;
+    private emit;
+}
+export {};

package/dist/editor/TimelineEngine.js

@@ -0,0 +1,413 @@
+import { produce } from 'immer';
+import { generateId } from '../utils/id';
+import { getTotalFrames, toFrame, findOverlaps } from '../utils/frames';
+import { createTrack } from '../track/track';
+import { createClip } from '../elements/base';
+import { addClip } from '../visitor/add';
+import { removeClip, removeTrack, pruneOrphanedTransitions } from '../visitor/remove';
+import { updateClip, updateTrack } from '../visitor/update';
+import { splitClip } from '../visitor/split';
+import { cloneClip } from '../visitor/clone';
+function buildEmptyProject(fps, stage, initialTracks, defaultTrackHeight) {
+    const specs = initialTracks && initialTracks.length > 0
+        ? initialTracks
+        : [{ kind: 'video', name: 'Track 1' }];
+    const tracks = specs.map((spec, order) => createTrack({
+        kind: spec.kind,
+        name: spec.name,
+        order,
+        height: defaultTrackHeight,
+    }));
+    const clips = {};
+    for (const track of tracks)
+        clips[track.id] = [];
+    return {
+        id: generateId(),
+        fps,
+        stage,
+        tracks,
+        clips,
+        transitions: [],
+        version: 1,
+    };
+}
+export class TimelineEngine {
+    constructor(config) {
+        this.undoStack = [];
+        this.redoStack = [];
+        this.batchDepth = 0;
+        this.batchPrev = null;
+        this.batchDescription = null;
+        this.interactionPrev = null;
+        this.listeners = new Map();
+        const stage = config.stage ?? { width: 1080, height: 1920 };
+        this.maxHistorySize = config.maxHistorySize ?? 100;
+        this.defaultTrackHeight = config.defaultTrackHeight ?? 64;
+        this.project = buildEmptyProject(config.fps, stage, config.initialTracks, this.defaultTrackHeight);
+    }
+    getProject() {
+        return this.project;
+    }
+    getTrack(trackId) {
+        return this.project.tracks.find((t) => t.id === trackId);
+    }
+    getClipsOnTrack(trackId) {
+        return this.project.clips[trackId] ?? [];
+    }
+    findClip(clipId) {
+        for (const [trackId, clips] of Object.entries(this.project.clips)) {
+            const clip = clips.find((c) => c.id === clipId);
+            if (clip)
+                return { clip, trackId };
+        }
+        return null;
+    }
+    getTotalFrames() {
+        return getTotalFrames(this.project.clips);
+    }
+    canUndo() {
+        return this.undoStack.length > 0;
+    }
+    canRedo() {
+        return this.redoStack.length > 0;
+    }
+    setStage(width, height) {
+        this.commit((draft) => {
+            draft.stage = { width, height };
+        }, 'Change aspect ratio');
+    }
+    addTrack(kind, options) {
+        const order = this.project.tracks.length;
+        const track = createTrack({
+            kind,
+            order,
+            height: this.defaultTrackHeight,
+            ...options,
+        });
+        this.commit((draft) => {
+            draft.tracks.push(track);
+            draft.clips[track.id] = [];
+        }, `Add ${kind} track`);
+        this.emit('track:added', track);
+        return track;
+    }
+    removeTrack(trackId) {
+        this.commit((draft) => removeTrack(draft, trackId), `Remove track`);
+        this.emit('track:removed', trackId);
+    }
+    updateTrack(trackId, updates) {
+        this.commit((draft) => updateTrack(draft, trackId, updates), `Update track`);
+    }
+    reorderTracks(orderedIds) {
+        this.commit((draft) => {
+            orderedIds.forEach((id, index) => {
+                const track = draft.tracks.find((t) => t.id === id);
+                if (track)
+                    track.order = index;
+            });
+            draft.tracks.sort((a, b) => a.order - b.order);
+        }, 'Reorder tracks');
+    }
+    addClip(options) {
+        const clip = createClip(options);
+        this.commit((draft) => addClip(draft, clip), `Add ${clip.type} clip`);
+        this.emit('clip:added', clip);
+        return clip;
+    }
+    removeClip(clipId, trackId) {
+        this.commit((draft) => removeClip(draft, clipId, trackId), `Remove clip`);
+        this.emit('clip:removed', { clipId, trackId });
+    }
+    updateClip(clipId, trackId, updates) {
+        this.commit((draft) => updateClip(draft, clipId, trackId, updates), `Update clip`);
+        const clip = this.findClip(clipId)?.clip;
+        if (clip)
+            this.emit('clip:updated', clip);
+    }
+    previewClip(clipId, trackId, updates) {
+        if (this.interactionPrev === null)
+            this.interactionPrev = this.project;
+        const next = produce(this.project, (draft) => updateClip(draft, clipId, trackId, updates));
+        if (next === this.project)
+            return;
+        this.project = next;
+        this.emit('change', this.project);
+        this.emit('clip:updated', this.findClip(clipId).clip);
+    }
+    commitInteraction(description = 'Edit clip') {
+        const prev = this.interactionPrev;
+        if (prev === null)
+            return;
+        this.interactionPrev = null;
+        const next = this.project;
+        if (next === prev)
+            return;
+        this.undoStack.push({ prev, next, description });
+        if (this.undoStack.length > this.maxHistorySize) {
+            this.undoStack.shift();
+        }
+        this.redoStack = [];
+        this.emit('history:change', {
+            canUndo: this.canUndo(),
+            canRedo: this.canRedo(),
+        });
+    }
+    cancelInteraction() {
+        const prev = this.interactionPrev;
+        if (prev === null)
+            return;
+        this.interactionPrev = null;
+        if (this.project !== prev) {
+            this.project = prev;
+            this.emit('change', this.project);
+        }
+    }
+    moveClip(clipId, fromTrackId, toTrackId, startFrame) {
+        const fromClips = this.project.clips[fromTrackId];
+        if (!fromClips)
+            return;
+        const clip = fromClips.find((c) => c.id === clipId);
+        if (!clip)
+            return;
+        const newStart = toFrame(startFrame);
+        const candidate = { startFrame: newStart, durationFrames: clip.durationFrames };
+        const destClips = this.project.clips[toTrackId] ?? [];
+        if (findOverlaps(destClips, candidate, clipId).length > 0)
+            return;
+        this.commit((draft) => {
+            const fromClipsDraft = draft.clips[fromTrackId];
+            if (!fromClipsDraft)
+                return;
+            const idx = fromClipsDraft.findIndex((c) => c.id === clipId);
+            if (idx === -1)
+                return;
+            const [movedClip] = fromClipsDraft.splice(idx, 1);
+            movedClip.startFrame = newStart;
+            movedClip.trackId = toTrackId;
+            if (!draft.clips[toTrackId])
+                draft.clips[toTrackId] = [];
+            draft.clips[toTrackId].push(movedClip);
+            draft.clips[toTrackId].sort((a, b) => a.startFrame - b.startFrame);
+            pruneOrphanedTransitions(draft);
+        }, 'Move clip');
+    }
+    trimClip(clipId, trackId, startFrame, durationFrames) {
+        const trackClips = this.project.clips[trackId];
+        const existing = trackClips?.find((c) => c.id === clipId);
+        if (!existing)
+            return;
+        const isText = existing.type === 'text';
+        const maxDuration = isText ? Infinity : existing.sourceDurationFrames;
+        const clampedDuration = Math.min(maxDuration, Math.max(1, toFrame(durationFrames)));
+        const rawStart = Math.max(0, toFrame(startFrame));
+        const minAllowedStart = isText
+            ? 0
+            : Math.max(0, existing.startFrame - existing.sourceStartFrame);
+        const newStart = Math.max(minAllowedStart, rawStart);
+        const candidate = { startFrame: newStart, durationFrames: clampedDuration };
+        if (findOverlaps(trackClips, candidate, clipId).length > 0)
+            return;
+        const startDelta = newStart - existing.startFrame;
+        const sourceStartFrame = isText
+            ? existing.sourceStartFrame
+            : Math.max(0, existing.sourceStartFrame + startDelta);
+        this.commit((draft) => {
+            updateClip(draft, clipId, trackId, {
+                startFrame: newStart,
+                durationFrames: clampedDuration,
+                sourceStartFrame,
+            });
+            pruneOrphanedTransitions(draft);
+        }, 'Trim clip');
+    }
+    splitClip(clipId, trackId, atFrame) {
+        let result = null;
+        this.commit((draft) => {
+            result = splitClip(draft, clipId, trackId, atFrame);
+            pruneOrphanedTransitions(draft);
+        }, 'Split clip');
+        if (result) {
+            this.emit('clip:split', {
+                leftId: result[0],
+                rightId: result[1],
+                trackId,
+            });
+        }
+        return result;
+    }
+    cloneClip(clipId, trackId, startFrame) {
+        let newId = null;
+        this.commit((draft) => {
+            newId = cloneClip(draft, clipId, trackId, startFrame);
+        }, 'Clone clip');
+        return newId;
+    }
+    addTransition(options) {
+        const fromClip = this.project.clips[options.trackId]?.find((c) => c.id === options.fromClipId);
+        const toClip = this.project.clips[options.trackId]?.find((c) => c.id === options.toClipId);
+        if (!fromClip || !toClip)
+            return null;
+        const half = Math.max(1, Math.floor(options.durationFrames / 2));
+        const offset = options.offsetFrames ?? 0;
+        const transition = {
+            id: generateId(),
+            kind: options.kind,
+            fromClipId: options.fromClipId,
+            toClipId: options.toClipId,
+            trackId: options.trackId,
+            startFrame: toClip.startFrame - half + offset,
+            durationFrames: half * 2,
+            easing: options.easing,
+            direction: options.direction,
+        };
+        this.commit((draft) => {
+            draft.transitions.push(transition);
+        }, 'Add transition');
+        this.emit('transition:added', transition);
+        return transition;
+    }
+    removeTransition(transitionId) {
+        this.commit((draft) => {
+            const idx = draft.transitions.findIndex((t) => t.id === transitionId);
+            if (idx !== -1)
+                draft.transitions.splice(idx, 1);
+        }, 'Remove transition');
+        this.emit('transition:removed', transitionId);
+    }
+    updateTransition(transitionId, patch) {
+        const existing = this.project.transitions.find((t) => t.id === transitionId);
+        if (!existing)
+            return;
+        this.commit((draft) => {
+            const t = draft.transitions.find((t) => t.id === transitionId);
+            if (!t)
+                return;
+            if (patch.kind !== undefined)
+                t.kind = patch.kind;
+            if (patch.easing !== undefined)
+                t.easing = patch.easing;
+            if (patch.direction !== undefined)
+                t.direction = patch.direction;
+            if (patch.durationFrames !== undefined || patch.offsetFrames !== undefined) {
+                const newDuration = patch.durationFrames ?? t.durationFrames;
+                const half = Math.max(1, Math.floor(newDuration / 2));
+                t.durationFrames = half * 2;
+                const toClipEntry = Object.values(draft.clips)
+                    .flat()
+                    .find((c) => c.id === t.toClipId);
+                if (toClipEntry) {
+                    const offset = patch.offsetFrames ?? (t.startFrame - (toClipEntry.startFrame - half));
+                    t.startFrame = toClipEntry.startFrame - half + offset;
+                }
+            }
+        }, 'Update transition');
+    }
+    loadProject(project) {
+        this.project = project;
+        this.undoStack = [];
+        this.redoStack = [];
+        this.emit('change', this.project);
+        this.emit('history:change', { canUndo: false, canRedo: false });
+    }
+    batch(recipe, description) {
+        if (this.batchDepth === 0) {
+            this.batchPrev = this.project;
+            this.batchDescription = description ?? null;
+        }
+        this.batchDepth++;
+        try {
+            recipe();
+        }
+        catch (err) {
+            this.batchDepth--;
+            if (this.batchDepth === 0) {
+                this.project = this.batchPrev;
+                this.batchPrev = null;
+                this.batchDescription = null;
+            }
+            throw err;
+        }
+        this.batchDepth--;
+        if (this.batchDepth > 0)
+            return;
+        const prev = this.batchPrev;
+        const next = this.project;
+        const desc = this.batchDescription ?? 'Batch';
+        this.batchPrev = null;
+        this.batchDescription = null;
+        if (next === prev)
+            return;
+        const entry = { prev, next, description: desc };
+        this.undoStack.push(entry);
+        if (this.undoStack.length > this.maxHistorySize) {
+            this.undoStack.shift();
+        }
+        this.redoStack = [];
+        this.emit('change', this.project);
+        this.emit('history:change', {
+            canUndo: this.canUndo(),
+            canRedo: this.canRedo(),
+        });
+    }
+    undo() {
+        const entry = this.undoStack.pop();
+        if (!entry)
+            return false;
+        this.redoStack.push(entry);
+        this.project = entry.prev;
+        this.emit('change', this.project);
+        this.emit('history:change', {
+            canUndo: this.canUndo(),
+            canRedo: this.canRedo(),
+        });
+        return true;
+    }
+    redo() {
+        const entry = this.redoStack.pop();
+        if (!entry)
+            return false;
+        this.undoStack.push(entry);
+        this.project = entry.next;
+        this.emit('change', this.project);
+        this.emit('history:change', {
+            canUndo: this.canUndo(),
+            canRedo: this.canRedo(),
+        });
+        return true;
+    }
+    on(event, listener) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(listener);
+    }
+    off(event, listener) {
+        this.listeners.get(event)?.delete(listener);
+    }
+    commit(recipe, description) {
+        const prev = this.project;
+        const next = produce(prev, recipe);
+        if (next === prev)
+            return;
+        this.project = next;
+        if (this.batchDepth > 0) {
+            if (this.batchDescription === null)
+                this.batchDescription = description;
+            return;
+        }
+        const entry = { prev, next, description };
+        this.undoStack.push(entry);
+        if (this.undoStack.length > this.maxHistorySize) {
+            this.undoStack.shift();
+        }
+        this.redoStack = [];
+        this.emit('change', this.project);
+        this.emit('history:change', {
+            canUndo: this.canUndo(),
+            canRedo: this.canRedo(),
+        });
+    }
+    emit(event, payload) {
+        this.listeners.get(event)?.forEach((fn) => fn(payload));
+    }
+}

package/dist/editor-context.d.ts

@@ -0,0 +1,10 @@
+import type { TimelineEngine } from './editor/TimelineEngine';
+import type { PlaybackEngine } from './playback/PlaybackEngine';
+export interface EditorContextValue {
+    engine: TimelineEngine;
+    playback: PlaybackEngine;
+}
+export declare const EditorContext: import("react").Context<EditorContextValue | null>;
+export declare function useEditor(): EditorContextValue;
+export declare const useTimelineEngine: () => TimelineEngine;
+export declare const usePlaybackEngine: () => PlaybackEngine;

package/dist/editor-context.js

@@ -0,0 +1,10 @@
+import { createContext, useContext } from 'react';
+export const EditorContext = createContext(null);
+export function useEditor() {
+    const ctx = useContext(EditorContext);
+    if (!ctx)
+        throw new Error('useEditor must be used inside <EditorProvider>');
+    return ctx;
+}
+export const useTimelineEngine = () => useEditor().engine;
+export const usePlaybackEngine = () => useEditor().playback;

package/dist/elements/audio.d.ts

@@ -0,0 +1,13 @@
+import type { Clip, Transform } from '../types';
+export interface CreateAudioClipOptions {
+    trackId: string;
+    name?: string;
+    startFrame: number;
+    durationFrames: number;
+    src: string;
+    assetId?: string;
+    volume?: number;
+    opacity?: number;
+    transform?: Transform;
+}
+export declare function createAudioClip(options: CreateAudioClipOptions): Clip;

package/dist/elements/audio.js

@@ -0,0 +1,4 @@
+import { createClip } from './base';
+export function createAudioClip(options) {
+    return createClip({ ...options, type: 'audio', name: options.name ?? 'Audio' });
+}

package/dist/elements/base.d.ts

@@ -0,0 +1,40 @@
+import type { Clip, Transform } from '../types';
+interface BaseCreateOptions {
+    trackId: string;
+    name?: string;
+    startFrame: number;
+    durationFrames: number;
+    volume?: number;
+    opacity?: number;
+    transform?: Transform;
+}
+interface CreateVideoOptions extends BaseCreateOptions {
+    type: 'video';
+    src: string;
+    assetId?: string;
+}
+interface CreateAudioOptions extends BaseCreateOptions {
+    type: 'audio';
+    src: string;
+    assetId?: string;
+}
+interface CreateImageOptions extends BaseCreateOptions {
+    type: 'image';
+    src: string;
+    assetId?: string;
+}
+export interface TextClipMetadata {
+    content: string;
+    fontSize?: number;
+    color?: string;
+    fontFamily?: string;
+    fontWeight?: 'normal' | 'bold';
+    textAlign?: 'left' | 'center' | 'right';
+}
+interface CreateTextOptions extends BaseCreateOptions {
+    type: 'text';
+    text: TextClipMetadata;
+}
+export type CreateClipOptions = CreateVideoOptions | CreateAudioOptions | CreateImageOptions | CreateTextOptions;
+export declare function createClip(options: CreateClipOptions): Clip;
+export {};

package/dist/elements/base.js

@@ -0,0 +1,39 @@
+import { generateId } from '../utils/id';
+import { toFrame } from '../utils/frames';
+export function createClip(options) {
+    const durationFrames = Math.max(1, toFrame(options.durationFrames));
+    const base = {
+        id: generateId(),
+        trackId: options.trackId,
+        type: options.type,
+        name: options.name ?? options.type,
+        startFrame: toFrame(options.startFrame),
+        durationFrames,
+        sourceStartFrame: 0,
+        sourceDurationFrames: durationFrames,
+        volume: options.volume ?? 1,
+        opacity: options.opacity ?? 1,
+        locked: false,
+        disabled: false,
+        ...(options.transform ? { transform: options.transform } : {}),
+    };
+    if (options.type === 'text') {
+        const { text } = options;
+        return {
+            ...base,
+            type: 'text',
+            content: text.content,
+            ...(text.fontSize !== undefined ? { fontSize: text.fontSize } : {}),
+            ...(text.color !== undefined ? { color: text.color } : {}),
+            ...(text.fontFamily !== undefined ? { fontFamily: text.fontFamily } : {}),
+            ...(text.fontWeight !== undefined ? { fontWeight: text.fontWeight } : {}),
+            ...(text.textAlign !== undefined ? { textAlign: text.textAlign } : {}),
+        };
+    }
+    return {
+        ...base,
+        type: options.type,
+        src: options.src,
+        assetId: options.assetId,
+    };
+}

package/dist/elements/image.d.ts

@@ -0,0 +1,13 @@
+import type { Clip, Transform } from '../types';
+export interface CreateImageClipOptions {
+    trackId: string;
+    name?: string;
+    startFrame: number;
+    durationFrames: number;
+    src: string;
+    assetId?: string;
+    volume?: number;
+    opacity?: number;
+    transform?: Transform;
+}
+export declare function createImageClip(options: CreateImageClipOptions): Clip;

package/dist/elements/image.js

@@ -0,0 +1,4 @@
+import { createClip } from './base';
+export function createImageClip(options) {
+    return createClip({ ...options, type: 'image', name: options.name ?? 'Image' });
+}

package/dist/elements/text.d.ts

@@ -0,0 +1,12 @@
+import type { Clip } from '../types';
+import { type TextClipMetadata } from './base';
+export interface CreateTextClipOptions {
+    trackId: string;
+    name?: string;
+    startFrame: number;
+    durationFrames: number;
+    text: TextClipMetadata;
+    volume?: number;
+    opacity?: number;
+}
+export declare function createTextClip(options: CreateTextClipOptions): Clip;

package/dist/elements/text.js

@@ -0,0 +1,8 @@
+import { createClip } from './base';
+export function createTextClip(options) {
+    return createClip({
+        ...options,
+        type: 'text',
+        name: options.name ?? 'Text',
+    });
+}

package/dist/elements/video.d.ts

@@ -0,0 +1,13 @@
+import type { Clip, Transform } from '../types';
+export interface CreateVideoClipOptions {
+    trackId: string;
+    name?: string;
+    startFrame: number;
+    durationFrames: number;
+    src: string;
+    assetId?: string;
+    volume?: number;
+    opacity?: number;
+    transform?: Transform;
+}
+export declare function createVideoClip(options: CreateVideoClipOptions): Clip;

package/dist/elements/video.js

@@ -0,0 +1,4 @@
+import { createClip } from './base';
+export function createVideoClip(options) {
+    return createClip({ ...options, type: 'video', name: options.name ?? 'Video' });
+}

package/dist/export/ExportWorker.d.ts

@@ -0,0 +1 @@
+export {};