@elah/core 0.1.0

package/dist/utils/frames.js

@@ -0,0 +1,40 @@
+export function toFrame(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.max(0, Math.round(value));
+}
+export function secondsToFrames(seconds, fps) {
+    return toFrame(seconds * fps);
+}
+export function framesToSeconds(frames, fps) {
+    return frames / fps;
+}
+export function framesToTimecode(frames, fps) {
+    const f = frames % fps;
+    const totalSeconds = Math.floor(frames / fps);
+    const s = totalSeconds % 60;
+    const m = Math.floor(totalSeconds / 60) % 60;
+    const h = Math.floor(totalSeconds / 3600);
+    return `${pad(h)}:${pad(m)}:${pad(s)}:${pad(f)}`;
+}
+function pad(n) {
+    return String(Math.floor(n)).padStart(2, '0');
+}
+export function getTotalFrames(clips) {
+    let max = 0;
+    for (const trackClips of Object.values(clips)) {
+        for (const clip of trackClips) {
+            const end = clip.startFrame + clip.durationFrames;
+            if (end > max)
+                max = end;
+        }
+    }
+    return max;
+}
+export function clipsOverlap(a, b) {
+    return (a.startFrame < b.startFrame + b.durationFrames &&
+        a.startFrame + a.durationFrames > b.startFrame);
+}
+export function findOverlaps(trackClips, candidate, excludeId) {
+    return trackClips.filter((c) => c.id !== excludeId && clipsOverlap(c, candidate));
+}

package/dist/utils/id.d.ts

@@ -0,0 +1 @@
+export declare function generateId(): string;

package/dist/utils/id.js

@@ -0,0 +1,3 @@
+export function generateId() {
+    return Math.random().toString(36).slice(2, 10);
+}

package/dist/utils/snap.d.ts

@@ -0,0 +1,5 @@
+import type { Clip } from '../types';
+export declare function snapFrame(frame: number, snapPoints: number[], threshold: number): number;
+export declare function buildSnapPoints(clips: Record<string, Clip[]>, excludeId?: string): number[];
+export declare const DEFAULT_OVERLAP_TOLERANCE = 0.4;
+export declare function resolveOverlapEdgeSnap(nextStart: number, movingClip: Clip, trackClips: Clip[], overlapTolerance?: number): number;

package/dist/utils/snap.js

@@ -0,0 +1,79 @@
+export function snapFrame(frame, snapPoints, threshold) {
+    let nearest = frame;
+    let minDist = threshold;
+    for (const point of snapPoints) {
+        const dist = Math.abs(frame - point);
+        if (dist < minDist) {
+            minDist = dist;
+            nearest = point;
+        }
+    }
+    return nearest;
+}
+export function buildSnapPoints(clips, excludeId) {
+    const points = new Set();
+    for (const trackClips of Object.values(clips)) {
+        for (const clip of trackClips) {
+            if (clip.id === excludeId)
+                continue;
+            points.add(clip.startFrame);
+            points.add(clip.startFrame + clip.durationFrames);
+        }
+    }
+    points.add(0);
+    return [...points].sort((a, b) => a - b);
+}
+export const DEFAULT_OVERLAP_TOLERANCE = 0.4;
+const MAX_OVERLAP_RESOLVE_ITERATIONS = 48;
+function clipEndFrame(c) {
+    return c.startFrame + c.durationFrames;
+}
+function overlapFrames(aStart, aEnd, bStart, bEnd) {
+    const lo = Math.max(aStart, bStart);
+    const hi = Math.min(aEnd, bEnd);
+    const n = hi - lo;
+    return n > 0 ? n : 0;
+}
+function clipsOverlappingMoving(start, durationFrames, movingId, trackClips) {
+    const mEnd = start + durationFrames;
+    return trackClips.filter((c) => {
+        if (c.id === movingId)
+            return false;
+        return overlapFrames(start, mEnd, c.startFrame, clipEndFrame(c)) > 0;
+    });
+}
+export function resolveOverlapEdgeSnap(nextStart, movingClip, trackClips, overlapTolerance = DEFAULT_OVERLAP_TOLERANCE) {
+    const D = movingClip.durationFrames;
+    let start = nextStart;
+    for (let iter = 0; iter < MAX_OVERLAP_RESOLVE_ITERATIONS; iter++) {
+        const overlapping = clipsOverlappingMoving(start, D, movingClip.id, trackClips);
+        if (overlapping.length === 0)
+            return start;
+        let dominant = null;
+        let maxRatio = -1;
+        const mEnd = start + D;
+        for (const c of overlapping) {
+            const ov = overlapFrames(start, mEnd, c.startFrame, clipEndFrame(c));
+            const ratio = ov / Math.max(1, c.durationFrames);
+            if (ratio > maxRatio) {
+                maxRatio = ratio;
+                dominant = c;
+            }
+        }
+        if (!dominant)
+            return start;
+        const targetStart = dominant.startFrame;
+        const targetEnd = clipEndFrame(dominant);
+        let candidate = maxRatio > overlapTolerance
+            ? targetEnd
+            : Math.max(0, targetStart - D);
+        if (candidate === start) {
+            candidate = Math.max(...overlapping.map((c) => clipEndFrame(c)));
+        }
+        start = candidate;
+    }
+    const finalOverlapping = clipsOverlappingMoving(start, D, movingClip.id, trackClips);
+    if (finalOverlapping.length === 0)
+        return start;
+    return Math.max(start, ...finalOverlapping.map((c) => clipEndFrame(c)));
+}

package/dist/visitor/add.d.ts

@@ -0,0 +1,3 @@
+import type { Draft } from 'immer';
+import type { Clip, Project } from '../types';
+export declare function addClip(draft: Draft<Project>, clip: Clip): void;

package/dist/visitor/add.js

@@ -0,0 +1,16 @@
+import { findOverlaps } from '../utils/frames';
+export function addClip(draft, clip) {
+    const track = draft.tracks.find((t) => t.id === clip.trackId);
+    if (!track) {
+        throw new Error(`Track "${clip.trackId}" not found`);
+    }
+    if (!draft.clips[clip.trackId]) {
+        draft.clips[clip.trackId] = [];
+    }
+    const overlaps = findOverlaps(draft.clips[clip.trackId], clip);
+    if (overlaps.length > 0) {
+        throw new Error(`Clip overlaps with existing clip "${overlaps[0].id}" on track "${clip.trackId}"`);
+    }
+    draft.clips[clip.trackId].push(clip);
+    draft.clips[clip.trackId].sort((a, b) => a.startFrame - b.startFrame);
+}

package/dist/visitor/clone.d.ts

@@ -0,0 +1,3 @@
+import type { Draft } from 'immer';
+import type { Project } from '../types';
+export declare function cloneClip(draft: Draft<Project>, clipId: string, trackId: string, startFrame: number): string | null;

package/dist/visitor/clone.js

@@ -0,0 +1,25 @@
+import { generateId } from '../utils/id';
+import { toFrame } from '../utils/frames';
+import { findOverlaps } from '../utils/frames';
+export function cloneClip(draft, clipId, trackId, startFrame) {
+    const trackClips = draft.clips[trackId];
+    if (!trackClips)
+        return null;
+    const original = trackClips.find((c) => c.id === clipId);
+    if (!original)
+        return null;
+    const newStartFrame = toFrame(startFrame);
+    const candidate = { startFrame: newStartFrame, durationFrames: original.durationFrames };
+    const overlaps = findOverlaps(trackClips, candidate);
+    if (overlaps.length > 0)
+        return null;
+    const clone = {
+        ...original,
+        id: generateId(),
+        startFrame: newStartFrame,
+        sourceStartFrame: original.sourceStartFrame,
+    };
+    trackClips.push(clone);
+    trackClips.sort((a, b) => a.startFrame - b.startFrame);
+    return clone.id;
+}

package/dist/visitor/remove.d.ts

@@ -0,0 +1,5 @@
+import type { Draft } from 'immer';
+import type { Project } from '../types';
+export declare function pruneOrphanedTransitions(draft: Draft<Project>): void;
+export declare function removeClip(draft: Draft<Project>, clipId: string, trackId: string): void;
+export declare function removeTrack(draft: Draft<Project>, trackId: string): void;

package/dist/visitor/remove.js

@@ -0,0 +1,29 @@
+export function pruneOrphanedTransitions(draft) {
+    const allClips = Object.values(draft.clips).flat();
+    draft.transitions = draft.transitions.filter((t) => {
+        const from = allClips.find((c) => c.id === t.fromClipId);
+        const to = allClips.find((c) => c.id === t.toClipId);
+        if (!from || !to)
+            return false;
+        const gap = to.startFrame - (from.startFrame + from.durationFrames);
+        return gap >= 0 && gap <= 2;
+    });
+}
+export function removeClip(draft, clipId, trackId) {
+    const trackClips = draft.clips[trackId];
+    if (!trackClips)
+        return;
+    const idx = trackClips.findIndex((c) => c.id === clipId);
+    if (idx !== -1) {
+        trackClips.splice(idx, 1);
+    }
+    pruneOrphanedTransitions(draft);
+}
+export function removeTrack(draft, trackId) {
+    const idx = draft.tracks.findIndex((t) => t.id === trackId);
+    if (idx !== -1) {
+        draft.tracks.splice(idx, 1);
+    }
+    delete draft.clips[trackId];
+    pruneOrphanedTransitions(draft);
+}

package/dist/visitor/split.d.ts

@@ -0,0 +1,3 @@
+import type { Draft } from 'immer';
+import type { Project } from '../types';
+export declare function splitClip(draft: Draft<Project>, clipId: string, trackId: string, atFrame: number): [string, string] | null;

package/dist/visitor/split.js

@@ -0,0 +1,31 @@
+import { generateId } from '../utils/id';
+import { toFrame } from '../utils/frames';
+export function splitClip(draft, clipId, trackId, atFrame) {
+    const trackClips = draft.clips[trackId];
+    if (!trackClips)
+        return null;
+    const idx = trackClips.findIndex((c) => c.id === clipId);
+    if (idx === -1)
+        return null;
+    const clip = trackClips[idx];
+    const splitFrame = toFrame(atFrame);
+    if (splitFrame <= clip.startFrame ||
+        splitFrame >= clip.startFrame + clip.durationFrames) {
+        return null;
+    }
+    const leftDuration = splitFrame - clip.startFrame;
+    const rightDuration = clip.durationFrames - leftDuration;
+    const rightId = generateId();
+    const rightClip = {
+        ...clip,
+        id: rightId,
+        startFrame: splitFrame,
+        durationFrames: rightDuration,
+        sourceStartFrame: clip.sourceStartFrame + leftDuration,
+        sourceDurationFrames: rightDuration,
+    };
+    clip.durationFrames = leftDuration;
+    clip.sourceDurationFrames = leftDuration;
+    trackClips.splice(idx + 1, 0, rightClip);
+    return [clip.id, rightId];
+}

package/dist/visitor/update.d.ts

@@ -0,0 +1,4 @@
+import type { Draft } from 'immer';
+import type { Clip, Project, Track } from '../types';
+export declare function updateClip(draft: Draft<Project>, clipId: string, trackId: string, updates: Partial<Clip>): void;
+export declare function updateTrack(draft: Draft<Project>, trackId: string, updates: Partial<Track>): void;

package/dist/visitor/update.js

@@ -0,0 +1,31 @@
+import { toFrame } from '../utils/frames';
+import { findOverlaps } from '../utils/frames';
+export function updateClip(draft, clipId, trackId, updates) {
+    const trackClips = draft.clips[trackId];
+    if (!trackClips)
+        return;
+    const clip = trackClips.find((c) => c.id === clipId);
+    if (!clip)
+        return;
+    if (updates.startFrame !== undefined) {
+        updates.startFrame = toFrame(updates.startFrame);
+    }
+    if (updates.durationFrames !== undefined) {
+        updates.durationFrames = Math.max(1, toFrame(updates.durationFrames));
+    }
+    const merged = { ...clip, ...updates };
+    const overlaps = findOverlaps(trackClips, merged, clipId);
+    if (overlaps.length > 0) {
+        throw new Error(`Update would cause clip "${clipId}" to overlap with "${overlaps[0].id}"`);
+    }
+    Object.assign(clip, updates);
+    if (updates.startFrame !== undefined) {
+        trackClips.sort((a, b) => a.startFrame - b.startFrame);
+    }
+}
+export function updateTrack(draft, trackId, updates) {
+    const track = draft.tracks.find((t) => t.id === trackId);
+    if (!track)
+        return;
+    Object.assign(track, updates);
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@elah/core",
+  "version": "0.1.0",
+  "description": "Framework-agnostic video timeline engine",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "tsc --noEmit && tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "immer": "^10.1.1",
+    "zustand": "^5.0.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.6"
+  }
+}