@vvfx/artis 0.0.1-alpha.0

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

@@ -0,0 +1,211 @@
+import { Ray, Box2, Euler, Plane, Vector2, Vector3, Matrix4 } from '@vvfx/gizmo';
+import type { CameraInteractionParam, ViewInteractionParam } from '../../utils/types';
+/**
+ * 视口数据提供者
+ * 提供当前视口的宽高、缩放、平移信息
+ */
+export type ViewportProvider = {
+    /**
+     * 获取当前视口的宽高、缩放因子与平移信息
+     * @returns 视口宽高；zoom 用户缩放、contentRatio 容器 aspect 补偿、viewScale 展示场景缩放、translation 平移
+     */
+    getViewport(): {
+        width: number;
+        height: number;
+        zoom: number;
+        contentRatio: number;
+        widthRatio: number;
+        heightRatio: number;
+        pixelRatio: number;
+        translation: Vector2;
+    };
+};
+/**
+ * 相机数据提供者
+ * 提供相机的 VP 矩阵、逆 VP 矩阵、位置等信息
+ */
+export type CameraProvider = {
+    /**
+     * 获取相机的 VP、逆 VP、view 矩阵及 viewport 矩阵
+     * @returns 相机矩阵信息；场景未就绪时返回 undefined
+  
+     */
+    getCameraInfo(): {
+        viewProjectionMatrix: Matrix4;
+        inverseViewProjectionMatrix: Matrix4;
+        viewMatrix: Matrix4;
+        viewportMatrix: Matrix4;
+    } | undefined;
+};
+/**
+ * 元素变换提供者
+ * 提供指定元素的世界变换矩阵
+ */
+export type ItemTransformProvider = {
+    getWorldMatrix(id: string): Matrix4 | undefined;
+};
+/**
+ * InteractionService 配置
+ */
+export type InteractionConfig = {
+    viewportProvider: ViewportProvider;
+    cameraProvider: CameraProvider;
+    itemTransformProvider: ItemTransformProvider;
+};
+/**
+ * InteractionService - 坐标转换与交互计算服务
+ *
+ * 纯计算类，不直接引用 Player / PageData / Store。
+ * 所有外部数据通过接口注入，调用 refresh*() 时从接口拉取最新状态。
+ */
+export declare class InteractionService {
+    /** 交互平面（用于射线求交） */
+    plane: Plane;
+    /** 交互射线 */
+    ray: Ray;
+    /** 视口参数缓存 */
+    viewportParam: ViewInteractionParam;
+    /** 相机参数缓存 */
+    cameraParam: CameraInteractionParam;
+    private _config;
+    /**
+     * 注入视口、相机、元素变换数据提供者
+     * @param config 数据提供者配置
+     */
+    constructor(config: InteractionConfig);
+    /**
+     * 从 ViewportProvider 刷新视口参数（含 zoom / contentRatio 三因子）
+     */
+    refreshViewport(): void;
+    /**
+     * 渲染端有效缩放比 = zoom · contentRatio
+     */
+    getEffectiveScale(): number;
+    /**
+     * 从 CameraProvider 刷新相机参数
+     */
+    refreshCamera(): void;
+    /**
+     * 通过原始相机配置参数刷新（用于场景未就绪时的静态初始化）
+     * @param camera 相机原始配置
+     */
+    refreshCameraByRawConfig(camera: {
+        near: number;
+        far: number;
+        fov: number;
+        aspect: number;
+        position: [number, number, number];
+        clipMode: number;
+    }): void;
+    /**
+     * 初始化交互平面
+     * @param position 平面上的参考点，缺省取相机焦点
+     * @param rotation 平面法线朝向，缺省取相机旋转
+     */
+    initInteractionPlane(position?: Vector3, rotation?: Euler): void;
+    /**
+     * 将世界坐标投影到视口坐标
+     * @param point 世界坐标
+     * @returns 视口坐标
+     */
+    projectPoint(point: Vector3): Vector2;
+    /**
+     * 通过视口坐标获取世界坐标（射线与相机焦点平面求交）
+     * @param point 视口坐标
+     * @returns 世界坐标；射线与平面无交点时返回 undefined
+     */
+    getWorldPositionByViewPosition(point: Vector2): Vector3 | undefined;
+    /**
+     * 屏幕坐标 → NDC 坐标
+     * @param point 视口坐标
+     * @returns NDC 坐标
+     */
+    getNDCPositionByViewPosition(point: Vector2): Vector2;
+    /**
+     * 像素坐标 → 视口坐标（应用 zoom + translation）
+     * @param point 像素坐标
+     * @returns 视口坐标
+     */
+    getViewPositionByPixelPoint(point: Vector2): Vector2;
+    /**
+     * 视口坐标 → 像素坐标（逆向 zoom + translation）
+     * @param point 视口坐标
+     * @returns 像素坐标
+     */
+    getPixelPositionByViewPoint(point: Vector2): Vector2;
+    /**
+     * 像素坐标系包围盒 → 视口坐标系包围盒（应用 zoom + translation）
+     *
+     * 以容器中心为锚点缩放后再平移，与 getViewPositionByPixelPoint 的坐标系一致。
+     * @param box 像素坐标系包围盒
+     * @returns 视口坐标系包围盒
+     */
+    getViewBoxByBox(box: Box2): Box2;
+    /**
+     * 像素尺寸 → 视口（容器）尺寸
+     *
+     * @param pixelSize 像素尺寸（DOM delta）
+     * @returns 容器像素尺寸
+     */
+    getViewSizeByPixelSize(pixelSize: Vector2): Vector2;
+    getWorldSizeByPixelSize(pixelSize: Vector2, isWorld?: boolean, itemId?: string): Vector3;
+    /**
+     * 视口（容器）尺寸 → 基准像素尺寸
+     *
+     * 与 {@link getViewSizeByPixelSize} 互逆：基准像素 = 容器像素 / effectiveScale / pixelRatio · (widthRatio, heightRatio)。
+     * effectiveScale 与 renderer viewportMatrix 同源，口径与 getWorldSizeByViewSize/投影一致。
+     * @param viewSize 容器像素尺寸（含视图缩放）
+     * @returns 基准像素尺寸
+     */
+    getPixelSizeByViewSize(viewSize: Vector2): Vector2;
+    /**
+     * 世界尺寸 → 基准像素尺寸
+     *
+     * 走纯 VP 投影得容器像素差，再经 `getPixelSizeByViewSize` 转基准像素，与之互逆自洽。
+     * @param worldSize 世界尺寸
+     * @returns 基准像素尺寸（取绝对值）
+     */
+    getPixelSizeByWorldSize(worldSize: Vector3): Vector2;
+    /**
+     * 视口（容器）尺寸 → 世界尺寸
+     *
+     * 入参 viewSize 为容器像素（与 `getViewSizeByPixelSize` 输出配套）。内部先除以
+     * effectiveScale 转基准像素，再走纯 VP 射线求交，与 `getPixelSizeByWorldSize` 自洽。
+     * @param viewSize 视口（容器）尺寸
+     * @param isWorld 是否基于世界坐标系（否则基于元素坐标系）
+     * @param itemId 目标元素 ID（用于确定交互平面）
+     * @returns 世界尺寸；超界时返回零向量
+     */
+    getWorldSizeByViewSize(viewSize: Vector2, isWorld?: boolean, itemId?: string): Vector3;
+    /**
+     * 世界点 → 基准像素（用纯 VP），与 `projectPoint`（含 viewport）对应。
+     * @param point 世界坐标
+     * @returns 基准像素坐标
+     */
+    private _projectPointBaseline;
+    /**
+     * 基准像素 → 世界坐标（射线与交互平面求交，用纯逆 VP）
+     * @param baselinePoint 基准像素坐标
+     * @returns 世界坐标；射线与平面无交点时返回 undefined
+     */
+    private _getWorldPositionByBaselineView;
+    private _createInteractionPlane;
+    /**
+     * 视口尺寸合法性校验——几何坐标转换的前置防御。
+     *
+     * viewport width/height 为 0（容器未布局/隐藏）或 NaN（view-service handleResize 中
+     * `0/0` 中毒、widthRatio 污染）时，下游 `toViewCoordinate` / `viewPositionToNDC` /
+     * `.divide(widthRatio,heightRatio)` 会除零得 NaN，**JS 不抛错、静默污染 transform/gizmo**，
+     * 导致元素创建后 LoadingGizmo 挂死、坐标运算失真且无法被 catch。
+     *
+     * 此处把隐式 NaN 显式化为抛错（普通 Error，message 含 width/height + 调用方法名），
+     * 供调用方（createItemCore 等 service 层）try/catch 后经 captureSnapshot 产出
+     * 「场景快照 + 最近5 Command」emit('error')。gizmo 包不直接依赖 InteractionService，
+     * 故抛错不在拖拽/命中的热路径上，仅冒泡到 service 层创建/换源/布局/同步链路。
+     *
+     * 注：本类被 ItemService/FrameService/ItemSyncService 等 service 层调用，非 gizmo 热路径。
+     * 仅做入口输入校验，不对运算结果 NaN 二次检查（避免内部高频辅助调用每帧抛）。
+     * @param methodName 触发校验的方法名，写入 message 供排查
+     */
+    private _assertViewportValid;
+}

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

@@ -0,0 +1,120 @@
+import { spec, VFXItem } from '../../shared';
+import { Vector3 } from '@vvfx/gizmo';
+import { type Store } from '../store';
+import { type AssetManager } from '../asset';
+import { type AssetLoadResult } from '../types';
+import { type Renderer } from '../renderer';
+import { type InteractionService } from './interaction-service';
+/**
+ * ItemAssetService - 元素资源加载与切换（资源操作层）服务
+ *
+ * 只管资源操作本身（Texture 准备/绑定、引用计数释放、Component.setTexture）：
+ * 不写 ArtisItem.property、不 gotoEdit、不感知 loading(gizmo)——以上收敛在 ItemService
+ * （统一换源协调器 + property 写入 + gotoEdit 单源头）。
+ *
+ * 贌责边界：只管资源生命周期（加载 / 删除 / 异步加载 / 切换），不修改元素自身尺寸/transform。
+ * 元素尺寸由创建层（ItemCreatorService / ItemService）在 create 期决定。
+ *
+ * 负责：
+ * 1. 首次加载：loadItemAsset（创建时发起，纹理绑定；loading 态由 ItemService.withLoading 管）
+ * 2. 切换资源：updateSpriteImage / switchVideoAsset（带引用计数的旧资源释放）
+ * 3. 特效/画板预合成异步加载：loadEffectsAsset / loadFrameAsset（仅创建子合成并适配渲染，不改元素尺寸）
+ * 4. 生成器转换：setGeneratorResource
+ * 注：generator→sprite/video 的元素类型转换与父子重挂归 ItemService.setGeneratorResourceCore，不在本服务。
+ */
+export declare class ItemAssetService {
+    private _store;
+    private _renderer;
+    private _assetManager;
+    private _interactionService;
+    /** 查找 Player 元素（注入避免循环依赖） */
+    private _findPlayerItemById;
+    /**
+     * 注入依赖与跨服务查找回调
+     * @param options 构造选项
+     */
+    constructor(options: {
+        store: Store;
+        renderer: Renderer;
+        assetManager: AssetManager;
+        interactionService: InteractionService;
+        findPlayerItemById: (id: string) => VFXItem | undefined;
+        registerMapping: (elementId: string, vfxItemId: string) => void;
+    });
+    /** 当前激活的合成（场景未加载时返回 undefined） */
+    private get composition();
+    /**
+     * 加载元素资源（异步）
+     *
+     * 在 createItem 后调用。加载过程中元素处于 loading 态。
+     * 加载完成后将资源绑定到 VFXItem 的 Component，并在 AssetManager 中记录映射。
+     * @param id 元素实例 ID
+     * @param url 资源地址
+     * @param assetType 资源类型，默认 image
+     * @returns 加载结果；失败时返回含 error 的结果
+     */
+    loadItemAsset(id: string, url: string, assetType?: 'image' | 'video'): Promise<AssetLoadResult>;
+    /**
+     * 切换元素绑定的资源（带引用计数的释放/复用）
+     *
+     * 流程：先准备新 Texture → 绑定新 asset → 返回延迟释放回调
+     * 调用方在 setTexture 应用完新贴图后调用 releaseOldAssets，确保无空帧闪烁。
+     * @param id 元素实例 ID
+     * @param newUrl 新资源地址
+     * @param assetType 资源类型
+     * @returns 新 Texture 与延迟释放旧资源的回调；准备失败时返回 undefined
+     */
+    private switchItemAsset;
+    /**
+     * 切换图片元素的贴图到新资源（带引用计数的释放/复用）。
+     *
+     * 资源操作层：只负责准备新 Texture、绑定、应用到 SpriteComponent、释放旧资源。
+     * 不写 ArtisItem.property.image、不 gotoEdit —— 由 ItemService 的统一换源协调器提交 property 与渲染。
+     * @param id 元素实例 ID
+     * @param imageUrl 新图片地址
+     * @returns true 表示新贴图已成功应用到 Component；false 表示失败（playerItem 缺失或贴图未就绪）
+     */
+    updateSpriteImage(id: string, imageUrl: string, shouldApply?: () => boolean): Promise<boolean>;
+    /**
+     * 切换视频元素资源并应用到 VideoComponent（带引用计数）。
+     *
+     * @param id 元素实例 ID
+     * @param videoUrl 新视频地址
+     */
+    switchVideoAsset(id: string, videoUrl: string, shouldApply?: () => boolean): Promise<boolean>;
+    /**
+     * 加载特效资源（异步）——仅资源生命周期：fetch→解析→patch→缓存→建子合成→适配渲染→挂占位。
+     *
+     * URL 资源经 AssetManager 统一管理（fetch→解析→patch 主合成 endBehavior→缓存，含引用计数），
+     * 切换同 URL 直接命中缓存不重复 fetch。
+     *
+     * autoFit：autoFit=true 时，资源就绪后以主合成 previewSize（像素）回写元素尺寸
+     * （property.width/height + 占位 transform.setSize），并按新尺寸重算 cover 适配；
+     * autoFit=false 时维持「尺寸在 create 期定死、加载层不改」的既定语义。
+     *
+     * @param id 元素实例 ID
+     * @param name 元素名称
+     * @param effects 特效资源（URL 或 JSONScene；JSONScene 走旧路径不经 AssetManager）
+     * @param worldSize 世界坐标系下的尺寸（创建层已定；autoFit 时按主合成回写后会被本地变量覆盖）
+     * @param worldPosition 世界坐标位置
+     * @param worldRotation 世界坐标旋转
+     * @param worldScale 世界坐标缩放
+     * @param autoFit 是否自适应大小（true=随资源主合成改变尺寸）
+     */
+    loadEffectsAsset(id: string, name: string, effects: string | spec.JSONScene, worldSize: [number, number], worldPosition: Vector3, worldRotation: Vector3, worldScale: Vector3, autoFit?: boolean, shouldApply?: () => boolean): Promise<void>;
+    /**
+     * autoFit 尺寸回写：把像素 previewSize 写进 ArtisItem.property.width/height。
+     * 单位为像素（对齐当前 property 约定，非 origin/master 旧世界坐标）。
+     * 仅写 property，世界坐标换算与占位 setSize 在调用方按需进行。
+     */
+    private _applyAutoFitSize;
+    /**
+     * 加载画板底层预合成资源（异步）
+     * @param id 元素实例 ID
+     * @param compositionItemId 预合成元素实例 ID
+     * @param worldSize 世界坐标系下的尺寸
+     * @param scene 预合成场景数据
+     * @returns 元素或占位元素不存在时返回 undefined，否则无返回值
+     */
+    loadFrameAsset(id: string, compositionItemId: string, worldSize: [number, number], scene: spec.JSONScene): Promise<any>;
+}

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

@@ -0,0 +1,211 @@
+import { spec, VFXItem } from '../../shared';
+import { SpriteItem, TextItem, VideoItem, GroupItem, GeneratorItem, EffectsItem, FrameItem, CardItem } from '../item';
+import type { AutoLayoutConfig, FrameManager, LayoutInfo } from '@vvfx/gizmo';
+import { Vector3 } from '@vvfx/gizmo';
+import { type Store } from '../store';
+import { GeneratorType, TextItemSchema } from '../types';
+import { type Renderer } from '../renderer';
+import { type UserPreferencesManager } from '../preferences';
+/**
+ * ItemCreatorService - 元素创建工厂
+ *
+ * 负责各类型元素的创建逻辑：
+ * 1. 在 Store 中创建对应的 ArtisItem 并推入 store.items
+ * 2. 在 Player 中创建对应的 VFXItem 占位（不含资源）
+ * 3. 资源加载由 ItemAssetService 负责（通过 loadItemAsset 回调注入）
+ */
+export declare class ItemCreatorService {
+    private _store;
+    private _renderer;
+    private _userPreferences;
+    private _frameManager;
+    /** 异步资源加载回调（注入自 ItemService，避免循环依赖） */
+    private _loadItemAsset;
+    private _loadEffectsAsset;
+    /** 资源空 url 占位回调：置 _pendingResource + 挂 loading（注入自 ItemService） */
+    private _markResourcePending;
+    private _loadFrameAsset;
+    /** Frame 子元素管理回调（避免引入 FrameService 循环依赖） */
+    private _moveItemsToFrame;
+    private _syncAllItemsFromPlayer;
+    /** 注册 elementId ↔ vfxItemId 映射（注入自 ItemService，创建 VFXItem 后回调用） */
+    private _registerMapping;
+    /** 元素ID → vfxItemId 翻译（注入自 ItemService，Group reparent 查 child 用） */
+    private _vfxItemIdOf;
+    private _elementIdOf;
+    /** 决定 artisItem.id（注入自 ItemService 策略）：Artis 返 schemaId，SceneArtis 返 instanceId */
+    private _resolveItemId;
+    /**
+     * 注入依赖与异步资源加载、Frame 管理回调
+     * @param options 构造选项
+     */
+    constructor(options: {
+        store: Store;
+        renderer: Renderer;
+        userPreferences: UserPreferencesManager;
+        frameManager: FrameManager;
+        loadItemAsset: (id: string, url: string, assetType: 'image' | 'video') => Promise<void>;
+        loadEffectsAsset: (id: string, name: string, effects: string | spec.JSONScene, worldSize: [number, number], worldPosition: Vector3, worldRotation: Vector3, worldScale: Vector3, autoFit: boolean) => Promise<void>;
+        markResourcePending: (id: string) => void;
+        loadFrameAsset: (id: string, compositionItemId: string, worldSize: [number, number], scene: spec.JSONScene) => Promise<VFXItem | undefined>;
+        moveItemsToFrame: (itemIds: string[], frameId: string) => void;
+        syncAllItemsFromPlayer: () => void;
+        registerMapping: (elementId: string, vfxItemId: string) => void;
+        vfxItemIdOf: (elementId: string) => string | undefined;
+        elementIdOf: (vfxItemId: string) => string | undefined;
+        resolveItemId: (schemaId: string, vfxItem: VFXItem) => string;
+    });
+    /** 当前激活的合成（场景未加载时返回 undefined） */
+    private get composition();
+    /**
+     * 根据生成器类型获取对应的默认名称，未知类型统一回退为“生成器”。
+     * @param generatorType 生成器类型
+     * @returns 生成器默认名称
+     */
+    private _getGeneratorName;
+    /**
+     * 创建图片元素（建 ArtisItem + Player 占位 VFXItem，资源异步加载）
+     * @param id 元素 ID
+     * @param _name 元素名称（保留参数兼容性，生成器名称由 generatorType 决定）
+     * @param pixelPosition 像素坐标 [x, y]
+     * @param rotation 旋转角度（度，Z 轴）
+     * @param scale 缩放 [sx, sy]
+     * @param width 像素宽
+     * @param height 像素高
+     * @param worldSize 世界尺寸 [w, h]
+     * @param worldPosition 世界坐标
+     * @param worldRotation 世界旋转
+     * @param worldScale 世界缩放
+     * @param resourceUrl 图片资源 URL，缺省不加载资源
+     */
+    createSpriteItem(id: string, name: string, pixelPosition: [number, number], rotation: number, scale: [number, number], width: number, height: number, worldSize: [number, number], worldPosition: Vector3, worldRotation: Vector3, worldScale: Vector3, resourceUrl?: string, sizeMode?: 'auto' | 'fixed'): {
+        artisItem: SpriteItem;
+        resourcePromise?: Promise<void>;
+    };
+    /**
+     * 创建文本元素
+     * @param id 元素 ID
+     * @param name 元素名称
+     * @param pixelPosition 像素坐标 [x, y]
+     * @param rotation 旋转角度（度，Z 轴）
+     * @param scale 缩放 [sx, sy]
+     * @param width 像素宽
+     * @param height 像素高
+     * @param worldSize 世界尺寸 [w, h]
+     * @param worldPosition 世界坐标
+     * @param worldRotation 世界旋转
+     * @param worldScale 世界缩放
+     * @param text 文本内容
+     * @param fontSize 字号，缺省 40
+     * @param fontFamily 字体族，缺省空串
+     */
+    createTextItem(id: string, name: string, pixelPosition: [number, number], rotation: number, scale: [number, number], width: number, height: number, worldSize: [number, number], worldPosition: Vector3, worldRotation: Vector3, worldScale: Vector3, property: TextItemSchema['property']): TextItem;
+    /**
+     * 创建视频元素（资源异步加载）
+     * @param id 元素 ID
+     * @param name 元素名称
+     * @param pixelPosition 像素坐标 [x, y]
+     * @param rotation 旋转角度（度，Z 轴）
+     * @param scale 缩放 [sx, sy]
+     * @param width 像素宽
+     * @param height 像素高
+     * @param worldSize 世界尺寸 [w, h]
+     * @param worldPosition 世界坐标
+     * @param worldRotation 世界旋转
+     * @param worldScale 世界缩放
+     * @param videoUrl 视频资源 URL
+     * @param muted 是否静音，缺省 true
+     * @param transparent 是否透明视频，缺省 false（普通视频；true 时按左右分屏 alpha 合成）
+     */
+    createVideoItem(id: string, name: string, pixelPosition: [number, number], rotation: number, scale: [number, number], width: number, height: number, worldSize: [number, number], worldPosition: Vector3, worldRotation: Vector3, worldScale: Vector3, videoUrl: string | null | undefined, sizeMode?: 'auto' | 'fixed', muted?: boolean, transparent?: boolean): {
+        artisItem: VideoItem;
+        resourcePromise?: Promise<void>;
+    };
+    /**
+     * 创建组元素，并将指定子元素挂到组下
+     * @param id 元素 ID
+     * @param name 元素名称
+     * @param pixelPosition 像素坐标 [x, y]
+     * @param rotation 旋转角度（度，Z 轴）
+     * @param scale 缩放 [sx, sy]
+     * @param width 像素宽
+     * @param height 像素高
+     * @param worldSize 世界尺寸 [w, h]
+     * @param worldPosition 世界坐标
+     * @param worldRotation 世界旋转
+     * @param worldScale 世界缩放
+     * @param children 子元素 ID 列表
+     */
+    createGroupItem(id: string, name: string, pixelPosition: [number, number], rotation: number, scale: [number, number], width: number, height: number, worldSize: [number, number], worldPosition: Vector3, worldRotation: Vector3, worldScale: Vector3, children?: string[]): GroupItem;
+    /**
+     * 创建生成器元素（无资源占位）
+     * @param id 元素 ID
+     * @param name 元素名称
+     * @param pixelPosition 像素坐标 [x, y]
+     * @param rotation 旋转角度（度，Z 轴）
+     * @param scale 缩放 [sx, sy]
+     * @param width 像素宽
+     * @param height 像素高
+     * @param worldSize 世界尺寸 [w, h]
+     * @param worldPosition 世界坐标
+     * @param worldRotation 世界旋转
+     * @param worldScale 世界缩放
+     * @param generatorType 生成器类型，缺省 IMAGE
+     */
+    createGeneratorItem(id: string, _name: string, pixelPosition: [number, number], rotation: number, scale: [number, number], width: number, height: number, worldSize: [number, number], worldPosition: Vector3, worldRotation: Vector3, worldScale: Vector3, generatorType?: GeneratorType): GeneratorItem;
+    /**
+     * 创建特效元素（异步加载预合成资源）
+     * @param id 元素 ID
+     * @param name 元素名称
+     * @param pixelPosition 像素坐标 [x, y]
+     * @param rotation 旋转角度（度，Z 轴）
+     * @param scale 缩放 [sx, sy]
+     * @param width 像素宽
+     * @param height 像素高
+     * @param worldSize 世界尺寸 [w, h]
+     * @param worldPosition 世界坐标
+     * @param worldRotation 世界旋转
+     * @param worldScale 世界缩放
+     * @param effectsUrl 特效资源 URL
+     */
+    createEffectsItem(id: string, name: string, pixelPosition: [number, number], rotation: number, scale: [number, number], width: number, height: number, worldSize: [number, number], worldPosition: Vector3, worldRotation: Vector3, worldScale: Vector3, effectsUrl?: string, autoFit?: boolean): {
+        artisItem: EffectsItem;
+        resourcePromise?: Promise<void>;
+    };
+    /**
+     * 创建画板元素（sync 段）：建 ArtisItem + Player 控制器(空 null + FrameComponent)，
+     * 完成 id/vfxItemId/register。不含资源加载与子元素挂载（见 {@link loadFrameAssetFor}）。
+     *
+     * 拆分 sync/async 的理由：id（经策略 resolveItemId）与 vfxItemId 在 createEmpty 后同步可得，
+     * 供同步 createItemCore 即时返回真实 id；资源加载（loadFrameAsset）+ 子元素挂载 + 全量同步
+     * 留待 async 段，由 createItem(await) 等待或 createItemCore fire-and-forget。
+     * @returns 新建的 Frame ArtisItem（id/vfxItemId 已就绪）
+     */
+    createFrameItemSync(id: string, name: string, pixelPosition: [number, number], rotation: number, scale: [number, number], width: number, height: number, worldSize: [number, number], worldPosition: Vector3, worldRotation: Vector3, worldScale: Vector3, layoutMode?: 'auto' | 'free', children?: string[], autoLayoutConfig?: AutoLayoutConfig, layoutInfos?: Record<string, LayoutInfo>): FrameItem;
+    /**
+     * 画板资源加载与子元素挂载（async 段，配合 {@link createFrameItemSync}）：
+     * 加载底层预合成 → 把子元素移入画板 → 全量同步 transform。
+     * @param artisItem createFrameItemSync 返回的画板元素（id/subCompositionItemId 已就绪）
+     * @param worldSize 世界尺寸 [w, h]
+     * @param scene 预合成场景数据
+     * @param children 子元素 ID 列表
+     */
+    loadFrameAssetFor(artisItem: FrameItem, worldSize: [number, number], scene: spec.JSONScene, children?: string[]): Promise<void>;
+    /**
+     * 创建卡片元素
+     * @param id 元素 ID
+     * @param name 元素名称
+     * @param pixelPosition 像素坐标 [x, y]
+     * @param rotation 旋转角度（度，Z 轴）
+     * @param scale 缩放 [sx, sy]
+     * @param width 像素宽
+     * @param height 像素高
+     * @param worldSize 世界尺寸 [w, h]
+     * @param worldPosition 世界坐标
+     * @param worldRotation 世界旋转
+     * @param worldScale 世界缩放
+     * @param cardType 卡片类型，缺省空串
+     * @param autoHeight 是否自动高度
+     */
+    createCardItem(id: string, name: string, pixelPosition: [number, number], rotation: number, scale: [number, number], width: number, height: number, worldSize: [number, number], worldPosition: Vector3, worldRotation: Vector3, worldScale: Vector3, cardType?: string, autoHeight?: boolean): CardItem;
+}