@vvfx/artis 0.0.1-alpha.0

package/dist/shared/index.d.ts

@@ -0,0 +1 @@
+export * from './player';

package/dist/shared/player.d.ts

@@ -0,0 +1,9 @@
+import '@galacean/effects';
+export { spec, VFXItem, Player, math, Composition, type Region, EventEmitter, assertExist, SpriteComponent, TextComponent, FrameComponent, Texture, generateGUID, version as PlayerVersion, CompositionComponent, Control, } from '@galacean/effects';
+import '@galacean/effects-plugin-rich-text';
+export { RichTextComponent } from '@galacean/effects-plugin-rich-text';
+import '@galacean/effects-plugin-model';
+import '@galacean/effects-plugin-multimedia';
+export { VideoComponent } from '@galacean/effects-plugin-multimedia';
+import '@galacean/effects-plugin-spine';
+import '@galacean/effects-plugin-ffd';

package/dist/utils/background-manager.d.ts

@@ -0,0 +1,76 @@
+import { BackgroundGridConfig, BackgroundPreset } from './types';
+/**
+ * 背景管理器
+ * 负责管理画布背景的配置、渲染和跟随变换
+ */
+export declare class BackgroundManager {
+    /**
+     * 默认网格配置
+     */
+    static readonly DEFAULT_GRID_CONFIG: BackgroundGridConfig;
+    /**
+     * 背景预设配置
+     */
+    static readonly PRESETS: Record<string, BackgroundPreset>;
+    private container;
+    private config;
+    /**
+     * 当前背景位置（用于跟随移动）
+     */
+    private offsetX;
+    private offsetY;
+    constructor(config?: Partial<BackgroundGridConfig>);
+    /**
+     * 绑定容器元素
+     * @param element 画布容器元素
+     */
+    attach(element: HTMLElement): void;
+    /**
+     * 解绑容器元素
+     */
+    detach(): void;
+    /**
+     * 应用背景预设
+     * @param presetName 预设名称
+     * @param color 可选的背景色覆盖
+     * @returns 是否成功应用（容器或预设不存在时返回 false）
+     */
+    applyPreset(presetName: string, color?: string): boolean;
+    /**
+     * 设置纯色背景
+     * @param color 颜色值
+     */
+    setColorBackground(color: string): void;
+    /**
+     * 设置图片背景
+     * @param url 图片 URL
+     */
+    setImageBackground(url: string): void;
+    /**
+     * 更新背景变换（跟随画布移动和缩放）
+     * @param shift 画布移动的偏移量
+     * @param zoom 当前缩放比例
+     */
+    updateTransform(shift: {
+        x: number;
+        y: number;
+    }, zoom: number): void;
+    /**
+     * 重置背景位置和大小
+     */
+    reset(): void;
+    /**
+     * 清除背景样式
+     * @param element 需要清除背景样式的元素
+     */
+    private clearBackground;
+    /**
+     * 计算循环缩放比例
+     * zoom 在 [1, 2) 时，bgZoom = zoom
+     * zoom 在 [2, 4) 时，bgZoom = zoom / 2
+     * zoom 在 [0.5, 1) 时，bgZoom = zoom / 0.5
+     * @param zoom 当前缩放比例
+     * @returns 归一化到单个缩放周期内的比例
+     */
+    private calculateZoomCycle;
+}

package/dist/utils/common-utils.d.ts

@@ -0,0 +1,39 @@
+export declare function deepClone<T>(target: T): T;
+export { assertExist } from '@galacean/effects';
+/**
+ * 向数组添加元素，已存在（基本类型按值去重）则跳过
+ */
+export declare function arrAdd<T>(arr: T[], item: T): void;
+/**
+ * 判断是否为对象（含数组），排除 null 与基本类型
+ */
+export declare function isObj(value: unknown): value is object;
+/**
+ * 深度相等比较，支持对象/数组/Date/RegExp
+ */
+export declare function isEqual(a: unknown, b: unknown): boolean;
+/** isEqual 的别名 */
+export declare const deepEquals: typeof isEqual;
+/**
+ * 在已有名称集合中生成不重复的名称，冲突时追加 " (n)"
+ */
+export declare function getUniqueName(base: string, existing: string[]): string;
+type NormalizeColor = [number, number, number, number];
+/**
+ * 归一化颜色 [0~1] -> RGBA [0~255, 0~1]
+ */
+export declare function getColorByNormalizeColor(color: NormalizeColor): NormalizeColor;
+/**
+ * RGBA [0~255, 0~1] -> 归一化颜色 [0~1]
+ */
+export declare function getNormalizeColorByColor(color: NormalizeColor): NormalizeColor;
+export declare function asserts(condition: any, msg?: string): asserts condition;
+/**
+ * @example
+ * Input: logger('log', ['VVFX', 'SDK'], 'xx is required');
+ * Output: [VVFX SDK] xx is required
+ */
+type Level = 'error' | 'info' | 'debug' | 'warn' | 'log';
+export declare function logger(level: Level, prefixs: string[], ...args: any[]): void;
+export declare function loadScriptAsync(src: string, attrs?: Record<string, string>): Promise<unknown>;
+export declare function downloadBlob(buffer: BlobPart | BlobPart[], filename: string, mimeType?: string): void;

package/dist/utils/container-size.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 取画布容器的布局尺寸，优先 offsetWidth/Height。
+ *
+ * @param container 画布 DOM 容器
+ * @returns [width, height]（像素）
+ */
+export declare function getContainerSize(container: HTMLElement): [number, number];

package/dist/utils/find-player-item.d.ts

@@ -0,0 +1,9 @@
+import { VFXItem } from '../shared';
+/**
+ * 递归遍历组合树，返回首个 instanceId 匹配的节点。
+ *
+ * @param items 组合树根节点列表（Player composition.items）
+ * @param id 目标元素实例 ID
+ * @returns 命中节点；未命中返回 undefined
+ */
+export declare function findPlayerItemByInstanceId(items: VFXItem[] | undefined, id: string): VFXItem | undefined;

package/dist/utils/index.d.ts

@@ -0,0 +1,11 @@
+export * from './common-utils';
+export * from './background-manager';
+export * from './json-data-utils';
+export * from './layout-utils';
+export * from './pixel-box-utils';
+export * from './types';
+export * from './player-data-utils';
+export * from './player-utils';
+export * from './find-player-item';
+export { getContainerSize } from './container-size';
+export * from './replay-utils';

package/dist/utils/json-data-utils.d.ts

@@ -0,0 +1,198 @@
+import { Vector2, Vector3 } from '@vvfx/gizmo';
+import { spec } from '@galacean/effects';
+import { ItemJSONInfo } from './types';
+/**
+ * 创建 Frame 元素的内部合成场景
+ * @param frameId Frame 元素ID（用于标识）
+ * @param size 场景尺寸 [width, height]
+ * @param name 场景名称
+ * @returns Frame 内部的合成场景
+ */
+export declare function createFrameCompositionScene(size: spec.vec2, name: string, compositionId?: string): spec.JSONScene;
+/**
+ * 创建基础场景信息
+ * @param viewSize 画布大小
+ * @returns 场景信息
+ */
+export declare function getBasicScene(viewSize?: number[], name?: string): spec.JSONScene;
+/**
+ * 构建导出用 JSONScene 骨架：composition + 空 CompositionComponent + 空 TimelineAsset（miscs 内）。
+ *
+ * 与 {@link getBasicScene} 的差异（导出口径）：
+ * - compositionId 由调用方传入（exportScene 复用现有 composition.id；createSceneByItemIds 用新生成 id），
+ *   不自建。
+ * - `endBehavior` 固定 restart（getBasicScene 为 forward）。
+ * - `camera` 由调用方传入：exportScene 用无 aspect 默认相机；createSceneByItemIds 用
+ *   `getBasicScene(previewSize).camera`（带 aspect）。
+ * - 初始化 `videos` 字段（getBasicScene 未初始化）。
+ *
+ * 元素的 item/components/tracks/资源 + ObjectBindingTrack/sceneBindings 不在此处组装，
+ * 由调用方逐个 {@link addItemInfoToScene} 委托（绑定契约真源在本模块）。scene.images/videos/textures
+ * 为内部新建的空数组，调用方可直接拿这些引用作 serializeItemToJSON 的 out-param，收集后即挂在 scene 上。
+ *
+ * @param compositionId 合成 ID
+ * @param name 合成名称
+ * @param previewSize 预览尺寸
+ * @param camera 相机配置
+ * @returns 导出用 JSONScene 骨架（images/videos/textures 为空数组，供调用方累加）
+ */
+export declare function createExportableScene(compositionId: string, name: string, previewSize: spec.vec2, camera: spec.CameraOptions): spec.JSONScene;
+export declare function createSpriteItemJSON(spriteId: string, position: Vector3, rotation: Vector3, size: Vector2, scale: Vector3, name: string, texture?: string): ItemJSONInfo;
+/**
+ * 创建视频生成器 Item JSON
+ * 以 SpriteItem 形式渲染，但设置透明颜色
+ * 在 content 中存储 isVideoGenerator 标记
+ */
+export declare function createVideoGeneratorItemJSON(id: string, position: Vector3, rotation: Vector3, size: Vector2, scale: Vector3, name: string): ItemJSONInfo;
+export declare function createNullItemJSON(nullId: string, name: string, position: Vector3, scale?: Vector2, rotation?: Vector3, worldSize?: Vector2): ItemJSONInfo;
+export declare function createTextItemJSON(textId: string, name: string, position: Vector3, rotation: Vector3, size: Vector2, fontInfo: spec.TextContentOptions): ItemJSONInfo;
+export declare function createVideoItemJSON(videoId: string, position: Vector3, rotation: Vector3, size: Vector2, scale: Vector3, name: string, isMuted?: boolean, transparent?: boolean, volume?: number, playbackRate?: number, texture?: string, video?: string): ItemJSONInfo;
+/**
+ * 创建预合成元素
+ * @param effectsId 预合成元素ID
+ * @param position 位置信息
+ * @param rotation 旋转信息
+ * @param scale 缩放信息
+ * @param name 名称
+ */
+export declare function createCompositionItemJSON(effectsId: string, position: Vector3, rotation: Vector3, scale: Vector3, name: string): {
+    item: spec.VFXItemData;
+    components: never[];
+    tracks: {
+        id: string;
+        dataType: spec.DataType;
+        children: never[];
+        clips: {
+            start: number;
+            duration: number;
+            endBehavior: spec.EndBehavior;
+            asset: {
+                id: string;
+            };
+        }[];
+    }[];
+    playableAssets: {
+        id: string;
+        dataType: spec.DataType;
+    }[];
+};
+/**
+ * 添加元素信息到JSON
+ * @param scene 场景信息
+ * @param itemInfo 元素信息
+ */
+export declare function addItemInfoToScene(scene: spec.JSONScene, itemInfo: ItemJSONInfo): void;
+/**
+ * 设置元素父节点信息
+ * @param scene 场景信息
+ * @param itemId 元素Id
+ * @param parentId 父节点Id
+ */
+export declare function setItemJSONParentId(scene: spec.JSONScene, itemId: string, parentId: string): void;
+/**
+ * 清理元素父节点信息
+ * @param scene 场景信息
+ * @param itemId 元素Id
+ */
+export declare function clearItemParentInfo(scene: spec.JSONScene, itemId: string): void;
+/**
+ * 删除元素信息
+ * @param scene 场景信息
+ * @param itemId 元素Id
+ */
+export declare function deleteItemInfoFromScene(scene: spec.JSONScene, itemId: string): spec.JSONScene | undefined;
+/**
+ * 从场景中移除并获取元素的完整 ItemJSONInfo
+ * @param scene 场景信息
+ * @param itemId 元素ID
+ * @returns ItemJSONInfo 或 undefined（如果元素不存在）
+ */
+export declare function removeItemInfoFromScene(scene: spec.JSONScene, itemId: string): ItemJSONInfo | undefined;
+export declare function getTextureUrlById(scene: spec.JSONScene, itemId: string): string | undefined;
+export declare function addCompositionItemByComposition(main: spec.JSONScene, inputChild: spec.JSONScene, compositionItemId: string, parentId?: string): spec.JSONScene;
+/**
+ * 删除预合成数据
+ * @param scene 场景数据
+ * @param itemId 预合成ID
+ * @returns 场景数据
+ */
+export declare function deleteCompositionItemFromScene(scene: spec.JSONScene, itemIds: string[]): spec.JSONScene;
+/**
+ * 删除合成信息
+ * @param scene 场景数据
+ * @param compositionId 合成ID
+ */
+export declare function deleteCompositionFromScene(scene: spec.JSONScene, compositionId: string): void;
+/**
+ * 重置元素ID - 加载时会新建guid，需要保持一致
+ * @param scene 场景数据
+ * @param idMap id名称列表
+ */
+export declare function resetSubCompositionItemId(scene: spec.JSONScene, idMap: Map<string, string>): void;
+/**
+ * 设置场景中元素名称
+ * @param scene 场景数据
+ * @param itemId 元素ID
+ * @param name 名称
+ */
+export declare function setJSONItemName(scene: spec.JSONScene, itemId: string, name: string): void;
+/**
+ * 元素变换选项
+ */
+export type MoveItemTransformOptions = {
+    position?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    size?: {
+        x: number;
+        y: number;
+    };
+    scale?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotation?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+};
+/**
+ * 将元素从一个合成移动到另一个合成
+ * @param scene 场景数据
+ * @param itemId 元素ID
+ * @param targetCompositionId 目标合成ID，为null时表示移动到主合成
+ * @param options 可选的位置、大小、缩放、旋转信息
+ * @returns 是否移动成功
+ */
+export declare function moveItemBetweenCompositions(scene: spec.JSONScene, itemId: string, targetCompositionId: string | null, options?: MoveItemTransformOptions): boolean;
+export declare function getCompositionIdByRefCompositionItemId(scene: spec.JSONScene, compositionItemId: string): any;
+/**
+ * 获取预合成元素所指向的合成数据
+ * @param scene 场景数据
+ * @param compositionItemId 预合成元素ID
+ * @returns 对应的合成数据 (CompositionData)，如果未找到则返回 undefined
+ */
+export declare function getCompositionDataByRefCompositionItemId(scene: spec.JSONScene, compositionItemId: string): spec.CompositionData | undefined;
+/**
+ * 提取子合成元素及其所有关联资源为独立的 JSONScene
+ * @param scene 主场景数据
+ * @param compositionItemId 预合成元素ID（子合成元素ID）
+ * @returns 独立的子合成场景 JSONScene，如果未找到则返回 undefined
+ */
+export declare function extractSubCompositionToScene(scene: spec.JSONScene, compositionItemId: string): spec.JSONScene | undefined;
+export declare function fixStandardJSON(scene: spec.JSONScene): void;
+/**
+ * 创建遮罩合成场景：把入参 BaseScene 以预合成形式挂到新建的 MaskScene 主合成下，
+ * 并在预合成父级加一个带 FrameComponent 的空节点（界外遮罩画板）。
+ *
+ * - MaskScene 主合成的 previewSize / camera 与 BaseScene 主合成一致
+ * - 空节点（null + FrameComponent）为预合成 item 的父级，size 由相机参数换算的世界尺寸铺满视口
+ * - FrameComponent 以 FrameComponentData 序列化进 MaskScene.components，加载后由 runtime 装配
+ * @param scene BaseScene（被包裹的原始场景）
+ * @returns MaskScene（外层遮罩合成场景）
+ */
+export declare function createMaskScene(scene: spec.JSONScene): spec.JSONScene;

package/dist/utils/layout-utils.d.ts

@@ -0,0 +1,144 @@
+import type { LayoutPosition } from '@vvfx/gizmo';
+import { Box2 } from '@vvfx/gizmo';
+import { type ArtisItem, type FrameItem } from '../core';
+import { type AutoLayoutConfig, type LayoutInfo } from '../core/types';
+/**
+ * 布局元素信息
+ */
+export type LayoutItem = {
+    id: string;
+    box: Box2;
+    row?: number;
+    column?: number;
+};
+/**
+ * 布局结果项
+ */
+export type LayoutResultItem = {
+    id: string;
+    position: [number, number];
+    row: number;
+    column: number;
+};
+/**
+ * 自动排布配置
+ */
+export type AutoLayoutOptions = {
+    padding?: number;
+    gap?: number;
+    config?: AutoLayoutConfig;
+};
+/**
+ * 自动排布结果
+ */
+export type AutoLayoutResult = {
+    items: LayoutResultItem[];
+    size: [number, number];
+};
+/**
+ * 全局自适应排布元素
+ */
+export type LayoutElement = {
+    id: string;
+    box: Box2;
+};
+/**
+ * 全局自适应排布结果
+ */
+export type GlobalAutoLayoutResult = {
+    items: {
+        id: string;
+        position: [number, number];
+    }[];
+    boundingBox: Box2;
+};
+/**
+ * 全局自适应排布配置
+ */
+export type GlobalAutoLayoutOptions = {
+    /**
+     * 元素间隔（默认10）
+     */
+    gap?: number;
+    /**
+     * 目标宽高比（默认1:1正方形）
+     */
+    targetAspectRatio?: number;
+    /**
+     * 排布模式
+     * - 'adaptive': 基于元素包围盒自适应排布（MaxRects算法，更紧凑）
+     * - 'ordered': 基于元素顺序的行列排布（保持输入顺序，流式行排布，行优先）
+     */
+    mode?: GlobalLayoutMode;
+};
+/**
+ * 全局自适应排布模式
+ */
+export declare enum GlobalLayoutMode {
+    ADAPTIVE = "adaptive",
+    ORDERED = "ordered"
+}
+/**
+ * 自动排布函数
+ * 根据元素信息中的行列数参数进行排布：
+ * - 如果元素有 row/column，则按指定行列排布
+ * - 如果元素没有 row/column，则使用 Shelf 算法自动生成行列数，再排布
+ *
+ * @param canvasBox 画布范围（Box2），min为左上角，max为右下角
+ * @param items 元素信息列表（包含 ID、Box2、可选的 row/column）
+ * @param options 可选配置（padding, gap）
+ * @returns 各元素的位置信息和整体尺寸
+ */
+export declare function autoLayout(items: LayoutItem[], options?: AutoLayoutOptions): AutoLayoutResult;
+/**
+ * 计算元素到目标位置的位移
+ * @param currentPosition 当前位置 [x, y]
+ * @param targetPosition 目标位置 [x, y]
+ * @returns 位移向量 [dx, dy]
+ */
+export declare function calculateDisplacement(currentPosition: [number, number], targetPosition: [number, number]): [number, number];
+/**
+ * 为 autoLayout 结果计算位移信息
+ * @param items 元素列表（包含当前位置）
+ * @param layoutResult autoLayout 的返回结果
+ * @returns 每个元素的位移信息
+ */
+export declare function calculateLayoutDisplacements(items: {
+    id: string;
+    currentPosition: [number, number];
+}[], layoutResult: AutoLayoutResult): {
+    id: string;
+    displacement: [number, number];
+    targetPosition: [number, number];
+}[];
+/**
+ * 更新元素的 layoutInfo
+ * @param item 要更新的元素
+ * @param parent 父画板
+ * @param layoutPosition 新的布局位置
+ */
+export declare function updateItemLayoutInfo(item: ArtisItem, parent: FrameItem, layoutPosition: LayoutPosition): void;
+/**
+ * 全局自适应排布
+ * 支持两种模式：
+ * 1. 'adaptive'（默认）: 基于元素包围盒自适应排布（MaxRects算法，更紧凑）
+ * 2. 'ordered': 基于元素顺序的流式行排布（保持输入顺序，每行尽可能多放元素）
+ *
+ * @param elements 元素列表（包含ID和包围盒）
+ * @param options 配置选项
+ * @returns 各元素位置和整体包围盒
+ */
+export declare function globalAutoLayout(elements: LayoutElement[], options?: GlobalAutoLayoutOptions): GlobalAutoLayoutResult;
+/**
+ * 调整其他元素的行列信息
+ * 当被拖拽元素移动到新位置时，需要调整其他受影响的元素：
+ * 1. 同行内移动：原位置到新位置之间的元素需要相应调整列号
+ * 2. 跨行移动：原行中后面的元素前移，目标行中后面的元素后移
+ * @param originLayoutInfos 原始布局信息
+ * @param draggedItemId 被拖拽的元素ID
+ * @param fromRow 原始行号
+ * @param fromColumn 原始列号
+ * @param toRow 目标行号
+ * @param toColumn 目标列号
+ */
+export declare function adjustOtherElementsLayoutInfo(originLayoutInfos: Record<string, LayoutInfo>, draggedItemId: string, fromRow: number, fromColumn: number, toRow: number, toColumn: number): Record<string, LayoutInfo>;

package/dist/utils/pixel-box-utils.d.ts

@@ -0,0 +1,26 @@
+import { Box2 } from '@vvfx/gizmo';
+import { type ItemSchema } from '../core/types';
+/**
+ * 按单个 ItemSchema 计算像素包围盒（基准像素空间、含 rotation、size 补乘 scale）。
+ *
+ * 纯计算、不依赖任何运行时服务 / Player 实例，供「手上有 ItemSchema 而非运行时 artisItem」的
+ * 离线场景（导出 / 复制粘贴 / 布局）按数据算盒。GROUP（空节点）无自身尺寸，直接返回空盒——
+ * 批量场景下空节点按子元素 union 的口径见 {@link getPixelBoxBySchemas}；text 高度缺省取 lineHeight；
+ * effects 等缺宽高的返回空盒。
+ *
+ * @param schema 元素 Schema
+ * @returns 基准像素包围盒；无有效尺寸时返回空盒
+ */
+export declare function getPixelBoxBySchema(schema: ItemSchema): Box2;
+/**
+ * 按 ItemSchema 批量计算像素包围盒（离线口径，不依赖 Player 实例）。
+ *
+ * - 非空节点（sprite / text / video / generator / effects / frame / card）：直接按 position +
+ *   width/height 补乘 scale + rotation 算盒（复用 {@link getPixelBoxBySchema}）；
+ * - 空节点（GROUP）：自身无尺寸，需等本批所有非空节点算完后，按其 children 包围盒做 union 得到
+ *   （支持 GROUP 嵌套，按依赖顺序迭代到收敛；存在环或引用本批外元素时填空盒，不死循环）。
+ *
+ * @param schemas 元素 Schema 列表
+ * @returns 元素 ID → 像素包围盒映射（无 id 的 schema 跳过；GROUP 子元素不在本批内时不贡献面积）
+ */
+export declare function getPixelBoxBySchemas(schemas: ItemSchema[]): Map<string, Box2>;

package/dist/utils/player-data-utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 此文件的实现已迁移至 `@vvfx/gizmo (internal/player-data-utils.ts)`（gizmo 依赖收口的单一来源）。
+ * 此处反向 re-export 该文件实际对外暴露的符号，保持 `utils` barrel 与现有深路径引用不变。
+ *
+ * 注意：这里显式列举需要的符号而非 `export * from '@vvfx/gizmo'`，以免把 gizmo 全部导出
+ * （含 FrameLayoutMode/AutoLayoutConfig/LayoutInfo 等）带入 artis barrel，与 artis 本地定义的
+ * 同名类型产生重复导出冲突。
+ */
+export { DefaultVFXItems, VFXItemFactory } from '@vvfx/gizmo';

package/dist/utils/player-utils.d.ts

@@ -0,0 +1,42 @@
+import { VFXItem } from '@galacean/effects';
+import { MoveItemTransformOptions } from './json-data-utils';
+/**
+ * 计算元素在新父节点下保持世界绝对 transform 不变时所需的局部 transform
+ *
+ * 返回 position / size / scale / **rotation**。历史实现经 `decompose` 解出旋转却未返回，
+   * 导致带旋转的元素移入 / 移出 Frame 时旋转丢失；补齐 rotation（角度，与 effects
+ * `setRotation` / `eulerHint` 单位一致，参考 item-service decompose→Euler.setFromQuaternion 模式）。
+ *
+ * @param item 要移动的元素
+ * @param targetParentVFXItem 目标父 VFXItem（移入 Frame 时为 compositionItem，移出 Frame 时为 composition.rootItem）
+ */
+export declare function getItemTransformUnderParent(item: VFXItem, targetParentVFXItem: VFXItem): MoveItemTransformOptions | undefined;
+/**
+ * 将单个元素移入画板（Frame）合成，并应用保持世界 transform 的局部 transform。
+ * @param item 要移动的元素
+ * @param frameCompositionItem 画板合成元素
+ * @param targetTransformInfo getItemTransformUnderParent 计算出的局部 transform
+ */
+export declare function moveItemToFrame(item: VFXItem, frameCompositionItem: VFXItem, targetTransformInfo: MoveItemTransformOptions): void;
+/**
+ * 将单个元素移出画板（Frame）合成。
+ * 仅当移回根（parentId 为空）时写入 transform；移到中间父级时仅变更父子关系。
+ * @param item 要移动的元素
+ * @param parentId 目标父 id（移回根时为 undefined）
+ * @param parentItem 目标父元素
+ * @param targetTransformInfo getItemTransformUnderParent 计算出的局部 transform
+ */
+export declare function moveItemOutOfFrame(item: VFXItem, parentId: string | undefined, parentItem: VFXItem, targetTransformInfo: MoveItemTransformOptions): void;
+/**
+ * 把元素提升到合成根节点，并按世界 transform 重新计算 local
+ *
+ * 用于取消打组 / 脱离父容器：reparent 到 root 的同时 bake 世界 transform，
+ * 使元素在父级变更后世界位置 / 旋转 / 缩放保持不变。
+ * 内部复用 getItemTransformUnderParent + moveItemOutOfFrame 的「移回根（!parentId）」路径，
+ * 与 frame-service.moveItemsOutOfFrame 走同一套矩阵 decompose 方案。
+ *
+ * @param item 要提升的元素
+ * @param rootItem 合成根元素（composition.sceneRoot）
+ * @returns 是否成功完成 reparent + bake（info 算不出时返回 false）
+ */
+export declare function moveItemToRoot(item: VFXItem, rootItem: VFXItem): boolean;

package/dist/utils/replay-utils.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Replay args 序列化：把 Command 工厂入参（单参对象）序列化为 JSON-safe 数据，
+ * 用于错误上报快照中携带"可重放"的操作上下文。
+ *
+ * 入参为<b>单参对象</b>（与命令 args 形状同源，key-value）。按 key 逐字段应用清洗规则，产出
+ * `Record<string, unknown>`——比历史位置数组更稳定（无下标约定耦合，复现页按具名 key 解构）。
+ *
+ * 规则（每字段）：
+ * - 函数直接丢弃（记为 null），replayable 置 false
+ * - 不可 JSON 序列化的对象（循环引用 / Symbol / 不可枚举宿主对象）→ 丢弃该项、replayable 置 false
+ * - 类实例（Vector2/Box2/Matrix 等，constructor 非 Object）JSON 会剥掉原型 → 标 replayable=false，
+ *   避免重放时方法丢失（如 setZoom 调 anchor.add()）崩溃
+ * - 其余纯数据对象/数组用 deepClone（复用 common-utils，与全工程同语义）克隆为 JSON-safe
+ * - undefined 字段直接保留为 undefined
+ *
+ * @param args Command 工厂单参入参对象
+ * @returns 序列化后的 args（对象）与是否可完整重放标志
+ */
+export declare function serializeReplayArgs(args: unknown): {
+    args: Record<string, unknown>;
+    replayable: boolean;
+};