@elah/editor 0.3.2 → 0.4.1

package/README.md

@@ -2,7 +2,7 @@
 
 The full Elah video editor SDK for React. Combines the core engine, timeline UI, WebGL2 renderer, media library, and export pipeline into a single package.
 
-Ships `EditorProvider`, `Preview` (WebGL2 canvas + interactive transform overlays), `Timeline`, `AssetPanel`, `SourcePanel`, and `ElementsPanel`, and re-exports the entire `@elah/core` and `@elah/timeline` API. Supports video, image, text, **shape**, and **freehand** clips, **multi-track audio**, and MP4 export.
+Ships `EditorProvider`, `Preview` (WebGL2 canvas + interactive transform overlays), `Timeline`, `AssetPanel`, `SourcePanel`, and `ElementsPanel`, and re-exports the public `@elah/core`, `@elah/react`, and `@elah/timeline` API — so most apps only ever import from `@elah/editor`. (Renderer and debug internals are the exception; import those from `@elah/core` directly.) Supports video, image, text, **shape**, and **freehand** clips, **multi-track audio**, and MP4 export.
 
 [![npm](https://img.shields.io/npm/v/@elah/editor)](https://www.npmjs.com/package/@elah/editor)
 [![gzip size](https://img.shields.io/badge/gzip-~63%20KiB%20full%20SDK-brightgreen)](../../BUNDLE_STRATEGY.md)
@@ -16,7 +16,9 @@ Ships `EditorProvider`, `Preview` (WebGL2 canvas + interactive transform overlay
 npm install @elah/editor
 ```
 
-Peer dependencies: `react`, `react-dom` >= 18.
+Peer dependencies: `react`, `react-dom` >= 18, `lucide-react` >= 0.400.0 (used by the
+bundled `@elah/timeline` UI for clip icons — install it alongside `react`/`react-dom`
+even though nothing in your own code imports it).
 
 **Bundle size:** ~10 KiB gzipped for the editor layer (51 KiB raw); ~63 KiB gzipped for the full SDK graph (`core` + `timeline` + `editor`, 330 KiB raw). `mediabunny` is injected, never bundled — see [BUNDLE_STRATEGY.md](../../BUNDLE_STRATEGY.md).
 
@@ -84,14 +86,16 @@ function App() {
 ## Import media
 
 ```ts
-import { importFiles, importUrl, useMediaLibrary } from '@elah/editor'
+import { importFiles, importUrl, importBlob, useMediaLibrary } from '@elah/editor'
 
-await importFiles(Array.from(fileList))   // local files
-await importUrl('https://example.com/clip.mp4') // remote URL (also importBlob for blobs)
+await importFiles(Array.from(fileList))          // local files
+await importUrl('https://example.com/clip.mp4')  // remote URL
+await importBlob(recordedBlob, { name: 'take-1.webm' })
 
 // Subscribe in React — useMediaLibrary() takes no arguments and returns
-// { assets, getAsset, removeAsset, updateAsset } with assets in insertion order.
-const { assets } = useMediaLibrary()
+// { assets, getAsset, removeAsset, updateAsset, importFiles, importUrl, importBlob }
+// with assets in insertion order. `useAssets` is an alias for the same hook.
+const { assets, importFiles: addFiles } = useMediaLibrary()
 ```
 
 ### Programmatic insertion (no drag)
@@ -142,16 +146,27 @@ Runs in a web worker. Reuses `resolveTimeline` + the GPU renderer's placement ma
 ## Package layers
 
 ```
-@elah/core      — engine, playback, resolver, stores, media, export (framework-agnostic)
-@elah/timeline  — React timeline UI components and hooks
-@elah/editor    — EditorProvider, Preview, AssetPanel + re-exports everything above
+@elah/core      — engine, playback, resolver, vanilla stores, media, export (framework-agnostic)
+@elah/react     — React bindings: EditorContext, store hooks, audio hooks
+@elah/timeline  — React timeline UI components and hooks (consumes @elah/core + @elah/react)
+@elah/editor    — EditorProvider, Preview, AssetPanel + re-exports @elah/core, @elah/react, @elah/timeline
 @elah/cli       — headless split/trim/build/export/serve on top of @elah/core
 ```
 
 Use `@elah/editor` for the full in-browser experience. Use `@elah/core` directly
-for headless or custom rendering pipelines. Use `@elah/cli` for automation,
+for headless or custom rendering pipelines, or pair it with `@elah/react` if you
+want the hooks without the timeline UI. Use `@elah/cli` for automation,
 AI-generation pipelines, and server-side rendering.
 
+**One active project per page.** `@elah/core`'s stores (`tracksStore`,
+`playbackStore`, `selectionStore`, `transitionsStore`, `mediaLibraryStore`) are
+module-level singletons, and `<EditorProvider>` wires the `TimelineEngine` /
+`PlaybackEngine` it creates into those same shared stores. Mounting a second
+`<EditorProvider>` on the same page (two independent projects at once) will have
+both instances overwrite each other's state — there is currently no per-instance
+scoping. If you need multiple concurrent editors, isolate each in its own
+tab/window/iframe.
+
 ---
 
 ## Links

package/dist/editor/AssetPanel/AssetPanel.js

@@ -1,7 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useCallback, useEffect, useRef, useState, } from 'react';
 import { createPortal } from 'react-dom';
-import { importFiles, importUrl, MEDIA_DRAG_MIME, mediaDragKindMime, useMediaLibrary, useMediaLibraryStore, } from '@elah/core';
+import { importFiles, importUrl, MEDIA_DRAG_MIME, mediaDragKindMime, } from '@elah/core';
+import { useMediaLibrary, useMediaLibraryStore } from '@elah/react';
 import { cn } from '@elah/timeline';
 import { isActivationKey, useAssetActivation, } from '../activation';
 const KIND_ICONS = {

package/dist/editor/EditorProvider.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useMemo } from 'react';
-import { TimelineEngine, PlaybackEngine, useTracksStore, usePlaybackStore, useTransitionsStore, EditorContext, installTraceGlobal, trace, } from '@elah/core';
+import { TimelineEngine, PlaybackEngine, installTraceGlobal, trace, } from '@elah/core';
+import { useTracksStore, usePlaybackStore, useTransitionsStore, EditorContext, } from '@elah/react';
 export function EditorProvider({ fps, stage, defaultTrackHeight, maxHistorySize, initialTracks, children, }) {
     const engine = useMemo(() => new TimelineEngine({
         fps,

package/dist/editor/Preview/MediaTransformOverlay.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useLayoutEffect, useMemo, useRef, useState, } from 'react';
-import { useTimelineEngine, useSelectionStore, usePlaybackStore, useMediaLibraryStore, resolveDrawRect, transformFromContainRect, computeContainViewport, } from '@elah/core';
+import { resolveDrawRect, transformFromContainRect, computeContainViewport, } from '@elah/core';
+import { useTimelineEngine, useSelectionStore, usePlaybackStore, useMediaLibraryStore, } from '@elah/react';
 import { useResolvedScene } from '../useResolvedScene';
 const MIN_BOX_PX = 28;
 const BOX_PAD = 0;

package/dist/editor/Preview/Preview.js

@@ -2,8 +2,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef, useEffect, useImperativeHandle, useRef, } from 'react';
 import { GpuRenderer } from '@elah/core';
 import { resolveTimeline } from '@elah/core';
-import { useTimelineEngine, usePlaybackEngine } from '@elah/core';
-import { AudioPlaybackController, useMediaLibraryStore, preloadProjectImages, warmImageSrc } from '@elah/core';
+import { useTimelineEngine, usePlaybackEngine, useMediaLibraryStore } from '@elah/react';
+import { AudioPlaybackController, preloadProjectImages, warmImageSrc } from '@elah/core';
 import { cn } from '@elah/timeline';
 import { TextOverlay } from './TextOverlay';
 import { ShapeOverlay } from './ShapeOverlay';

package/dist/editor/Preview/ShapeOverlay.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useLayoutEffect, useMemo, useRef, useState, } from 'react';
-import { useTimelineEngine, useSelectionStore, usePlaybackStore, computeContainViewport, } from '@elah/core';
+import { computeContainViewport } from '@elah/core';
+import { useTimelineEngine, useSelectionStore, usePlaybackStore, } from '@elah/react';
 import { useResolvedScene } from '../useResolvedScene';
 const DEFAULT_SCALE = 0.5;
 const DEFAULT_CENTER = 0.5;

package/dist/editor/Preview/StageBorder.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useLayoutEffect, useMemo, useRef, useState } from 'react';
-import { computeContainViewport, useTracksStore } from '@elah/core';
+import { computeContainViewport } from '@elah/core';
+import { useTracksStore } from '@elah/react';
 export function StageBorder() {
     const rootRef = useRef(null);
     const [size, setSize] = useState({ width: 0, height: 0 });

package/dist/editor/Preview/TextOverlay.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
-import { computeTextLayout, computeContainViewport, useTimelineEngine, useSelectionStore, usePlaybackStore, SIDE_MARGIN, } from '@elah/core';
+import { computeTextLayout, computeContainViewport, SIDE_MARGIN, } from '@elah/core';
+import { useTimelineEngine, useSelectionStore, usePlaybackStore, } from '@elah/react';
 import { useResolvedScene } from '../useResolvedScene';
 const MIN_FONT_SIZE = 6;
 const MAX_FONT_SIZE = 4000;

package/dist/editor/SourcePanel/SourcePanel.js

@@ -1,7 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useCallback, useEffect, useRef, useState, } from 'react';
 import { createPortal } from 'react-dom';
-import { importFiles, importUrl, MEDIA_DRAG_MIME, mediaDragKindMime, useMediaLibrary, useMediaLibraryStore, } from '@elah/core';
+import { importFiles, importUrl, MEDIA_DRAG_MIME, mediaDragKindMime, } from '@elah/core';
+import { useMediaLibrary, useMediaLibraryStore } from '@elah/react';
 import { ELEMENT_DRAG_MIME, cn } from '@elah/timeline';
 import { isActivationKey, useAssetActivation, } from '../activation';
 const KIND_ICONS = { video: '▶', audio: '♪', image: '◻' };

package/dist/editor/activation.d.ts

@@ -1,4 +1,4 @@
-import { type MediaAsset } from '@elah/core';
+import type { MediaAsset } from '@elah/core';
 import { type ElementKind, type ShapeVariant } from '@elah/timeline';
 export interface ActivationToast {
     message: string;

package/dist/editor/activation.js

@@ -1,5 +1,5 @@
 import { useCallback, useContext } from 'react';
-import { EditorContext } from '@elah/core';
+import { EditorContext } from '@elah/react';
 import { insertElement, insertMediaAsset, } from '@elah/timeline';
 export function isActivationKey(key) {
     return key === 'Enter' || key === ' ';

package/dist/editor/useResolvedScene.js

@@ -1,5 +1,6 @@
 import { useMemo, useRef } from 'react';
-import { useTimelineEngine, useTracksStore, usePlaybackStore, resolveTimeline, } from '@elah/core';
+import { resolveTimeline } from '@elah/core';
+import { useTimelineEngine, useTracksStore, usePlaybackStore, } from '@elah/react';
 export function useResolvedScene(frameOverride) {
     const engine = useTimelineEngine();
     const playbackFrame = usePlaybackStore((s) => (s.isPlaying ? null : s.currentFrame));

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { TimelineEngine } from '@elah/core';
 export { PlaybackEngine } from '@elah/core';
 export type { PlaybackSnapshot, PlaybackEngineConfig } from '@elah/core';
 export { resolveTimeline } from '@elah/core';
-export type { Scene, ActiveTransition, ActiveVideoClip, ActiveAudioClip, ActiveTextClip, ActiveImageClip, ActiveClipBase, } from '@elah/core';
+export type { Scene, ActiveTransition, ActiveVideoClip, ActiveAudioClip, ActiveTextClip, ActiveImageClip, ActiveShapeClip, ActiveFreehandClip, ActiveClipBase, } from '@elah/core';
 export type { Renderer } from '@elah/core';
 export { GpuRenderer } from '@elah/core';
 export type { RendererOptions } from '@elah/core';
@@ -11,44 +11,62 @@ export { GpuDebugCounters } from '@elah/core';
 export type { CounterSnapshot } from '@elah/core';
 export { createDefaultDemuxerFactory, createMediabunnyBackend, isMediabunnyCompatible } from '@elah/core';
 export type { MediabunnyModule, CreateMediabunnyBackendOpts } from '@elah/core';
-export type { DemuxerBackend, DemuxerFactory } from '@elah/core';
+export type { DemuxerBackend, DemuxerFactory, MediabunnyDemuxer } from '@elah/core';
 export type { VideoFrameProvider, VideoFrameProviderDeps } from '@elah/core';
 export { createVideoFrameProvider, MockVideoFrameProvider, SyntheticVideoFrameProvider } from '@elah/core';
 export { AudioPlaybackController } from '@elah/core';
 export type { AudioPlaybackControllerOptions } from '@elah/core';
 export { defaultAudioResolver } from '@elah/core';
 export type { AudioResolver } from '@elah/core';
-export { useMediaLibrary, useMediaLibraryStore, MEDIA_DRAG_MIME, mediaDragKindMime, importFiles, importUrl } from '@elah/core';
-export type { MediaAsset, MediaKind, DragMediaPayload, ImportFilesOptions, ImportFilesResult, SkippedImport } from '@elah/core';
-export { useTracksStore } from '@elah/core';
-export { usePlaybackStore } from '@elah/core';
-export { useSelectionStore } from '@elah/core';
+export { warmImageSrc, preloadProjectImages } from '@elah/core';
+export type { ImageLoader, LoadedImage } from '@elah/core';
+export { MEDIA_DRAG_MIME, mediaDragKindMime, importFiles, importUrl, importBlob } from '@elah/core';
+export { useMediaLibrary, useAssets, useMediaLibraryStore } from '@elah/react';
+export type { MediaAsset, MediaKind, DragMediaPayload, ImportFilesOptions, ImportFilesResult, ImportUrlOptions, ImportBlobOptions, SkippedImport, MediaLibraryState, MediaLibraryActions, } from '@elah/core';
+export type { UseMediaLibraryApi } from '@elah/react';
+export { useTracksStore } from '@elah/react';
+export { usePlaybackStore } from '@elah/react';
+export { useSelectionStore } from '@elah/react';
+export { useTransitionsStore } from '@elah/react';
+export type { BoundStoreHook } from '@elah/react';
+export { tracksStore, playbackStore, selectionStore, transitionsStore, mediaLibraryStore } from '@elah/core';
+export type { TracksState, TracksActions, PlaybackState, PlaybackActions, SelectionState, SelectionActions, TransitionsState, TransitionsActions, } from '@elah/core';
 export { createVideoClip } from '@elah/core';
 export { createAudioClip } from '@elah/core';
 export { createTextClip } from '@elah/core';
 export { createImageClip } from '@elah/core';
+export { createShapeClip } from '@elah/core';
+export { createFreehandClip } from '@elah/core';
+export type { CreateClipOptions, CreateShapeClipOptions, CreateFreehandClipOptions, ShapeClipMetadata, FreehandClipMetadata, } from '@elah/core';
 export { splitClipAtPlayhead } from '@elah/core';
 export type { SplitAtPlayheadData } from '@elah/core';
 export type { ActionResult, ActionFailureReason } from '@elah/core';
 export { framesToTimecode, secondsToFrames, framesToSeconds, getTotalFrames } from '@elah/core';
 export { generateId } from '@elah/core';
 export { transformFromCoverRect } from '@elah/core';
+export { snapFrame, buildSnapPoints, resolveOverlapEdgeSnap, clipsOverlap, DEFAULT_OVERLAP_TOLERANCE } from '@elah/core';
+export { serializeProject, deserializeProject } from '@elah/core';
 export { exportVideo } from '@elah/core';
 export { lazyExportVideo } from '@elah/core';
 export type { ExportOptions, ExportProgress, ExportVideoCodec, ExportAudioCodec } from '@elah/core';
 export { Timeline } from '@elah/timeline';
-export type { TimelineProps, TimelineRef } from '@elah/timeline';
+export type { TimelineProps, TimelineRef, TimelineClassNames } from '@elah/timeline';
+export { cn } from '@elah/timeline';
 export { useTimeline } from '@elah/timeline';
 export { useTracks } from '@elah/timeline';
 export { usePlayback } from '@elah/timeline';
 export { useSelection } from '@elah/timeline';
 export { useTimelineDrop } from '@elah/timeline';
+export type { TimelineDropState } from '@elah/timeline';
 export { insertMediaAsset, insertElement } from '@elah/timeline';
 export { ELEMENT_DRAG_MIME } from '@elah/timeline';
 export type { DragElementPayload, ElementKind, ShapeVariant, InsertAssetOptions, InsertAssetResult, InsertAssetFailureReason, InsertedKind, } from '@elah/timeline';
 export { EditorProvider } from './editor/EditorProvider';
 export type { EditorProviderProps } from './editor/EditorProvider';
-export { useEditor, useTimelineEngine, usePlaybackEngine } from '@elah/core';
+export { EditorContext, useEditor, useTimelineEngine, usePlaybackEngine } from '@elah/react';
+export type { EditorContextValue } from '@elah/react';
+export { useAudioMixer, useMasterVolume, useTrackLevels } from '@elah/react';
+export type { AudioMixerApi, MasterVolumeApi, TrackLevel } from '@elah/react';
 export { useResolvedScene } from './editor/useResolvedScene';
 export { AssetPanel } from './editor/AssetPanel';
 export type { AssetPanelProps } from './editor/AssetPanel';

package/dist/index.js

@@ -7,21 +7,30 @@ export { createDefaultDemuxerFactory, createMediabunnyBackend, isMediabunnyCompa
 export { createVideoFrameProvider, MockVideoFrameProvider, SyntheticVideoFrameProvider } from '@elah/core';
 export { AudioPlaybackController } from '@elah/core';
 export { defaultAudioResolver } from '@elah/core';
-export { useMediaLibrary, useMediaLibraryStore, MEDIA_DRAG_MIME, mediaDragKindMime, importFiles, importUrl } from '@elah/core';
-export { useTracksStore } from '@elah/core';
-export { usePlaybackStore } from '@elah/core';
-export { useSelectionStore } from '@elah/core';
+export { warmImageSrc, preloadProjectImages } from '@elah/core';
+export { MEDIA_DRAG_MIME, mediaDragKindMime, importFiles, importUrl, importBlob } from '@elah/core';
+export { useMediaLibrary, useAssets, useMediaLibraryStore } from '@elah/react';
+export { useTracksStore } from '@elah/react';
+export { usePlaybackStore } from '@elah/react';
+export { useSelectionStore } from '@elah/react';
+export { useTransitionsStore } from '@elah/react';
+export { tracksStore, playbackStore, selectionStore, transitionsStore, mediaLibraryStore } from '@elah/core';
 export { createVideoClip } from '@elah/core';
 export { createAudioClip } from '@elah/core';
 export { createTextClip } from '@elah/core';
 export { createImageClip } from '@elah/core';
+export { createShapeClip } from '@elah/core';
+export { createFreehandClip } from '@elah/core';
 export { splitClipAtPlayhead } from '@elah/core';
 export { framesToTimecode, secondsToFrames, framesToSeconds, getTotalFrames } from '@elah/core';
 export { generateId } from '@elah/core';
 export { transformFromCoverRect } from '@elah/core';
+export { snapFrame, buildSnapPoints, resolveOverlapEdgeSnap, clipsOverlap, DEFAULT_OVERLAP_TOLERANCE } from '@elah/core';
+export { serializeProject, deserializeProject } from '@elah/core';
 export { exportVideo } from '@elah/core';
 export { lazyExportVideo } from '@elah/core';
 export { Timeline } from '@elah/timeline';
+export { cn } from '@elah/timeline';
 export { useTimeline } from '@elah/timeline';
 export { useTracks } from '@elah/timeline';
 export { usePlayback } from '@elah/timeline';
@@ -30,7 +39,8 @@ export { useTimelineDrop } from '@elah/timeline';
 export { insertMediaAsset, insertElement } from '@elah/timeline';
 export { ELEMENT_DRAG_MIME } from '@elah/timeline';
 export { EditorProvider } from './editor/EditorProvider';
-export { useEditor, useTimelineEngine, usePlaybackEngine } from '@elah/core';
+export { EditorContext, useEditor, useTimelineEngine, usePlaybackEngine } from '@elah/react';
+export { useAudioMixer, useMasterVolume, useTrackLevels } from '@elah/react';
 export { useResolvedScene } from './editor/useResolvedScene';
 export { AssetPanel } from './editor/AssetPanel';
 export { ElementsPanel } from './editor/ElementsPanel';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elah/editor",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "Full React video editor SDK — timeline UI, WebGL2 preview, media library, drag and drop, and MP4 export",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,11 +55,13 @@
   "license": "Apache-2.0",
   "peerDependencies": {
     "react": ">=18.0.0",
-    "react-dom": ">=18.0.0"
+    "react-dom": ">=18.0.0",
+    "lucide-react": ">=0.400.0"
   },
   "dependencies": {
-    "@elah/core": "^0.3.0",
-    "@elah/timeline": "^0.3.0",
+    "@elah/core": "^0.4.1",
+    "@elah/react": "^0.4.1",
+    "@elah/timeline": "^0.4.1",
     "immer": "^10.1.1",
     "zustand": "^5.0.3"
   },
@@ -67,6 +69,7 @@
     "@types/react": "^18.3.18",
     "@types/react-dom": "^18.3.5",
     "autoprefixer": "^10.4.21",
+    "lucide-react": "^0.511.0",
     "postcss": "^8.5.3",
     "tailwindcss": "^3.4.17",
     "typescript": "^5.7.3",