melies-video-editor 0.1.4 → 0.1.6

package/dist/types/App.d.ts

@@ -1,4 +1,6 @@
 import './index.less';
+import type { CusTomTimelineRow } from './mock';
+import type { FootageItem } from './footageBin';
 export type MeliesVideoEditorProps = {
     /**
      * URLs (often blob: URLs) to show in the footage bin.
@@ -28,6 +30,73 @@ export type MeliesVideoEditorProps = {
      * Defaults to false.
      */
     autoPlaceFootage?: boolean;
+    /**
+     * Optional initial timeline snapshot (e.g. loaded from your DB).
+     *
+     * Note: if you store `blob:` URLs in the snapshot, they will not be valid across sessions.
+     * Prefer storing stable asset ids and rehydrating to playable URLs before loading.
+     */
+    initialTimelineSnapshot?: MeliesTimelineSnapshot;
+    /**
+     * Called whenever timeline state changes.
+     *
+     * Consumers should debounce/throttle this callback when persisting to a DB.
+     */
+    onTimelineStateChange?: (snapshot: MeliesTimelineSnapshot) => void;
+    /**
+     * Fired when the user imports files into the footage bin.
+     *
+     * This exposes the actual `File` objects to the host app (for upload/OPFS/storage).
+     * Note: imported `blob:` URLs are session-only; hosts should persist and rehydrate using
+     * stable asset identifiers if they need cross-session restore.
+     */
+    onFootageImported?: (event: MeliesFootageImportEvent) => void;
+};
+export type MeliesFootageImportEntry = {
+    /** The bin item added to the footage bin. */
+    item: FootageItem;
+    /** The underlying file selected by the user. */
+    file: File;
+};
+export type MeliesFootageImportEvent = {
+    /** Pairs each created bin item to its underlying file. */
+    entries: MeliesFootageImportEntry[];
+    /** Convenience list of items. */
+    items: FootageItem[];
+    /** Convenience list of files. */
+    files: File[];
+};
+export type MeliesTimelineSnapshot = {
+    /** Bump this when snapshot schema changes. */
+    version: 1;
+    /** Timeline rows/actions data (seconds). */
+    editorData: CusTomTimelineRow[];
+    /** UI selection (optional to restore). */
+    selectedActionId: string | null;
+    /** UI zoom (optional to restore). */
+    timelineScaleWidth: number;
+};
+export type MeliesVideoEditorRef = {
+    /**
+     * Get a deep-cloned snapshot of the current timeline state.
+     * Safe to store/mutate externally.
+     */
+    getTimelineSnapshot: () => MeliesTimelineSnapshot;
+    /**
+     * Load a snapshot into the editor.
+     * Resets undo/redo history.
+     */
+    setTimelineSnapshot: (snapshot: MeliesTimelineSnapshot) => void;
+    /**
+     * Get the imported `File` for a given footage item id (only for user-imported items).
+     * Returns null if the id was not imported this session.
+     */
+    getImportedFileByFootageId: (footageId: string) => File | null;
+    /** List all imported files currently known to the editor (this session). */
+    listImportedFiles: () => Array<{
+        footageId: string;
+        file: File;
+    }>;
 };
-declare const MeliesVideoEditor: ({ footageUrls, footageFiles, footageFileHandles, autoPlaceFootage, }: MeliesVideoEditorProps) => import("react/jsx-runtime").JSX.Element;
+declare const MeliesVideoEditor: import("react").ForwardRefExoticComponent<MeliesVideoEditorProps & import("react").RefAttributes<MeliesVideoEditorRef>>;
 export default MeliesVideoEditor;

package/dist/types/appVersion.d.ts

@@ -0,0 +1,2 @@
+/** Compile-time version string injected by Vite (from package.json). */
+export declare const APP_VERSION: string;

package/dist/types/dev/DevRoot.d.ts

@@ -1,3 +1,4 @@
+import './devRoot.css';
 export default function DevRoot({ defaultFootageUrls, useHostShell, }: {
     defaultFootageUrls?: string[];
     useHostShell: boolean;

package/dist/types/{services → dev}/opfs.d.ts

@@ -1,37 +1,35 @@
-export type OpfsRoot = FileSystemDirectoryHandle;
-export declare const ensureOpfsRoot: () => Promise<OpfsRoot>;
-export declare const ensureDir: (root: OpfsRoot, path: string) => Promise<FileSystemDirectoryHandle>;
+type OpfsRoot = FileSystemDirectoryHandle;
+type Maybe<T> = T | null | undefined;
+export type OpfsSupport = {
+    supported: boolean;
+    reason?: string;
+};
 /**
- * Writes a Blob or File to OPFS.
- * Uses createWritable() which is the standard async way to write.
+ * Best-effort OPFS capability check.
+ *
+ * Notes:
+ * - Many browsers require a secure context (HTTPS); desktop browsers often treat localhost as secure.
+ * - Some mobile browsers may not implement OPFS at all.
  */
-export declare const writeFileToOpfs: (opts: {
+export declare const getOpfsSupport: () => OpfsSupport;
+export declare const ensureOpfsRoot: () => Promise<OpfsRoot>;
+export declare const ensureDir: (root: OpfsRoot, path: string) => Promise<FileSystemDirectoryHandle>;
+export declare const writeBlobToOpfs: (opts: {
     root: OpfsRoot;
     dirPath: string;
     fileName: string;
-    file: Blob | File;
+    blob: Blob;
 }) => Promise<{
     fileHandle: FileSystemFileHandle;
     path: string;
 }>;
-export declare const getOpfsFile: (path: string) => Promise<File | undefined>;
-export declare const listFiles: (opts: {
-    root: OpfsRoot;
-    dirPath: string;
-}) => Promise<FileSystemFileHandle[]>;
 export declare const clearDir: (opts: {
     root: OpfsRoot;
     dirPath: string;
 }) => Promise<void>;
-type Maybe<T> = T | null | undefined;
-export declare const getFileFromPublicUrl: (url: string, fallbackName?: Maybe<string>) => Promise<File>;
-export declare const writeBlobToOpfs: (opts: {
+export declare const listFiles: (opts: {
     root: OpfsRoot;
     dirPath: string;
-    fileName: string;
-    blob: Blob;
-}) => Promise<{
-    fileHandle: FileSystemFileHandle;
-    path: string;
-}>;
+}) => Promise<FileSystemFileHandle[]>;
+export declare const getFileFromPublicUrl: (url: string, fallbackName?: Maybe<string>) => Promise<File>;
 export {};

package/dist/types/lib/index.d.ts

@@ -1,3 +1,3 @@
 export { default as MeliesVideoEditor } from '../App';
-export type { MeliesVideoEditorProps } from '../App';
+export type { MeliesFootageImportEntry, MeliesFootageImportEvent, MeliesTimelineSnapshot, MeliesVideoEditorProps, MeliesVideoEditorRef, } from '../App';
 export type { TimelineAction, TimelineEffect, TimelineRow, TimelineState, } from '@xzdarcy/react-timeline-editor';

package/dist/types/mediaCache.d.ts

@@ -1,30 +1,11 @@
 type MediaKind = 'video' | 'audio' | 'other';
-export type ProxyEvent = {
-    type: 'proxy-start';
-    originalSrc: string;
-} | {
-    type: 'proxy-progress';
-    originalSrc: string;
-    value?: number;
-    status?: string;
-} | {
-    type: 'proxy-ready';
-    originalSrc: string;
-    proxySrc: string;
-} | {
-    type: 'proxy-failed';
-    originalSrc: string;
-    error: string;
-};
 declare const guessKind: (src: string) => MediaKind;
 declare class MediaCache {
     private blobUrlBySrc;
     private pendingBySrc;
     private metaBySrc;
-    private proxyEventListeners;
-    /** Subscribe to proxy generation events (useful for UI debug on mobile where console logs aren't visible). */
-    onProxyEvent(listener: (event: ProxyEvent) => void): () => void;
-    private emitProxyEvent;
+    private durationSecBySrc;
+    private pendingDurationBySrc;
     registerSrcMeta(src: string, meta: {
         name?: string;
         mimeType?: string;
@@ -33,24 +14,13 @@ declare class MediaCache {
         name?: string;
         mimeType?: string;
     } | undefined;
+    /** Returns the cached duration (seconds) if known. */
+    getCachedDurationSec(src: string): number | undefined;
     /**
-     * Ingests a File object into OPFS.
-     * Returns a virtual 'opfs://' URL that can be used as a src reference.
+     * Attempts to read media duration from browser metadata (seconds).
+     * Returns null when duration cannot be determined (e.g. unsupported/CORS/streaming).
      */
-    ingest(file: File): Promise<string>;
-    private initProxy;
-    /**
-     * Returns a URL that is safe to assign to a media element (`<video>`/`<audio>`).
-     *
-     * Notes:
-     * - `opfs://...` is NOT directly playable by browsers.
-     * - For OPFS sources, this will kick off an async preload (creating a `blob:` URL) and return `undefined`.
-     */
-    resolveForMediaElement(src: string): string | undefined;
-    /**
-     * Helper to fetch a file from OPFS given an opfs:// URL
-     */
-    getFileFromOpfs(opfsUrl: string): Promise<File | undefined>;
+    getDurationSec(src: string, kindHint?: MediaKind): Promise<number | null>;
     /**
      * Preloads a URL into memory and returns a blob: URL.
      * Useful to avoid runtime buffering/stalls when seeking frequently.

package/dist/types/videoControl.d.ts

@@ -66,6 +66,26 @@ declare class VideoControl {
     warm(src: string): void;
     releaseVideo(_actionId: string): void;
     setActive(_active: boolean): void;
+    /**
+     * Returns the active (visible) video element, if any.
+     * Useful for UI-level logic that needs to wait for buffering after a seek.
+     */
+    getActiveVideoElement(): HTMLVideoElement | null;
+    /**
+     * Checks whether a video has at least `minSecondsAhead` buffered at its current time.
+     *
+     * Note: buffered ranges are in media time, not timeline time.
+     */
+    private hasBufferedAhead;
+    /**
+     * Waits until the active element appears ready for smooth playback after a seek.
+     * Returns true if the readiness criteria is met before timing out.
+     */
+    waitForActiveBufferedAhead(opts?: {
+        minSecondsAhead?: number;
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<boolean>;
 }
 declare const _default: VideoControl;
 export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "melies-video-editor",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "A React video timeline editor GUI built on @xzdarcy/react-timeline-editor.",
   "type": "module",
   "license": "MIT",

package/dist/types/services/proxyManager.d.ts

@@ -1,19 +0,0 @@
-declare class ProxyManager {
-    private activeJobs;
-    /**
-     * Create (or reuse) a proxy file for an OPFS video.
-     *
-     * `originalOpfsPath` should be an `opfs://...` URL.
-     */
-    createProxy(originalOpfsPath: string, opts?: {
-        onProgress?: (info: {
-            value?: number;
-            status?: string;
-        }) => void;
-    }): Promise<string>;
-    private _runWorker;
-    private getHandle;
-    private ensureDir;
-}
-export declare const proxyManager: ProxyManager;
-export {};

package/dist/types/workers/proxyWorker.d.ts

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