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

package/README.md

@@ -13,17 +13,11 @@ const editor = new AmkEditor({
   container,
   projectId: 'your-project-id',
   endpoint: 'https://your-backend.example.com',
-  // 可选：自定义客户代理服务所需的请求头，SDK 不约定鉴权格式并会原样透传。
-  auth: {
-    getHeaders: async () => {
-      const response = await fetch('/api/session-token');
-      const { token } = await response.json();
-      return {
-        Authorization: `Bearer ${token}`,
-        'X-Customer-Id': 'your-customer-id',
-      };
-    },
-  },
+  // 可选：每次请求前动态获取，SDK 不解析或改写返回的 Header。
+  getHeaders: async () => ({
+    Authorization: `Bearer ${await getLatestToken()}`,
+    'X-Customer-Id': 'your-customer-id',
+  }),
   material: {
     onUploadMaterial: async files => {
       // 上传到业务存储后返回素材列表，每项必须带 source_material_id
@@ -42,12 +36,21 @@ const editor = new AmkEditor({
   },
 });
 
-// 运行时替换鉴权逻辑，后续所有 AMK 请求立即使用新的 Header。
-editor.setAuth({
-  getHeaders: () => ({ Authorization: 'Custom new-token' }),
+
+// 外部工具栏可复用素材面板的同一套导入弹窗与入库链路。
+editor.requestMaterialImport('local'); // 本地文件选择 + 本地上传确认弹窗
+editor.requestMaterialImport('url'); // URL 上传弹窗
+editor.requestMaterialImport('system'); // 业务资产库回调
+
+// 只有这个外部调用触发的导入成功后才回调；编辑器自身的导入按钮不会触发它。
+editor.requestMaterialImport('local', {
+  onMaterialsImported: materials => {
+    console.log('本次已入库素材', materials);
+  },
 });
-// 清除鉴权 Header。
-editor.setAuth(null);
+
+// 从服务端重新拉取当前工程，并热更新素材与 Track（不写入撤销历史）。
+await editor.refreshProject();
 ```
 页面卸载时销毁：
 ```ts
@@ -55,8 +58,23 @@ editor.destroy();
 ```
 ## 接入说明
 - `projectId`、`endpoint` 必填。`endpoint` 指向你的业务代理。
-- `auth` 可选，用于浏览器访问客户代理时附加自定义请求头。SDK 不约定 Token 格式或 Header 名称，只会将 `getHeaders` 返回的内容原样合并到工程、素材、tools、tasks、导出等全部 AMK 请求中。运行期间可通过 `setAuth()` 替换，传入 `null` 或 `undefined` 可清除。
+- `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 { AmkEditorAuthConfig, AmkEditorOptions, AmkExportRequestResult, 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 {
@@ -10,6 +10,7 @@ export declare class AmkEditor {
     private layout?;
     private exportModal?;
     private exportRequestInFlight?;
+    private importActions?;
     private asrProgressModal?;
     private confirmModal?;
     private emptyTrackConfirmInFlight?;
@@ -24,6 +25,7 @@ export declare class AmkEditor {
     private emptyTrackSaveBlocked;
     private savedMaterials;
     private saveQueue;
+    private projectRefreshInFlight?;
     private pendingSaveCount;
     private readonly asrPollingControllers;
     /** 当前前台 ASR 会话；取消、关闭或销毁后直接丢弃，不写入工程 JSON。 */
@@ -65,8 +67,6 @@ export declare class AmkEditor {
     whenReady(): Promise<this>;
     getEditor(): VeVeditorInstance | undefined;
     getI18n(): AmkI18nInstance;
-    /** 替换后续 AMK 请求使用的鉴权 Header 提供器；传入 null/undefined 可清除。 */
-    setAuth(auth?: AmkEditorAuthConfig | null): void;
     /** 通用工具调用：POST /api/v1/tools/{toolName} */
     invokeTool<T = unknown>(options: AmkInvokeToolParams): Promise<T>;
     /**
@@ -75,11 +75,29 @@ export declare class AmkEditor {
      * 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;
     /**
      * 刷新素材播放信息（按需触发，如播放前 / 初始化）。
      * - TOS 直传素材会先使用临时 STS 重签私有对象 URL
@@ -181,10 +199,14 @@ export declare class AmkEditor {
      * 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;

package/dist/api/client.d.ts

@@ -1,8 +1,8 @@
-import type { AmkEditorAuthConfig } from '../types';
+import type { AmkEditorGetHeaders } from '../types';
 export type AmkApiClientOptions = {
     endpoint: string;
-    /** 客户业务代理鉴权；返回的自定义请求头会随每次请求动态获取。 */
-    auth?: AmkEditorAuthConfig;
+    /** 每次请求前动态获取并原样透传给客户业务代理的请求头。 */
+    getHeaders?: AmkEditorGetHeaders;
     /** 调用 tools 接口时写入请求体的产物存储目标，例如 `tos://bucket`。 */
     mediaOutputDestination?: string;
 };
@@ -16,12 +16,10 @@ export type AmkInvokeToolParams = {
 };
 export declare class AmkApiClient {
     private readonly baseUrl;
-    private auth?;
+    private readonly getHeaders?;
     private readonly mediaOutputDestination?;
     constructor(options: AmkApiClientOptions);
     getBaseUrl(): string;
-    /** 替换后续请求使用的鉴权 Header 提供器；传入 null/undefined 可清除。 */
-    setAuth(auth?: AmkEditorAuthConfig | null): void;
     invokeTool<T = unknown>(options: AmkInvokeToolParams): Promise<T>;
     invokeSyncTool<T = unknown>(options: AmkInvokeToolParams): Promise<T>;
     private mergeToolParams;
@@ -39,6 +37,5 @@ export declare class AmkApiClient {
         body?: unknown;
         signal?: AbortSignal;
     }): Promise<T>;
-    private resolveAuthHeaders;
 }
 export declare function createAmkApiClient(options: AmkApiClientOptions): AmkApiClient;

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/export-modal.d.ts

@@ -34,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']>[];
@@ -54,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/import-actions.d.ts

@@ -1,4 +1,4 @@
-import type { MaterialItem, SystemMaterialItem } from './types';
+import type { AmkMaterialImportType, AmkMaterialImportRequestOptions, MaterialItem, SystemMaterialItem } from './types';
 import type { AmkI18nInstance } from './i18n';
 interface MountImportActionsOptions {
     /** AMKEditor 自己的浮层容器；按钮仍挂在 VeVeditor 提供的工具栏插槽中。 */
@@ -7,9 +7,18 @@ interface MountImportActionsOptions {
     onUploadMaterial?: (files: File[]) => Promise<MaterialItem[]> | MaterialItem[];
     onUploadUrlMaterial?: (urls: string[]) => Promise<MaterialItem[]> | MaterialItem[];
     onUploadFromSystem?: () => Promise<SystemMaterialItem[] | undefined | null> | SystemMaterialItem[] | undefined | null;
-    onMaterialsImported: (materials: SystemMaterialItem[]) => void | Promise<void>;
+    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, AmkEditorAuthConfig, AmkEditorStorageConfig, AmkEditorUploadSTSCredentials, AmkEditorConfig, AmkEditorDecodeOptions, AmkEditorExportConfig, AmkEditorHeaderConfig, AmkEditorInternalConfig, AmkExportRequestResult, AmkProjectSnapshot, ExportVideoParams, MaterialConfig, MaterialItem, PersistExtractUrlsResult, RecommendedExtractStorageFields, SystemMaterialItem, 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';