@volcengine/amk-editor 0.0.1 → 0.0.2-beta.1

package/README.md

@@ -13,6 +13,11 @@ const editor = new AmkEditor({
   container,
   projectId: 'your-project-id',
   endpoint: 'https://your-backend.example.com',
+  // 可选：每次请求前动态获取，SDK 不解析或改写返回的 Header。
+  getHeaders: async () => ({
+    Authorization: `Bearer ${await getLatestToken()}`,
+    'X-Customer-Id': 'your-customer-id',
+  }),
   material: {
     onUploadMaterial: async files => {
       // 上传到业务存储后返回素材列表，每项必须带 source_material_id
@@ -30,14 +35,46 @@ const editor = new AmkEditor({
       })),
   },
 });
+
+
+// 外部工具栏可复用素材面板的同一套导入弹窗与入库链路。
+editor.requestMaterialImport('local'); // 本地文件选择 + 本地上传确认弹窗
+editor.requestMaterialImport('url'); // URL 上传弹窗
+editor.requestMaterialImport('system'); // 业务资产库回调
+
+// 只有这个外部调用触发的导入成功后才回调；编辑器自身的导入按钮不会触发它。
+editor.requestMaterialImport('local', {
+  onMaterialsImported: materials => {
+    console.log('本次已入库素材', materials);
+  },
+});
+
+// 从服务端重新拉取当前工程，并热更新素材与 Track（不写入撤销历史）。
+await editor.refreshProject();
 ```
 页面卸载时销毁：
 ```ts
 editor.destroy();
 ```
 ## 接入说明
-- `projectId`、`endpoint` 必填。`endpoint` 指向你的业务服务，由服务端转发并注入鉴权，不要把 API Key 放到浏览器。
+- `projectId`、`endpoint` 必填。`endpoint` 指向你的业务代理。
+- `theme` 默认 `light`。未传或传入其他值时按浅色渲染；只有显式 `theme: 'dark'` 才走暗色。
+- 产物是单文件 ESM。依赖里的 AMD `define(["./core"])` 已在构建时剔除，避免 Next.js / webpack 误解析不存在的 `dist/core.js`。
+- `getHeaders` 可选，每次请求前都会重新调用；SDK 不解析、不缓存、不改写返回值，仅将其合并到发往 `endpoint` 的工程、素材、tools、tasks、导出等请求中。闭包内 Token 更新会自动用于下一次请求。
 - 本地上传、URL 导入由业务回调完成。返回的素材必须带业务主键 `source_material_id`，不必填写 `material_id`。
 - 播放地址、封面、雪碧图可能有时效。通过 `onRefreshPlayInfo` 返回新的访问地址。
+- 可选实现 `onMaterialsImported`：素材成功入库后回调已合并 `material_id` 的列表；可用于把新素材挂到对话草稿。失败或取消不会触发。
 - 可选实现 `onPersistExtractUrls`：把抽帧得到的临时地址转存为业务长期地址，并随 `materialPatch` 写回自定义存储字段。
 - 可选配置 `export.qualityEnhancement: true` 以在导出弹窗展示「视频画质增强」；默认不展示。
+- 可选配置 `header.mount` 为外部 DOM 节点，将顶栏渲染到该节点（而不是编辑器内部），便于宿主做全宽顶栏；`header.show: false` 仍可完全隐藏顶栏。
+- 可选配置 `header.onTitleUpdateSuccess`：工程名 PATCH 成功后回调 `{ projectId, title }`。保存成功前编辑器继续展示旧名称；保存失败不会修改编辑器标题，也不会触发回调。
+- `requestMaterialImport(type, options?)` 返回是否成功触发已配置入口；`local`、`url`、`system` 分别要求存在本地上传能力、`onUploadUrlMaterial`、`onUploadFromSystem`。外部入口不会复制上传逻辑，仍走素材面板相同的回调、TOS 签名、素材入库与元信息处理。可选的 `options.onMaterialsImported` 只对这一次外部触发有效，编辑器自身的导入按钮不会调用它。
+- `toolbar.customItems` 的只读态不会自动置灰。需要禁用时在该项 `disabled({ readonly })` 里自行返回 true（例如 `disabled: ({ readonly }) => readonly`）。录音中仍会全局锁定自定义项。内置 ASR 按钮在只读时仍会禁用。
+- `refreshProject()` 会等待当前保存队列结束，再重新拉取工程、刷新临时播放地址并热更新素材与 Track；远端 Track 不会写入本地撤销历史，也不会被自动保存回服务端。
+## 样式隔离
+SDK 会随 `import '@volcengine/amk-editor'` 自动注入样式，导航栏、左侧分类、素材网格的布局由 SDK 自己负责。**接入方不必再写补丁 CSS 才能让界面正常显示。**
+编辑器挂在普通 DOM（`#track-video-editor`）里，不是 Shadow DOM。宿主页面里针对 `section` / `nav` / `aside` 的全局布局重置会穿透进来，把顶栏或左侧分类挤扁。
+请避免：
+- 对 `section`、`nav`、`aside` 写全局 `display` / `flex` / `height` / `margin` 规则。
+- 用 `#track-video-editor nav { ... }` 这类按标签名锁定内部节点。同名标签在编辑器里用途不同，一条规则会同时打到顶栏和分类栏。
+如需约束编辑器尺寸，只设置挂载容器或 `#track-video-editor` 本身的 `width` / `height` / `min-height`。

package/dist/amk-editor.d.ts

@@ -1,5 +1,5 @@
 import './veveditor.css';
-import type { AmkEditorOptions, AmkProjectSnapshot, MaterialItem, VeVeditorInstance } from './types';
+import type { AmkMaterialImportType, AmkMaterialImportRequestOptions, AmkEditorOptions, AmkExportRequestResult, AmkProjectSnapshot, MaterialItem, VeVeditorInstance } from './types';
 import { type AmkI18nInstance } from './i18n';
 import { type AmkInvokeToolParams } from './api/client';
 export declare class AmkEditor {
@@ -9,6 +9,8 @@ export declare class AmkEditor {
     private editor?;
     private layout?;
     private exportModal?;
+    private exportRequestInFlight?;
+    private importActions?;
     private asrProgressModal?;
     private confirmModal?;
     private emptyTrackConfirmInFlight?;
@@ -23,6 +25,7 @@ export declare class AmkEditor {
     private emptyTrackSaveBlocked;
     private savedMaterials;
     private saveQueue;
+    private projectRefreshInFlight?;
     private pendingSaveCount;
     private readonly asrPollingControllers;
     /** 当前前台 ASR 会话；取消、关闭或销毁后直接丢弃，不写入工程 JSON。 */
@@ -31,8 +34,18 @@ export declare class AmkEditor {
     private readonly asrStartingElementIds;
     /** sprite 抽帧任务轮询：key = material_id / source */
     private readonly spritePollingControllers;
+    private readonly posterPollingControllers;
+    /** TOS 上传完成前的素材面板占位：key = source_material_id。 */
+    private readonly tosUploadPlaceholders;
     /** 同一素材的封面/雪碧图转存结果串行写回，避免自定义字段互相覆盖。 */
     private readonly materialPatchQueues;
+    /** 等待批量落盘的素材；同一素材在窗口内只保留合并后的最新状态。 */
+    private readonly pendingMaterialPatches;
+    /** 包含等待中和提交中的最新本地状态，用于合并跨批次的并发字段。 */
+    private readonly latestMaterialPatches;
+    private materialPatchBatchTimer?;
+    /** 批次串行提交，避免先发批次晚返回后覆盖更新批次。 */
+    private materialPatchFlushQueue;
     /** 同一素材的 sprite 失败只处理一次，避免多个缩略图同时 403 重复建任务。 */
     private readonly thumbnailErrorInFlight;
     /** 前端抽帧封面缓存（不落盘）：key = materialKey，value = dataURL */
@@ -43,6 +56,10 @@ export declare class AmkEditor {
     private readonly posterCaptureControllers;
     /** 启动时加载的内置预设资源，供编辑器面板和 ASR 字幕复用。 */
     private presetLibrary;
+    /** 所有 TOS 素材共用一个刷新定时器，避免按素材创建大量 timer。 */
+    private tosSignedUrlRefreshTimer?;
+    private tosSignedUrlRefreshInFlight?;
+    private readonly handleVisibilityChange;
     private readonly handleTrackChanged;
     private readonly handleEditParamChanged;
     constructor(options: AmkEditorOptions);
@@ -52,18 +69,44 @@ export declare class AmkEditor {
     getI18n(): AmkI18nInstance;
     /** 通用工具调用：POST /api/v1/tools/{toolName} */
     invokeTool<T = unknown>(options: AmkInvokeToolParams): Promise<T>;
+    /**
+     * Opens the existing export modal and resolves after the user confirms or cancels.
+     * Intended for Agent frontend tools (`request_export_task`). Header export still
+     * uses `open()` + direct submit and is unchanged.
+     */
+    requestExport(): Promise<AmkExportRequestResult>;
+    /**
+     * 从外部工具栏打开 AMK Editor 已配置的素材导入入口。
+     * 本地、URL、资产库均复用素材面板中的同一套弹窗、回调和入库链路。
+     * @returns 当前入口存在且已触发时返回 true；未配置或尚未挂载时返回 false。
+     */
+    requestMaterialImport(type: AmkMaterialImportType, options?: AmkMaterialImportRequestOptions): boolean;
     /**
      * 获取工程全量参数（materials + editParam + projectName）。
      * 从 VeVeditor 当前素材/草稿快照读取；未挂载时回落内置拉取到的快照。
      */
     getProject(): AmkProjectSnapshot;
+    /**
+     * 从 Editing 工程接口重新拉取完整素材列表。
+     * 与 `getProject()` 的当前编辑器快照不同，该方法每次都会请求服务端，
+     * 适合素材引用面板等必须包含最新导出产物的场景。
+     */
+    fetchProjectMaterials(): Promise<MaterialItem[]>;
+    /**
+     * 重新拉取服务端工程，并把最新素材与 Track 热更新到当前编辑器。
+     * 用于 Agent 完成远端编辑后刷新右侧预览；不会产生撤销记录，也不会把回灌事件再次保存到服务端。
+     */
+    refreshProject(): Promise<AmkProjectSnapshot>;
+    private refreshProjectFromServer;
     /**
      * 刷新素材播放信息（按需触发，如播放前 / 初始化）。
-     * - 未配置 `material.onRefreshPlayInfo`：直接从当前素材库返回匹配项，不发请求
-     * - 配置后：把完整素材列表传给业务方，业务方返回要覆盖的字段（url / sprite / poster 等）
+     * - TOS 直传素材会先使用临时 STS 重签私有对象 URL
+     * - 配置 `material.onRefreshPlayInfo` 后，宿主可继续覆盖播放字段
+     * - 两者都未配置时直接返回当前素材，不发请求
      * @param materialIdOrIds 单个 material_id、material_id 列表；省略则刷新当前全部有 material_id 的素材
      */
     refreshPlayInfo(materialIdOrIds?: string | string[]): Promise<MaterialItem | MaterialItem[] | undefined>;
+    private refreshPlayInfoInternal;
     private bootstrap;
     /** 内置拉取工程：project + materials + editor → 归一化 → 组装 initialData。 */
     private resolveAndApplyProject;
@@ -72,8 +115,20 @@ export declare class AmkEditor {
      * 再把轨道元素里的 URL 回填到最新值，完成后回写 editor 文档。
      */
     private refreshProjectOnInit;
+    /** TOS 私有桶签名刷新优先，宿主刷新回调随后可继续覆盖播放信息。 */
+    private refreshMaterialTargets;
+    /**
+     * 将重签后的素材 URL 按 material_id 同步到轨道节点并重建媒体节点。
+     * URL 是运行时数据：保存工程，但不产生撤销步骤。
+     */
+    private applyTrackMaterialUrls;
+    private getExpiringTosMaterialIds;
+    private scheduleTosSignedUrlRefresh;
+    private refreshExpiringTosUrls;
+    private readonly handlePreviewNodeRefresh;
     private resolveAndApplyPresetLibrary;
-    mount(): VeVeditorInstance;
+    mount(): VeVeditorInstance | undefined;
+    private mountVeVeditor;
     destroy(): void;
     private resolveConfig;
     /** 与 VeVeditor 同一套顶层扁平资源字段：boolean 面板开关 + 内部 xgplayer 组装 */
@@ -119,19 +174,48 @@ export declare class AmkEditor {
     private finishAsrAndCreateTextTrack;
     private startAsrPolling;
     private startAsrTask;
+    private resolveLocalFileType;
+    private createTosUploadPlaceholder;
+    /** 资产库选中后立即展示 0% 上传占位卡片，写入素材库成功后再切换为完成态。 */
+    private addSystemTosImportPlaceholders;
+    private removeTosUploadPlaceholders;
+    private hasTosUploadPlaceholders;
+    private uploadTosMaterials;
+    private extractToolResult;
+    private requirePositiveNumber;
+    private waitForToolTask;
+    private probeAsyncMetadata;
+    private prepareTosMaterial;
+    /** 将业务资产库的原始条目归一化为 SDK 素材；TOS 地址随后由 SDK 自行签发。 */
+    private normalizeSystemMaterial;
+    /**
+     * 资产库选择的 TOS 条目：同步签发播放 URL 并补齐基础元信息。
+     * 入参应为已 normalize 的素材；poster/sprite 在正式素材入库后后台处理。
+     */
+    private prepareSystemTosMaterials;
+    private ingestTosImportedMaterials;
     /**
      * 本地 / URL 上传入库后的统一收口：
      * POST 远端素材库 → 按 sprite/poster 判断发起抽帧并 PUT 更新。
      */
     private ingestImportedMaterials;
+    /**
+     * 通知宿主素材已入库。抽帧仍在后台进行，不阻塞对话引用。
+     */
+    private notifyMaterialsImported;
     /**
      * 本地上传 / URL 上传完成后，将新素材 POST 到 Editing API。
-     * addSketchItems 已写入面板；此处确保远端持久化，并把 Editing API
-     * 返回的 material_id 记到面板（业务不用传这个字段；不覆盖本地 source / kid / 预览字段）。
+     * 先确保远端持久化并合并 Editing API 返回的 material_id；成功后调用方
+     * 才写入素材面板（业务不用传 material_id；不覆盖本地 source / kid / 预览字段）。
      */
     private persistUploadedMaterials;
     private isHttpUrl;
     private resolveDisplayPoster;
+    /**
+     * DataURL 已上屏时保留到本次会话结束，HTTP poster 只负责落库。
+     * 没有前端预览或当前缓存也是 HTTP 时，才切换到新的 HTTP 地址。
+     */
+    private cachePersistedPosterForDisplay;
     private withDisplayPosters;
     private blobToDataUrl;
     /** AMK 视频抽帧：指定第 0 帧并轮询任务结果。 */
@@ -140,9 +224,13 @@ export declare class AmkEditor {
     private captureVideoPosterFromFrontend;
     private isThumbnailFrontendDecodeEnabled;
     /**
-     * 封面只做运行时刷新，不写素材/工程：
-     * - enableThumbnailDecode=true：优先前端 Range + WebCodecs，失败再 AMK 第 0 帧兜底
-     * - 默认 false：只走 AMK SpecifiedFrames 第 0 帧接口
+     * 浏览器先解一帧仅作会话展示（DataURL 不落库）。
+     * 正式封面仍由 AMK 接口返回的 HTTP URL 负责持久化。
+     */
+    private previewPosterFromFrontend;
+    /**
+     * 正式封面只走 AMK 抽帧接口；返回可落库的 HTTP URL。
+     * 前端预览由 {@link previewPosterFromFrontend} 并行触发。
      */
     private captureVideoPosterFromUrl;
     /**
@@ -159,24 +247,30 @@ export declare class AmkEditor {
      * 统一入口：初始化 / 本地上传 / URL 上传拿到素材后，按 sprite/poster 判断是否抽帧。
      * - sprite / poster 缺失或 auth_key 过期：重新抽帧
      * - http 结果：先临时链上屏/PUT；若配置 onPersistExtractUrls 则后台转存换链
-     * - 前端 dataURL 不落盘
-     * - enableThumbnailDecode=true：跳过 sprite 接口，封面优先前端解码
+     * - 封面：浏览器可并行解一帧作会话预览（DataURL 不落盘）；正式封面始终走 AMK 接口 URL 落库
+     * - enableThumbnailDecode=true：跳过 sprite 接口，轨道缩略图走前端解码
      */
     private ensureMaterialExtractTasks;
     private createExtractFramesTask;
     private startSpritePolling;
+    private startPosterPolling;
     private buildSpriteFromExtractResult;
     private extractFirstSnapshotUrl;
     /**
-     * 时间轴 sprite 真实请求失败后的兜底：不解析 URL 的签名格式，直接以 Image.onerror 为准。
-     * 先让业务通过 onRefreshPlayInfo 更新素材；刷新后仍没有新的 sprite，再重新抽帧。
+     * 时间轴 sprite / 素材库 poster 真实请求失败后的兜底：不解析 URL 的签名格式，直接以 Image.onerror 为准。
+     * 先让业务通过 onRefreshPlayInfo 更新素材；刷新后仍没有新地址，再重新抽帧。
      */
     private handleThumbnailError;
+    /** 兼容时间轴元素与素材库 sketch 项，定位失败资源所属素材。 */
+    private resolveMaterialFromThumbnailError;
     private findMaterialByKey;
     private applyMaterialToPanel;
     private enqueueMaterialPatch;
     private patchMaterialRemote;
+    private flushPendingMaterialPatches;
     private clearSpriteTimer;
     private clearSpritePollingTimers;
+    private clearPosterTimer;
+    private clearPosterPollingTimers;
 }
 export declare function createAmkEditor(options: AmkEditorOptions): AmkEditor;

package/dist/api/client.d.ts

@@ -1,17 +1,28 @@
+import type { AmkEditorGetHeaders } from '../types';
 export type AmkApiClientOptions = {
     endpoint: string;
+    /** 每次请求前动态获取并原样透传给客户业务代理的请求头。 */
+    getHeaders?: AmkEditorGetHeaders;
+    /** 调用 tools 接口时写入请求体的产物存储目标，例如 `tos://bucket`。 */
+    mediaOutputDestination?: string;
 };
 export type AmkInvokeToolParams = {
     toolName: string;
     params?: Record<string, unknown>;
+    /** 默认注入配置的产物存储目标；纯探测类工具应设为 false。 */
+    includeMediaOutputDestination?: boolean;
     headers?: Record<string, string>;
     signal?: AbortSignal;
 };
 export declare class AmkApiClient {
     private readonly baseUrl;
+    private readonly getHeaders?;
+    private readonly mediaOutputDestination?;
     constructor(options: AmkApiClientOptions);
     getBaseUrl(): string;
     invokeTool<T = unknown>(options: AmkInvokeToolParams): Promise<T>;
+    invokeSyncTool<T = unknown>(options: AmkInvokeToolParams): Promise<T>;
+    private mergeToolParams;
     /**
      * 查询异步任务：GET /api/v1/tasks/{task_id}
      * @see https://docs.volcengine.com/docs/6448/2278532

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

@@ -5,6 +5,8 @@ export type PresetLibraryItem = {
     name: string;
     icon_url: string;
     package_url: string;
+    /** 滤镜分类；无显式 categories 时 SDK 按 tag 聚合侧栏（值即分类名）。 */
+    tag?: string;
     default?: boolean;
 };
 export type PresetLibrary = Partial<Record<PresetLibraryResourceKey, PresetLibraryItem[]>>;

package/dist/api/project.d.ts

@@ -8,6 +8,7 @@ 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 updateAmkProjectName(client: EditingApiClient, projectId: string, projectName: string): Promise<void>;
 /**

package/dist/assets/import-menu-chevron-down.svg

@@ -0,0 +1,3 @@
+<svg preserveAspectRatio="none" overflow="visible" style="display: block;" width="7.74994" height="4.24997" viewBox="0 0 7.74994 4.24997" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path id="Vector (Stroke)" d="M7.10984 0.109835C7.25628 -0.0366117 7.49366 -0.0366116 7.64011 0.109835C7.78656 0.256282 7.78656 0.493662 7.64011 0.640108L4.14011 4.14011C4.06978 4.21043 3.97443 4.24997 3.87497 4.24997C3.77552 4.24997 3.68016 4.21043 3.60983 4.14011L0.109835 0.640108C-0.0366116 0.493662 -0.0366117 0.256282 0.109835 0.109835C0.256282 -0.0366116 0.493662 -0.0366117 0.640108 0.109835L3.87497 3.3447L7.10984 0.109835Z" fill="#101013"/>
+</svg>

package/dist/assets/import-menu-local.svg

@@ -0,0 +1,3 @@
+<svg preserveAspectRatio="none" overflow="visible" style="display: block;" width="12" height="12" viewBox="0 0 12 12" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path id="Vector (Stroke)" d="M1.07402e-06 8.58474V7.84615C1.07402e-06 7.59125 0.206639 7.38461 0.461539 7.38461C0.71644 7.38461 0.923078 7.59125 0.923078 7.84615V8.58474C0.923078 9.10926 0.923257 9.47494 0.946515 9.75961C0.969334 10.0389 1.012 10.1994 1.07392 10.3209C1.20667 10.5814 1.41856 10.7933 1.67909 10.9261C1.80063 10.988 1.96111 11.0307 2.24039 11.0535C2.52506 11.0767 2.89074 11.0769 3.41527 11.0769H8.58474C9.10926 11.0769 9.47494 11.0767 9.75962 11.0535C10.0389 11.0307 10.1994 10.988 10.3209 10.9261C10.5814 10.7933 10.7933 10.5814 10.9261 10.3209C10.988 10.1994 11.0307 10.0389 11.0535 9.75961C11.0767 9.47494 11.0769 9.10926 11.0769 8.58474V7.84615C11.0769 7.59125 11.2836 7.38461 11.5385 7.38461C11.7934 7.38461 12 7.59125 12 7.84615V8.58474C12 9.09402 12.0006 9.50376 11.9736 9.83473C11.9461 10.1711 11.8875 10.4664 11.7482 10.7398C11.5269 11.174 11.174 11.5269 10.7398 11.7482C10.4664 11.8875 10.1711 11.9461 9.83474 11.9736C9.50376 12.0006 9.09402 12 8.58474 12H3.41527C2.90598 12 2.49624 12.0006 2.16527 11.9736C1.82889 11.9461 1.53357 11.8875 1.26022 11.7482C0.825997 11.5269 0.47305 11.174 0.251804 10.7398C0.112532 10.4664 0.0539263 10.1711 0.0264434 9.83473C-0.000595874 9.50376 1.01767e-06 9.09402 1.07402e-06 8.58474ZM5.53846 7.84615V1.57572L3.2494 3.86478C3.06916 4.04503 2.777 4.04503 2.59676 3.86478C2.41651 3.68454 2.41651 3.39238 2.59676 3.21214L5.67368 0.135216L5.74399 0.077524C5.81925 0.0273516 5.90821 1.16544e-07 6 0C6.12241 0 6.23977 0.0486612 6.32632 0.135216L9.40324 3.21214C9.58349 3.39238 9.58349 3.68454 9.40324 3.86478C9.223 4.04503 8.93084 4.04503 8.7506 3.86478L6.46154 1.57572V7.84615C6.46154 8.10105 6.2549 8.30769 6 8.30769C5.7451 8.30769 5.53846 8.10105 5.53846 7.84615Z" fill="#101013"/>
+</svg>

package/dist/assets/import-menu-system-arrow.svg

@@ -0,0 +1,3 @@
+<svg preserveAspectRatio="none" overflow="visible" style="display: block;" width="4.41019" height="5.64103" viewBox="0 0 4.41019 5.64103" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path id="Vector (Stroke)" d="M1.74355 1.57572V5.17949C1.74355 5.43439 1.95019 5.64103 2.20509 5.64103C2.45999 5.64102 2.66663 5.43439 2.66663 5.17949V1.57572L3.62236 2.53145C3.8026 2.71169 4.09476 2.71169 4.275 2.53145C4.45525 2.35121 4.45525 2.05905 4.275 1.87881L2.53141 0.135216C2.44486 0.0486612 2.3275 0 2.20509 0C2.11331 0 2.02434 0.0273516 1.94908 0.077524L1.87877 0.135216L0.135181 1.87881C-0.0450605 2.05905 -0.0450605 2.35121 0.135181 2.53145C0.315423 2.71169 0.607583 2.71169 0.787825 2.53145L1.74355 1.57572Z" fill="#101013"/>
+</svg>

package/dist/assets/import-menu-system-cloud.svg

@@ -0,0 +1,3 @@
+<svg preserveAspectRatio="none" overflow="visible" style="display: block;" width="13.0093" height="9.54572" viewBox="0 0 13.0093 9.54572" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path id="Vector" d="M0.721682 6.03213C0.52041 5.42761 0.459347 4.78521 0.54312 4.15359C0.626893 3.52197 0.853304 2.9177 1.2052 2.38655C1.5571 1.85539 2.02527 1.41128 2.57422 1.08786C3.12318 0.764439 3.73855 0.570185 4.3737 0.519811C5.00886 0.469438 5.64715 0.564267 6.24022 0.797115C6.8333 1.02996 7.36561 1.39472 7.79684 1.86377C8.22806 2.33282 8.54689 2.89384 8.72918 3.50436H9.80292C10.3821 3.5043 10.9459 3.69051 11.4111 4.0355C11.8763 4.38049 12.2183 4.86596 12.3864 5.42019C12.5545 5.97443 12.5399 6.56804 12.3447 7.11334C12.1496 7.65863 11.9344 8.0263 11.119 8.57093C10.3036 9.11555 7.8181 9.03484 7.8181 9.03484" stroke="black" stroke-width="1.01333" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/dist/assets/import-menu-url.svg

@@ -0,0 +1,3 @@
+<svg preserveAspectRatio="none" overflow="visible" style="display: block;" width="12.9997" height="12.9998" viewBox="0 0 12.9997 12.9998" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path id="Vector (Stroke)" d="M2.2056 5.58315C2.40085 5.38809 2.71742 5.38803 2.91263 5.58315C3.10783 5.77836 3.10772 6.09491 2.91263 6.29018L1.78633 7.41649C0.737757 8.46506 0.737873 10.165 1.78633 11.2134C2.8348 12.2618 4.53519 12.2618 5.58385 11.2134L6.70885 10.0877C6.90402 9.89237 7.22053 9.89192 7.41589 10.0871C7.61124 10.2822 7.61106 10.5987 7.41589 10.7941L6.29154 11.9204H6.29089C4.85194 13.3591 2.51846 13.3598 1.0793 11.921C-0.359868 10.482 -0.359663 8.14842 1.0793 6.70946L2.2056 5.58315ZM8.39896 3.89435C8.59424 3.69931 8.91081 3.69916 9.10599 3.89435C9.30115 4.08954 9.30101 4.40611 9.10599 4.60138L4.60143 9.10594C4.40622 9.30104 4.08964 9.301 3.8944 9.10594C3.69918 8.91071 3.69925 8.59417 3.8944 8.39891L8.39896 3.89435ZM6.70951 1.07925C8.14865 -0.359805 10.4814 -0.359693 11.9204 1.07925C13.3595 2.51826 13.3595 4.85116 11.9204 6.29018L10.7948 7.41649C10.5996 7.61156 10.283 7.61163 10.0878 7.41649C9.89259 7.22128 9.89266 6.90473 10.0878 6.70946L11.2134 5.58315L11.3085 5.48289C12.2608 4.42893 12.2292 2.80199 11.2134 1.78628C10.1648 0.737765 8.46506 0.73782 7.41654 1.78628L6.29024 2.91193C6.09497 3.10719 5.77846 3.1072 5.5832 2.91193C5.38805 2.71665 5.38797 2.40012 5.5832 2.2049L6.70951 1.07925Z" fill="#101013"/>
+</svg>

package/dist/export-modal.d.ts

@@ -12,7 +12,20 @@ export interface ExportModalController {
     open: () => void;
     close: () => void;
     destroy: () => void;
+    /**
+     * Opens the modal and waits for the user to confirm or cancel.
+     * Confirmed results are returned to the caller and do not invoke `onConfirm`
+     * (callers such as Agent tools own the submit path). Header `open()` still
+     * uses `onConfirm` for the direct-export path.
+     */
+    request: () => Promise<ExportModalRequestResult>;
 }
+export type ExportModalRequestResult = {
+    status: 'confirmed';
+    params: ExportVideoParams;
+} | {
+    status: 'cancel';
+};
 type SelectOption<T extends string> = {
     label: string;
     value: T;
@@ -21,7 +34,7 @@ type SelectOption<T extends string> = {
 export declare const QUALITY_TOOLTIP = "AI MediaKit \u753B\u8D28\u589E\u5F3A\u96C6\u6210\u667A\u80FD\u8D85\u5206\u3001\u63D2\u5E27\u3001\u753B\u9762\u589E\u5F3A\u3001\u81EA\u9002\u5E94\u9510\u5316\u3001\u8272\u5F69\u589E\u5F3A\u7B49 30+ \u9AD8\u8D28\u91CF\u7B97\u6CD5\uFF0C\u7ED3\u5408\u81EA\u7814\u89C6\u9891\u5185\u5BB9\u7406\u89E3\u4E0E\u667A\u80FD\u8C03\u5EA6\uFF0C\u6309\u573A\u666F\u81EA\u52A8\u62E9\u4F18\u8C03\u7528\uFF0C\u5168\u9762\u63D0\u5347\u89C6\u9891\u753B\u8D28\u3002";
 export declare function getBaseResolutions(t: AmkI18nInstance['t']): SelectOption<ExportVideoParams['resolution']>[];
 /** 画质增强开启后的分辨率：不含原画；大模型版不含 4K */
-export declare function getEnhancedResolutions(t: AmkI18nInstance['t'], enhancementVersion?: ExportVideoParams['enhancementVersion']): SelectOption<ExportVideoParams['resolution']>[];
+export declare function getEnhancedResolutions(_t: AmkI18nInstance['t'], enhancementVersion?: ExportVideoParams['enhancementVersion']): SelectOption<ExportVideoParams['resolution']>[];
 /** 当前模式下合法分辨率；非法时回落到默认项 */
 export declare function normalizeExportResolution(params: Pick<ExportVideoParams, 'qualityEnhancement' | 'enhancementVersion' | 'resolution'>, t?: AmkI18nInstance['t']): ExportVideoParams['resolution'];
 export declare function getEnhancementVersions(t: AmkI18nInstance['t']): SelectOption<ExportVideoParams['enhancementVersion']>[];
@@ -41,7 +54,7 @@ export declare function createDefaultExportVideoParams(videoName: string): Expor
 /** 导出帧率合法区间（含端点） */
 export declare const EXPORT_FRAME_RATE_MIN = 15;
 export declare const EXPORT_FRAME_RATE_MAX = 120;
-/** 将导出帧率钳制到 15～120；非法输入回落 30 */
+/** 将导出帧率钳制到 15～120；非法输入回落 24 */
 export declare function normalizeExportFrameRate(frameRate: unknown): number;
 export declare function toggleQualityEnhancement(params: ExportVideoParams, enabled: boolean): ExportVideoParams;
 export declare function createExportModal(options: CreateExportModalOptions): ExportModalController;

package/dist/header.d.ts

@@ -9,6 +9,8 @@ export interface CreateAmkEditorLayoutOptions {
     title: string;
     theme?: 'light' | 'dark';
     showHeader: boolean;
+    /** When set, append the header here instead of inside the editor root. */
+    headerMount?: HTMLElement;
     onExport: () => void;
     /** 传入则展示返回按钮 */
     onBack?: () => void;
@@ -21,6 +23,7 @@ export type AmkSaveStatus = 'saving' | 'saved';
 export interface AmkEditorLayout {
     root: HTMLDivElement;
     workspace: HTMLDivElement;
+    setTitle: (title: string) => void;
     setSaveStatus: (status: AmkSaveStatus) => void;
     destroy: () => void;
 }

package/dist/i18n/keys.d.ts

@@ -23,6 +23,8 @@ export declare const AMK_I18N_KEYS: {
     readonly import: {
         readonly local: "amk.import.local";
         readonly url: "amk.import.url";
+        readonly system: "amk.import.system";
+        readonly action: "amk.import.action";
     };
     readonly localUpload: {
         readonly title: "amk.localUpload.title";

package/dist/import-actions-dropdown-view.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+export interface ImportDropdownAction {
+    key: string;
+    label: string;
+    onSelect: () => void;
+}
+export interface ImportActionsDropdownViewProps {
+    actions: ImportDropdownAction[];
+    label: string;
+}
+/**
+ * “导入”是固定的操作入口，而非表单选择值：菜单项点击后只触发对应回调。
+ * selection="none" 同时确保组件不会维护选中态或展示勾选图标。
+ */
+export declare function ImportActionsDropdownView({ actions, label, }: ImportActionsDropdownViewProps): React.ReactElement;

package/dist/import-actions.d.ts

@@ -1,4 +1,4 @@
-import type { MaterialItem } from './types';
+import type { AmkMaterialImportType, AmkMaterialImportRequestOptions, MaterialItem, SystemMaterialItem } from './types';
 import type { AmkI18nInstance } from './i18n';
 interface MountImportActionsOptions {
     /** AMKEditor 自己的浮层容器；按钮仍挂在 VeVeditor 提供的工具栏插槽中。 */
@@ -6,9 +6,19 @@ interface MountImportActionsOptions {
     uploadAccept?: string;
     onUploadMaterial?: (files: File[]) => Promise<MaterialItem[]> | MaterialItem[];
     onUploadUrlMaterial?: (urls: string[]) => Promise<MaterialItem[]> | MaterialItem[];
-    onMaterialsImported: (materials: MaterialItem[]) => void;
+    onUploadFromSystem?: () => Promise<SystemMaterialItem[] | undefined | null> | SystemMaterialItem[] | undefined | null;
+    onMaterialsImported: (materials: SystemMaterialItem[]) => MaterialItem[] | Promise<MaterialItem[]>;
     t?: AmkI18nInstance['t'];
 }
+/**
+ * 素材面板按钮与外部入口共用的控制器。保留可调用的 cleanup 形态，兼容已有
+ * `renderImportActions` 挂载协议；外部入口通过 trigger 复用完全相同的导入链路。
+ */
+export type ImportActionsController = (() => void) & {
+    hasAction: (type: AmkMaterialImportType) => boolean;
+    trigger: (type: AmkMaterialImportType, options?: AmkMaterialImportRequestOptions) => boolean;
+    destroy: () => void;
+};
 /** AMK 独立拥有素材导入 UI 与业务回调，VeVeditor 仅提供挂载容器和标准数据写入 API。 */
-export declare function mountImportActions(container: HTMLElement, options: MountImportActionsOptions): () => void;
+export declare function mountImportActions(container: HTMLElement, options: MountImportActionsOptions): ImportActionsController;
 export {};

package/dist/index.d.ts

@@ -4,4 +4,4 @@ export type { AmkApiClientOptions, AmkInvokeToolParams } from './api/client';
 export type { PresetLibrary, PresetLibraryItem, PresetLibraryResourceKey, } from './api/preset-library';
 export { AMK_I18N_KEYS, createAmkI18n, tAmk, getGlobalAmkI18n, setGlobalAmkI18n, } from './i18n';
 export type { AmkI18nInstance, AmkI18nOptions, Locale, LocaleMessages, Messages, } from './i18n';
-export type { AmkEditorOptions, AmkEditorConfig, AmkEditorDecodeOptions, AmkEditorExportConfig, AmkEditorHeaderConfig, AmkEditorInternalConfig, AmkProjectSnapshot, ExportVideoParams, MaterialConfig, MaterialItem, PersistExtractUrlsResult, RecommendedExtractStorageFields, Theme, VeVeditorInstance, } from './types';
+export type { AmkEditorOptions, AmkEditorStorageConfig, AmkEditorUploadSTSCredentials, AmkEditorConfig, AmkEditorDecodeOptions, AmkEditorExportConfig, AmkEditorGetHeaders, AmkEditorHeaderConfig, AmkEditorHeaderTitleUpdateSuccess, AmkEditorInternalConfig, AmkMaterialImportType, AmkMaterialImportRequestOptions, AmkExportRequestResult, AmkProjectSnapshot, ExportVideoParams, MaterialConfig, MaterialItem, PersistExtractUrlsResult, RecommendedExtractStorageFields, SystemMaterialItem, Theme, VeVeditorInstance, } from './types';