@cut-workbench/core 0.3.0 → 0.4.0

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>;
+}