@vvfx/sdk 0.1.19-alpha.1 → 0.1.19-alpha.10

package/dist/index.d.ts

@@ -1,602 +1,755 @@
 import * as _galacean_effects from '@galacean/effects';
-import { spec, math, Player } from '@galacean/effects';
+import { math, spec, Player } from '@galacean/effects';
 export { generateGUID, spec } from '@galacean/effects';
 import { Point } from '@pixi/constants';
 
 /**
- * @description SDKItem 基础选项接口
- * @description 支持扩展属性，允许添加任意额外属性
+ * @class 二维线段
  */
-type SDKItemOptions = {
-    /**
-     * @description 元素ID
-     */
-    id: string;
+declare class Line2 {
+    start: Vector2;
+    end: Vector2;
+    constructor(start?: Vector2, end?: Vector2);
     /**
-     * @description 元素名称
+     * 设置二维线段
+     * @param {Vector2} start 线段起点
+     * @param {Vector2} end 线段终点
+     * @returns {Line2} 二维线段
      */
-    name: string;
+    set(start: Vector2, end: Vector2): this;
     /**
-     * @description 父节点ID
+     * 复制二维线段
+     * @param {Line2} line 复制对象
+     * @returns {Line2} 复制结果
      */
-    parentId?: string;
+    copyFrom(line: Line2): this;
     /**
-     * @description 子元素ID列表
+     * 二维线段求方向
+     * @returns {Vector2} 二维线段方向
      */
-    children?: string[];
+    direction(): Vector2;
     /**
-     * @description 元素生命周期
+     * 二维线段求中点
+     * @param {Vector2} [target=new Vector2()] 目标保存对象
+     * @returns {Vector2} 二维线段中点
      */
-    duration?: number;
+    getCenter(target?: Vector2): Vector2;
     /**
-     * @description 元素生命周期延时
+     * 二维线段向量值
+     * @param {Vector2} [target=new Vector2()] 目标保存对象
+     * @returns {Vector2} 二维线段向量值
      */
-    delay?: number;
+    delta(target?: Vector2): Vector2;
     /**
-     * @description 可视状态
+     * 二维线段欧式距离平方(应用于计算)
+     * @returns {number} 计算结果
      */
-    visible?: boolean;
+    distanceSq(): number;
     /**
-     * @description 元素结束行为
+     * 二维线段欧式距离
+     * @returns {number} 计算结果
      */
-    endBehavior?: spec.EndBehavior;
+    distance(): number;
     /**
-     * @description 是否处于锁定状态
+     * 求二维线段比例点
+     * @param {number} t 比例值
+     * @param {Vector2} target 目标保存对象
+     * @returns {Vector2} 比例点结果
      */
-    isLocked?: boolean;
+    at(t: number, target?: Vector2): Vector2;
     /**
-     * @description 关键属性是否可编辑
+     * 求点与线段的最短距离
+     * @param {Vector2} point 二维空间点
+     * @param {boolean} clampToLine 是否限制于线段内
+     * @returns {number} 距离结果
      */
-    isCoreEditable: boolean;
+    closestPointToPointParameter(point: Vector2, clampToLine: boolean): number;
     /**
-     * @description 扩展属性存储（属性名 -> 属性值）
+     * 求点与线段的最近交点
+     * @param {Vector2} point 二维空间点
+     * @param {boolean} clampToLine 是否限制于线段内
+     * @param {Vector2} target 目标保存对象
+     * @returns {Vector2} 最近交点
      */
-    extension?: Record<string, any>;
+    closestPointToPoint(point: Vector2, clampToLine: boolean, target?: Vector2): Vector2;
     /**
-     * @description 允许任意额外属性（用于兼容旧代码）
+     * 二维线段判等
+     * @param {Line2} line 二维线段
+     * @returns {boolean} 判等结果
      */
-    [extraProp: string]: any;
-};
-/**
- * @description Sprite SDKItem 选项
- */
-type SpriteItemOptions = SDKItemOptions & {
+    equals(line: Line2): boolean;
     /**
-     * @description 元素属性
+     * 克隆二维线段
+     * @returns {Line2} 克隆结果
      */
-    property?: Partial<SpriteItemProperty>;
-};
-/**
- * @description Text SDKItem 选项
- */
-type TextItemOptions = SDKItemOptions & {
+    clone(): Line2;
     /**
-     * @description 元素属性
+     * 二维线段求长度
+     * @returns {number} 长度
      */
-    property?: Partial<TextItemProperty>;
-};
-/**
- * @description Video SDKItem 选项
- */
-type VideoItemOptions = SDKItemOptions & {
+    length(): number;
     /**
-     * @description 元素属性
+     * 二维线段判断相交
+     * @param {Line2} other 二维线段
+     * @returns {boolean} 相交判断结果
      */
-    property?: Partial<VideoItemProperty>;
-};
-/**
- * @description Group SDKItem 选项（空节点/组）
- */
-type GroupItemOptions = SDKItemOptions & {
+    crossWithLine(other: Line2): boolean;
+}
+
+declare class Vector2 extends math.Vector2 {
+    subtract(other: Vector2): this;
+    toViewCoordinate(width: number, height: number): this;
+    clone(): Vector2;
+    distanceTo(other: Vector2): number;
+    scaleByCenter(scalar: Vector2, anchor?: Vector2): this;
+    round(precision?: number): this;
     /**
-     * @description 元素属性
+     * 点到直线的最短距离
+     * @returns {{d: number, t: number}} d表示距离，t表示最近点在直线的比例
      */
-    property?: Partial<GroupItemProperty>;
-};
-/**
- * @description Generator SDKItem 选项（资源生成器）
- * @description 支持 image 和 video 两种生成器类型
- * @description 使用 GeneratorItemProperty 包含 generatorType
- */
-type GeneratorItemOptions = SDKItemOptions & {
+    distanceToLine(line: Line2): {
+        d: number;
+        t: number;
+    };
     /**
-     * @description 元素属性（包含 generatorType）
+     * 二维向量与x轴夹角
+     * @returns {number} 弧度值
      */
-    property?: Partial<GeneratorItemProperty>;
-};
-type EffectsItemOptions = SDKItemOptions & {
-    property?: Partial<EffectsItemProperty>;
-};
-/**
- * @description Frame 画板元素 SDKItem 选项
- */
-type FrameItemOptions = SDKItemOptions & {
+    angle(): number;
     /**
-     * @description 元素属性
+     * 二维点绕点旋转
+     * @param {Vec2} center 旋转中心
+     * @param {number} angle 旋转角度
+     * @returns {Vec2} 旋转结果
      */
-    property?: Partial<FrameItemProperty>;
-};
-/**
- * @description SDKItem 类型（独立于 spec.ItemType）
- * @description 包含所有 SDK 层级的元素类型，包括虚拟类型如 generator
- */
-declare enum SDKItemType {
-    SPRITE = "sprite",
-    TEXT = "text",
-    VIDEO = "video",
-    GROUP = "group",
-    GENERATOR = "generator",
-    EFFECTS = "effects",
-    FRAME = "frame"
+    rotateAround(center: Vector2, angle: number): this;
 }
 
 /**
- * @description SDKItem 抽象基类
- * @description 支持属性扩展，允许添加任意自定义属性
+ * @class 二维包围盒
  */
-declare abstract class BaseItem {
+declare class Box2 {
     /**
-     * @description 元素ID
+     * @member {Vector2[]} corners 二维包围盒角点
      */
-    id: string;
+    corners: Vector2[];
+    min: Vector2;
+    max: Vector2;
     /**
-     * @description 元素名称
+     * 构造函数，传入值为空时表示空包围盒
+     * @param {Vector2} [min=new Vector2(Infinity, Infinity)] 最小点
+     * @param {Vector2} [max=new Vector2(-Infinity, -Infinity)] 最大点
      */
-    name: string;
+    constructor(min?: Vector2, max?: Vector2);
     /**
-     * @description 父节点ID
+     * 通过最大最小点设置二维包围盒
+     * @param {Vector2} min 最小点
+     * @param {Vector2} max 最大点
+     * @returns {Box2} 二维包围盒
      */
-    parentId?: string;
+    set(min: Vector2, max: Vector2): this;
     /**
-     * @description 元素生命周期
+     * 通过角点设置二维包围盒
+     * @param {Vector2[]} vecArray 二维空间点数组
+     * @returns {Box2} 二维包围盒
      */
-    duration: number;
+    setFromVec2Array(vecArray: Vector2[]): this;
     /**
-     * @description 元素生命周期延时
+     * 通过屏幕坐标点设置二维包围盒 - 点为屏幕坐标点，x正方向为右，y正方向为向上
+     * @param vecArray 屏幕坐标点
      */
-    delay: number;
+    setFromVec2ArrayWithOutCorners(vecArray: Vector2[]): this;
     /**
-     * @description 元素结束行为
+     * 通过中心与大小设置二维包围盒
+     * @param {Vector2} center 二维中心点
+     * @param {Vector2} size 二维大小
+     * @returns {Box2} 二维包围盒
      */
-    endBehavior: spec.EndBehavior;
+    setFromCenterAndSize(center: Vector2, size: Vector2): this;
     /**
-     * @description 是否可见
+     * 克隆二维包围盒
+     * @returns {Box2} 克隆结果
      */
-    visible: boolean;
+    clone(): Box2;
     /**
-     * @description 是否处于锁定状态
+     * 复制二维包围盒
+     * @param {Box2} box 二维包围盒
+     * @returns {Box2} 复制结果
      */
-    isLocked: boolean;
-    isCoreEditable: boolean;
+    copyFrom(box: Box2): this;
     /**
-     * @description 扩展属性存储（与 property 同级）
+     * 二维包围盒置空
+     * @returns {Box2} 置空结果
      */
-    private _extension;
+    makeEmpty(): this;
     /**
-     * @description 元素类型（由子类实现）
-     * @description 支持 spec.ItemType 或扩展的 SDKItemType
+     * 二维包围盒判空
+     * @returns {boolean} 判空结果
      */
-    abstract readonly type: SDKItemType;
+    isEmpty(): boolean;
     /**
-     * @description 元素属性（由子类实现）
+     * 获取二维包围盒角点
+     * @returns {Vector2[]} 二维包围盒角点
      */
-    abstract readonly property: BaseItemProperty;
-    constructor(options: SDKItemOptions);
+    getCorners(): Vector2[];
     /**
-     * @description 设置扩展属性
-     * @param key 属性名
-     * @param value 属性值
+     * 获取二维包围盒中心点
+     * @param {Vector2} [target=new Vector2()] 目标点(用以存放二维包围盒中心点)
+     * @returns {Vector2} 二维包围盒中心点
      */
-    setExtension(key: string, value: any): void;
+    getCenter(target?: Vector2): Vector2;
     /**
-     * @description 获取扩展属性
-     * @param key 属性名
-     * @returns 属性值
-     */
-    getExtension(key: string): any;
+     * 获取二维包围盒大小
+     * @param {Vector2} [target=new Vector2()] 目标向量(用以存放二维包围盒大小)
+     * @returns {Vector2} 二维包围盒大小
+     */
+    getSize(target?: Vector2): Vector2;
     /**
-     * @description 检查是否存在指定扩展属性
-     * @param key 属性名
-     * @returns 是否存在
+     * 通过二维空间点扩展二维包围盒
+     * @param {Vector2} point 二维空间点
+     * @returns {Box2} 扩展包围盒
      */
-    hasExtension(key: string): boolean;
+    expandByPoint(point: Vector2): this;
     /**
-     * @description 删除扩展属性
-     * @param key 属性名
-     * @returns 是否删除成功
+     * 通过向量扩展二维包围盒
+     * @param {Vector2} vector 二维向量
+     * @returns {Box2} 扩展结果
      */
-    deleteExtension(key: string): boolean;
+    expandByVector(vector: Vector2): this;
     /**
-     * @description 获取所有扩展属性的键名列表
-     * @returns 键名数组
+     * 通过大小扩展二维包围盒
+     * @param {number} scalar 扩展大小
+     * @returns {Box2} 扩展结果
      */
-    getExtensionKeys(): string[];
+    expandByScalar(scalar: number): this;
     /**
-     * @description 获取所有扩展属性
-     * @returns 扩展属性对象
+     * 判断二维包围盒是否包含二维空间点
+     * @param {Vector2} point 二维空间点
+     * @param {boolean} [isOrthogonal=true] 包围盒正交判断(默认为true)
+     * @returns {boolean} 点包含判断结果
      */
-    getAllExtension(): Record<string, any>;
+    containsPoint(point: Vector2, isOrthogonal?: boolean): boolean;
     /**
-     * @description 批量设置扩展属性
-     * @param extensions 扩展属性对象
+     * 判断二维包围盒包含关系(if this contains other)
+     * @param {Box2} box 其它包围盒
+     * @returns {boolean} 二维包围盒包含判断结果
      */
-    setExtensions(extensions: Record<string, any>): void;
+    containsBox(box: Box2): boolean;
     /**
-     * @description 清空所有扩展属性
+     * 获取点以包围盒左上角顶点为原点的相对位置
+     * @param {Vector2} point 指定二维空间点
+     * @param {Vector2} [target=new Vector2()] 目标空间点
+     * @returns {Vector2} 计算结果空间点
      */
-    clearExtension(): void;
+    getParameter(point: Vector2, target?: Vector2): Vector2;
     /**
-     * @description 转换为 CreateInfo（用于元素复制/导出）
-     * @param withParent 是否包含父节点ID
-     * @returns CreateInfo 对象
+     * 求点与二维包围盒的最近点
+     * @param {Vector2} point 二维空间点
+     * @param {Vector2} [target=new Vector2()] 结果点
+     * @returns {Vector2} 二维空间点
      */
-    abstract toCreateInfo(withParent?: boolean): ItemCreateInfo;
+    clampPoint(point: Vector2, target?: Vector2): Vector2;
     /**
-     * @description 克隆 SDKItem
-     * @returns 新的 SDKItem 实例
+     * 求点到二维包围盒的距离
+     * @param {Vector2} point 二维空间点
+     * @returns {number} 距离
      */
-    abstract clone(): BaseItem;
+    distanceToPoint(point: Vector2): number;
     /**
-     * @description 获取基础属性的 JSON 对象,转换为普通对象（用于序列化）
-     * @returns 普通对象
+     * 二维包围盒求交集
+     * @param {Box2} box 二维包围盒
+     * @returns {Box2} 求交结果
      */
-    toJSON(): Record<string, any>;
+    intersect(box: Box2): this;
+    /**
+     * 二维包围盒求并集
+     * @param {Box2} box 二维包围盒
+     * @returns {Box2} 求并结果
+     */
+    union(target: Box2 | Vector2): this;
+    /**
+     * 二维包围盒位移
+     * @param {Vector2} offset 位移向量
+     * @returns {Box2} 位移结果
+     */
+    translate(offset: Vector2): this;
+    scale(scalar: number | Vector2, anchor?: Vector2): this;
+    /**
+     * 二维包围盒判等
+     * @param {Box2} box 二维包围盒
+     * @returns {boolean} 判等结果
+     */
+    equals(box: Box2): boolean;
+    /**
+     * 判断二维包围盒相交关系(if this intersect other)
+     * @param {Box2} box 二维包围盒
+     * @param {boolean} [isOrthogonal=true] 正交判断(当前包围盒)
+     * @returns {boolean} 相交判断结果
+     */
+    intersectsBox(box: Box2, isOrthogonal?: boolean): boolean;
+    rotate(angle: number, center?: Vector2): this;
 }
-/**
- * @description 类型守卫函数：检查对象是否是 BaseItem
- * @param obj 要检查的对象
- * @returns 是否是 BaseItem 实例
- */
-declare function isBaseItem(obj: any): obj is BaseItem;
 
+type SizeAdaptDirection = 'x' | 'y';
+
+declare const MEDIA_TYPE: {
+    readonly APNG: "APNG";
+    readonly MP4: "MP4";
+    readonly WebM: "WebM";
+    readonly Images: "Images";
+    readonly WebP: "WebP";
+    readonly GIF: "GIF";
+    readonly AlphaMaskVideo: "AlphaMaskVideo";
+};
 /**
- * @description 图片元素 SDKItem 类
- * @description 支持属性扩展
+ * GIF 压缩参数
+ * 核心通过参数 flags + palettegen + paletteuse 实现
+ * highest: lanczos + max_colors=256 + dither=bayer
+ * high: bicubic + max_colors=200 + dither=bayer
+ * medium: bilinear + max_colors=64 + dither=bayer
+ * low: neighbor + max_colors=32 + dither=none
  */
-declare class SpriteItem extends BaseItem {
+declare const GIF_QUALITY_TO_FFMPEG_ARGS: {
+    highest: string;
+    high: string;
+    medium: string;
+    low: string;
+};
+
+declare global {
+    interface Window {
+        /**
+         * @description 创建 WebP Core 实例
+         */
+        createWebPCore: (config: any) => Promise<Img2WebPCore>;
+    }
+}
+type FileBuffer = ArrayBuffer | Uint8Array;
+type MediaType = typeof MEDIA_TYPE[keyof typeof MEDIA_TYPE];
+type FS = {
+    writeFile: (path: string, data: Uint8Array | string) => void;
+    readFile(path: string, opts: {
+        encoding: 'binary';
+        flags?: string | undefined;
+    }): Uint8Array;
+    readFile(path: string, opts: {
+        encoding: 'utf8';
+        flags?: string | undefined;
+    }): string;
+    readFile(path: string, opts?: {
+        flags?: string | undefined;
+    }): Uint8Array;
+    unlink: (path: string) => void;
+    quit: () => void;
+};
+type Pointer = number;
+type Img2WebPCore = {
+    FS: FS;
+    run: (...args: string[]) => number;
+    cwrap: (ident: string, returnType: string, argTypes: string[]) => ((argc: number, argv: Pointer) => number);
+    _malloc: (size: number) => Pointer;
+    writeAsciiToMemory: (str: string, buffer: number, dontAddNull?: boolean) => void;
+    setValue: (ptr: number, value: any, type: string, noSafe?: boolean) => void;
+};
+type ExportMediaInitOptions = {
     /**
-     * @description 元素类型
+     * 导出类型
      */
-    readonly type = SDKItemType.SPRITE;
+    mediaType: MediaType;
     /**
-     * @description 元素属性
+     * 额外画布，导出透明视频时使用
      */
-    property: SpriteItemProperty;
-    constructor(options: SpriteItemOptions);
+    extraCanvas?: HTMLCanvasElement | null;
     /**
-     * @description 图片地址
+     * 是否打印转码过程中的日志，仅在导出 MP4/AlphaMaskVideo 时有效， 默认 false
+     * 供开发调试使用
      */
-    get image(): string;
-    set image(value: string);
+    loggerInTranscoding?: boolean;
     /**
-     * @description 位置
+     * ffmpeg 转码是否开启多线程，默认 false，确保环境支持 SharedArrayBuffer
      */
-    get position(): [number, number];
-    set position(value: [number, number]);
-    get width(): number;
-    set width(value: number);
-    get height(): number;
-    set height(value: number);
+    multiThreading?: boolean;
     /**
-     * @description 旋转（二维旋转角度）
+     * 是否输出 buffer，默认 false
      */
-    get rotation(): number;
-    set rotation(value: number);
+    isOutputBuffer?: boolean;
+};
+type MP4Config = {
     /**
-     * @description 完整旋转（包含 x, y, z）
+     * @description MP4 导出时是否需要导出最后一帧 PNG
      */
-    get fullRotation(): [number, number, number];
-    set fullRotation(value: [number, number, number]);
+    isExportLastFrameJPEG?: boolean;
+};
+type GifConfig = {
     /**
-     * @description 是否正在编辑关键属性
-     * @deprecated 该属性即将废弃，使用 isCoreEditable 代替
+     * @description GIF 导出时的帧率
      */
-    get keyPropertyEditing(): boolean;
-    set keyPropertyEditing(value: boolean);
+    fps?: number;
     /**
-     * @description 转换为 CreateInfo
-     * @param withParent 是否包含父节点ID
+     * @description GIF 导出时的缩放比例
+     * 默认 '-1:-1'， 表示不缩放
+     * 例如 '100:-1'， 表示宽度 100，高度自动
+     * 例如 '-1:100'， 表示宽度自动，高度 100
      */
-    toCreateInfo(withParent?: boolean): SpriteCreateInfo;
+    scale?: string;
     /**
-     * @description 克隆 SDKItem
+     * @description GIF 导出时的质量
+     * 默认 'highest'
+     * 可选 'highest', 'high', 'medium', 'low'
      */
-    clone(): SpriteItem;
+    quality?: keyof typeof GIF_QUALITY_TO_FFMPEG_ARGS;
+};
+type ApngConfig = {
     /**
-     * @description 创建包含扩展属性的 CreateInfo
-     * @param withParent 是否包含父节点ID
-     * @param extraProps 额外的属性
+     * @description APNG 导出时的帧率
      */
-    toCreateInfoWithExtensions(withParent?: boolean, extraProps?: Record<string, any>): SpriteCreateInfo;
-}
-/**
- * @description 类型守卫：检查是否是 SpriteItem
- */
-declare function isSpriteItem(obj: any): obj is SpriteItem;
-
-/**
- * @description 文本元素 SDKItem 类
- * @description 支持属性扩展
- */
-declare class TextItem extends BaseItem {
+    fps?: number;
     /**
-     * @description 元素类型
+     * @description APNG 导出时的缩放比例
+     * 默认 '-1:-1'， 表示不缩放
+     * 例如 '100:-1'， 表示宽度 100，高度自动
+     * 例如 '-1:100'， 表示宽度自动，高度 100
      */
-    readonly type = SDKItemType.TEXT;
+    scale?: string;
     /**
-     * @description 元素属性
+     * @description APNG 导出时的质量
+     * 默认 'highest'
+     * 可选 'highest', 'high', 'medium', 'low'
      */
-    property: TextItemProperty;
-    constructor(options: TextItemOptions);
+    quality?: keyof typeof GIF_QUALITY_TO_FFMPEG_ARGS;
+};
+type ExportMediaItemOptions = {
     /**
-     * @description 文本内容
+     * 尺寸
      */
-    get text(): string;
-    set text(value: string);
+    size: [number, number];
     /**
-     * @description 字体名称
+     * 动效资源
      */
-    get fontFamily(): string;
-    set fontFamily(value: string);
+    scene: spec.JSONScene;
     /**
-     * @description 字号
+     * 视频时长，目前仅在导出 MP4 / AlphaMaskVideo 时有效，默认取动效资源时长
      */
-    get fontSize(): number;
-    set fontSize(value: number);
+    time?: number;
     /**
-     * @description 字重
+     * 是否生成音轨，默认 false，仅在导出 MP4 时有效
      */
-    get fontWeight(): spec.TextWeight;
-    set fontWeight(value: spec.TextWeight);
+    audioEnable?: boolean;
     /**
-     * @description 字体样式
+     * 帧率， 默认 30
      */
-    get fontStyle(): spec.FontStyle;
-    set fontStyle(value: spec.FontStyle);
+    fps?: number;
     /**
-     * @description 文本对齐方式
+     * 是否循环，默认 true
      */
-    get textAlign(): spec.TextAlignment;
-    set textAlign(value: spec.TextAlignment);
+    loop?: boolean;
     /**
-     * @description 文本颜色 [r, g, b, a]
+     * 视频背景颜色，默认 #000000
      */
-    get color(): [number, number, number, number];
-    set color(value: [number, number, number, number]);
+    backgroundColor?: string;
     /**
-     * @description 文本宽度
+     * 导出 MP4 时，设置的导出配置
      */
-    get width(): number;
-    set width(value: number);
+    mp4Config?: MP4Config;
     /**
-     * @description 行高
+     * 导出 GIF 时，设置的导出配置
      */
-    get lineHeight(): number;
-    set lineHeight(value: number);
+    gifConfig?: GifConfig;
     /**
-     * @description 文本高度
+     * 导出 APNG 时，设置的导出配置
      */
-    get height(): number;
-    set height(value: number);
+    apngConfig?: ApngConfig;
+};
+type ExportMediaItemDownloadInfo = {
     /**
-     * @description 描边颜色
+     * @description 导出文件夹名称
      */
-    get outlineColor(): spec.vec4 | undefined;
-    set outlineColor(value: spec.vec4 | undefined);
+    folderName: string;
     /**
-     * @description 描边宽度
+     * @description 导出视频名称
      */
-    get outlineWidth(): number | undefined;
-    set outlineWidth(value: number | undefined);
+    name: string;
+};
+type ExportItemParams = ExportMediaItemOptions & ExportMediaItemDownloadInfo;
+type ExportParams = ExportItemParams[];
+type Buffers = FileBuffer[] | undefined;
+type Extras = (FileBuffer | null)[] | null | undefined;
+
+/**
+ * @description SDKItem 基础选项接口
+ * @description 支持扩展属性，允许添加任意额外属性
+ */
+type SDKItemOptions = {
     /**
-     * @description 描边开关
+     * @description 元素ID
      */
-    get outlineEnabled(): boolean;
-    set outlineEnabled(value: boolean);
+    id: string;
     /**
-     * @description 位置
+     * @description 元素名称
      */
-    get position(): [number, number];
-    set position(value: [number, number]);
+    name: string;
     /**
-     * @description 旋转（二维旋转角度）
+     * @description 父节点ID
      */
-    get rotation(): number;
-    set rotation(value: number);
+    parentId?: string;
     /**
-     * @description 转换为 CreateInfo
-     * @param withParent 是否包含父节点ID
+     * @description 子元素ID列表
      */
-    toCreateInfo(withParent?: boolean): TextCreateInfo;
+    children?: string[];
     /**
-     * @description 克隆 SDKItem
+     * @description 元素生命周期
      */
-    clone(): TextItem;
-}
+    duration?: number;
+    /**
+     * @description 元素生命周期延时
+     */
+    delay?: number;
+    /**
+     * @description 可视状态
+     */
+    visible?: boolean;
+    /**
+     * @description 元素结束行为
+     */
+    endBehavior?: spec.EndBehavior;
+    /**
+     * @description 是否处于锁定状态
+     */
+    isLocked?: boolean;
+    /**
+     * @description 关键属性是否可编辑
+     */
+    isCoreEditable: boolean;
+    /**
+     * @description 扩展属性存储（属性名 -> 属性值）
+     */
+    extension?: Record<string, any>;
+    /**
+     * @description 允许任意额外属性（用于兼容旧代码）
+     */
+    [extraProp: string]: any;
+};
 /**
- * @description 类型守卫：检查是否是 TextItem
+ * @description Sprite SDKItem 选项
  */
-declare function isTextItem(obj: any): obj is TextItem;
-
+type SpriteItemOptions = SDKItemOptions & {
+    /**
+     * @description 元素属性
+     */
+    property?: Partial<SpriteItemProperty>;
+};
 /**
- * @description 视频元素 SDKItem 类
- * @description 支持属性扩展
+ * @description Text SDKItem 选项
  */
-declare class VideoItem extends BaseItem {
+type TextItemOptions = SDKItemOptions & {
     /**
-     * @description 元素类型
+     * @description 元素属性
      */
-    readonly type = SDKItemType.VIDEO;
+    property?: Partial<TextItemProperty>;
+};
+/**
+ * @description Video SDKItem 选项
+ */
+type VideoItemOptions = SDKItemOptions & {
     /**
      * @description 元素属性
      */
-    property: VideoItemProperty;
-    constructor(options: VideoItemOptions);
+    property?: Partial<VideoItemProperty>;
+};
+/**
+ * @description Group SDKItem 选项（空节点/组）
+ */
+type GroupItemOptions = SDKItemOptions & {
     /**
-     * @description 视频地址
+     * @description 元素属性
      */
-    get video(): string;
-    set video(value: string);
+    property?: Partial<GroupItemProperty>;
+};
+/**
+ * @description Generator SDKItem 选项（资源生成器）
+ * @description 支持 image 和 video 两种生成器类型
+ * @description 使用 GeneratorItemProperty 包含 generatorType
+ */
+type GeneratorItemOptions = SDKItemOptions & {
     /**
-     * @description 位置
+     * @description 元素属性（包含 generatorType）
      */
-    get position(): [number, number];
-    set position(value: [number, number]);
+    property?: Partial<GeneratorItemProperty>;
+};
+type EffectsItemOptions = SDKItemOptions & {
+    property?: Partial<EffectsItemProperty>;
+};
+/**
+ * @description Frame 画板元素 SDKItem 选项
+ */
+type FrameItemOptions = SDKItemOptions & {
     /**
-     * @description 宽度
+     * @description 元素属性
      */
-    get width(): number;
-    set width(value: number);
+    property?: Partial<FrameItemProperty>;
+};
+/**
+ * @description SDKItem 类型（独立于 spec.ItemType）
+ * @description 包含所有 SDK 层级的元素类型，包括虚拟类型如 generator
+ */
+declare enum SDKItemType {
+    SPRITE = "sprite",
+    TEXT = "text",
+    VIDEO = "video",
+    GROUP = "group",
+    GENERATOR = "generator",
+    EFFECTS = "effects",
+    FRAME = "frame"
+}
+
+/**
+ * @description SDKItem 抽象基类
+ * @description 支持属性扩展，允许添加任意自定义属性
+ */
+declare abstract class BaseItem {
     /**
-     * @description 高度
+     * @description 元素ID
      */
-    get height(): number;
-    set height(value: number);
+    id: string;
     /**
-     * @description 旋转（二维旋转角度）
+     * @description 元素名称
+     */
+    name: string;
+    /**
+     * @description 父节点ID
+     */
+    parentId?: string;
+    /**
+     * @description 元素生命周期
+     */
+    duration: number;
+    /**
+     * @description 元素生命周期延时
      */
-    get rotation(): number;
-    set rotation(value: number);
+    delay: number;
     /**
-     * @description 完整旋转（包含 x, y, z）
+     * @description 元素结束行为
      */
-    get fullRotation(): [number, number, number];
-    set fullRotation(value: [number, number, number]);
+    endBehavior: spec.EndBehavior;
     /**
-     * @description 是否正在编辑关键属性
-     * @deprecated 该属性即将废弃，使用 isCoreEditable 代替
+     * @description 是否可见
      */
-    get keyPropertyEditing(): boolean;
-    set keyPropertyEditing(value: boolean);
+    visible: boolean;
     /**
-     * @description 是否静音
+     * @description 是否处于锁定状态
      */
-    get muted(): boolean;
-    set muted(state: boolean);
+    isLocked: boolean;
     /**
-     * @description 是否为透明视频
+     * @description 核心数据是否支持编辑
      */
-    get transparent(): boolean;
-    set transparent(state: boolean);
+    isCoreEditable: boolean;
     /**
-     * @description 播放音量
+     * @description 扩展属性存储（与 property 同级）
      */
-    get volume(): number;
-    set volume(value: number);
+    extension: Map<string, any>;
     /**
-     * @description 播放速率
+     * @description 元素类型（由子类实现）
+     * @description 支持 spec.ItemType 或扩展的 SDKItemType
      */
-    get playbackRate(): number;
-    set playbackRate(value: number);
+    abstract readonly type: SDKItemType;
     /**
-     * @description 转换为 CreateInfo
-     * @param withParent 是否包含父节点ID
+     * @description 元素属性（由子类实现）
      */
-    toCreateInfo(withParent?: boolean): VideoCreateInfo;
+    abstract readonly property: BaseItemProperty;
+    constructor(options: SDKItemOptions);
     /**
-     * @description 克隆 SDKItem
+     * @description 设置扩展属性
+     * @param key 属性名
+     * @param value 属性值
      */
-    clone(): VideoItem;
-}
-/**
- * @description 类型守卫：检查是否是 VideoItem
- */
-declare function isVideoItem(obj: any): obj is VideoItem;
-
-/**
- * @description 空节点/组 SDKItem 类
- * @description 支持属性扩展
- */
-declare class GroupItem extends BaseItem {
+    setExtension(key: string, value: any): void;
     /**
-     * @description 元素类型
+     * @description 获取扩展属性
+     * @param key 属性名
+     * @returns 属性值
      */
-    readonly type = SDKItemType.GROUP;
+    getExtension(key: string): any;
     /**
-     * @description 元素属性
+     * @description 检查是否存在指定扩展属性
+     * @param key 属性名
+     * @returns 是否存在
      */
-    property: GroupItemProperty;
-    constructor(options: GroupItemOptions);
+    hasExtension(key: string): boolean;
     /**
-     * @description 位置
+     * @description 删除扩展属性
+     * @param key 属性名
+     * @returns 是否删除成功
      */
-    get position(): [number, number];
-    set position(value: [number, number]);
+    deleteExtension(key: string): boolean;
     /**
-     * @description 大小
+     * @description 获取所有扩展属性的键名列表
+     * @returns 键名数组
      */
-    get scale(): [number, number];
-    set scale(value: [number, number]);
+    getExtensionKeys(): string[];
     /**
-     * @description 旋转（二维旋转角度）
+     * @description 获取所有扩展属性
+     * @returns 扩展属性对象
      */
-    get rotation(): number;
-    set rotation(value: number);
+    getAllExtension(): Record<string, any>;
     /**
-     * @description 完整旋转（包含 x, y, z）
+     * @description 批量设置扩展属性
+     * @param extensions 扩展属性对象
      */
-    get fullRotation(): [number, number, number];
-    set fullRotation(value: [number, number, number]);
+    setExtensions(extensions: Record<string, any>): void;
     /**
-     * @description 是否正在编辑关键属性
-     * @deprecated 该属性即将废弃，使用 isCoreEditable 代替
+     * @description 清空所有扩展属性
      */
-    get keyPropertyEditing(): boolean;
-    set keyPropertyEditing(value: boolean);
+    clearExtension(): void;
     /**
-     * @description 转换为 CreateInfo
+     * @description 转换为 CreateInfo（用于元素复制/导出）
      * @param withParent 是否包含父节点ID
+     * @returns CreateInfo 对象
      */
-    toCreateInfo(withParent?: boolean): GroupCreateInfo;
+    abstract toCreateInfo(withParent?: boolean): ItemCreateInfo;
     /**
      * @description 克隆 SDKItem
+     * @returns 新的 SDKItem 实例
      */
-    clone(): GroupItem;
+    abstract clone(): BaseItem;
+    /**
+     * @description 获取基础属性的 JSON 对象,转换为普通对象（用于序列化）
+     * @returns 普通对象
+     */
+    toJSON(): Record<string, any>;
 }
 /**
- * @description 类型守卫：检查是否是 GroupItem
+ * @description 类型守卫函数：检查对象是否是 BaseItem
+ * @param obj 要检查的对象
+ * @returns 是否是 BaseItem 实例
  */
-declare function isGroupItem(obj: any): obj is GroupItem;
+declare function isBaseItem(obj: any): obj is BaseItem;
 
 /**
- * @description 资源生成器元素 SDKItem 类
- * @description 支持 image 和 video 两种生成器类型
- * @description 在 Player 中以透明 SpriteItem 形式渲染
- * @description 支持属性扩展，可转换为 SpriteItem 或 VideoItem
+ * @description 图片元素 SDKItem 类
+ * @description 支持属性扩展
  */
-declare class GeneratorItem extends BaseItem {
-    /**
-     * @description 元素类型（独立类型，不属于 spec.ItemType）
-     */
-    readonly type = SDKItemType.GENERATOR;
+declare class SpriteItem extends BaseItem {
     /**
-     * @description 元素属性（包含 generatorType）
+     * @description 元素类型
      */
-    property: GeneratorItemProperty;
-    constructor(options: GeneratorItemOptions);
+    readonly type = SDKItemType.SPRITE;
     /**
-     * @description 生成器类型
+     * @description 元素属性
      */
-    get generatorType(): 'image' | 'video';
-    set generatorType(value: 'image' | 'video');
+    property: SpriteItemProperty;
+    constructor(options: SpriteItemOptions);
     /**
-     * @description 图片地址（生成器返回空）
+     * @description 图片地址
      */
     get image(): string;
-    set image(_value: string);
+    set image(value: string);
     /**
      * @description 位置
      */
     get position(): [number, number];
     set position(value: [number, number]);
-    /**
-     * @description 宽度
-     */
     get width(): number;
     set width(value: number);
-    /**
-     * @description 高度
-     */
     get height(): number;
     set height(value: number);
     /**
@@ -616,120 +769,149 @@ declare class GeneratorItem extends BaseItem {
     get keyPropertyEditing(): boolean;
     set keyPropertyEditing(value: boolean);
     /**
-     * @description 转换为 GeneratorCreateInfo
+     * @description 转换为 CreateInfo
      * @param withParent 是否包含父节点ID
      */
-    toCreateInfo(withParent?: boolean): GeneratorCreateInfo;
+    toCreateInfo(withParent?: boolean): SpriteCreateInfo;
     /**
-     * @description 转换为 VideoCreateInfo（用于转换为视频元素）
-     * @param videoUrl 视频资源地址
-     * @param withParent 是否包含父节点ID
+     * @description 克隆 SDKItem
      */
-    toVideoCreateInfo(videoUrl: string, withParent?: boolean): VideoCreateInfo;
+    clone(): SpriteItem;
     /**
-     * @description 转换为 SpriteCreateInfo（用于转换为图片元素）
-     * @param imageUrl 图片资源地址
+     * @description 创建包含扩展属性的 CreateInfo
      * @param withParent 是否包含父节点ID
+     * @param extraProps 额外的属性
      */
-    toSpriteCreateInfo(imageUrl: string, withParent?: boolean): SpriteCreateInfo;
-    /**
-     * @description 克隆 SDKItem
-     */
-    clone(): GeneratorItem;
+    toCreateInfoWithExtensions(withParent?: boolean, extraProps?: Record<string, any>): SpriteCreateInfo;
 }
 /**
- * @description 类型守卫：检查是否是 GeneratorItem
+ * @description 类型守卫：检查是否是 SpriteItem
  */
-declare function isGeneratorItem(obj: any): obj is GeneratorItem;
+declare function isSpriteItem(obj: any): obj is SpriteItem;
 
 /**
- * @description 特效产物 元素 SDKItem 类
+ * @description 文本元素 SDKItem 类
+ * @description 支持属性扩展
  */
-declare class EffectsItem extends BaseItem {
+declare class TextItem extends BaseItem {
     /**
-     * @description 元素类型（独立类型，不属于 spec.ItemType）
+     * @description 元素类型
      */
-    readonly type = SDKItemType.EFFECTS;
+    readonly type = SDKItemType.TEXT;
     /**
      * @description 元素属性
      */
-    property: EffectsItemProperty;
-    constructor(options: EffectsItemOptions);
+    property: TextItemProperty;
+    constructor(options: TextItemOptions);
     /**
-     * @description 特效资源地址
+     * @description 文本内容
      */
-    get effects(): string;
-    set effects(value: string);
+    get text(): string;
+    set text(value: string);
     /**
-     * @description 位置
+     * @description 字体名称
      */
-    get position(): [number, number];
-    set position(value: [number, number]);
+    get fontFamily(): string;
+    set fontFamily(value: string);
     /**
-     * @description 宽度
+     * @description 字号
+     */
+    get fontSize(): number;
+    set fontSize(value: number);
+    /**
+     * @description 字重
+     */
+    get fontWeight(): spec.TextWeight;
+    set fontWeight(value: spec.TextWeight);
+    /**
+     * @description 字体样式
+     */
+    get fontStyle(): spec.FontStyle;
+    set fontStyle(value: spec.FontStyle);
+    /**
+     * @description 文本对齐方式
+     */
+    get textAlign(): spec.TextAlignment;
+    set textAlign(value: spec.TextAlignment);
+    /**
+     * @description 文本颜色 [r, g, b, a]
+     */
+    get color(): [number, number, number, number];
+    set color(value: [number, number, number, number]);
+    /**
+     * @description 文本宽度
      */
     get width(): number;
     set width(value: number);
     /**
-     * @description 高度
+     * @description 行高
+     */
+    get lineHeight(): number;
+    set lineHeight(value: number);
+    /**
+     * @description 文本高度
      */
     get height(): number;
     set height(value: number);
     /**
-     * @description 旋转（二维旋转角度）
+     * @description 描边颜色
      */
-    get rotation(): number;
-    set rotation(value: number);
+    get outlineColor(): spec.vec4 | undefined;
+    set outlineColor(value: spec.vec4 | undefined);
     /**
-     * @description 完整旋转（包含 x, y, z）
+     * @description 描边宽度
      */
-    get fullRotation(): [number, number, number];
-    set fullRotation(value: [number, number, number]);
+    get outlineWidth(): number | undefined;
+    set outlineWidth(value: number | undefined);
+    /**
+     * @description 描边开关
+     */
+    get outlineEnabled(): boolean;
+    set outlineEnabled(value: boolean);
+    /**
+     * @description 位置
+     */
+    get position(): [number, number];
+    set position(value: [number, number]);
     /**
-     * @description 是否正在编辑关键属性
-     * @deprecated 该属性即将废弃，使用 isCoreEditable 代替
+     * @description 旋转（二维旋转角度）
      */
-    get keyPropertyEditing(): boolean;
-    set keyPropertyEditing(value: boolean);
+    get rotation(): number;
+    set rotation(value: number);
     /**
-     * @description 转换为 EffectsCreateInfo
+     * @description 转换为 CreateInfo
      * @param withParent 是否包含父节点ID
      */
-    toCreateInfo(withParent?: boolean): EffectsCreateInfo;
+    toCreateInfo(withParent?: boolean): TextCreateInfo;
     /**
      * @description 克隆 SDKItem
      */
-    clone(): EffectsItem;
+    clone(): TextItem;
 }
 /**
- * @description 类型守卫：检查是否是 EffectsItem
+ * @description 类型守卫：检查是否是 TextItem
  */
-declare function isEffectsItem(obj: any): obj is EffectsItem;
+declare function isTextItem(obj: any): obj is TextItem;
 
 /**
- * @description 画板/框架元素 SDKItem 类
- * @description 支持自动布局和自由布局两种模式
- * @description 底层以 composition 形式渲染
+ * @description 视频元素 SDKItem 类
+ * @description 支持属性扩展
  */
-declare class FrameItem extends BaseItem {
+declare class VideoItem extends BaseItem {
     /**
      * @description 元素类型
      */
-    readonly type = SDKItemType.FRAME;
+    readonly type = SDKItemType.VIDEO;
     /**
      * @description 元素属性
      */
-    property: FrameItemProperty;
-    constructor(options: FrameItemOptions);
-    /**
-     * @description 子元素ID列表（只读）
-     */
-    get children(): readonly string[];
+    property: VideoItemProperty;
+    constructor(options: VideoItemOptions);
     /**
-     * @description 布局模式
+     * @description 视频地址
      */
-    get layoutMode(): FrameLayoutMode;
-    set layoutMode(value: FrameLayoutMode);
+    get video(): string;
+    set video(value: string);
     /**
      * @description 位置
      */
@@ -745,11 +927,6 @@ declare class FrameItem extends BaseItem {
      */
     get height(): number;
     set height(value: number);
-    /**
-     * @description 缩放
-     */
-    get scale(): [number, number];
-    set scale(value: [number, number]);
     /**
      * @description 旋转（二维旋转角度）
      */
@@ -761,535 +938,369 @@ declare class FrameItem extends BaseItem {
     get fullRotation(): [number, number, number];
     set fullRotation(value: [number, number, number]);
     /**
-     * @description 添加子元素
-     * @param itemId 子元素ID
-     * @returns 是否添加成功
-     */
-    addChild(itemId: string): boolean;
-    /**
-     * @description 批量添加子元素
-     * @param itemIds 子元素ID列表
+     * @description 是否正在编辑关键属性
+     * @deprecated 该属性即将废弃，使用 isCoreEditable 代替
      */
-    addChildren(itemIds: string[]): void;
+    get keyPropertyEditing(): boolean;
+    set keyPropertyEditing(value: boolean);
     /**
-     * @description 移除子元素
-     * @param itemId 子元素ID
-     * @returns 是否移除成功
+     * @description 是否静音
      */
-    removeChild(itemId: string): boolean;
+    get muted(): boolean;
+    set muted(state: boolean);
     /**
-     * @description 批量移除子元素
-     * @param itemIds 子元素ID列表
+     * @description 是否为透明视频
      */
-    removeChildren(itemIds: string[]): void;
+    get transparent(): boolean;
+    set transparent(state: boolean);
     /**
-     * @description 是否包含指定子元素
-     * @param itemId 子元素ID
+     * @description 播放音量
      */
-    hasChild(itemId: string): boolean;
+    get volume(): number;
+    set volume(value: number);
     /**
-     * @description 清空所有子元素
+     * @description 播放速率
      */
-    clearChildren(): void;
+    get playbackRate(): number;
+    set playbackRate(value: number);
     /**
-     * @description 转换为 FrameCreateInfo
+     * @description 转换为 CreateInfo
      * @param withParent 是否包含父节点ID
      */
-    toCreateInfo(withParent?: boolean): FrameCreateInfo;
+    toCreateInfo(withParent?: boolean): VideoCreateInfo;
     /**
      * @description 克隆 SDKItem
      */
-    clone(): FrameItem;
+    clone(): VideoItem;
 }
 /**
- * @description 类型守卫：检查是否是 FrameItem
- */
-declare function isFrameItem(obj: any): obj is FrameItem;
-
-/**
- * @description 根据 item type 创建对应的 SDKItem 实例
- * @param type 元素类型
- * @param options SDKItem 选项
- * @returns SDKItem 实例
- */
-declare function createSDKItem(type: spec.ItemType, options: SDKItemOptions): BaseItem;
-/**
- * @description SDKItem 类型联合
- * @description 用于替换原来的 SDKItem type
- */
-type SDKItem$1 = SpriteItem | TextItem | VideoItem | GroupItem | GeneratorItem | EffectsItem | FrameItem;
-
-/**
- * @class 二维线段
+ * @description 类型守卫：检查是否是 VideoItem
  */
-declare class Line2 {
-    start: Vector2;
-    end: Vector2;
-    constructor(start?: Vector2, end?: Vector2);
-    /**
-     * 设置二维线段
-     * @param {Vector2} start 线段起点
-     * @param {Vector2} end 线段终点
-     * @returns {Line2} 二维线段
-     */
-    set(start: Vector2, end: Vector2): this;
-    /**
-     * 复制二维线段
-     * @param {Line2} line 复制对象
-     * @returns {Line2} 复制结果
-     */
-    copyFrom(line: Line2): this;
-    /**
-     * 二维线段求方向
-     * @returns {Vector2} 二维线段方向
-     */
-    direction(): Vector2;
-    /**
-     * 二维线段求中点
-     * @param {Vector2} [target=new Vector2()] 目标保存对象
-     * @returns {Vector2} 二维线段中点
-     */
-    getCenter(target?: Vector2): Vector2;
-    /**
-     * 二维线段向量值
-     * @param {Vector2} [target=new Vector2()] 目标保存对象
-     * @returns {Vector2} 二维线段向量值
-     */
-    delta(target?: Vector2): Vector2;
-    /**
-     * 二维线段欧式距离平方(应用于计算)
-     * @returns {number} 计算结果
-     */
-    distanceSq(): number;
-    /**
-     * 二维线段欧式距离
-     * @returns {number} 计算结果
-     */
-    distance(): number;
-    /**
-     * 求二维线段比例点
-     * @param {number} t 比例值
-     * @param {Vector2} target 目标保存对象
-     * @returns {Vector2} 比例点结果
-     */
-    at(t: number, target?: Vector2): Vector2;
-    /**
-     * 求点与线段的最短距离
-     * @param {Vector2} point 二维空间点
-     * @param {boolean} clampToLine 是否限制于线段内
-     * @returns {number} 距离结果
-     */
-    closestPointToPointParameter(point: Vector2, clampToLine: boolean): number;
-    /**
-     * 求点与线段的最近交点
-     * @param {Vector2} point 二维空间点
-     * @param {boolean} clampToLine 是否限制于线段内
-     * @param {Vector2} target 目标保存对象
-     * @returns {Vector2} 最近交点
-     */
-    closestPointToPoint(point: Vector2, clampToLine: boolean, target?: Vector2): Vector2;
-    /**
-     * 二维线段判等
-     * @param {Line2} line 二维线段
-     * @returns {boolean} 判等结果
-     */
-    equals(line: Line2): boolean;
-    /**
-     * 克隆二维线段
-     * @returns {Line2} 克隆结果
-     */
-    clone(): Line2;
-    /**
-     * 二维线段求长度
-     * @returns {number} 长度
-     */
-    length(): number;
-    /**
-     * 二维线段判断相交
-     * @param {Line2} other 二维线段
-     * @returns {boolean} 相交判断结果
-     */
-    crossWithLine(other: Line2): boolean;
-}
-
-declare class Vector2 extends math.Vector2 {
-    subtract(other: Vector2): this;
-    toViewCoordinate(width: number, height: number): this;
-    clone(): Vector2;
-    distanceTo(other: Vector2): number;
-    scaleByCenter(scalar: Vector2, anchor?: Vector2): this;
-    round(precision?: number): this;
-    /**
-     * 点到直线的最短距离
-     * @returns {{d: number, t: number}} d表示距离，t表示最近点在直线的比例
-     */
-    distanceToLine(line: Line2): {
-        d: number;
-        t: number;
-    };
-    /**
-     * 二维向量与x轴夹角
-     * @returns {number} 弧度值
-     */
-    angle(): number;
-    /**
-     * 二维点绕点旋转
-     * @param {Vec2} center 旋转中心
-     * @param {number} angle 旋转角度
-     * @returns {Vec2} 旋转结果
-     */
-    rotateAround(center: Vector2, angle: number): this;
-}
+declare function isVideoItem(obj: any): obj is VideoItem;
 
 /**
- * @class 二维包围盒
+ * @description 空节点/组 SDKItem 类
+ * @description 支持属性扩展
  */
-declare class Box2 {
-    /**
-     * @member {Vector2[]} corners 二维包围盒角点
-     */
-    corners: Vector2[];
-    min: Vector2;
-    max: Vector2;
-    /**
-     * 构造函数，传入值为空时表示空包围盒
-     * @param {Vector2} [min=new Vector2(Infinity, Infinity)] 最小点
-     * @param {Vector2} [max=new Vector2(-Infinity, -Infinity)] 最大点
-     */
-    constructor(min?: Vector2, max?: Vector2);
-    /**
-     * 通过最大最小点设置二维包围盒
-     * @param {Vector2} min 最小点
-     * @param {Vector2} max 最大点
-     * @returns {Box2} 二维包围盒
-     */
-    set(min: Vector2, max: Vector2): this;
-    /**
-     * 通过角点设置二维包围盒
-     * @param {Vector2[]} vecArray 二维空间点数组
-     * @returns {Box2} 二维包围盒
+declare class GroupItem extends BaseItem {
+    /**
+     * @description 元素类型
      */
-    setFromVec2Array(vecArray: Vector2[]): this;
+    readonly type = SDKItemType.GROUP;
     /**
-     * 通过屏幕坐标点设置二维包围盒 - 点为屏幕坐标点，x正方向为右，y正方向为向上
-     * @param vecArray 屏幕坐标点
+     * @description 元素属性
      */
-    setFromVec2ArrayWithOutCorners(vecArray: Vector2[]): this;
+    property: GroupItemProperty;
+    constructor(options: GroupItemOptions);
     /**
-     * 通过中心与大小设置二维包围盒
-     * @param {Vector2} center 二维中心点
-     * @param {Vector2} size 二维大小
-     * @returns {Box2} 二维包围盒
+     * @description 位置
      */
-    setFromCenterAndSize(center: Vector2, size: Vector2): this;
+    get position(): [number, number];
+    set position(value: [number, number]);
     /**
-     * 克隆二维包围盒
-     * @returns {Box2} 克隆结果
+     * @description 大小
      */
-    clone(): Box2;
+    get scale(): [number, number];
+    set scale(value: [number, number]);
     /**
-     * 复制二维包围盒
-     * @param {Box2} box 二维包围盒
-     * @returns {Box2} 复制结果
+     * @description 旋转（二维旋转角度）
      */
-    copyFrom(box: Box2): this;
+    get rotation(): number;
+    set rotation(value: number);
     /**
-     * 二维包围盒置空
-     * @returns {Box2} 置空结果
+     * @description 完整旋转（包含 x, y, z）
      */
-    makeEmpty(): this;
+    get fullRotation(): [number, number, number];
+    set fullRotation(value: [number, number, number]);
     /**
-     * 二维包围盒判空
-     * @returns {boolean} 判空结果
+     * @description 是否正在编辑关键属性
+     * @deprecated 该属性即将废弃，使用 isCoreEditable 代替
      */
-    isEmpty(): boolean;
+    get keyPropertyEditing(): boolean;
+    set keyPropertyEditing(value: boolean);
     /**
-     * 获取二维包围盒角点
-     * @returns {Vector2[]} 二维包围盒角点
+     * @description 转换为 CreateInfo
+     * @param withParent 是否包含父节点ID
      */
-    getCorners(): Vector2[];
+    toCreateInfo(withParent?: boolean): GroupCreateInfo;
     /**
-     * 获取二维包围盒中心点
-     * @param {Vector2} [target=new Vector2()] 目标点(用以存放二维包围盒中心点)
-     * @returns {Vector2} 二维包围盒中心点
+     * @description 克隆 SDKItem
      */
-    getCenter(target?: Vector2): Vector2;
+    clone(): GroupItem;
+}
+/**
+ * @description 类型守卫：检查是否是 GroupItem
+ */
+declare function isGroupItem(obj: any): obj is GroupItem;
+
+/**
+ * @description 资源生成器元素 SDKItem 类
+ * @description 支持 image 和 video 两种生成器类型
+ * @description 在 Player 中以透明 SpriteItem 形式渲染
+ * @description 支持属性扩展，可转换为 SpriteItem 或 VideoItem
+ */
+declare class GeneratorItem extends BaseItem {
     /**
-     * 获取二维包围盒大小
-     * @param {Vector2} [target=new Vector2()] 目标向量(用以存放二维包围盒大小)
-     * @returns {Vector2} 二维包围盒大小
+     * @description 元素类型（独立类型，不属于 spec.ItemType）
      */
-    getSize(target?: Vector2): Vector2;
+    readonly type = SDKItemType.GENERATOR;
     /**
-     * 通过二维空间点扩展二维包围盒
-     * @param {Vector2} point 二维空间点
-     * @returns {Box2} 扩展包围盒
+     * @description 元素属性（包含 generatorType）
      */
-    expandByPoint(point: Vector2): this;
+    property: GeneratorItemProperty;
+    constructor(options: GeneratorItemOptions);
     /**
-     * 通过向量扩展二维包围盒
-     * @param {Vector2} vector 二维向量
-     * @returns {Box2} 扩展结果
+     * @description 生成器类型
      */
-    expandByVector(vector: Vector2): this;
+    get generatorType(): 'image' | 'video';
+    set generatorType(value: 'image' | 'video');
     /**
-     * 通过大小扩展二维包围盒
-     * @param {number} scalar 扩展大小
-     * @returns {Box2} 扩展结果
+     * @description 图片地址（生成器返回空）
      */
-    expandByScalar(scalar: number): this;
+    get image(): string;
+    set image(_value: string);
     /**
-     * 判断二维包围盒是否包含二维空间点
-     * @param {Vector2} point 二维空间点
-     * @param {boolean} [isOrthogonal=true] 包围盒正交判断(默认为true)
-     * @returns {boolean} 点包含判断结果
+     * @description 位置
      */
-    containsPoint(point: Vector2, isOrthogonal?: boolean): boolean;
+    get position(): [number, number];
+    set position(value: [number, number]);
     /**
-     * 判断二维包围盒包含关系(if this contains other)
-     * @param {Box2} box 其它包围盒
-     * @returns {boolean} 二维包围盒包含判断结果
+     * @description 宽度
      */
-    containsBox(box: Box2): boolean;
+    get width(): number;
+    set width(value: number);
     /**
-     * 获取点以包围盒左上角顶点为原点的相对位置
-     * @param {Vector2} point 指定二维空间点
-     * @param {Vector2} [target=new Vector2()] 目标空间点
-     * @returns {Vector2} 计算结果空间点
+     * @description 高度
      */
-    getParameter(point: Vector2, target?: Vector2): Vector2;
+    get height(): number;
+    set height(value: number);
     /**
-     * 求点与二维包围盒的最近点
-     * @param {Vector2} point 二维空间点
-     * @param {Vector2} [target=new Vector2()] 结果点
-     * @returns {Vector2} 二维空间点
+     * @description 旋转（二维旋转角度）
      */
-    clampPoint(point: Vector2, target?: Vector2): Vector2;
+    get rotation(): number;
+    set rotation(value: number);
     /**
-     * 求点到二维包围盒的距离
-     * @param {Vector2} point 二维空间点
-     * @returns {number} 距离
+     * @description 完整旋转（包含 x, y, z）
      */
-    distanceToPoint(point: Vector2): number;
+    get fullRotation(): [number, number, number];
+    set fullRotation(value: [number, number, number]);
     /**
-     * 二维包围盒求交集
-     * @param {Box2} box 二维包围盒
-     * @returns {Box2} 求交结果
+     * @description 是否正在编辑关键属性
+     * @deprecated 该属性即将废弃，使用 isCoreEditable 代替
      */
-    intersect(box: Box2): this;
+    get keyPropertyEditing(): boolean;
+    set keyPropertyEditing(value: boolean);
     /**
-     * 二维包围盒求并集
-     * @param {Box2} box 二维包围盒
-     * @returns {Box2} 求并结果
+     * @description 转换为 GeneratorCreateInfo
+     * @param withParent 是否包含父节点ID
      */
-    union(target: Box2 | Vector2): this;
+    toCreateInfo(withParent?: boolean): GeneratorCreateInfo;
     /**
-     * 二维包围盒位移
-     * @param {Vector2} offset 位移向量
-     * @returns {Box2} 位移结果
+     * @description 转换为 VideoCreateInfo（用于转换为视频元素）
+     * @param videoUrl 视频资源地址
+     * @param withParent 是否包含父节点ID
      */
-    translate(offset: Vector2): this;
-    scale(scalar: number | Vector2, anchor?: Vector2): this;
+    toVideoCreateInfo(videoUrl: string, withParent?: boolean): VideoCreateInfo;
     /**
-     * 二维包围盒判等
-     * @param {Box2} box 二维包围盒
-     * @returns {boolean} 判等结果
+     * @description 转换为 SpriteCreateInfo（用于转换为图片元素）
+     * @param imageUrl 图片资源地址
+     * @param withParent 是否包含父节点ID
      */
-    equals(box: Box2): boolean;
+    toSpriteCreateInfo(imageUrl: string, withParent?: boolean): SpriteCreateInfo;
     /**
-     * 判断二维包围盒相交关系(if this intersect other)
-     * @param {Box2} box 二维包围盒
-     * @param {boolean} [isOrthogonal=true] 正交判断(当前包围盒)
-     * @returns {boolean} 相交判断结果
+     * @description 克隆 SDKItem
      */
-    intersectsBox(box: Box2, isOrthogonal?: boolean): boolean;
-    rotate(angle: number, center?: Vector2): this;
+    clone(): GeneratorItem;
 }
-
-type SizeAdaptDirection = 'x' | 'y';
-
-declare const MEDIA_TYPE: {
-    readonly APNG: "APNG";
-    readonly MP4: "MP4";
-    readonly WebM: "WebM";
-    readonly Images: "Images";
-    readonly WebP: "WebP";
-    readonly GIF: "GIF";
-    readonly AlphaMaskVideo: "AlphaMaskVideo";
-};
 /**
- * GIF 压缩参数
- * 核心通过参数 flags + palettegen + paletteuse 实现
- * highest: lanczos + max_colors=256 + dither=bayer
- * high: bicubic + max_colors=200 + dither=bayer
- * medium: bilinear + max_colors=64 + dither=bayer
- * low: neighbor + max_colors=32 + dither=none
+ * @description 类型守卫：检查是否是 GeneratorItem
  */
-declare const GIF_QUALITY_TO_FFMPEG_ARGS: {
-    highest: string;
-    high: string;
-    medium: string;
-    low: string;
-};
+declare function isGeneratorItem(obj: any): obj is GeneratorItem;
 
-declare global {
-    interface Window {
-        /**
-         * @description 创建 WebP Core 实例
-         */
-        createWebPCore: (config: any) => Promise<Img2WebPCore>;
-    }
-}
-type FileBuffer = ArrayBuffer | Uint8Array;
-type MediaType = typeof MEDIA_TYPE[keyof typeof MEDIA_TYPE];
-type FS = {
-    writeFile: (path: string, data: Uint8Array | string) => void;
-    readFile(path: string, opts: {
-        encoding: 'binary';
-        flags?: string | undefined;
-    }): Uint8Array;
-    readFile(path: string, opts: {
-        encoding: 'utf8';
-        flags?: string | undefined;
-    }): string;
-    readFile(path: string, opts?: {
-        flags?: string | undefined;
-    }): Uint8Array;
-    unlink: (path: string) => void;
-    quit: () => void;
-};
-type Pointer = number;
-type Img2WebPCore = {
-    FS: FS;
-    run: (...args: string[]) => number;
-    cwrap: (ident: string, returnType: string, argTypes: string[]) => ((argc: number, argv: Pointer) => number);
-    _malloc: (size: number) => Pointer;
-    writeAsciiToMemory: (str: string, buffer: number, dontAddNull?: boolean) => void;
-    setValue: (ptr: number, value: any, type: string, noSafe?: boolean) => void;
-};
-type ExportMediaInitOptions = {
+/**
+ * @description 特效产物 元素 SDKItem 类
+ */
+declare class EffectsItem extends BaseItem {
+    /**
+     * @description 元素类型（独立类型，不属于 spec.ItemType）
+     */
+    readonly type = SDKItemType.EFFECTS;
+    /**
+     * @description 预合成元素ID
+     */
+    subCompositionItemId: string;
+    /**
+     * @description 元素属性
+     */
+    property: EffectsItemProperty;
+    constructor(options: EffectsItemOptions);
+    /**
+     * @description 特效资源地址
+     */
+    get effects(): string;
+    set effects(value: string);
     /**
-     * 导出类型
+     * @description 位置
      */
-    mediaType: MediaType;
+    get position(): [number, number];
+    set position(value: [number, number]);
     /**
-     * 额外画布，导出透明视频时使用
+     * @description 宽度
      */
-    extraCanvas?: HTMLCanvasElement | null;
+    get width(): number;
+    set width(value: number);
     /**
-     * 是否打印转码过程中的日志，仅在导出 MP4/AlphaMaskVideo 时有效， 默认 false
-     * 供开发调试使用
+     * @description 高度
      */
-    loggerInTranscoding?: boolean;
+    get height(): number;
+    set height(value: number);
     /**
-     * ffmpeg 转码是否开启多线程，默认 false，确保环境支持 SharedArrayBuffer
+     * @description 旋转（二维旋转角度）
      */
-    multiThreading?: boolean;
+    get rotation(): number;
+    set rotation(value: number);
     /**
-     * 是否输出 buffer，默认 false
+     * @description 完整旋转（包含 x, y, z）
      */
-    isOutputBuffer?: boolean;
-};
-type MP4Config = {
+    get fullRotation(): [number, number, number];
+    set fullRotation(value: [number, number, number]);
     /**
-     * @description MP4 导出时是否需要导出最后一帧 PNG
+     * @description 是否正在编辑关键属性
+     * @deprecated 该属性即将废弃，使用 isCoreEditable 代替
      */
-    isExportLastFrameJPEG?: boolean;
-};
-type GifConfig = {
+    get keyPropertyEditing(): boolean;
+    set keyPropertyEditing(value: boolean);
     /**
-     * @description GIF 导出时的帧率
+     * @description 转换为 EffectsCreateInfo
+     * @param withParent 是否包含父节点ID
      */
-    fps?: number;
+    toCreateInfo(withParent?: boolean): EffectsCreateInfo;
     /**
-     * @description GIF 导出时的缩放比例
-     * 默认 '-1:-1'， 表示不缩放
-     * 例如 '100:-1'， 表示宽度 100，高度自动
-     * 例如 '-1:100'， 表示宽度自动，高度 100
+     * @description 克隆 SDKItem
      */
-    scale?: string;
+    clone(): EffectsItem;
+}
+/**
+ * @description 类型守卫：检查是否是 EffectsItem
+ */
+declare function isEffectsItem(obj: any): obj is EffectsItem;
+
+/**
+ * @description 画板/框架元素 SDKItem 类
+ * @description 支持自动布局和自由布局两种模式
+ * @description 底层以 composition 形式渲染
+ */
+declare class FrameItem extends BaseItem {
     /**
-     * @description GIF 导出时的质量
-     * 默认 'highest'
-     * 可选 'highest', 'high', 'medium', 'low'
+     * @description 元素类型
      */
-    quality?: keyof typeof GIF_QUALITY_TO_FFMPEG_ARGS;
-};
-type ApngConfig = {
+    readonly type = SDKItemType.FRAME;
     /**
-     * @description APNG 导出时的帧率
+     * @description 预合成元素ID
      */
-    fps?: number;
+    subCompositionItemId: string;
     /**
-     * @description APNG 导出时的缩放比例
-     * 默认 '-1:-1'， 表示不缩放
-     * 例如 '100:-1'， 表示宽度 100，高度自动
-     * 例如 '-1:100'， 表示宽度自动，高度 100
+     * @description 元素属性
      */
-    scale?: string;
+    property: FrameItemProperty;
+    constructor(options: FrameItemOptions);
     /**
-     * @description APNG 导出时的质量
-     * 默认 'highest'
-     * 可选 'highest', 'high', 'medium', 'low'
+     * @description 子元素ID列表（只读）
      */
-    quality?: keyof typeof GIF_QUALITY_TO_FFMPEG_ARGS;
-};
-type ExportMediaItemOptions = {
+    get children(): readonly string[];
     /**
-     * 尺寸
+     * @description 布局模式
      */
-    size: [number, number];
+    get layoutMode(): FrameLayoutMode;
+    set layoutMode(value: FrameLayoutMode);
     /**
-     * 动效资源
+     * @description 位置
      */
-    scene: spec.JSONScene;
+    get position(): [number, number];
+    set position(value: [number, number]);
     /**
-     * 视频时长，目前仅在导出 MP4 / AlphaMaskVideo 时有效，默认取动效资源时长
+     * @description 宽度
      */
-    time?: number;
+    get width(): number;
+    set width(value: number);
     /**
-     * 是否生成音轨，默认 false，仅在导出 MP4 时有效
+     * @description 高度
      */
-    audioEnable?: boolean;
+    get height(): number;
+    set height(value: number);
     /**
-     * 帧率， 默认 30
+     * @description 缩放
      */
-    fps?: number;
+    get scale(): [number, number];
+    set scale(value: [number, number]);
     /**
-     * 是否循环，默认 true
+     * @description 旋转（二维旋转角度）
      */
-    loop?: boolean;
+    get rotation(): number;
+    set rotation(value: number);
     /**
-     * 视频背景颜色，默认 #000000
+     * @description 完整旋转（包含 x, y, z）
      */
-    backgroundColor?: string;
+    get fullRotation(): [number, number, number];
+    set fullRotation(value: [number, number, number]);
     /**
-     * 导出 MP4 时，设置的导出配置
+     * @description 添加子元素
+     * @param itemId 子元素ID
+     * @returns 是否添加成功
      */
-    mp4Config?: MP4Config;
+    addChild(itemId: string): boolean;
     /**
-     * 导出 GIF 时，设置的导出配置
+     * @description 批量添加子元素
+     * @param itemIds 子元素ID列表
      */
-    gifConfig?: GifConfig;
+    addChildren(itemIds: string[]): void;
     /**
-     * 导出 APNG 时，设置的导出配置
+     * @description 移除子元素
+     * @param itemId 子元素ID
+     * @returns 是否移除成功
      */
-    apngConfig?: ApngConfig;
-};
-type ExportMediaItemDownloadInfo = {
+    removeChild(itemId: string): boolean;
     /**
-     * @description 导出文件夹名称
+     * @description 批量移除子元素
+     * @param itemIds 子元素ID列表
      */
-    folderName: string;
+    removeChildren(itemIds: string[]): void;
     /**
-     * @description 导出视频名称
+     * @description 是否包含指定子元素
+     * @param itemId 子元素ID
      */
-    name: string;
-};
-type ExportItemParams = ExportMediaItemOptions & ExportMediaItemDownloadInfo;
-type ExportParams = ExportItemParams[];
-type Buffers = FileBuffer[] | undefined;
-type Extras = (FileBuffer | null)[] | null | undefined;
+    hasChild(itemId: string): boolean;
+    /**
+     * @description 清空所有子元素
+     */
+    clearChildren(): void;
+    /**
+     * @description 转换为 FrameCreateInfo
+     * @param withParent 是否包含父节点ID
+     */
+    toCreateInfo(withParent?: boolean): FrameCreateInfo;
+    /**
+     * @description 克隆 SDKItem
+     */
+    clone(): FrameItem;
+}
+/**
+ * @description 类型守卫：检查是否是 FrameItem
+ */
+declare function isFrameItem(obj: any): obj is FrameItem;
+
+/**
+ * @description 根据 item type 创建对应的 SDKItem 实例
+ * @param type 元素类型
+ * @param options SDKItem 选项
+ * @returns SDKItem 实例
+ */
+declare function createSDKItem(type: spec.ItemType, options: SDKItemOptions): BaseItem;
+/**
+ * @description SDKItem 类型联合
+ * @description 用于替换原来的 SDKItem type
+ */
+type SDKItem = SpriteItem | TextItem | VideoItem | GroupItem | GeneratorItem | EffectsItem | FrameItem;
 
 type BaseItemProperty = {
     position: [number, number];
@@ -1319,6 +1330,10 @@ type TextItemProperty = BaseItemProperty & {
      * @description 描边开关
      */
     outlineEnabled?: boolean;
+    /**
+     * @description 文本字间距
+     */
+    letterSpacing?: number;
     fontUrl?: string;
 };
 type VideoItemProperty = BaseItemProperty & {
@@ -1351,6 +1366,7 @@ type GeneratorItemProperty = BaseItemProperty & {
 };
 type EffectsItemProperty = BaseItemProperty & {
     effects: string;
+    children?: string[];
 };
 /**
  * @description Frame 画板元素布局模式
@@ -1670,13 +1686,6 @@ type ActiveData = {
      */
     loadingItems?: string[];
 };
-/**
- * @description 视图元素
- * @description 注意：SDKItem 现在已从类实现中导入，见 view-item/index.ts
- * @description SDKItem 现在是类实例而非普通对象，支持属性扩展
- * @description 保持类型兼容性：新 SDKItem 类拥有与旧类型相同的属性
- */
-type SDKItem = SDKItem$1;
 type SDKBackgroundType = 'color' | 'image' | 'chess-board' | 'dot-board';
 /**
  * @description 图层创建信息
@@ -1706,7 +1715,7 @@ type SpriteCreateInfo = {
         /**
          * @description 图片资源地址 | 数据
          */
-        image: string;
+        image?: string;
         /**
          * @description 图层像素宽度
          */
@@ -1865,6 +1874,10 @@ type TextCreateInfo = {
          * @description 字体文件地址
          */
         fontUrl?: string;
+        /**
+         * @description 文本字间距
+         */
+        letterSpacing?: number;
     };
 };
 /**
@@ -1895,7 +1908,7 @@ type VideoCreateInfo = {
         /**
          * @description 视频资源地址 | 数据
          */
-        video: string;
+        video?: string;
         /**
          * @description 视频元素像素宽度
          */
@@ -2092,7 +2105,7 @@ type EffectsCreateInfo = {
         /**
          * @description 动效资源地址
          */
-        effects: string | spec.JSONScene;
+        effects: string;
     };
     /**
      * @description 扩展属性
@@ -2147,6 +2160,10 @@ type FrameCreateInfo = {
          * @description 布局模式: 'auto' | 'free'
          */
         layoutMode?: FrameLayoutMode;
+        /**
+         * @description 子元素序号
+         */
+        children: string[];
     };
     /**
      * @description 扩展属性
@@ -2209,6 +2226,14 @@ type UpdateOperation = {
     oldData: ItemCreateInfo[];
 };
 type Operation = CreateOperation | UpdateOperation | DeleteOperation;
+/**
+ * 通用撤销重做操作类型
+ */
+type GizmoOperation<T> = {
+    type: 'update';
+    newData: T;
+    oldData: T;
+};
 declare class UndoRedo {
     private index;
     private operations;
@@ -2332,6 +2357,7 @@ type ExportConfig = {
  */
 type ScreenShotConfig = {
     enabled: boolean;
+    defaultBackgroundColor: [number, number, number, number];
 };
 /**
  * @description 尺寸自适应功能配置
@@ -2491,6 +2517,14 @@ type TransformGizmoConfig = {
      * @description 视频Logo地址
      */
     videoLogoUrl: string;
+    /**
+     * @description 画板Logo地址
+     */
+    frameLogoUrl: string;
+    /**
+     * @description 特效Logo地址
+     */
+    effectsLogoUrl: string;
     /**
      * @description 大小文字颜色
      */
@@ -2757,6 +2791,10 @@ type MaskGizmoConfig = {
      * @description 蒙版透明度
      */
     maskAlpha: number;
+    /**
+     * @description 蒙版图片
+     */
+    maskImage?: HTMLImageElement;
     /**
      * @description 元素包围盒线框宽度
      */
@@ -2910,8 +2948,41 @@ type ItemCreateGizmoConfig = {
      * @description 填充透明度
      */
     frameFillAlpha: number;
+    /**
+     * @description 选中子元素包围盒透明度
+     */
+    frameChildBoxAlpha: number;
+    /**
+     * @description 选中子元素包围盒颜色
+     */
+    frameChildBoxColor: number;
 };
 
+/**
+ * @description 图片蒙版工具结果
+ */
+type MaskResult = {
+    /**
+     * @description 状态
+    */
+    status: 'init' | 'done';
+    /**
+     * @description 包围盒
+     */
+    box?: Box2;
+    /**
+     * @description 鼠标位置
+     */
+    point?: Vector2;
+    /**
+     * @description 蒙版线条列表
+     */
+    lines: {
+        brushSize: number;
+        points: Vector2[];
+        type?: 'paint' | 'erase';
+    }[];
+};
 /**
  * @description 精准改字功能初始化信息
  */
@@ -2955,6 +3026,35 @@ declare module '@pixi/graphics' {
     }
 }
 
+type LoadingGizmoTip = {
+    text: string;
+    fontSize?: number;
+    fontFamily?: string;
+    color?: number;
+};
+type LoadingGizmoItemOptions = {
+    /** Loading 提示文案 */
+    tip?: LoadingGizmoTip;
+    /** 指定 Loading 区域 */
+    loadingBox?: Box2;
+    /** 清理选中 */
+    clearSelected?: boolean;
+};
+
+/**
+ * 蒙版工具的撤销重做数据类型
+ */
+type MaskUndoRedoData = {
+    lines: MaskResult['lines'];
+};
+
+/**
+ * 图片裁切工具的撤销重做数据类型
+ */
+type PictureCutUndoRedoData = {
+    normalizeCutBox: Box2;
+};
+
 type SDKEvents = {
     'loadingItemChange': [id: string[]];
     'selectedItemChange': [id: string[]];
@@ -2970,7 +3070,7 @@ type SDKEvents = {
     }];
     'itemPropertyChange': [{
         id: string;
-        property: string;
+        propertyKeys: string[];
     }];
     'exportProgress': [progress?: number];
     'exportDone': [item: ExportItemParams | undefined, success: boolean, buffer?: FileBuffer];
@@ -2984,6 +3084,8 @@ type SDKEvents = {
         fontFamily: string;
     }];
     'undoRedoChange': [Operation];
+    'maskGizmoUndoRedoChange': [GizmoOperation<MaskUndoRedoData>];
+    'pictureCutGizmoUndoRedoChange': [GizmoOperation<PictureCutUndoRedoData>];
     'viewportTransform': [{
         zoom: number;
         translation: [number, number];
@@ -3031,7 +3133,7 @@ declare class SDK {
     get undoRedo(): UndoRedo;
     private get exportOptions();
     dispose(): void;
-    on: <E extends "progress" | "loadingItemChange" | "selectedItemChange" | "preSelectedItemChange" | "selectedViewChange" | "pageDataChange" | "zoomChange" | "itemPropertyChange" | "exportProgress" | "exportDone" | "exportComplete" | "sdkConfigChange" | "cutBoxChange" | "expandBoxChange" | "textInput" | "undoRedoChange" | "viewportTransform" | "itemOnDragStart" | "itemOnDrag" | "itemOnDragEnd" | "spriteTextClick" | "videoPlay" | "itemCreate" | "viewLost" | "viewRebuildFinish">(eventName: E, listener: _galacean_effects.EventEmitterListener<SDKEvents[E]>, options?: _galacean_effects.EventEmitterOptions) => () => void;
+    on: <E extends "progress" | "loadingItemChange" | "selectedItemChange" | "preSelectedItemChange" | "selectedViewChange" | "pageDataChange" | "zoomChange" | "itemPropertyChange" | "exportProgress" | "exportDone" | "exportComplete" | "sdkConfigChange" | "cutBoxChange" | "expandBoxChange" | "textInput" | "undoRedoChange" | "maskGizmoUndoRedoChange" | "pictureCutGizmoUndoRedoChange" | "viewportTransform" | "itemOnDragStart" | "itemOnDrag" | "itemOnDragEnd" | "spriteTextClick" | "videoPlay" | "itemCreate" | "viewLost" | "viewRebuildFinish">(eventName: E, listener: _galacean_effects.EventEmitterListener<SDKEvents[E]>, options?: _galacean_effects.EventEmitterOptions) => () => void;
     initPlayer(mode: SDKMode): void;
     setSDKMode(mode: SDKMode): void;
     private getInitParam;
@@ -3075,13 +3177,13 @@ declare class SDK {
      * @param id 元素ID
      * @returns 元素
      * */
-    getSDKItem(id: string): SDKItem$1 | undefined;
+    getSDKItem(id: string): SDKItem | undefined;
     /**
      * @description 获取元素数组
      * @param id 元素ID数组
      * @returns 元素数组
      * */
-    getSDKItems(ids?: string[]): SDKItem$1[];
+    getSDKItems(ids?: string[]): SDKItem[];
     setPlayState(playState: 'play' | 'pause'): Promise<void>;
     /**
      * @description 获取场景预览图
@@ -3246,7 +3348,54 @@ declare class SDK {
      * @param mode 模式类型：'paint' 表示涂抹，'erase' 表示擦除
      */
     setMaskGizmoMode(mode: 'paint' | 'erase'): void;
-    openLoadingGizmo(id: string, loadingBox?: Box2, clearResult?: boolean): void;
+    /**
+     * 撤销蒙版操作
+     * @returns 是否成功撤销
+     */
+    undoMaskGizmo(): boolean;
+    /**
+     * 重做蒙版操作
+     * @returns 是否成功重做
+     */
+    redoMaskGizmo(): boolean;
+    /**
+     * 检查蒙版是否可以撤销
+     */
+    get canUndoMaskGizmo(): boolean;
+    /**
+     * 检查蒙版是否可以重做
+     */
+    get canRedoMaskGizmo(): boolean;
+    /**
+     * 清空蒙版 undoRedo 历史
+     */
+    clearMaskGizmoUndoRedo(): void;
+    /**
+     * 撤销图片裁切操作
+     * @returns 是否成功撤销
+     */
+    undoPictureCutGizmo(): boolean;
+    /**
+     * 重做图片裁切操作
+     * @returns 是否成功重做
+     */
+    redoPictureCutGizmo(): boolean;
+    /**
+     * 检查图片裁切是否可以撤销
+     */
+    get canUndoPictureCutGizmo(): boolean;
+    /**
+     * 检查图片裁切是否可以重做
+     */
+    get canRedoPictureCutGizmo(): boolean;
+    /**
+     * 清空图片裁切 undoRedo 历史
+     */
+    clearPictureCutGizmoUndoRedo(): void;
+    openLoadingGizmo(id: string, options?: LoadingGizmoItemOptions): void;
+    updateLoadingGizmo(id: string, options: {
+        tip?: LoadingGizmoTip;
+    }): void;
     closeLoadingGizmo(id: string): void;
     /**
      * @description 元素打组
@@ -3261,6 +3410,7 @@ declare class SDK {
     getItemCreateInfo(id: string): ItemCreateInfo | undefined;
     getItemCreateInfos(ids?: string[]): ItemCreateInfo[];
     createScreenShotSceneByIds(idInfo: string | string[], time?: number): Promise<string | undefined>;
+    createScreenShotByFrame(id: string): Promise<string | undefined>;
     getChildrenIds(id: string): string[];
     /**
      * @description 更新元素在图层中的顺序
@@ -3355,9 +3505,13 @@ declare class SDK {
     setSpriteTextEditState(id: string, index: number, isEditing: boolean): void;
     getVideoItemPlayTime(id: string): number;
     setVideoItemPlayTime(id: string, time: number): void;
+    getEffectsItemPlayTime(id: string): number | undefined;
+    setEffectsItemPlayTime(id: string, time: number): void;
+    setEffectsResource(id: string, effects: string): void;
     getPixelPositionByViewPosition(viewPosition: Vector2): Vector2;
     hitTest(x: number, y: number): string[] | undefined;
     setInteractType(type: GestureHandlerInteractType): void;
+    getInteractType(): GestureHandlerInteractType;
     makeItemAlign(type: AlignType, ids?: string[]): void;
     makeItemDistribute(type: DistributeType, ids?: string[]): void;
     /**
@@ -3367,7 +3521,7 @@ declare class SDK {
      */
     addGeneratorItem(createInfo: GeneratorCreateInfo): string;
     /**
-     * @description 创建动效元素（仅限调试使用）
+     * @description 创建动效元素
      * @param effectsInfo 动效创建信息
      */
     addEffectsItem(effectsInfo: EffectsCreateInfo): Promise<string | undefined>;
@@ -3376,7 +3530,19 @@ declare class SDK {
      * @param createInfo 画板创建信息
      * @returns 画板元素ID
      */
-    addFrameItem(createInfo: FrameCreateInfo): string;
+    addFrameItem(createInfo: FrameCreateInfo): Promise<string>;
+    /**
+     * @description 将元素移动到 Frame 中
+     * @param itemIds 要移动的元素ID列表
+     * @param frameId 目标 Frame ID
+     */
+    moveItemsToFrame(itemIds: string[], frameId: string): void;
+    /**
+     * @description 将元素从 Frame 中移出到主场景
+     * @param itemIds 要移动的元素ID列表
+     * @param frameId 源 Frame ID（可选，如果不传则从元素的 parentId 推断）
+     */
+    moveItemsOutOfFrame(itemIds: string[], frameId?: string): void;
     /**
      * @description 设置生成器资源，将生成器转换为对应的元素
      * @param id 生成器元素ID
@@ -3407,4 +3573,4 @@ declare class SDK {
     setSafeAreaPreviewVisible(id: number, type: 'url' | 'color', visible: boolean): void;
 }
 
-export { type ActiveData, BaseItem, type BaseItemProperty, type BaseItemPropertyKey, type BaseItemPropertyValueMap, Box2, type CreateOperation, type DeleteOperation, type EffectsCreateInfo, EffectsItem, type EffectsItemOptions, type FrameCreateInfo, FrameItem, type FrameItemOptions, type FrameItemProperty, FrameLayoutMode, type GeneratorCreateInfo, GeneratorItem, type GeneratorItemOptions, type GeneratorItemProperty, type GizmoType, type GroupCreateInfo, GroupItem, type GroupItemOptions, type ItemCreateInfo, ItemOrderAction, type ItemPropertyMap, type Operation, type PageData, type PageProperty, SDK, type SDKEvents, type SDKInputParam, type SDKItem$1 as SDKItem, type SDKItemOptions, SDKItemType, type SDKOptions, type SetItemPropertyParam, type SetSingleItemMultiplePropertiesParam, type SetSingleItemSinglePropertyParam, type SpriteCreateInfo, SpriteItem, type SpriteItemOptions, type SpriteItemProperty, type TextCreateInfo, TextItem, type TextItemOptions, type TextItemProperty, type UpdateOperation, Vector2, type VideoCreateInfo, VideoItem, type VideoItemOptions, type VideoItemProperty, type ViewParam, type ViewProperty, createSDKItem, isBaseItem, isEffectsItem, isFrameItem, isGeneratorItem, isGroupItem, isSpriteItem, isTextItem, isVideoItem };
+export { type ActiveData, BaseItem, type BaseItemProperty, type BaseItemPropertyKey, type BaseItemPropertyValueMap, Box2, type CreateOperation, type DeleteOperation, type EffectsCreateInfo, EffectsItem, type EffectsItemOptions, type FrameCreateInfo, FrameItem, type FrameItemOptions, type FrameItemProperty, FrameLayoutMode, type GeneratorCreateInfo, GeneratorItem, type GeneratorItemOptions, type GeneratorItemProperty, type GizmoType, type GroupCreateInfo, GroupItem, type GroupItemOptions, type ItemCreateInfo, ItemOrderAction, type ItemPropertyMap, type Operation, type PageData, type PageProperty, SDK, type SDKEvents, type SDKInputParam, type SDKItem, type SDKItemOptions, SDKItemType, type SDKOptions, type SetItemPropertyParam, type SetSingleItemMultiplePropertiesParam, type SetSingleItemSinglePropertyParam, type SpriteCreateInfo, SpriteItem, type SpriteItemOptions, type SpriteItemProperty, type TextCreateInfo, TextItem, type TextItemOptions, type TextItemProperty, type UpdateOperation, Vector2, type VideoCreateInfo, VideoItem, type VideoItemOptions, type VideoItemProperty, type ViewParam, type ViewProperty, createSDKItem, isBaseItem, isEffectsItem, isFrameItem, isGeneratorItem, isGroupItem, isSpriteItem, isTextItem, isVideoItem };