@volcengine/amk-editor 0.0.2 → 0.0.3

package/README.md

@@ -65,7 +65,7 @@ editor.destroy();
 - 产物是单文件 ESM。依赖里的 AMD `define(["./core"])` 已在构建时剔除，避免 Next.js / webpack 误解析不存在的 `dist/core.js`。
 - `getHeaders` 可选，每次请求前都会重新调用；SDK 不解析、不缓存、不改写返回值，仅将其合并到发往 `endpoint` 的工程、素材、tools、tasks、导出等请求中。闭包内 Token 更新会自动用于下一次请求。
 - 本地上传、URL 导入由业务回调完成。返回的素材必须带业务主键 `source_material_id`，不必填写 `material_id`。
-- 播放地址、封面、雪碧图可能有时效。通过 `onRefreshPlayInfo` 返回新的访问地址。
+- 播放地址、封面、雪碧图可能有时效。通过 `onRefreshPlayInfo` 返回新的访问地址；补丁按 `material_id`、`source_material_id`、无标识时数组顺序依次匹配，未返回的字段保持原值。
 - 可选实现 `onMaterialsImported`：素材成功入库后回调已合并 `material_id` 的列表；可用于把新素材挂到对话草稿。失败或取消不会触发。
 - 可选实现 `onPersistExtractUrls`：把抽帧得到的临时地址转存为业务长期地址，并随 `materialPatch` 写回自定义存储字段。
 - 可选配置 `export.qualityEnhancement: true` 以在导出弹窗展示「视频画质增强」；默认不展示。

package/dist/amk-editor.d.ts

@@ -20,6 +20,8 @@ export declare class AmkEditor {
     private emptyTrackConfirmInFlight?;
     private readonly apiClient;
     private readonly ready;
+    private readonly bootstrapAbortController;
+    private destroyed;
     private projectName?;
     private editorRevision;
     private projectHydrated;
@@ -29,6 +31,11 @@ export declare class AmkEditor {
     private emptyTrackSaveBlocked;
     private savedMaterials;
     private saveQueue;
+    /** 最近一次 GET 或成功 PUT 后的服务端 editor 深比较基线。 */
+    private latestEditorFingerprint;
+    private latestEditorHasTrack;
+    /** 正在等待或执行的 editor 文档快照，用于合并高频重复事件。 */
+    private readonly pendingEditorSaveFingerprints;
     private projectRefreshInFlight?;
     private pendingSaveCount;
     private readonly asrPollingControllers;
@@ -65,6 +72,10 @@ export declare class AmkEditor {
     /** 所有 TOS 素材共用一个刷新定时器，避免按素材创建大量 timer。 */
     private tosSignedUrlRefreshTimer?;
     private tosSignedUrlRefreshInFlight?;
+    /** 同一轮播放地址刷新合并 materialId，并串行执行各批次，避免并发覆盖轨道和 revision。 */
+    private readonly pendingPlayInfoRefreshes;
+    private playInfoRefreshBatchScheduled;
+    private playInfoRefreshQueue;
     private readonly handleVisibilityChange;
     private readonly handleTrackChanged;
     private readonly handleEditParamChanged;
@@ -121,13 +132,19 @@ export declare class AmkEditor {
      * @param materialIdOrIds 单个 material_id、material_id 列表；省略则刷新当前全部有 material_id 的素材
      */
     refreshPlayInfo(materialIdOrIds?: string | string[]): Promise<MaterialItem | MaterialItem[] | undefined>;
+    private flushPlayInfoRefreshBatch;
     private refreshPlayInfoInternal;
+    /**
+     * 异步初始化入口：并行加载工程与预设，完成数据归一化后再挂载编辑器，
+     * 最后注册运行期的 URL 刷新和页面可见性监听。destroy() 可随时中断该流程。
+     */
     private bootstrap;
     /** 内置拉取工程：project + materials + editor → 归一化 → 组装 initialData。 */
     private resolveAndApplyProject;
     /**
      * 初始化时批量 refresh 素材（完整素材列表交给业务方），
-     * 再把轨道元素里的 URL 回填到最新值，完成后回写 editor 文档。
+     * 再把轨道元素里的 URL 回填到当前运行时。仅 UserData 变化不回写 editor 文档；
+     * Source 等真实协议字段变化时才保存。
      */
     private refreshProjectOnInit;
     /** TOS 私有桶签名刷新优先，宿主刷新回调随后可继续覆盖播放信息。 */
@@ -146,6 +163,7 @@ export declare class AmkEditor {
     mount(): VeVeditorInstance | undefined;
     private mountVeVeditor;
     destroy(): void;
+    private assertNotDestroyed;
     private resolveConfig;
     /** 与 VeVeditor 同一套顶层扁平资源字段：boolean 面板开关 + 内部 xgplayer 组装 */
     private resolveVeVeditorOptions;
@@ -158,6 +176,7 @@ export declare class AmkEditor {
      */
     private deleteMaterial;
     private queueEditorSave;
+    private setLatestEditorSnapshot;
     private confirmAbnormalEmptyTrackSave;
     private enqueueEditorSaveWithCurrentEditParam;
     /**

package/dist/api/preset-library.d.ts

@@ -10,4 +10,6 @@ export type PresetLibraryItem = {
     default?: boolean;
 };
 export type PresetLibrary = Partial<Record<PresetLibraryResourceKey, PresetLibraryItem[]>>;
-export declare function fetchPresetLibrary(client: Pick<AmkApiClient, 'requestJson'>, resources: PresetLibraryResourceKey[]): Promise<PresetLibrary>;
+export declare function fetchPresetLibrary(client: Pick<AmkApiClient, 'requestJson'>, resources: PresetLibraryResourceKey[], options?: {
+    signal?: AbortSignal;
+}): Promise<PresetLibrary>;

package/dist/api/project.d.ts

@@ -8,8 +8,12 @@ export type SavedAmkEditor = {
     revision: number;
     editParam: Record<string, unknown>;
 };
-export declare function fetchAmkProjectMaterials(client: EditingApiClient, projectId: string): Promise<MaterialItem[]>;
-export declare function fetchAmkProject(client: EditingApiClient, projectId: string): Promise<LoadedAmkProject>;
+export declare function fetchAmkProjectMaterials(client: EditingApiClient, projectId: string, options?: {
+    signal?: AbortSignal;
+}): Promise<MaterialItem[]>;
+export declare function fetchAmkProject(client: EditingApiClient, projectId: string, options?: {
+    signal?: AbortSignal;
+}): Promise<LoadedAmkProject>;
 export declare function updateAmkProjectName(client: EditingApiClient, projectId: string, projectName: string): Promise<void>;
 /**
  * POST 一批新素材到 AMK 工程。

package/dist/export-task-polling.d.ts

@@ -1,12 +1,15 @@
 import { type TaskPollingController } from './task-polling';
 export declare const EXPORT_TASK_POLL_INTERVAL_MS = 5000;
+export declare const EXPORT_TASK_VISIBLE_WINDOW_MS: number;
 export type ExportTaskPollingStatus = 'polling' | 'success' | 'failed';
 export declare function resolveExportTaskPollingStatus(payload: unknown): ExportTaskPollingStatus;
 export declare function resolveExportTaskProgress(payload: unknown): number | undefined;
 export declare function resolveExportTaskOutputUrl(payload: unknown): string | undefined;
+/** 服务端仍查最新 10 条，前端只展示提交时间位于最近 24 小时内的任务。 */
+export declare function filterRecentExportTasks<T extends Record<string, unknown>>(items: T[], now?: number): T[];
 export declare function startExportTaskPolling(options: {
     taskId: string;
     getTask: (taskId: string) => Promise<unknown>;
     onStatusChange: (status: ExportTaskPollingStatus, payload?: unknown) => void | Promise<void>;
-    onError?: (error: unknown) => void;
+    onError?: (error: unknown) => void | Promise<void>;
 }): TaskPollingController;

package/dist/header.d.ts

@@ -30,6 +30,8 @@ export type AmkExportTaskListItem = {
     name: string;
     format: 'mp4' | 'mp3';
     status: Exclude<AmkExportTaskStatus, 'idle'>;
+    /** 任务提交时间；历史任务来自任务列表接口的 submitted_at。 */
+    submittedAt?: string;
     /** 服务端返回的任务进度（0-100）；没有进度时使用不定长动画。 */
     progress?: number;
     /** 是否已在当前页面触发过浏览器下载。 */