@cut-workbench/core 0.3.1 → 0.4.1

package/dist/editor/create-editor.d.ts

@@ -6,119 +6,21 @@
  * - 暴露命令式 API（play / seek / addFiles / export / undo …）
  * - 通过事件总线对外广播状态变化
  *
- * 设计原则：命令直接调 store / runtime，**不**经过 React。这样：
+ * 设计原则：命令直接调 store / runtime，**不经过 React**。这样：
  * - `initCutWorkbench()` 这种非 React 接入方式可以完整操作编辑器；
  * - 事件总线成为唯一对外通知渠道，接入方不必知道内部 store 结构。
+ *
+ * 文件导入与导出会**懒加载**引擎的对应模块：宿主调 `addFiles()` / `export()`
+ * 时不需要自己写 `await import('@cut-workbench/core/engine')`。
  */
-import type { StoreApi } from 'zustand/vanilla';
-import type { MediaAsset, Project, TimelineClip } from '../types';
-import type { SerializedProject } from '../project/schema';
-import { type EditorState } from './editor-store';
-import { type HistoryStore } from './history-store';
 import { type EditorRuntime } from './runtime';
-import { type EventEmitterView } from './event-bus';
-import type { StoragePort } from '../project/storage';
-import type { HostBridge } from '../ports/host-bridge';
-/** 对外事件表。新增事件时必须同步更新此接口。 */
-export interface CutEventMap {
-    ready: {
-        editorId: string;
-    };
-    'project:changed': {
-        project: Project;
-        dirty: boolean;
-    };
-    'assets:changed': {
-        assets: MediaAsset[];
-    };
-    'selection:changed': {
-        clipIds: string[];
-        assetId: string | null;
-    };
-    'playhead:changed': {
-        us: number;
-        playing: boolean;
-    };
-    'history:changed': {
-        canUndo: boolean;
-        canRedo: boolean;
-    };
-    'export:start': {
-        totalUs: number;
-    };
-    'export:progress': {
-        progress: number;
-    };
-    'export:done': {
-        blob: Blob;
-        filename: string;
-    };
-    'export:error': {
-        message: string;
-    };
-    error: {
-        scope: string;
-        error: unknown;
-    };
-    dispose: Record<string, never>;
-}
-export interface EditorOptions {
-    /** 宿主桥；不传则使用浏览器内置实现 */
-    bridge?: HostBridge;
-    /** 工程持久化端口；不传则用内存实现（不落盘） */
-    storage?: StoragePort;
-    /** 持久化命名空间（多项目 / 多实例隔离） */
-    namespace?: string;
-    /** 初始工程 */
-    project?: Project;
-    /** 初始素材 */
-    assets?: MediaAsset[];
-    /** 首次初始化后是否自动从 storage 加载 */
-    autoLoad?: boolean;
-    /** 初始化时立即载入的文件 */
-    initialFiles?: File[];
-}
-export interface CutEditorHandle {
-    readonly id: string;
-    readonly store: StoreApi<EditorState>;
-    readonly history: HistoryStore;
-    readonly runtime: EditorRuntime;
-    readonly events: EventEmitterView<CutEventMap>;
-    readonly bridge: HostBridge;
-    readonly storage: StoragePort;
-    getProject(): Project;
-    getAssets(): MediaAsset[];
-    getState(): EditorState;
-    setProject(project: Project, assets: MediaAsset[], missingAssetIds?: string[]): void;
-    serialize(): SerializedProject;
-    load(project: SerializedProject | Project): Promise<void>;
-    save(): Promise<{
-        ok: boolean;
-        error?: string;
-    }>;
-    play(): void;
-    pause(): void;
-    toggle(): void;
-    seek(us: number): void;
-    getPlayhead(): number;
-    getDuration(): number;
-    isPlaying(): boolean;
-    undo(): void;
-    redo(): void;
-    addClip(clip: TimelineClip): void;
-    removeClips(ids: string[]): void;
-    selectClips(ids: string[]): void;
-    dispose(): Promise<void>;
-}
-export interface CreateEditorResult {
-    editor: CutEditorHandle;
-    /** 运行时的 WebAV 模块（懒加载完成后填充） */
-    engine: Promise<unknown> | null;
-}
+import type { AddFilesOptions, AddFilesResult, AddSubtitleAssetParams, AddTextAssetParams, AutoSaveOptions, CutEditorHandle, CutEventMap, EditorCommands, EditorOptions, ImportJsonOptions, ImportJsonResult, SaveAsResult } from './handle-types';
+export type { AddFilesOptions, AddFilesResult, AddSubtitleAssetParams, AddTextAssetParams, AutoSaveOptions, CutEditorHandle, CutEventMap, EditorCommands, EditorOptions, ImportJsonOptions, ImportJsonResult, SaveAsResult, };
+export type { EditorRuntime };
 /**
  * 创建编辑器实例。
  *
- * 不加载 WebAV：`engine` 子入口需要由调用方按需 `await import()`，因为 opfs-tools
+ * 不加载 WebAV：引擎模块在首次导入素材 / 导出时才动态加载 —— opfs-tools
  * 在模块加载期就会访问 `navigator.storage`，非 Chromium 环境会直接抛错。
  */
 export declare function createEditor(options?: EditorOptions): CutEditorHandle;

package/dist/editor/editor-store.d.ts

@@ -36,6 +36,10 @@ export interface EditorState {
     resetProject: () => void;
     renameProject: (name: string) => void;
     setProjectSize: (width: number, height: number, mode?: 'scale' | 'keep') => void;
+    /** 运行期改工程 id（宿主把临时工程归入某项目时用） */
+    setProjectId: (id: string) => void;
+    /** 整体替换「缺失素材」列表（importJson 补齐二进制后回写） */
+    setMissingAssetIds: (ids: string[]) => void;
     addAsset: (asset: MediaAsset) => void;
     clearMissing: (assetId: string) => void;
     replaceAsset: (assetId: string, next: MediaAsset) => void;

package/dist/editor/handle-types.d.ts

@@ -0,0 +1,256 @@
+/**
+ * 编辑器句柄的公开契约（纯类型）。
+ *
+ * 本文件只含 `import type`，因此可以被根入口安全导出：不会把 WebAV /
+ * 运行时拉进 `@cut-workbench/core` 的模块图，Node 环境 import 依旧无副作用。
+ */
+import type { StoreApi } from 'zustand/vanilla';
+import type { MediaAsset, Project, SubtitleStyle, TextStyle, TimelineClip, Track } from '../types';
+import type { SerializedProject } from '../project/schema';
+import type { StoragePort } from '../project/storage';
+import type { HostBridge, SaveFileResult } from '../ports/host-bridge';
+import type { CapabilityReport } from '../capability';
+import type { ExportHandle, ExportRequest, ExportResult } from '../export/types';
+import type { EditorState } from './editor-store';
+import type { HistoryStore } from './history-store';
+import type { EventEmitterView } from './event-bus';
+import type { EditorRuntime } from './runtime';
+/** 对外事件表。新增事件时必须同步更新此接口。 */
+export interface CutEventMap {
+    ready: {
+        editorId: string;
+    };
+    'project:changed': {
+        project: Project;
+        dirty: boolean;
+    };
+    'assets:changed': {
+        assets: MediaAsset[];
+    };
+    'selection:changed': {
+        clipIds: string[];
+        assetId: string | null;
+    };
+    'playhead:changed': {
+        us: number;
+        playing: boolean;
+    };
+    'history:changed': {
+        canUndo: boolean;
+        canRedo: boolean;
+    };
+    /** 工程结构变化（dirty 由 false → true 或反向） */
+    'project:dirty': {
+        dirty: boolean;
+    };
+    /** 保存完成（成功或失败）；`path` 是宿主存储给出的位置（若有） */
+    'project:saved': {
+        path?: string;
+        ok: boolean;
+        error?: string;
+    };
+    /** 工程载入完成；`missing` 是缺少二进制源的素材数 */
+    'project:loaded': {
+        project: Project;
+        assetCount: number;
+        missing: number;
+    };
+    'export:start': {
+        totalUs: number;
+        settings: import('../types').ExportSettings;
+    };
+    /** 0~1 */
+    'export:progress': {
+        progress: number;
+    };
+    /**
+     * 导出完成。
+     *
+     * `result` 是完整结果（宿主入库需要时长 / 尺寸 / 码率）。
+     * 顶层 `blob` / `filename` 是为兼容既有订阅方保留的**便捷副本**，会被新代码忽略。
+     */
+    'export:done': {
+        result: ExportResult;
+        blob: Blob;
+        filename: string;
+    };
+    'export:error': {
+        message: string;
+        error: unknown;
+    };
+    error: {
+        scope: string;
+        error: unknown;
+    };
+    dispose: Record<string, never>;
+}
+/** 自动保存：结构性变更后节流写入 */
+export interface AutoSaveOptions {
+    storage: StoragePort;
+    namespace: string;
+    /** 节流窗口，默认 2000ms */
+    intervalMs?: number;
+}
+export interface EditorOptions {
+    /** 宿主桥；不传则使用浏览器内置实现 */
+    bridge?: HostBridge;
+    /** 工程持久化端口；不传则用内存实现（不落盘） */
+    storage?: StoragePort;
+    /** 持久化命名空间（多项目 / 多实例隔离） */
+    namespace?: string;
+    /** 直接给一个完整工程 */
+    project?: Project;
+    /**
+     * 覆盖空工程的默认 id。宿主可用自己的项目 id，实现「一个项目一个剪辑工程」。
+     *
+     * 传了 `project` 时本字段被忽略（以工程自身的 id 为准）。
+     */
+    projectId?: string;
+    /** 初始素材元数据 */
+    assets?: MediaAsset[];
+    /** 自动保存；不传则不自动落盘 */
+    autoSave?: AutoSaveOptions;
+}
+export interface AddFilesOptions {
+    /** 导入成功后选中第一个素材；默认 true。批量预导入传 false，避免抢焦点 */
+    select?: boolean;
+    /** 逐文件进度：index 为入参数组下标，progress 为 0~1 */
+    onProgress?: (index: number, progress: number) => void;
+    /**
+     * 由宿主指定素材 id。返回 falsy 则回退到库生成的 `asset_xxx`。
+     * 用于宿主把自己的素材记录 id 作为 MediaAsset.id，实现「工程 ↔ 宿主库」一一对应。
+     */
+    idFor?: (file: File, index: number) => string | null | undefined;
+    /** 与缺失源文件的素材同名同类型时重连而非新增；默认 true */
+    reconnect?: boolean;
+}
+export interface AddFilesResult {
+    imported: MediaAsset[];
+    failures: Array<{
+        name: string;
+        error: string;
+    }>;
+    /** 其中走重连的数量 */
+    reconnected: number;
+}
+export interface AddTextAssetParams {
+    text: string;
+    style?: Partial<TextStyle>;
+    /** 素材默认时长（微秒）；缺省 5s */
+    durationUs?: number;
+}
+export interface AddSubtitleAssetParams {
+    srt: string;
+    style?: Partial<SubtitleStyle>;
+    /** 素材默认时长（微秒）；缺省取 SRT 最后一条字幕的结束时间 */
+    durationUs?: number;
+}
+export interface ImportJsonOptions {
+    /**
+     * 由宿主补齐二进制。返回 null 表示该素材缺失，进入 missingAssetIds。
+     */
+    resolveFile?: (asset: MediaAsset) => Promise<File | null>;
+}
+export interface ImportJsonResult {
+    missingAssetIds: string[];
+}
+export interface SaveAsResult {
+    ok: boolean;
+    path?: string;
+    error?: string;
+}
+/**
+ * 时间轴命令门面。
+ *
+ * 与 `CutEditorHandle` 上的同名方法完全等价，供宿主在「注入命令对象」的
+ * 场景（例如自己的快捷键表）里使用。
+ */
+export interface EditorCommands {
+    updateClip: (clipId: string, patch: Partial<TimelineClip>, recordHistory?: boolean, mergeKey?: string) => void;
+    moveClip: (clipId: string, trackId: string, startUs: number, recordHistory?: boolean) => void;
+    trimClip: (clipId: string, edge: 'start' | 'end', deltaUs: number, recordHistory?: boolean) => void;
+    splitClipsAt: (atUs: number, clipIds?: string[]) => string[];
+    duplicateSelection: (offsetUs: number) => Array<{
+        sourceId: string;
+        newId: string;
+    }>;
+    addTrack: (kind: Track['kind']) => string;
+    removeTrack: (trackId: string) => void;
+    updateTrack: (trackId: string, patch: Partial<Track>) => void;
+}
+export interface CutEditorHandle {
+    readonly id: string;
+    readonly store: StoreApi<EditorState>;
+    readonly history: HistoryStore;
+    readonly runtime: EditorRuntime;
+    readonly events: EventEmitterView<CutEventMap>;
+    readonly bridge: HostBridge;
+    readonly storage: StoragePort;
+    /** 时间轴命令门面（与下方同名方法等价） */
+    readonly commands: EditorCommands;
+    getProject(): Project;
+    getProjectId(): string;
+    /** 运行期改 id；会同步 emit `project:changed` */
+    setProjectId(id: string): void;
+    renameProject(name: string): void;
+    setProjectSize(width: number, height: number, mode?: 'scale' | 'keep'): void;
+    getAssets(): MediaAsset[];
+    getState(): EditorState;
+    setProject(project: Project, assets: MediaAsset[], missingAssetIds?: string[]): void;
+    serialize(): SerializedProject;
+    /** `serialize()` 的别名，语义更直白 */
+    exportJson(): SerializedProject;
+    /** 从 JSON / Project 恢复（不补齐二进制，缺源素材进入 missingAssetIds） */
+    load(input: SerializedProject | Project): Promise<void>;
+    /**
+     * 从 JSON 恢复，并由宿主补齐二进制。
+     * `resolveFile(asset)` 返回 null 表示该素材缺失，进入 missingAssetIds。
+     */
+    importJson(data: SerializedProject, options?: ImportJsonOptions): Promise<ImportJsonResult>;
+    save(): Promise<SaveAsResult>;
+    /** 换一个存储端口 / 命名空间保存，并把它设为后续 `save()` 的目标 */
+    saveAs(storage: StoragePort, namespace: string): Promise<SaveAsResult>;
+    isDirty(): boolean;
+    isEmpty(): boolean;
+    addFiles(files: File[], options?: AddFilesOptions): Promise<AddFilesResult>;
+    addTextAsset(params: AddTextAssetParams): Promise<MediaAsset>;
+    addSubtitleAsset(params: AddSubtitleAssetParams): Promise<MediaAsset>;
+    /** 为缺失源文件的素材补上文件（重新打开工程、按 id 找回本地文件后调用） */
+    reconnectAsset(assetId: string, file: File): Promise<void>;
+    getMissingAssetIds(): string[];
+    removeAsset(assetId: string): void;
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    seek(us: number): void;
+    getPlayhead(): number;
+    getDuration(): number;
+    isPlaying(): boolean;
+    undo(): void;
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    addClip(clip: TimelineClip): void;
+    removeClips(ids: string[]): void;
+    selectClips(ids: string[]): void;
+    getSelectedClipIds(): string[];
+    setSelection(clipIds: string[], assetId?: string | null): void;
+    updateClip(clipId: string, patch: Partial<TimelineClip>, recordHistory?: boolean, mergeKey?: string): void;
+    moveClip(clipId: string, trackId: string, startUs: number, recordHistory?: boolean): void;
+    trimClip(clipId: string, edge: 'start' | 'end', deltaUs: number, recordHistory?: boolean): void;
+    splitClipsAt(atUs: number, clipIds?: string[]): string[];
+    duplicateSelection(offsetUs: number): Array<{
+        sourceId: string;
+        newId: string;
+    }>;
+    addTrack(kind: Track['kind']): string;
+    removeTrack(trackId: string): void;
+    updateTrack(trackId: string, patch: Partial<Track>): void;
+    /** 启动导出；内部优先 Worker，不可用时回退主线程 */
+    export(request?: ExportRequest): ExportHandle;
+    /** 把导出结果交给宿主落盘（`bridge.files.saveBlob`） */
+    saveExport(result: ExportResult, suggestedName?: string): Promise<SaveFileResult>;
+    /** 能力探测结果（首次调用后缓存） */
+    getCapabilities(): Promise<CapabilityReport>;
+    dispose(): Promise<void>;
+}