@vvfx/artis 0.0.1-alpha.0

package/dist/core/service/item-service.d.ts

@@ -0,0 +1,641 @@
+import { spec, VFXItem } from '../../shared';
+import type { AnyArtisErrorInfo, ErrorPhase } from '../quality/error-monitor/types';
+import { ArtisItem } from '../item';
+import type { FrameManager, Selection } from '@vvfx/gizmo';
+import { Vector2, Box2, LoadingManager } from '@vvfx/gizmo';
+import { type InteractionService } from './interaction-service';
+import { type Store } from '../store';
+import { type AssetManager } from '../asset';
+import { type UserPreferencesManager } from '../preferences';
+import { GeneratorType, type ItemSchema, type LayoutInfo, type PageAutoLayoutParam, type AssetLoadResult } from '../types';
+import { Renderer } from '../renderer';
+import { type ViewService } from './view-service';
+import { type PerfMonitor } from '../quality/perf-monitor';
+import { type ElementIdentityStrategy } from '../element-registry';
+/**
+ * ItemService - 元素 CRUD 门面服务
+ *
+ * 对外保持稳定的统一 API，内部将职责委托给三个子服务：
+ * - ItemCreatorService：各类型元素的 ArtisItem + VFXItem 创建工厂
+ * - ItemAssetService：资源加载与切换（带引用计数）
+ * - ItemSyncService：Player → Store 数据同步
+ *
+ * 原有公共方法签名不变，外部调用方无需修改。
+ */
+export declare class ItemService {
+    private _store;
+    private _renderer;
+    private _viewService;
+    private _selection?;
+    private _interactionService;
+    private readonly _loadingManager;
+    private _frameService;
+    private _frameManager;
+    /** 资源换源请求代次：同一元素只允许最后一次请求提交运行态与资源引用。 */
+    private _resourceRequestSequence;
+    private readonly _resourceRequestByItem;
+    /** 编辑后刷新 GE 动画基线，避免带动画元素编辑器内播放回弹（见服务注释） */
+    private readonly _animBaseRefresher;
+    /**
+     * 初始化各子服务并注入跨服务依赖回调
+     *
+     * selection 在 GizmoManager 装配后才存在，故构造时不传，
+     * 由 {@link setSelection} 在装配后回填（同时下发给 ItemSyncService）。
+     * @param options 构造选项
+     */
+    constructor(options: {
+        renderer: Renderer;
+        viewService: ViewService;
+        store: Store;
+        assetManager: AssetManager;
+        userPreferences: UserPreferencesManager;
+        interactionService: InteractionService;
+        frameManager: FrameManager;
+        /** 元素身份策略（统一 id 基准与映射翻译），由 BaseArtis._createIdentityStrategy 注入 */
+        identityStrategy: ElementIdentityStrategy;
+        loadingManager: LoadingManager;
+        /** 尺寸 0 兜底尺寸 [width, height]，默认 1024×1024；显式 0 时经此兜底并 emit warning */
+        fallbackSize?: [number, number];
+    });
+    /**
+     * 注入性能监测器（enablePerfMonitor / options.perf 装配后调用）。
+     * 注入后 withLoading 内的资源加载会按元素记录 RESOURCE_LOAD 耗时。
+     * @param monitor 性能监测器；undefined 可用于解绑
+     */
+    setPerfMonitor(monitor?: PerfMonitor): void;
+    /**
+     * 配置尺寸 0 兜底尺寸。
+     *
+     * 外部传入显式 0 的 width/height 创建元素时，{@link createItemCore} 用此尺寸兜底（回写 property 落盘）
+     * 并 emit warning，避免 0 透传给 LoadingGizmo/interactionService 导致除零 NaN 挂死。
+     * 默认 1024×1024；宿主可按业务场景自行配置。两分量均须 > 0，非正值忽略并告警。
+     * @param size [width, height]，均须 > 0
+     */
+    setFallbackSize(size: [number, number]): void;
+    /**
+     * 注入事件 emit 与错误快照捕获回调（由 BaseArtis 装配后注入，避免 core 反向依赖 artis 事件总线）。
+     *
+     * - emit：warning（可降级，如尺寸 0 兜底）/ error（真失败，如资源加载失败、运算抛错）事件发散出口。
+     * - captureErrorSnapshot：桥接 ErrorMonitor.captureSnapshot，产出含场景快照 + 最近 5 条 Command 的
+     *   {@link AnyArtisErrorInfo}，供 error 事件载荷复现/调试。惰性读 monitor，未装配时由注入方返回降级最小结构。
+     *
+     * 未注入时（core 独立运行/测试），warning 与 error 降级为 console，保证 core 不依赖 artis 层即可工作。
+     * @param emit 事件 emit 回调
+     * @param captureErrorSnapshot 错误快照捕获回调
+     */
+    setEventEmitter(emit?: <K extends keyof import('../types/artis-events').BaseArtisEvents>(event: K, ...args: import('../types/artis-events').BaseArtisEvents[K]) => void, captureErrorSnapshot?: (error: unknown, phase: ErrorPhase, ctx?: {
+        gizmoType?: string;
+        commandId?: string;
+        methodName?: string;
+    }) => AnyArtisErrorInfo | undefined): void;
+    /**
+     * 元素ID 查重预检（决策 D1）：命中已占用 ID 抛 DuplicateElementIdError，错误携带可用候选 suggestedId。
+     * 不自动改名、不创建——调用方可拿 suggestedId 重试。供 ItemCreateCommand 构造时预检，
+     * 避免 execute 的 `void createItem(...)` 吞掉 async reject。
+     * @param elementId 待检元素ID
+     */
+    assertElementIdUnique(elementId: string): void;
+    /**
+     * 清空元素ID ↔ vfxItemId 映射注册表。
+     */
+    clearElementRegistry(): void;
+    /**
+     * 回填 Selection 实例（由 BaseArtis 在 GizmoManager 装配后注入）。
+     *
+     * Selection 由 GizmoManager 持有，构造晚于 ItemService，故构造时不传、装配后回填。
+     * 同时下发给 ItemSyncService，供其 syncSelectedItemsTransform 读取选中集。
+     * @param selection 选中态真源（来自 GizmoManager）
+     */
+    setSelection(selection: Selection): void;
+    /**
+     * 资源加载过程的 loading 包络：add → 执行 fn → finally delete。
+     *
+     * loading 态收敛到本层管理，子服务 ItemAssetService 只管资源加载本身、不感知 gizmo。
+     * 调用 add 时 shimmer VFXItem 由 LoadingGizmo 每帧按实时包围盒刷新位置/尺寸，故即便此时
+     * 元素 transform 尚未就绪（取到空盒），下一帧也会自动修正——无需调用方控制 add 时机。
+     * @param id 目标元素 ID
+     * @param fn 实际资源加载逻辑
+     * @returns fn 的返回值
+     */
+    private withLoading;
+    /**
+     * 统一图片/视频/特效换源闭环。
+     *
+     * 空白资源不发起网络请求，直接进入 pending + loading；非空资源仅在当前请求仍为最后一次时提交，
+     * 因而并发换源、删除中加载、undo 回空值都不会被较早完成的请求反向覆盖。
+     */
+    private _replaceResource;
+    /** 特效换源事务：新子合成成功挂载后才释放旧子合成与旧 effect 资源。 */
+    private _replaceEffectsResource;
+    /**
+     * 创建元素核心（同步）：建 ArtisItem + Player VFXItem + resolveItemId + registerMapping + goto，
+     * 同步返回真实 id（Artis=schemaId，SceneArtis=instanceId）与可选的资源加载 Promise。
+     *
+     * 同步性是 Command id 契约的前提——{@link ItemCreateCommand} 需 execute 后即得真实 id，
+     * 服务于 ArtisSDK._createByInfo 的同步返回契约（addXxxItem 同步返回新元素 id）。
+     * frame/effects 的资源加载为异步，经 resourcePromise 返回由调用方决定是否 await。
+     * @param info 元素 Schema 描述
+     * @returns 真实 id 与可选资源 Promise
+     */
+    createItemCore(info: ItemSchema, options?: {
+        goto?: boolean;
+    }): {
+        id: string;
+        resourcePromise?: Promise<void>;
+    };
+    /**
+     * 创建元素（异步）：执行 {@link createItemCore} 并等待异步资源（frame 预合成）加载完成。
+     * @param info 元素 Schema 描述
+     * @returns 新建元素的真实 ID
+     */
+    createItem(info: ItemSchema): Promise<string>;
+    /**
+     * 加载元素资源（异步）— 委托给 ItemAssetService
+     * @param id 元素 ID
+     * @param url 资源 URL
+     * @param assetType 资源类型，默认 image
+     * @returns 资源加载结果
+     */
+    loadItemAsset(id: string, url: string, assetType?: 'image' | 'video'): Promise<AssetLoadResult>;
+    /**
+     * auto 尺寸收敛：sprite/video 处于 sizeMode='auto' 时，按其当前绑定资源的原生尺寸
+     * （AssetManager entry 的 width/height，由 loadItemAsset/换源 register 时填入）回写元素尺寸
+     * （property.width/height + transform.setSize 经 getWorldSizeByPixelSize 重算世界尺寸）。
+     *
+     * 触发时机：① create 后首帧 loadItemAsset 完成；② 换源成功后。仅在尺寸真正变化时写并 gotoEdit。
+     * 兜底：entry 宽高为 0（视频跨域/损坏未读到 metadata）→ 维持占位 + console.warn，状态仍 auto，不抛。
+     * 不进 undo：create 内首次收敛属创建流程；换源收敛由换源入口各自决定 undo 粒度（图片走 sprite.image、
+     * 视频走 video.source command，URL 与尺寸在同一 command 单元）。
+     * @param id 元素 ID
+     */
+    applyAutoSizeByElementAsset(id: string): void;
+    /**
+     * 退出 auto → fixed：仅对 sprite/video 且当前 sizeMode='auto' 生效。由 {@link ItemTransformCommand}
+     * 在用户显式设尺寸（patch 含 width/height）时调用；gizmo 拖拽走 transform.scale 改 scale，
+     * 不触此方法，故 auto 状态保留。状态翻转本身不单独进 undo（尺寸变更已在该 command 的 undo 范围内）。
+     * @param id 元素 ID
+     */
+    markFixedSizeIfAuto(id: string): void;
+    /**
+     * 查询元素资源加载错误（运行态，不落盘/不进 undo）。
+     *
+     * loadItemAsset 失败时由创建/换源回调写入 `_loadError`（Error），成功后清空为 null。
+     * 供 `artis.item.getLoadError(id)` 门面查询 + loading/failure gizmo 显示，避免静默白板无法排查。
+     * @returns 加载失败返回 Error；从未加载或加载成功返回 null；元素不存在返回 undefined
+     */
+    getLoadError(id: string): Error | string | null | undefined;
+    /**
+     * 把视频元素的初始 property（muted/transparent/playbackRate/volume）下沉到 Player VideoComponent。
+     *
+     * create 时占位 VFXItem 的 VideoComponent 默认值可能与 ArtisItem.property 不一致（refactor 此前
+     * 只在用户后改 updateVideoContent 时才下沉）。对齐 master：create/资源就绪后立即下沉，保证
+     * property 与 component 一致；transparent 默认 false 防普通视频持久化后二次加载走 alpha 合成白板。
+     * @param id 元素 ID
+     * @param artisItem 视频元素（已校验 isVideoItem）
+     */
+    private _applyVideoInitProps;
+    /**
+     * 计算新元素的空闲落位 [x,y]（纯计算,不改任何元素）。
+     *
+     * 收口 packages/artis/docs/artis-functions.ts 的 initPositionByFree / initPositionByRow 两个布局算法:
+     * 业务方在 create 元素前调 `artis.item.getInitPosition(nodeSize, { layout })` 取得不与已有元素重叠的落位,
+     * 再用于 create schema 的 property.position。算法口径与原函数一致;依赖由原外部 commandBridge.artis
+     * 全局句柄改为直接读 store.items(等价旧 SDK 的 getSDKItems)+ ArtisItem.property。
+     *
+     * - 'free'(默认):找已有元素最右下角作参照 → 超过 wrapThreshold 或显式 wrap 时换行 → Y 轴碰撞下移。
+     *   忽略画板父级的子元素与组元素。wrapMode:'wrap'(立即换行)|'nowrap'(禁换行)；wrapThreshold 默认 12000px。
+     * - 'row':从 rowAnchor 往右避让,sprite/video 碰撞框按 scale 算实际占位,横向重叠则右移;带 10s 超时防死循环。
+     *
+     * @param nodeSize 新节点尺寸(宽高,用于落位中心偏移与碰撞框)
+     * @param options layout/wrapMode/wrapThreshold/excludeIds/rowAnchor/rowScale,见上
+     * @returns [x, y] 像素坐标;无已有元素时返回 [0,0]
+     */
+    getInitPosition(nodeSize: Vector2, options?: {
+        layout?: 'free' | 'row';
+        wrapMode?: 'wrap' | 'nowrap';
+        wrapThreshold?: number;
+        excludeIds?: string[];
+        rowAnchor?: Vector2;
+        rowScale?: Vector2;
+        shift?: number;
+    }): [number, number];
+    /** 两矩形是否相交(中心坐标+宽高) */
+    private _haveIntersection;
+    /** 自由落位:参考已有元素最右下角 → 换行 → Y 碰撞下移。忽略画板父级的子元素与组元素。 */
+    private _initPositionByFree;
+    /** 横向布局:从 rowAnchor 往右避让,sprite/video 碰撞框按 scale 算实际占位,横向重叠则右移;10s 超时防死循环。 */
+    private _initPositionByRow;
+    /**
+     * 同步 Store.items 的顺序到 Player 层的 renderOrder — 委托给 ItemSyncService
+     */
+    syncRenderOrder(): void;
+    /**
+     * 同步选中元素的变换信息（VFXItem.transform → ArtisItem.property）— 委托给 ItemSyncService
+     */
+    syncSelectedItemsTransform(): void;
+    /**
+     * 同步所有元素的变换（VFXItem.transform → ArtisItem.property）— 委托给 ItemSyncService
+     */
+    syncAllItemsFromPlayer(): void;
+    /**
+     * 同步单个元素的变换（VFXItem.transform → ArtisItem.property）— 委托给 ItemSyncService
+     * @param id 元素 ID
+     */
+    syncItemTransform(id: string): void;
+    /** 交互计算服务实例 */
+    get interactionService(): InteractionService;
+    /** Canonical Frame data owned by the gizmo package. */
+    get frames(): FrameManager;
+    /** 当前激活的合成（场景未加载时返回 undefined） */
+    get composition(): import("@galacean/effects").Composition;
+    /**
+     * 按像素增量平移元素，同步到 Player 与 ArtisItem
+     * @param id 元素 ID
+     * @param deltaPixel 像素坐标系下的位移增量 [dx, dy]
+     */
+    moveItem(id: string, deltaPixel: [number, number]): void;
+    /**
+     * 修改元素变换属性（像素坐标系）
+     *
+     * 更新流程：ArtisItem.property → VFXItem.transform → Scene JSON
+     * @param id 元素 ID
+     * @param transform 变换字段增量（仅提供需要变更的字段）
+     */
+    updateItemTransform(id: string, transform: Partial<{
+        position: [number, number];
+        rotation: number;
+        scale: [number, number];
+        width: number;
+        height: number;
+    }>): void;
+    /**
+     * 修改图片元素的图片源
+     *
+     * 经统一资源协调器进入 loading，再委托 `ItemAssetService` 准备新 Texture、提交贴图并释放旧资源。
+     * 贴图成功应用后才写 `ArtisItem.property.image`；空值则转入 pending，等待后续 replace。
+     * @param id 元素 ID
+     * @param imageUrl 新图片 URL
+     */
+    updateSpriteImage(id: string, imageUrl: string): Promise<void>;
+    /**
+     * 修改文本元素内容
+     * @param id 元素 ID
+     * @param content 文本属性增量（仅提供需要变更的字段）
+     */
+    updateTextContent(id: string, content: Partial<{
+        text: string;
+        fontSize: number;
+        fontFamily: string;
+        lineHeight: number;
+        color: spec.vec4;
+        fontWeight: spec.TextWeight;
+        fontStyle: spec.FontStyle;
+        textAlign: spec.TextAlignment;
+        outlineColor: spec.vec4;
+        outlineWidth: number;
+        outlineEnabled: boolean;
+    }>): void;
+    /**
+     * 实时修改固定宽度文字的排版宽度和中心点。
+     *
+     * 宽度只写 TextComponent，位置只做增量平移；不走 updateItemTransform，避免它重写
+     * transform.size 后与文字自身 scale 叠加，造成拖拽过程中字号视觉缩小。
+     * @param id 文本元素 ID
+     * @param position 目标像素中心点
+     * @param width 目标像素宽度
+     * @param resizeSnapshot Undo/Redo 文本缩放时需要一并恢复的排版与变换快照
+     */
+    updateTextItemBox(id: string, position: [number, number], width: number, resizeSnapshot?: {
+        scale: [number, number];
+        height: number;
+        fontSize: number;
+        lineHeight: number;
+    }): void;
+    /**
+     * 修改视频元素属性
+     * @param id 元素 ID
+     * @param content 视频属性增量（仅提供需要变更的字段）
+     */
+    updateVideoContent(id: string, content: Partial<{
+        videoUrl: string;
+        muted: boolean;
+        transparent: boolean;
+        playbackRate: number;
+        volume: number;
+    }>): void;
+    /**
+     * 修改生成器元素类型
+     * @param id 元素 ID
+     * @param generatorType 生成器类型
+     */
+    updateGeneratorType(id: string, generatorType: GeneratorType): void;
+    /**
+     * 设置生成器资源：将生成器元素原地替换为对应的 sprite / video 元素（复用同一 ID）。
+     *
+     * 对齐旧版 `setGeneratorResource`：generator 元素本身不承载资源，拿到资源后需转换为
+     * 真正的图片 / 视频元素。转换规则按 generatorType 决定（image → sprite，video → video）。
+     *
+     * @param id 生成器元素 ID
+     * @param resourceUrl 资源地址
+     * @returns 转换后的元素 ID（与入参 id 相同）；元素不存在或非生成器时返回 undefined
+     */
+    setGeneratorResource(id: string, resourceUrl: string): string | undefined;
+    /**
+     * 设置生成器资源的同步核心：将生成器元素原地替换为 sprite / video 元素（复用同一 Schema 种子 ID）。
+     *
+     * 同步版供 {@link ItemSetGeneratorResourceCommand} execute/redo 捕获转换后的真实 id
+     * （SceneArtis 下为 instanceId）。sprite/video 无预合成资源，createItemCore 的 resourcePromise
+     * 为 undefined，与原 async createItem 行为等价。
+     * @param id 生成器元素 ID
+     * @param resourceUrl 资源地址
+     * @returns 转换后的元素真实 ID；非生成器元素返回 undefined
+     */
+    setGeneratorResourceCore(id: string, resourceUrl: string): string | undefined;
+    /**
+     * 修改特效元素资源
+     * @param id 元素 ID
+     * @param effectsUrl 特效资源 URL
+     */
+    updateEffectsSource(id: string, effectsUrl: string): Promise<void>;
+    /**
+     * 静默替换在线资源（ready 元素不显示 loading，pending/error 元素复用 loading 闭环）。
+     *
+     * 与 {@link updateSpriteImage} / {@link updateVideoContent} / {@link updateEffectsSource} 的区别：
+     * 后三者始终进入 loading(gizmo 覆盖)。本方法对正常在线资源热替换保持静默；若元素来自空资源
+     * placeholder 或上次加载失败，则维持已有 loading，直到本次成功或失败后关闭。供 `item.replaceSource` command 调用。
+     *
+     * 按元素类型自动分发：sprite→image、video→video、effects→effects。auto 状态下换源后按新资源原生尺寸收敛
+     * （effects 走 autoFit 主合成 previewSize）。尺寸随换源实时算，故 undo URL 即可原子回退尺寸。
+     *
+     * effects 采用准备后提交：新子合成完整挂载后才释放旧子合成与旧资源；失败保留旧画面和旧 property。
+     * @param id 元素 ID
+     * @param newUrl 新资源 URL
+     * @returns true 表示换源已发起/完成；元素不存在或类型不支持返回 false
+     */
+    replaceSourceSilent(id: string, newUrl: string): Promise<boolean>;
+    /**
+     * 修改画板布局模式
+     * @param id 画板 ID
+     * @param layoutMode 布局模式 'auto' | 'free'
+     */
+    updateFrameLayoutMode(id: string, layoutMode: 'auto' | 'free'): void;
+    /**
+     * 计算「单元素行列变更」后的完整 layoutInfos（纯计算，不修改任何数据）
+     *
+     * @param frameId 画板 ID
+     * @param draggedItemId 被拖拽元素 ID
+     * @param fromRow 起始行
+     * @param fromColumn 起始列
+     * @param toRow 目标行
+     * @param toColumn 目标列
+     * @returns 完整的新 layoutInfos；Frame 或被拖拽元素不存在时返回 undefined
+     */
+    computeLayoutInfosAfterReorder(frameId: string, draggedItemId: string, fromRow: number, fromColumn: number, toRow: number, toColumn: number): Record<string, LayoutInfo> | undefined;
+    /**
+     * 调整 Frame 内元素行列顺序并重新自动排布
+     * @param frameId 画板 ID
+     * @param draggedItemId 被拖拽元素 ID
+     * @param fromRow 起始行
+     * @param fromColumn 起始列
+     * @param toRow 目标行
+     * @param toColumn 目标列
+     */
+    adjustFrameLayoutOrder(frameId: string, draggedItemId: string, fromRow: number, fromColumn: number, toRow: number, toColumn: number): void;
+    /**
+     * 修改画板子元素
+     * @param id 画板 ID
+     * @param children 子元素 ID 列表
+     */
+    updateFrameChildren(id: string, children: string[]): void;
+    /**
+     * 修改卡片元素属性
+     * @param id 元素 ID
+     * @param content 卡片属性增量
+     */
+    updateCardContent(id: string, content: Partial<{
+        cardType: string;
+        autoHeight: boolean;
+    }>): void;
+    /**
+     * 将元素移动到 Frame 中
+     * @param itemIds 要移动的元素ID列表
+     * @param frameId 目标 Frame ID
+     */
+    moveItemsToFrame(itemIds: string[], frameId: string): void;
+    /**
+     * 按 ID 获取 ArtisItem
+     * @param id 元素 ID
+     * @returns 对应的 ArtisItem；不存在时返回 undefined
+     */
+    getArtisItem(id: string): ArtisItem | undefined;
+    /**
+     * 获取元素的 ItemSchema（用于复制/导出/局部建场景）
+     *
+     * 委托各 ArtisItem 的 `toSchema`，元素不存在时返回 undefined。
+     *
+     * @param id 元素 ID
+     * @param withParent 是否在 Schema 中携带 parentId（默认 false）
+     * @returns 元素 Schema；元素不存在时返回 undefined
+     */
+    getItemSchema(id: string, withParent?: boolean): ItemSchema | undefined;
+    /**
+     * 批量获取元素 ItemSchema，ids 缺省时取场景内全部元素。
+     *
+     * @param ids 元素 ID 列表，缺省取全部
+     * @param withParent 是否携带 parentId（默认 true）
+     * @returns Schema 列表（跳过不存在的元素）
+     */
+    getItemSchemas(ids?: string[], withParent?: boolean): ItemSchema[];
+    /**
+     * 按 ItemSchema 批量更新元素属性（仅更新已存在元素的属性，不创建新元素）。
+     *
+     * 根据 schema.id 找到对应元素，用 schema.property 中提供的字段更新属性并同步到 Player。
+     * 资源类字段（image/video）走对应的资源切换逻辑。
+     * @param schema 单个或多个 ItemSchema
+     * @returns 实际被更新的元素 ID 列表
+     */
+    changeItemPropertyBySchema(schema: ItemSchema | ItemSchema[]): Promise<string[]>;
+    /**
+     * 将单个 ItemSchema 的 property 应用到已存在元素，按类型分派到对应的同步方法。
+     * @param id 元素 ID
+     * @param info 元素 Schema
+     */
+    private _applySchemaProperty;
+    /**
+     * 将元素从 Frame 移出到主场景根节点
+     *
+     * 父子关系保留规则：
+     * - Group 整组移出：只改 Group.parentId = undefined，内部子元素 parentId 保持不变
+     * - 单个元素脱离 Group 后移出：先从 Group.children 中移除，再移到根节点
+     * - Player 层只对顶层元素 setParent（子元素在场景图中自动跟随）
+     * @param itemIds 要移出的元素 ID 列表
+     */
+    moveItemsOutOfFrame(itemIds: string[]): void;
+    /**
+     * 将 Frame 内 Group 的部分直属子元素分离到主场景根节点，并保持世界变换。
+     * AssistedLayout 只生成该决策，实际模型与 Player 修改统一收口到此。
+     */
+    detachGroupChildrenToRoot(groupId: string, itemIds: readonly string[]): void;
+    /**
+     * 恢复 Group 的直属 children 顺序，并把指定子元素从当前位置挂回 Group，保持世界变换。
+     */
+    restoreGroupChildren(groupId: string, children: readonly string[], itemIdsToRestore?: readonly string[]): void;
+    /**
+     * 解除元素与父节点的父子关系
+     * 如果父节点是 Group，同时从 Group.children 中移除
+     * @param itemId 元素 ID
+     * @param parentId 父元素 ID
+     */
+    removeItemParent(itemId: string, parentId: string): void;
+    /**
+     * 对 Frame 内子元素执行自动布局（Shelf 算法，复用 layout-utils.autoLayout）
+     * @param frameId 画板 ID
+     */
+    applyFrameAutoLayout(frameId: string): void;
+    /**
+     * 对页面顶层元素执行全局自动排布（复用 layout-utils.globalAutoLayout）
+     *
+     * @param param 自动布局参数
+     * @param param.mode 排布模式，默认 'adaptive'
+     * @param param.ids 参与排布的元素 ID；不传则排布所有顶层元素
+     * @param param.focus 排布后是否聚焦，默认 true
+     * @param param.gap 元素间隔（像素），默认 10
+     * @param param.padding 聚焦后内容与容器的上下左右间距（像素），仅 focus 开启时生效
+     */
+    autoLayoutPage(param?: PageAutoLayoutParam): void;
+    /**
+     * 计算选中元素排布的锚点偏移：保持原始包围盒左上角位置不变
+     * @param layoutElements 参与排布的元素列表
+     * @param layoutBoundingBox 排布算法输出的包围盒
+     * @returns 锚点偏移量
+     */
+    private getPartialLayoutAnchor;
+    /**
+     * 计算全量排布的锚点偏移：以视口中心为锚点
+     * @param layoutBoundingBox 排布算法输出的包围盒
+     * @returns 锚点偏移量
+     */
+    private getGlobalLayoutAnchor;
+    /**
+     * 修改画板元素大小（仅 Player + ArtisItem，不涉及 JSON 层）
+     *
+     * @param id Frame 元素 ID
+     * @param size 目标大小 [width, height]（像素）
+     */
+    updateFrameItemSize(id: string, size: [number, number]): void;
+    /**
+     * 刷新 Frame 子元素列表：从 Player 层父子关系反向同步到 Frame.property.children
+     * @param frameId 画板 ID
+     */
+    refreshFrameChildren(frameId: string): void;
+    /**
+     * 递归收集元素及其所有嵌套子元素（处理 Group/Frame 容器）
+     * @param itemIds 起始元素 ID 列表
+     * @returns 含子元素的全部元素 ID 列表（去重）
+     */
+    collectItemsWithChildren(itemIds: string[]): string[];
+    /**
+     * 删除元素
+     *
+     * 按类型差异化处理子元素：
+     * - Group（空节点/编组）：解除编组，把所有子元素 parentId 清空提升到根节点
+     * - Frame（画板）：把子元素移出 Frame 到根节点，保持画布世界位置不变
+     * - Effects（特效）：递归删除所有子元素
+     * - 其他：直接删除
+     *
+     * 通用兜底：删除元素时从其 parent（Group/Frame）的 children 中移除自身 id
+     *
+     * 清理顺序：前置处理子元素 → 从 parent.children 移除 → Store → Player VFXItem → 选中列表
+     * @param id 要删除的元素 ID
+     */
+    removeItem(id: string): void;
+    /**
+     * vfxItemId / instanceId → 元素ID（elementId）。
+     *
+     * artis↔gizmo 边界翻译：gizmo 运行时全程用 VFXItem.instanceId，
+     * artis 数据侧（store 里 ArtisItem.id）是 elementId。本方法把传入的 instanceId
+     * 翻译回 elementId，供「按 id 查 store」类调用统一入口。
+     * 未注册时兜底原值（SceneArtis 走 identity 直返原值、Artis 理论上应命中 registry）。
+     */
+    toElementId(id: string): string;
+    /**
+     * 元素ID（elementId）→ vfxItemId / instanceId。
+     *
+     * 边界翻译的反向：artis 对外/数据侧用 elementId，需要喂给 gizmo 或查 Player 维度
+     * VFXItem 时翻译成 instanceId。未注册时兜底原值。
+     */
+    toVfxItemId(id: string): string;
+    /**
+     * 按 ID 查找 Player 层 VFXItem
+     * @param id 元素 ID
+     * @returns 对应的 VFXItem；不存在时返回 undefined
+     */
+    findPlayerItemById(id: string): VFXItem | undefined;
+    /**
+     * 按 ID 获取元素的像素包围盒。
+     *
+     * 走 {@link getItemSchema} 取 ItemSchema 后委托纯函数 `getPixelBoxBySchema`
+     * （utils/pixel-box-utils）按数据算盒（基准像素空间、size 补乘 scale、含 rotation）。
+     * GROUP 等空节点无自身尺寸，返回空盒。
+     *
+     * @param id 元素 ID
+     * @returns 元素像素包围盒；元素不存在时返回空包围盒
+     */
+    getPixelBox(id: string): Box2;
+    /**
+     * 按 ID 获取「画板子元素」像素包围盒：叶子走 {@link getPixelBox}；
+     * Group（空节点）取其所有后代包围盒的递归并集（用于画板自动布局把组当作单个 cell）。
+     *
+     * @param id 元素 ID
+     * @param visited 环路保护（内部递归用）
+     * @returns 元素像素包围盒；元素不存在或空组时返回空包围盒
+     */
+    getFrameChildPixelBox(id: string, visited?: Set<string>): Box2;
+    /**
+     * 按 ID 获取元素在视口坐标系下的包围盒
+     * @param id 元素 ID
+     * @returns 视口坐标系包围盒；元素不存在时返回空包围盒
+     */
+    getViewBox(id: string): Box2;
+    /**
+     * 读取视频元素当前播放时间（秒）。元素不存在或非视频时返回 0。
+     * @param id 视频元素 ID
+     * @returns 当前播放时间；读取失败返回 0
+     */
+    getVideoItemPlayTime(id: string): number;
+    /**
+     * 设置视频元素播放时间（秒），底层自动 clamp 到 [0, duration]。
+     * 静默定位到该帧，不动播放态与其他元素。
+     * @param id 视频元素 ID
+     * @param time 目标时间（秒）
+     */
+    setVideoItemPlayTime(id: string, time: number): void;
+    /**
+     * 暂停视频元素
+     * @param id 元素ID
+     */
+    pauseVideoItem(id: string): void;
+    /**
+     * 播放视频元素
+     * @param id 元素ID
+     */
+    playVideoItem(id: string): void;
+    /**
+     * 读取动效元素当前播放时间（秒）。元素不存在或非动效时返回 0。
+     *
+     * 动效元素在底层是 composition 子项，ArtisItem 经
+     * {@link EffectsItem.subCompositionItemId} 持有该子项 instanceId，
+     * 据此取 CompositionComponent.getTime。
+     * @param id 动效元素 ID
+     * @returns 当前播放时间；读取失败返回 0
+     */
+    getEffectsItemPlayTime(id: string): number;
+    /**
+     * 设置动效元素播放时间（秒）。静默定位到该帧，不动其他元素播放态。
+     * @param id 动效元素 ID
+     * @param time 目标时间（秒）
+     */
+    setEffectsItemPlayTime(id: string, time: number): void;
+    pauseEffectsItem(id: string): void;
+    playEffectsItem(id: string): void;
+}