@volcengine/amk-editor 0.0.5-beta.0 → 0.0.5

package/README.md

@@ -1,5 +1,12 @@
 # @volcengine/amk-editor
 火山引擎 AI MediaKit 官方 Web 视频编辑器 SDK。
+## 获取当前合成画面
+```ts
+await amkEditor.whenReady();
+const image = amkEditor.getEditor()?.getFrame?.({ type: 'image/png' });
+```
+`getFrame({ type?, quality? })` 透传底层画布截图，返回 data URL；画布未初始化时返回 `null`。native 渲染模式不支持此方法，会抛出底层异常。此方法不等待跳转或渲染完成，调用方需确保目标画面已就绪。
+
 ## 安装
 ```bash
 npm install @volcengine/amk-editor
@@ -19,9 +26,10 @@ const editor = new AmkEditor({
     'X-Customer-Id': 'your-customer-id',
   }),
   material: {
-    onUploadMaterial: async files => {
-      // 上传到业务存储后返回素材列表，每项必须带 source_material_id
-      return [];
+    onUploadFile: async file => {
+      // 只上传一个文件并返回一条素材，必须带 source_material_id。
+      // 多选的并发调度、占位卡和每项完成后的立即入库由 SDK 处理。
+      return uploadOneFile(file);
     },
     onUploadUrlMaterial: async urls => {
       return [];
@@ -67,7 +75,7 @@ editor.destroy();
 - `theme` 默认 `light`。未传或传入其他值时按浅色渲染；只有显式 `theme: 'dark'` 才走暗色。
 - 产物是面向浏览器的单文件 ESM。依赖里的 AMD `define(["./core"])`、`define(["dayjs"])` 和 Node `require('crypto')` 兜底已在构建时剔除或中和，避免 Next.js / webpack / Rspack 误解析依赖或报告动态 require 警告；浏览器加密仍使用 Web Crypto。
 - `getHeaders` 可选，每次请求前都会重新调用；SDK 不解析、不缓存、不改写返回值，仅将其合并到发往 `endpoint` 的工程、素材、tools、tasks、导出等请求中。闭包内 Token 更新会自动用于下一次请求。
-- 本地上传、URL 导入由业务回调完成。返回的素材必须带业务主键 `source_material_id`，不必填写 `material_id`。
+- 本地上传通过 `onUploadFile(file)` 实现单文件上传；SDK 负责多文件并发、逐项入库和部分失败收口。旧 `onUploadMaterial(files)` 仍兼容，但只能整批完成后入库。URL 导入仍由 `onUploadUrlMaterial` 完成。返回素材必须带业务主键 `source_material_id`，不必填写 `material_id`。
 - 播放地址、封面、雪碧图可能有时效。通过 `onRefreshPlayInfo` 返回新的访问地址；补丁按 `material_id`、`source_material_id`、无标识时数组顺序依次匹配，未返回的字段保持原值。
 - 可选实现 `onMaterialsImported`：素材成功入库后回调已合并 `material_id` 的列表；可用于把新素材挂到对话草稿。失败或取消不会触发。
 - 可选实现 `onPersistExtractUrls`：把抽帧得到的临时地址转存为业务长期地址，并随 `materialPatch` 写回自定义存储字段。
@@ -79,6 +87,9 @@ editor.destroy();
 - `updateTitle(title)` 复用顶栏标题保存链路：先 PATCH 工程名，成功后更新编辑器标题/工程快照并触发 `header.onTitleUpdateSuccess`；校验失败或保存失败会 reject，且不会触发成功回调。
 - `toolbar.customItems` 的只读态不会自动置灰。需要禁用时在该项 `disabled({ readonly })` 里自行返回 true（例如 `disabled: ({ readonly }) => readonly`）。录音中仍会全局锁定自定义项。内置 ASR 按钮在只读时仍会禁用。
 - `refreshProject()` 会等待当前保存队列结束，再重新拉取工程、刷新临时播放地址并热更新素材与 Track；远端 Track 不会写入本地撤销历史，也不会被自动保存回服务端。
+- `whenReady()` 完成后会每 5 秒拉取一次 Editing 工程；服务端 `editor.revision` 高于当前版本，或素材数量 / 素材 ID 集合发生变化时，都会复用 `refreshProject()` 的无撤销热更新链路。素材 ID 优先使用 `material_id`，缺失时回退 `source_material_id`，仅返回顺序变化不会触发刷新。页面进入后台时暂停轮询，重新可见后立即检查一次，`destroy()` 会停止后续轮询。相同 ID 的素材字段更新或纯标题变更仍需宿主主动调用 `refreshProject()`。
+- 轮询会额外检查相同素材后补的封面和雪碧图：当前页面对应字段为空且服务端已返回有效链接时，仅刷新素材面板展示，不重建 Track，也不调用素材或 editor 保存；当前页面已有链接时保持不变。其他相同 ID 的素材字段变化仍不会触发热更新。
+- 素材同步兼容尚未产生轨道的空工程：服务端 `editor.document` 为 `{}`、缺少 `Track` 时按空轨道处理，不会阻断新素材写入面板；显式返回非数组 `Track` 仍视为非法工程数据。
 - `getTask(taskId, options?)` 查询 `GET /api/v1/tasks/{task_id}`，复用编辑器初始化时的 `endpoint` 与 `getHeaders`；`options.signal` 可在宿主任务卡卸载时取消轮询请求。
 - 配置 `projectId` 后，API Client 会把 `invokeTool`、`invokeSyncTool` 的成功响应以及 `getTask` 的轮询结果，以 schema v2 best-effort 上报到 `POST /api/v1/editing/projects/{project_id}/tasks`。记录包含 `task_id`、`tool_name`、同步/异步模式、状态、原始请求和响应；台账写入失败只输出 warning，不会让已经成功的 AMK 调用失败。轮询上报会省略 `request.input`，避免覆盖首次提交保存的请求参数。
 - mediakit-studio `dev` 当前只提供上述任务台账写接口，尚无任务列表/详情 GET 接口。因此编辑器顶栏的导出记录仍只保留当前页面会话；如需刷新后读取历史导出列表，需要服务端补充按工程查询任务的接口。

package/dist/amk-editor.d.ts

@@ -39,11 +39,17 @@ export declare class AmkEditor {
     private saveQueue;
     /** 初始化 URL refresh 的远端回写；允许先挂载 UI，但 whenReady 仍等待它完成。 */
     private bootstrapRefreshSync;
+    /** 非轨道素材刷新必须在 VeVeditor 挂载后才启动，避免继续阻塞预览首帧。 */
+    private bootstrapRemainingMaterialRefresh?;
+    /** 初始化素材播放地址是否刷新成功；失败时禁止用工程旧 URL 新建抽帧任务。 */
+    private bootstrapMaterialRefreshSucceeded;
     /** 最近一次 GET 或成功 PUT 后的服务端 editor 深比较基线。 */
     private latestEditorFingerprint;
     private latestEditorHasTrack;
     /** 正在等待或执行的 editor 文档快照，用于合并高频重复事件。 */
     private readonly pendingEditorSaveFingerprints;
+    /** 完整工程与轻量 editor 刷新共用队列，保证后发请求最后应用。 */
+    private runtimeRefreshQueue;
     private projectRefreshInFlight?;
     private editParamRefreshInFlight?;
     private pendingSaveCount;
@@ -55,8 +61,12 @@ export declare class AmkEditor {
     /** sprite 抽帧任务轮询：key = material_id / source */
     private readonly spritePollingControllers;
     private readonly posterPollingControllers;
+    /** 同一素材的抽帧检查共享一条 Promise，避免初始化与热刷新重复建任务。 */
+    private readonly materialExtractInFlight;
     /** TOS 上传完成前的素材面板占位：key = source_material_id。 */
     private readonly tosUploadPlaceholders;
+    /** URL 上传完成前的素材面板占位：按本次导入批次暂存占位卡片 id。 */
+    private readonly urlUploadPlaceholders;
     /** 同一素材的封面/雪碧图转存结果串行写回，避免自定义字段互相覆盖。 */
     private readonly materialPatchQueues;
     /** 等待批量落盘的素材；同一素材在窗口内只保留合并后的最新状态。 */
@@ -148,6 +158,7 @@ export declare class AmkEditor {
      * 不请求或替换工程名称、素材列表，适合 Agent 运行过程中的轻量预览刷新。
      */
     refreshEditParam(): Promise<Record<string, unknown>>;
+    private enqueueRuntimeRefresh;
     private refreshEditParamFromServer;
     private refreshProjectFromServer;
     /**
@@ -168,16 +179,21 @@ export declare class AmkEditor {
     /** 内置拉取工程：project + materials + editor → 归一化 → 组装 initialData。 */
     private resolveAndApplyProject;
     /**
-     * 初始化时批量 refresh 素材（完整素材列表交给业务方），
+     * 初始化时批量 refresh 指定素材（未指定时保持全量刷新），
      * 再把轨道元素里的 URL 回填到当前运行时。UserData 与素材媒体 HTTP Source
      * 的变化都不作为主动回写 editor 文档的理由；其他剪辑变化保存时可附带最新 Source。
      */
     private refreshProjectOnInit;
+    /**
+     * 首屏编辑器已经挂载后再刷新非轨道素材。刷新成功先热更新素材面板，
+     * 再后台持久化；失败只保留旧地址，不影响预览与 whenReady 收敛。
+     */
+    private refreshRemainingMaterialsOnInit;
     /** TOS 私有桶签名刷新优先，宿主刷新回调随后可继续覆盖播放信息。 */
     private refreshMaterialTargets;
     /**
      * 将重签后的素材 URL 按 material_id 同步到轨道节点并重建媒体节点。
-     * URL 是运行时数据：保存工程，但不产生撤销步骤。
+     * URL 是运行时数据：只更新 SDK 内存与渲染节点，不主动保存工程，也不产生撤销步骤。
      */
     private applyTrackMaterialUrls;
     private resolveTosSignedResourceUrls;
@@ -253,15 +269,26 @@ export declare class AmkEditor {
     private startAsrTask;
     private resolveLocalFileType;
     private createTosUploadPlaceholder;
+    private createUrlUploadPlaceholder;
+    private removeUrlUploadPlaceholders;
     /** 资产库选中后立即展示 0% 上传占位卡片，写入素材库成功后再切换为完成态。 */
     private addSystemTosImportPlaceholders;
     private removeTosUploadPlaceholders;
     private hasTosUploadPlaceholders;
-    private uploadTosMaterials;
+    private uploadFileWithPlaceholder;
+    private uploadCustomFile;
+    private uploadTosFile;
     private extractToolResult;
     private requirePositiveNumber;
     private waitForToolTask;
     private probeAsyncMetadata;
+    private resolveMetadataProbeUrl;
+    private isPositiveNumber;
+    /**
+     * 自定义本地 / URL / 资产库导入的统一元信息兜底。
+     * 只探测当前缺失的必需字段，业务已经返回的合法值保持不变。
+     */
+    private ensureImportedMaterialMetadata;
     private prepareTosMaterial;
     /** 将业务资产库的原始条目归一化为 SDK 素材；TOS 地址随后由 SDK 自行签发。 */
     private normalizeSystemMaterial;
@@ -329,6 +356,9 @@ export declare class AmkEditor {
      * - enableThumbnailDecode=true：跳过 sprite 接口，轨道缩略图走前端解码
      */
     private ensureMaterialExtractTasks;
+    private ensureMaterialExtractTasksUnchecked;
+    private ensureTrackMaterialExtractTasks;
+    private ensureMaterialExtractTasksInBackground;
     private createExtractFramesTask;
     /** AMK 转存到私有 TOS 后，任务产物需先重签才能用于浏览器预览。 */
     private signTaskOutputUrls;

package/dist/amk-modal.d.ts

@@ -9,5 +9,8 @@ export interface AmkModalProps {
     onCancel: () => void;
     children: React.ReactNode;
 }
-/** AMK 弹窗统一使用 VEVEditor 已采用的组件库 Modal。 */
-export declare function AmkModal({ visible, className, width, popupContainer, ariaLabelledBy, ariaDescribedBy, onCancel, children, }: AmkModalProps): React.ReactElement;
+/**
+ * AMK 弹窗只复用 VEVEditor 的样式类，避免旧 Modal 运行时依赖 React 19
+ * 已移除的 ReactDOM.findDOMNode。
+ */
+export declare function AmkModal({ visible, className, width, popupContainer, ariaLabelledBy, ariaDescribedBy, onCancel, children, }: AmkModalProps): React.ReactPortal | null;

package/dist/assets/export-empty-dark.svg

@@ -0,0 +1,66 @@
+<svg width="64" height="64" viewBox="0 0 64 64" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g id="&#229;&#175;&#188;&#229;&#135;&#186;&#231;&#138;&#182;&#230;&#128;&#129;">
+<rect width="1139" height="1236" transform="translate(-871 -767)" fill="white"/>
+<g id="&#228;&#184;&#139;&#230;&#139;&#137;&#232;&#143;&#156;&#229;&#141;&#149; Dropdown" filter="url(#filter0_dd_1024_104309)">
+<path d="M-168 -25C-168 -31.6274 -162.627 -37 -156 -37H220C226.627 -37 232 -31.6274 232 -25V167C232 173.627 226.627 179 220 179H-156C-162.627 179 -168 173.627 -168 167V-25Z" fill="#131418"/>
+<path d="M-156 -36.75H220C226.489 -36.75 231.75 -31.4893 231.75 -25V167C231.75 173.489 226.489 178.75 220 178.75H-156C-162.489 178.75 -167.75 173.489 -167.75 167V-25L-167.746 -25.3037C-167.585 -31.6527 -162.388 -36.75 -156 -36.75Z" stroke="#EAEDF1" stroke-width="0.5"/>
+<g id="Frame 2147241402">
+<g id="&#231;&#169;&#186;&#231;&#138;&#182;&#230;&#128;&#129; Empty">
+<g id="_components_Empty pic">
+<g id="Empty pic_pic2">
+<g id="Container">
+<path id="Ellipse 749" d="M6.84329 17.3592C6.20417 18.4662 6.23008 19.9317 6.89953 21.6778C7.56814 23.4215 8.86444 25.4067 10.6956 27.5072C14.3562 31.7065 20.1151 36.3262 27.1053 40.362C34.0955 44.3979 40.9757 47.0753 46.4428 48.1459C49.1775 48.6814 51.5448 48.8115 53.3892 48.5186C55.2361 48.2253 56.5182 47.515 57.1573 46.408C57.7962 45.3011 57.77 43.8362 57.1006 42.0903C56.432 40.3465 55.1357 38.3614 53.3046 36.2609C49.6439 32.0616 43.8851 27.4419 36.8948 23.406C29.9046 19.3702 23.0244 16.6928 17.5574 15.6222C14.8227 15.0867 12.4554 14.9566 10.611 15.2494C8.76428 15.5427 7.48249 16.2524 6.84329 17.3592Z" stroke="white" stroke-width="0.509631"/>
+<g id="Container_2">
+<circle id="Ellipse 753" cx="30.9869" cy="32.3837" r="17.5644" fill="#131418" stroke="white" stroke-width="0.675556"/>
+<g id="Subtract" style="mix-blend-mode:darken">
+<path d="M30.9863 14.4814C40.8735 14.4815 48.8887 22.4966 48.8887 32.3838C48.8887 41.9954 41.3141 49.8358 31.8086 50.2656C39.92 49.1992 46.1816 42.2609 46.1816 33.8584C46.1816 24.7177 38.7715 17.3079 29.6309 17.3076C20.7552 17.3076 13.5106 24.2938 13.0977 33.0674C13.0891 32.8406 13.084 32.6127 13.084 32.3838C13.084 22.4966 21.0991 14.4814 30.9863 14.4814Z" fill="white" fill-opacity="0.2"/>
+<path d="M30.9863 14.4814C40.8735 14.4815 48.8887 22.4966 48.8887 32.3838C48.8887 41.9954 41.3141 49.8358 31.8086 50.2656C39.92 49.1992 46.1816 42.2609 46.1816 33.8584C46.1816 24.7177 38.7715 17.3079 29.6309 17.3076C20.7552 17.3076 13.5106 24.2938 13.0977 33.0674C13.0891 32.8406 13.084 32.6127 13.084 32.3838C13.084 22.4966 21.0991 14.4814 30.9863 14.4814Z" fill="url(#paint0_linear_1024_104309)"/>
+</g>
+<path id="Ellipse 751" d="M41.4578 33.5289C41.4578 27.1862 36.3161 22.0444 29.9734 22.0444" stroke="white" stroke-width="0.509631"/>
+</g>
+<path id="Ellipse 750" d="M57.2273 46.2809C54.4778 51.0431 40.8937 48.346 27.0005 40.3248C13.1073 32.3035 4.08814 22.1216 6.83756 17.3595" stroke="white" stroke-width="0.509631"/>
+<g id="&#228;&#186;&#174;&#230;&#152;&#159;&#230;&#152;&#159; 2" clip-path="url(#clip0_1024_104309)">
+<path id="Vector" d="M59.0151 16.0637C59.2605 16.827 59.6738 17.5321 60.2319 18.1243L60.2368 18.1301L60.2427 18.136C60.8368 18.6956 61.5445 19.1093 62.3101 19.3547C61.5459 19.6008 60.8392 20.0136 60.2437 20.5696L60.2368 20.5754L60.231 20.5813C59.6773 21.1724 59.2655 21.8746 59.019 22.634C58.774 21.866 58.3598 21.1557 57.7993 20.5598L57.7935 20.5549L57.7876 20.5491C57.1982 19.9948 56.4972 19.5838 55.7388 19.3391C56.5028 19.0935 57.2092 18.6801 57.8022 18.1213L57.814 18.1096C58.3641 17.5201 58.7719 16.8202 59.0151 16.0637Z" stroke="white" stroke-width="0.513422"/>
+</g>
+<g id="&#228;&#186;&#174;&#230;&#152;&#159;&#230;&#152;&#159; 3" clip-path="url(#clip1_1024_104309)">
+<path id="Vector_2" d="M48.2107 10.3486C48.3581 10.6939 48.5662 11.0136 48.8279 11.291L48.8328 11.2969L48.8386 11.3018C49.1163 11.5631 49.4358 11.7707 49.781 11.918C49.4364 12.0651 49.1169 12.2726 48.8386 12.5322L48.8269 12.5439C48.5681 12.82 48.3617 13.1372 48.2146 13.4795C48.0671 13.1323 47.8592 12.8103 47.5964 12.5312L47.5906 12.5264L47.5847 12.5205C47.3089 12.2614 46.9917 12.0557 46.6492 11.9092C46.9948 11.7618 47.3156 11.5556 47.5935 11.2939L47.6052 11.2822C47.8624 11.0068 48.065 10.6898 48.2107 10.3486Z" stroke="white" stroke-width="0.513422"/>
+</g>
+</g>
+</g>
+</g>
+</g>
+</g>
+</g>
+</g>
+<defs>
+<filter id="filter0_dd_1024_104309" x="-193" y="-58" width="450" height="266" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+<feFlood flood-opacity="0" result="BackgroundImageFix"/>
+<feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/>
+<feMorphology radius="2" operator="erode" in="SourceAlpha" result="effect1_dropShadow_1024_104309"/>
+<feOffset dy="2"/>
+<feGaussianBlur stdDeviation="2"/>
+<feColorMatrix type="matrix" values="0 0 0 0 0.0627451 0 0 0 0 0.0627451 0 0 0 0 0.0745098 0 0 0 0.05 0"/>
+<feBlend mode="normal" in2="BackgroundImageFix" result="effect1_dropShadow_1024_104309"/>
+<feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/>
+<feMorphology radius="1" operator="erode" in="SourceAlpha" result="effect2_dropShadow_1024_104309"/>
+<feOffset dy="4"/>
+<feGaussianBlur stdDeviation="13"/>
+<feColorMatrix type="matrix" values="0 0 0 0 0.0627451 0 0 0 0 0.0627451 0 0 0 0 0.0745098 0 0 0 0.05 0"/>
+<feBlend mode="normal" in2="effect1_dropShadow_1024_104309" result="effect2_dropShadow_1024_104309"/>
+<feBlend mode="normal" in="SourceGraphic" in2="effect2_dropShadow_1024_104309" result="shape"/>
+</filter>
+<linearGradient id="paint0_linear_1024_104309" x1="9.38005" y1="25.4664" x2="49.064" y2="25.4804" gradientUnits="userSpaceOnUse">
+<stop offset="0.298077" stop-color="#0066FF"/>
+<stop offset="0.710478" stop-color="#916DF5"/>
+<stop offset="0.785044" stop-color="#FF8C45"/>
+<stop offset="0.845261" stop-color="#FFD025"/>
+<stop offset="0.980769" stop-color="#006CFF"/>
+</linearGradient>
+<clipPath id="clip0_1024_104309">
+<rect width="8.10667" height="8.10667" fill="white" transform="translate(54.2935 15.9646)"/>
+</clipPath>
+<clipPath id="clip1_1024_104309">
+<rect width="5.40444" height="5.40444" fill="white" transform="translate(45.5112 9.20898)"/>
+</clipPath>
+</defs>
+</svg>

package/dist/header.d.ts

@@ -9,6 +9,8 @@ export interface CreateAmkEditorLayoutOptions {
     title: string;
     theme?: 'light' | 'dark';
     showHeader: boolean;
+    /** 是否展示项目初始化 loading，默认展示。 */
+    showProjectLoading?: boolean;
     /** 是否展示导出任务列表入口，默认开启。 */
     showExportTaskList?: boolean;
     /** When set, append the header here instead of inside the editor root. */
@@ -21,7 +23,7 @@ export interface CreateAmkEditorLayoutOptions {
     /** 传入则展示关闭按钮 */
     onClose?: () => void;
     onTitleSubmit?: (title: string) => void;
-    t?: AmkI18nInstance['t'];
+    i18n?: AmkI18nInstance;
 }
 export type AmkSaveStatus = 'saving' | 'saved';
 export type AmkExportTaskStatus = 'idle' | 'polling' | 'success' | 'failed';

package/dist/import-actions.d.ts

@@ -4,12 +4,15 @@ interface MountImportActionsOptions {
     /** AMKEditor 自己的浮层容器；按钮仍挂在 VeVeditor 提供的工具栏插槽中。 */
     modalContainer: HTMLElement;
     uploadAccept?: string;
+    onUploadStatusChange?: (uploading: boolean) => void;
+    onUploadFile?: (file: File) => Promise<MaterialItem> | MaterialItem;
     onUploadMaterial?: (files: File[]) => Promise<MaterialItem[]> | MaterialItem[];
     onUploadUrlMaterial?: (urls: string[]) => Promise<MaterialItem[]> | MaterialItem[];
     onUploadFromSystem?: () => Promise<SystemMaterialItem[] | undefined | null> | SystemMaterialItem[] | undefined | null;
-    onMaterialsImported: (materials: SystemMaterialItem[]) => MaterialItem[] | Promise<MaterialItem[]>;
+    onMaterialsImported: (materials: Array<MaterialItem | SystemMaterialItem>) => MaterialItem[] | Promise<MaterialItem[]>;
     t?: AmkI18nInstance['t'];
 }
+export declare function resolveImportErrorMessage(error: unknown, fallback: string): string;
 /**
  * 素材面板按钮与外部入口共用的控制器。保留可调用的 cleanup 形态，兼容已有
  * `renderImportActions` 挂载协议；外部入口通过 trigger 复用完全相同的导入链路。

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export declare const version: string;
 export { AmkEditor, createAmkEditor } from './amk-editor';
 export { AmkApiClient, createAmkApiClient } from './api/client';
 export type { AmkApiClientOptions, AmkInvokeToolParams } from './api/client';