@byteplus/amk-editor 0.0.0-beta.1

package/dist/legacy-export-adapter.d.ts

@@ -0,0 +1,7 @@
+import type { ExportVideoParams } from './types';
+type RecordValue = Record<string, any>;
+export declare function buildExportSubmission(editParam: RecordValue, params: Pick<ExportVideoParams, 'resolution' | 'format' | 'frameRate' | 'codec'>, legacy?: boolean): {
+    toolName: string;
+    params: Record<string, unknown>;
+};
+export {};

package/dist/local-upload-modal-view.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import type { AmkI18nInstance } from './i18n';
+export interface LocalUploadModalViewProps {
+    visible: boolean;
+    popupContainer: HTMLElement;
+    initialFiles: File[];
+    accept?: string;
+    t: AmkI18nInstance['t'];
+    /** 确认后弹窗立即关闭；上传过程由外部 Message 提示 */
+    onConfirm: (files: File[]) => void;
+    onClose: () => void;
+}
+export declare function LocalUploadModalView({ visible, popupContainer, initialFiles, accept, t, onConfirm, onClose, }: LocalUploadModalViewProps): React.ReactElement;

package/dist/local-upload-modal.d.ts

@@ -0,0 +1,13 @@
+import type { AmkI18nInstance } from './i18n';
+export interface CreateLocalUploadModalOptions {
+    container: HTMLElement;
+    accept?: string;
+    t: AmkI18nInstance['t'];
+    onConfirm: (files: File[]) => void;
+}
+export interface LocalUploadModalController {
+    open: (files?: File[]) => void;
+    close: () => void;
+    destroy: () => void;
+}
+export declare function createLocalUploadModal(options: CreateLocalUploadModalOptions): LocalUploadModalController;

package/dist/material-source.d.ts

@@ -0,0 +1,5 @@
+/** 媒体资源身份在入库时确定；url 独立保存 HTTP(S) 播放地址。 */
+export declare function resolveMaterialSource(material: {
+    source?: unknown;
+    source_material_id?: unknown;
+}): string;

package/dist/modal-page-overscroll.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Modal 进入 top layer 后锁住宿主页面，同时保留 Modal 内部可滚动区域的正常滚动。
+ */
+export declare function lockModalPageOverscroll(): () => void;

package/dist/project-bootstrap.d.ts

@@ -0,0 +1,11 @@
+import type { AmkProjectSnapshot, MaterialItem } from './types';
+/** 预览与导出统一使用 NativeRender 的多语言断行规则。 */
+export declare function addForceMultilingualLineBreak(editParam: Record<string, unknown>): Record<string, unknown>;
+export declare function normalizeLoadedProject(input: AmkProjectSnapshot | undefined): Required<Pick<AmkProjectSnapshot, 'materials' | 'editParam'>> & {
+    projectName?: string;
+};
+export declare function toEditorInitialData(params: {
+    projectName?: string;
+    materials: MaterialItem[];
+    editParam: Record<string, unknown>;
+}): AmkProjectSnapshot;

package/dist/public-types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * 公网包的自包含类型契约。
+ *
+ * 这些类型与底层编辑器的公开 Options 保持结构兼容，但不引用底层内部包，
+ * 避免公网用户安装 amk-editor 时还需要访问内网依赖。
+ */
+export type VeVeditorTheme = 'light' | 'dark';
+export type VeVeditorMediaErrorCategory = 'aborted' | 'network' | 'network_or_cors' | 'decode' | 'unsupported' | 'cors' | 'render' | 'initialization' | 'unknown';
+export interface VeVeditorMediaError {
+    name: 'VideoEditorMediaError';
+    type: 'video' | 'audio' | 'image' | string;
+    phase: 'init' | 'load' | 'decode' | 'render';
+    code: string;
+    category: VeVeditorMediaErrorCategory;
+    message: string;
+    url?: string;
+    nativeCode?: number;
+    possibleCauses: string[];
+    cause?: {
+        name?: string;
+        message: string;
+    };
+    originalEvent?: Event;
+}
+export interface VeVeditorMaterialItem {
+    id?: string;
+    type?: 'video' | 'audio' | 'image' | string;
+    source: string;
+    material_id?: string;
+    source_material_id?: string;
+    url?: string;
+    poster?: string;
+    sprite?: string | Record<string, unknown>;
+    waveform?: string | Record<string, unknown>;
+    duration?: number;
+    width?: number;
+    height?: number;
+    kid?: string;
+    bizMeta?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface VeVeditorI18nOptions {
+    locale?: string;
+    messages?: Record<string, Record<string, string>>;
+    messageOverrides?: Record<string, string>;
+}
+export interface VeVeditorDecodeOptions {
+    enableAudioFrontendDecode?: boolean;
+    /** @default true */
+    enableVideoFrontendDecode?: boolean;
+    decodeConcurrency?: number;
+    decodeTopK?: number;
+    enableThumbnailDecode?: boolean;
+}
+export type VeVeditorResourceOptionTypes = {
+    font: unknown;
+    wordArt: unknown;
+    textAnimation: unknown;
+    transition: unknown;
+    filter: unknown;
+    effect: unknown;
+};
+export type VeVeditorResourceSource<T = unknown> = T[] | {
+    resources: T[];
+    categories?: Array<Record<string, unknown>>;
+} | (() => Promise<T[] | {
+    resources: T[];
+    categories?: Array<Record<string, unknown>>;
+}>) | false;
+export interface VeVeditorMaterialOptions<TMaterialItem = VeVeditorMaterialItem> {
+    show?: boolean;
+    emptyIcon?: string;
+    showClassification?: boolean;
+    defaultClassificationId?: string | null;
+    showExportVideoClassification?: boolean;
+    sketchItems?: TMaterialItem[];
+    sketchShowAdd?: boolean;
+    sketchShowDelete?: boolean;
+    showProductCategory?: boolean;
+    renderChannels?: () => unknown;
+    renderImportActions?: (container: HTMLElement) => void | (() => void);
+    onDeleteMaterial?: (material: TMaterialItem) => boolean | void | Promise<boolean | void>;
+}
+export interface VeVeditorOptions<TMaterialOptions = VeVeditorMaterialOptions, TI18nOptions = VeVeditorI18nOptions, TResourceOptions extends VeVeditorResourceOptionTypes = VeVeditorResourceOptionTypes> {
+    container: HTMLElement;
+    /** 埋点来源标识，用于区分业务接入方。 */
+    source?: string;
+    /** 埋点账号 ID；上报时写入事件 params.AccountID（对齐 master）。 */
+    accountId?: string;
+    theme?: VeVeditorTheme;
+    /** 项目加载页配置；默认展示 SDK 内置 loading，设为 false 后由宿主自行渲染。 */
+    loading?: {
+        show?: boolean;
+    };
+    material?: TMaterialOptions;
+    i18n?: TI18nOptions;
+    decode?: VeVeditorDecodeOptions;
+    track?: Record<string, unknown>;
+    toolbar?: Record<string, unknown>;
+    navigationBar?: Record<string, unknown>;
+    videoOperationBar?: Record<string, unknown>;
+    layout?: Record<string, unknown>;
+    ui?: Record<string, unknown>;
+    shortcut?: Record<string, boolean | undefined>;
+    interaction?: {
+        readonly?: boolean;
+    };
+    frameRate?: {
+        type?: 'source' | 'target';
+        frameRate?: number;
+    };
+    timeDisplayFormat?: 'hms' | 'msms' | 'msf';
+    crashedFallback?: string;
+    debug?: boolean;
+    renderMode?: 'webgl' | 'native';
+    initialData?: Record<string, unknown>;
+    font?: TResourceOptions['font'];
+    wordArt?: TResourceOptions['wordArt'];
+    textAnimation?: TResourceOptions['textAnimation'];
+    transition?: TResourceOptions['transition'];
+    filter?: TResourceOptions['filter'];
+    effect?: TResourceOptions['effect'];
+    recording?: Record<string, unknown>;
+    onSketchItemsChange?: (params: {
+        sketchItems?: VeVeditorMaterialItem[];
+        action?: 'delete' | 'add';
+        item?: unknown;
+    }) => void;
+    onNodePreviewError?: (type: 'video' | 'audio' | 'image', node: unknown, error?: VeVeditorMediaError) => void;
+    onPreviewNodeRefresh?: (type: 'video' | 'audio' | 'image', node: unknown) => void | Promise<void>;
+    onBeforeUndo?: (payload: unknown) => boolean | void;
+    onBeforeRedo?: (payload: unknown) => boolean | void;
+    onBeforeTimestampMount?: (params: Record<string, unknown>) => boolean | Promise<boolean>;
+    onBeforeKeyframeMount?: (params: Record<string, unknown>) => boolean | Promise<boolean>;
+    onTrackChanged?: (payload: unknown) => unknown;
+    onRecordingUpload?: (params: Record<string, unknown>) => Promise<boolean | {
+        success: boolean;
+        url?: string;
+        name?: string;
+        userDataPatch?: Record<string, unknown>;
+    }> | boolean | {
+        success: boolean;
+        url?: string;
+        name?: string;
+        userDataPatch?: Record<string, unknown>;
+    };
+}

package/dist/react-mount.d.ts

@@ -0,0 +1,10 @@
+import type { ReactElement } from 'react';
+/**
+ * React 18/19 挂载封装：createRoot + render / unmount。
+ * 避免 ReactDOM.render / unmountComponentAtNode（React 18 弃用，19 已移除）。
+ * 命令式 modal 宿主需要同步刷 DOM，故 render 包一层 flushSync。
+ */
+export declare function createReactMount(container: HTMLElement): {
+    render: (element: ReactElement) => void;
+    unmount: () => void;
+};

package/dist/refresh-play-info.d.ts

@@ -0,0 +1,34 @@
+import type { MaterialItem } from './types';
+/**
+ * 业务方回写的播放信息补丁；未返回的字段保持原样。
+ * 优先按 SDK 内部 material_id 匹配，随后按业务 source_material_id 兜底；
+ * 两个标识都没有的补丁才按数组下标兜底。
+ * 可更新 url / poster / sprite / source_material_id 等。
+ * material_id 为 SDK 内部字段，补丁中的同名字段会被忽略。
+ */
+export type MaterialPlayInfoPatch = Partial<MaterialItem> & {
+    material_id?: string;
+    source_material_id?: string;
+};
+/** SDK 内部素材关联键：material_id（不暴露给业务改写） */
+export declare function resolveMaterialId(material: Pick<MaterialItem, 'material_id'> | MaterialPlayInfoPatch): string;
+/** 业务侧 / Editing API 主键：source_material_id */
+export declare function resolveSourceMaterialId(material: MaterialItem | MaterialPlayInfoPatch | Record<string, unknown>): string;
+export declare function mergePlayInfoOverrides(materials: MaterialItem[], overrides: MaterialPlayInfoPatch | MaterialPlayInfoPatch[]): MaterialItem[];
+/**
+ * 将异步播放信息刷新结果变基到最新素材列表。
+ * 刷新期间新写入的 sprite/poster 等字段会被保留；只有相对刷新前快照
+ * 确实发生变化的字段才会覆盖最新值，保证后完成的刷新不会回滚并发更新。
+ */
+export declare function mergeRefreshedPlayInfoIntoLatest(latestMaterials: MaterialItem[], baseMaterials: MaterialItem[], refreshedTargets: MaterialPlayInfoPatch | MaterialPlayInfoPatch[]): MaterialItem[];
+/** 从当前素材库按 material_id 选出待刷新列表；未传则全量有 material_id 的素材。 */
+export declare function pickMaterialsForRefresh(materials: MaterialItem[], materialIdOrIds?: string | string[]): MaterialItem[];
+/**
+ * 初始化刷新分组：轨道实际引用的素材进入首屏关键路径，其余素材留到
+ * 编辑器挂载后刷新。两个分组都保持素材库原有顺序，且忽略无 material_id
+ * 的条目（它们本身无法参与播放信息刷新）。
+ */
+export declare function partitionMaterialsByTrack(materials: MaterialItem[], track: unknown): {
+    trackMaterials: MaterialItem[];
+    remainingMaterials: MaterialItem[];
+};

package/dist/remote-edit-param-schema.d.ts

@@ -0,0 +1,29 @@
+export declare const REMOTE_MEDIA_SPEED_MIN = 0.1;
+export declare const REMOTE_MEDIA_SPEED_MAX = 4;
+export declare const REMOTE_MEDIA_SPEED_DEFAULT = 1;
+export declare const REMOTE_MEDIA_VOLUME_MIN = 0;
+export declare const REMOTE_MEDIA_VOLUME_MAX = 4;
+export declare const REMOTE_TRANSFORM_ALPHA_MIN = 0;
+export declare const REMOTE_TRANSFORM_ALPHA_MAX = 1;
+export declare const REMOTE_COLOR_ADJUSTMENT_MIN = 0;
+export declare const REMOTE_COLOR_ADJUSTMENT_MAX = 1;
+export declare const REMOTE_MEDIA_FADE_MIN_MS = 0;
+export declare const REMOTE_MEDIA_FADE_MAX_MS = 2000;
+export type RemoteEditParamSchemaIssue = {
+    path: string;
+    rule: 'media_speed' | 'media_volume' | 'transform_alpha' | 'color_adjustment' | 'media_fade';
+    reason: 'invalid_number' | 'coerced_number' | 'below_minimum' | 'above_maximum';
+    received: unknown;
+    normalized: number;
+};
+export type RemoteEditParamSchemaResult = {
+    value: Record<string, unknown>;
+    issues: RemoteEditParamSchemaIssue[];
+};
+/**
+ * 远端 editor document 进入 SDK 前的统一 schema 边界。
+ *
+ * 规则采用兼容式清洗：保留未知字段，只修正已声明且会影响 SDK 稳定性的字段。
+ * 新规则应加入 REMOTE_EDIT_PARAM_SCHEMA_RULES，禁止散落到本地编辑/保存链路。
+ */
+export declare function parseRemoteEditParam(input: unknown): RemoteEditParamSchemaResult;

package/dist/runtime/veveditor.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 构建占位模块：发布构建由 build.mjs 替换为内联的 VeVeditor UMD。
+ * 测试环境通过 Vitest mock 此模块注入编辑器实例。
+ */
+declare const VeVeditor: any;
+export default VeVeditor;

package/dist/task-polling.d.ts

@@ -0,0 +1,9 @@
+export declare function getTaskPollDelayMs(attempt: number): number;
+export type TaskPollingController = {
+    cancel: () => void;
+};
+export declare function startTaskPolling(options: {
+    poll: () => Promise<boolean>;
+    onError?: (error: unknown) => void | Promise<void>;
+    getDelayMs?: (attempt: number) => number;
+}): TaskPollingController;

package/dist/task-query-status.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 查询任务信息 API 的官方响应状态。
+ * @see https://docs.volcengine.com/docs/6448/2278532?lang=zh
+ */
+export type AmkTaskQueryStatus = 'running' | 'completed' | 'failed';
+/**
+ * `success` 表示查询请求本身是否成功；查询成功后才读取任务 `status`。
+ * 非官方响应同样按失败收口，避免未知响应被无限轮询。
+ */
+export declare function resolveAmkTaskQueryStatus(payload: unknown): AmkTaskQueryStatus;

package/dist/toast.d.ts

@@ -0,0 +1,36 @@
+export type AmkMessageType = 'info' | 'warning' | 'error' | 'success' | 'loading';
+export interface AmkMessageAction {
+    label: string;
+    onClick: () => void;
+}
+export interface ShowAmkMessageOptions {
+    action?: AmkMessageAction;
+    durationMs?: number;
+    type?: AmkMessageType;
+}
+type MessageCloser = () => void;
+export type AmkMessageScope = {
+    loading: (content: string) => MessageCloser;
+    success: (content: string, options?: Pick<ShowAmkMessageOptions, 'action'>) => MessageCloser;
+    error: (content: string) => MessageCloser;
+    warning: (content: string) => MessageCloser;
+    info: (content: string) => MessageCloser;
+    clear: () => void;
+};
+/** 为单个编辑器/控制器创建消息作用域，销毁时只清理自己的全局 Message。 */
+export declare function createAmkMessageScope(): AmkMessageScope;
+/** VeDesign 全局 Message；保留 AMK 原有命令式调用方式。 */
+export declare const Message: {
+    loading(content: string): MessageCloser;
+    success(content: string, options?: Pick<ShowAmkMessageOptions, "action">): MessageCloser;
+    error(content: string): MessageCloser;
+    warning(content: string): MessageCloser;
+    info(content: string): MessageCloser;
+    clear(): void;
+};
+/** @deprecated 使用 Message.* */
+export declare function showAmkToast(message: string, options?: {
+    type?: Exclude<AmkMessageType, 'loading'>;
+    durationMs?: number;
+}): void;
+export {};

package/dist/tos-upload.d.ts

@@ -0,0 +1,74 @@
+import type { AmkEditorStorageConfig, AmkEditorUploadSTSCredentials, MaterialItem } from './types';
+export declare const DEFAULT_TOS_REGION = "cn-beijing";
+export declare const DEFAULT_SIGNED_URL_EXPIRES_SECONDS: number;
+export declare const TOS_SIGNED_URL_REFRESH_AHEAD_MS: number;
+/** 签名最长 24 小时，但不能超过本次 STS 凭证的剩余有效期。 */
+export declare function resolveSignedUrlExpiresSeconds(credentials: AmkEditorUploadSTSCredentials, now?: number): number;
+/** 解析 TOS V4 签名 URL 的绝对过期时间；非 TOS 签名链返回 null。 */
+export declare function resolveTosSignedUrlExpiresAt(urlValue: unknown): number | null;
+interface TosClientLike {
+    putObject(input: {
+        bucket: string;
+        key: string;
+        body: File;
+        contentType?: string;
+    }): Promise<unknown>;
+    getPreSignedUrl(input: {
+        bucket: string;
+        key: string;
+        method?: 'GET' | 'PUT';
+        expires?: number;
+    }): string;
+}
+interface UploadFilesToTosOptions {
+    files: File[];
+    projectId: string;
+    storage: AmkEditorStorageConfig;
+    createClient?: (credentials: AmkEditorUploadSTSCredentials, region: string) => TosClientLike;
+    /** 单个文件完成 TOS 上传后回调；批量 Promise 会等待该文件的回调完成。 */
+    onFileUploaded?: (material: MaterialItem, index: number) => void | Promise<void>;
+}
+type UploadFileToTosOptions = Omit<UploadFilesToTosOptions, 'files' | 'onFileUploaded'> & {
+    file: File;
+};
+interface RefreshTosMaterialUrlsOptions {
+    materials: MaterialItem[];
+    storage: AmkEditorStorageConfig;
+    createClient?: UploadFilesToTosOptions['createClient'];
+}
+/** TOS 素材的稳定标识已包含 bucket 与 object key，无需额外持久化内部字段。 */
+export declare function parseTosResourceUrl(value: unknown): {
+    bucket: string;
+    key: string;
+} | null;
+/** 业务 ID 可独立于存储地址，优先有效 source_material_id，否则使用 source。 */
+export declare function resolveTosMaterialSource(material: {
+    source_material_id?: unknown;
+    source?: unknown;
+}): string | undefined;
+/** 与素材 TOS 上传保持一致，保留配置的产物存储目录。 */
+export declare function resolveTosOutputDestination(destination: string | undefined): string | undefined;
+/** 使用宿主下发的临时 STS 将本地文件直传客户 TOS，并转换为编辑器素材。 */
+export declare function uploadFilesToTos(options: UploadFilesToTosOptions): Promise<MaterialItem[]>;
+/**
+ * 内置 TOS 的单文件上传实现。本地多选时仍由上层 SDK 调度，
+ * 使 TOS 和业务自定义 onUploadFile 共用同一条逐项回写链路。
+ */
+export declare function uploadFileToTos(options: UploadFileToTosOptions): Promise<MaterialItem>;
+/** 为已持久化的私有 TOS 素材重新生成播放签名，供初始化和按需刷新使用。 */
+export declare function refreshTosMaterialUrls(options: RefreshTosMaterialUrlsOptions): Promise<Array<Partial<MaterialItem> & {
+    material_id: string;
+}>>;
+/** 将任意任务产物中的 tos:// 地址批量签成浏览器可访问的 HTTP URL。 */
+export declare function signTosResourceUrls(options: {
+    urls: unknown[];
+    storage: AmkEditorStorageConfig;
+    createClient?: UploadFilesToTosOptions['createClient'];
+}): Promise<unknown[]>;
+/** 为资产库导入的 TOS 素材签发播放 URL；稳定身份仍保留在 source_material_id。 */
+export declare function signTosImportedMaterialUrls(options: {
+    materials: MaterialItem[];
+    storage: AmkEditorStorageConfig;
+    createClient?: UploadFilesToTosOptions['createClient'];
+}): Promise<MaterialItem[]>;
+export {};