@vvfx/artis 0.0.1-alpha.0

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

@@ -0,0 +1,66 @@
+import type { Store } from '../store';
+import type { Selection } from '@vvfx/gizmo';
+import type { InteractionService } from './interaction-service';
+import type { Renderer } from '../renderer';
+/**
+ * ItemSyncService - Player → Store 数据同步服务
+ *
+ * 负责将 Player 层 VFXItem 的 transform 数据回写到 Store 中的 ArtisItem.property，
+ * 包括：
+ * 1. syncItemTransform：单个元素同步
+ * 2. syncAllItemsFromPlayer：全量同步（Command 执行后）
+ * 3. syncSelectedItemsTransform：选中元素同步（Gizmo 拖拽后）
+ * 4. syncRenderOrder：图层顺序同步
+ */
+export declare class ItemSyncService {
+    private _store;
+    private _renderer;
+    private _selection?;
+    private _interactionService;
+    /** 查找 Player 元素（注入避免循环依赖） */
+    private _findPlayerItemById;
+    /** vfxItemId → 元素ID 翻译（反向同步用，注入避免循环依赖）。未注册时返回 undefined，调用方兜底原值 */
+    private _elementIdOf;
+    /**
+     * 注入依赖与 Player 元素查找回调
+     *
+     * selection 在 GizmoManager 装配后才存在，故构造时不传，
+     * 由 {@link ItemService.setSelection} 在装配后回填。
+     * @param options 构造选项
+     */
+    constructor(options: {
+        store: Store;
+        renderer: Renderer;
+        interactionService: InteractionService;
+        findPlayerItemById: (id: string) => any;
+        elementIdOf: (vfxItemId: string) => string | undefined;
+    });
+    /**
+     * 回填 Selection 实例（由 ItemService 在 GizmoManager 装配后注入）。
+     * @param selection 选中态真源（来自 GizmoManager）
+     */
+    setSelection(selection: Selection): void;
+    /**
+     * 同步 Store.items 的顺序到 Player 层的 renderOrder
+     *
+     * 在图层顺序变更后调用，将 Store 中的 items 顺序同步到 Player VFXItem 的 renderOrder。
+     */
+    syncRenderOrder(): void;
+    /**
+     * 同步选中元素的变换信息（VFXItem.transform → ArtisItem.property）
+     *
+     * 在 ResizeSelectionGizmo 拖拽结束后调用，将 Player 层的变换数据回写到 Store。
+     */
+    syncSelectedItemsTransform(): void;
+    /**
+     * 同步所有元素的变换（VFXItem.transform → ArtisItem.property）
+     *
+     * 在 Command 执行后调用，确保 Store 中的数据与 Player 层保持一致。
+     */
+    syncAllItemsFromPlayer(): void;
+    /**
+     * 同步单个元素的变换（VFXItem.transform → ArtisItem.property + Scene JSON）
+     * @param id 元素实例 ID
+     */
+    syncItemTransform(id: string): void;
+}

package/dist/core/service/json-scene-sync-service.d.ts

@@ -0,0 +1,140 @@
+import { spec } from '../../shared';
+import { type ArtisItem } from '../item';
+import { type SceneStore } from '../store';
+import { type Renderer } from '../renderer';
+import { type AssetManager } from '../asset';
+import { type IOPlugin } from '../plugin/io-plugin';
+/**
+ * JsonSceneSyncService - ArtisItem 变更 → 激活场景 JSONScene 回写
+ *
+ * 承载需求4「修改元素时同步修改场景 JSON」。在现有「ArtisItem → VFXItem」单向同步之上，
+ * 增加「ArtisItem → JSONScene」原地回写。
+ *
+ * 与 IOPlugin.exportScene 的本质区别：后者现场拼装新 JSONScene；
+ * 本服务是**原地保活现有 JSON 的动画时间线**（TimelineAsset / Track），
+ * 仅更新静态 transform / content 字段，不破坏关键帧。
+ *
+ * v1 采用「按需全量回写变更 item」（简单可靠）；增量脏标记优化列为后续。
+ */
+export declare class JsonSceneSyncService {
+    private _sceneStore;
+    private _renderer;
+    private _assetManager;
+    /** IOPlugin 引用（含资源序列化，由 SceneArtis 在 IOPlugin 激活后回填；空时 insert 降级单体骨架） */
+    private _ioPlugin?;
+    /**
+     * 注入场景存储、渲染管线与资源管理器（后两者预留给后续资源类回写扩展）
+     * @param deps 依赖项
+     */
+    constructor(deps: {
+        sceneStore: SceneStore;
+        renderer: Renderer;
+        assetManager: AssetManager;
+    });
+    /**
+     * 回填 IOPlugin 引用（由 SceneArtis 在 setupPlugins 激活 IOPlugin 后注入）。
+     *
+     * IOPlugin 激活晚于本服务构造（BaseArtis ctor step 6 vs SceneArtis ctor），
+     * 故构造时不传、激活后回填。注入后，会话内新建元素 insert 走 {@link IOPlugin.serializeItemWithAssets}
+     * 联动并入 images/videos/textures，保证 reload 后图/视频资源可复建；未注入时降级单体骨架。
+     * @param ioPlugin IOPlugin 实例；undefined 可解绑
+     */
+    setIOPlugin(ioPlugin?: IOPlugin): void;
+    /**
+     * 同步发生变更的 item（全量回写），写入当前激活 SceneEntry.scene。
+     * 不存在的 item 跳过；JSON 中找不到对应 id 的 item 跳过。
+     * @param items 发生变更的 ArtisItem 列表
+     */
+    syncDirty(items: ArtisItem[]): void;
+    /**
+     * 同步单个 ArtisItem 到激活场景 JSON。
+     * @param item 待同步的 ArtisItem
+     */
+    syncItem(item: ArtisItem): void;
+    /**
+     * 把单个 ArtisItem 的静态字段回写到 JSONScene.items 中对应 id 的 item。
+     * 仅写 transform（position/eulerHint/scale/size）与类型专属 content；不动 timeline。
+     *
+     * **新建元素 insert**（F1）：会话内 createItem 产出的元素（id 为 runtime instanceId，
+     * 原不在 JSON 中）经 afterExecute → syncDirty 首次回写时，由 {@link serializeArtisItemToJSON}
+     * 构造 VFXItemData 骨架插入 scene.items，使其持久化/可导出。reload 后 Player 以 JSON item.id
+     * 作 instanceId，artisItem.id 不变，自洽。
+     *
+     * 资源引用完整化（sprite/video 的 texture、effects/frame 的子预合成 scene）为后续阶段（F1b）；
+     * 当前骨架 insert 已保证元素不彻底丢失、transform/结构/text 内容持久。
+     *
+     * @param artisItem 待回写的 ArtisItem
+     * @param scene 目标 JSONScene
+     * @returns 是否实际发生回写
+     */
+    private _syncItemIntoScene;
+    /**
+     * 会话内新建元素（id 不在原 JSON）insert 到 scene。
+     *
+     * 优先走 {@link IOPlugin.serializeItemWithAssets}：取含资源的完整 item+components+images/videos/textures，
+     * 联动并入 scene 各数组，使 reload 后图/视频资源可复建（sprite/video 完整）。
+     * IOPlugin 未注入或元素不支持序列化时，降级用 {@link serializeArtisItemToJSON} 单体骨架
+     * （仅 item+transform+text content，无资源——F1 主路径行为）。
+     *
+     * effects/frame 的子预合成 scene 暂未序列化（reload 后 composition 为空壳），列为 F1c。
+     * @returns 是否成功 insert
+     */
+    private _insertItemIntoScene;
+    /**
+     * 会话内新建 FRAME 元素 insert：用 {@link createFrameCompositionScene} 重建子预合成 scene，
+     * 委托通用 {@link _insertCompositionItemIntoScene} embed（F1c-frame）。
+     */
+    private _insertFrameIntoScene;
+    /**
+     * 会话内新建 composition 型元素（FRAME / EFFECTS）insert 通用逻辑：
+     * 把子预合成 scene 整体 merge 进主 scene（extractSubCompositionToScene 的逆协议），
+     * 并 push 带 refId 的 placeholder composition item（refId 指向子 scene 顶层 composition）。
+     *
+     * 去重：子 composition id（subScene.compositionId）已在主 scene.compositions 时跳过 merge
+     * （二次 afterExecute 不重复插入；此时该元素 id 已在 items 走 update，正常情况下不会进此分支）。
+     *
+     * @param artisItem 元素（取 id/name/property.transform）
+     * @param subScene 子预合成 scene（frame 重建 / effects 缓存）
+     * @param scene 主 scene
+     * @returns 是否成功 insert
+     */
+    private _insertCompositionItemIntoScene;
+    /**
+     * 把子预合成 scene 整体 merge 进主 scene（extractSubCompositionToScene 的逆）。
+     * 联动并入 items/components/compositions/miscs/textures/images/videos 等数组，
+     * 按 id 去重防重复。子 scene 的顶层 composition（即子预合成本身）作为一条 CompositionData 进主 compositions。
+     */
+    private _mergeSubSceneIntoScene;
+    /** 按 keyFn 的 key 去重后把 values push 到 scene[key]（数组不存在则创建） */
+    private _pushArrayDedup;
+    /** 把 item push 到 scene.items（数组不存在则创建） */
+    private _pushItems;
+    /** 把 values push 到 scene[key]（数组不存在则创建）；values 为空时不动 */
+    private _pushArray;
+    /**
+     * 类型专属 content 回写。v1 仅处理 TEXT 的文字内容（最常见编辑场景）；
+     * 纹理 / 视频源等资源类变更由 AssetManager 走引用更新，不在本服务重复处理。
+     * @param artisItem 待回写的 ArtisItem
+     * @param jsonItem 目标 JSON item 数据
+     * @param scene 所属 JSONScene（预留资源表扩展）
+     */
+    private _syncTypeSpecificContent;
+    /**
+     * 在 JSONScene.items 中按 id 查找 VFXItemData（含 composition 子项）
+     * @param scene 目标 JSONScene
+     * @param id 元素实例 ID
+     * @returns 命中的 VFXItemData；找不到时返回 undefined
+     */
+    private _findJSONItem;
+}
+/**
+ * 把单个 ArtisItem 序列化为 spec.VFXItemData（导出与回写共用底层）。
+ * 复用 json-data-utils 的 createXxxItemJSON 思路，按 ArtisItemType 分派。
+ *
+ * 注意：本方法生成的是「独立 JSON item」，不保活原 scene 动画。
+ * 导出主路径优先用 SceneStore.exportEntry（保活原 JSON）；此方法供局部序列化场景。
+ *
+ * @param artisItem 待序列化的 ArtisItem
+ * @returns 序列化后的 VFXItemData；未知类型返回 undefined
+ */
+export declare function serializeArtisItemToJSON(artisItem: ArtisItem): spec.VFXItemData | undefined;

package/dist/core/service/refresh-animation-base-service.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/service/scene-data-assembler.d.ts

@@ -0,0 +1,166 @@
+import type { FrameManager } from '@vvfx/gizmo';
+import { ArtisItemType, type ArtisItem } from '../item';
+import { type InteractionService } from './interaction-service';
+import { type Renderer } from '../renderer';
+/**
+ * id → ArtisItemType 类型表（可选）。
+ *
+ * 调用方在加载前若已知各元素的精确类型（来自原 JSON 的 className / 扩展字段 / 外部元数据），
+ * 可传入此表消除歧义。无表时按 VFXItem 兜底推断：
+ * - sprite → SPRITE（GENERATOR / CARD 无法仅靠 VFXItem 区分，需类型表）
+ * - null + FrameComponent → FRAME（EFFECTS 无法仅靠 VFXItem 区分，需类型表）
+ * - null + 无 FrameComponent → GROUP
+ * - text → TEXT，video → VIDEO
+ * - composition（顶层） → 跳过（属 EFFECTS/FRAME 内部子预合成）
+ */
+export type ArtisItemTypeTable = Record<string, ArtisItemType>;
+/**
+ * SceneDataAssembler 依赖
+ */
+export type SceneDataAssemblerDeps = {
+    /** 已完成 refreshViewport/refreshCamera 的交互服务，用于 VFXItem→像素换算 */
+    interactionService: InteractionService;
+    /** 渲染管线，用于访问 Player/Composition（traverseItems） */
+    renderer: Renderer;
+    frameManager: FrameManager;
+};
+/**
+ * SceneDataAssembler - JSON + runtime VFXItem → ArtisItem 装配器
+ *
+ * 与 {@link ItemService.createItem}（schema → item + VFXItem）互为逆向：
+ * 在一个已 player.loadScene(json) 并 gotoAndStop 冻结的 composition 上，
+ * 遍历 runtime VFXItem，反推编辑属性（复用 InteractionService 世界矩阵→像素坐标逻辑），
+ * 实例化对应 ArtisItem 子类，返回编辑模型数据 ArtisItem[]。
+ *
+ * 类型反推：见 {@link ArtisItemTypeTable}。GENERATOR/CARD/SPRITE、EFFECTS/FRAME
+ * 三组无法仅靠 VFXItem 区分，需调用方传类型表；无表时兜底到 SPRITE/FRAME。
+ */
+export declare class SceneDataAssembler {
+    private _interactionService;
+    private _renderer;
+    private _frameManager;
+    /**
+     * 注入交互服务与渲染管线
+     * @param deps 依赖项
+     */
+    constructor(deps: SceneDataAssemblerDeps);
+    /**
+     * 在一个已 loadScene 并 gotoAndStop 的 composition 上组装全部顶层 ArtisItem。
+     * 递归遍历 composition.items，跳过 EFFECTS/FRAME 的内部子预合成。
+     *
+     * @param composition 已加载冻结的 composition（缺省取 Player 第一个）
+     * @param typeTable 可选的类型表，消除 GENERATOR/CARD/EFFECTS 歧义
+     * @returns 顶层 ArtisItem 列表；composition 不存在时返回空数组
+     */
+    assemble(composition?: any, typeTable?: ArtisItemTypeTable): ArtisItem[];
+    /**
+     * 单元素组装（增量/局部刷新用）。元素无法装配时返回 undefined。
+     * @param item VFXItem
+     * @param typeTable 可选的类型表
+     * @returns 装配出的 ArtisItem；无法装配时返回 undefined
+     */
+    assembleItem(item: any, typeTable?: ArtisItemTypeTable): ArtisItem | undefined;
+    /**
+     * 遍历装配。`composition.items` 返回 `sceneRoot.getDescendants()`——全量扁平后代列表
+     * （含所有层级，非仅顶层），故**只需遍历一次**，不可再递归 `item.children`：否则非
+     * composition 子节点会被装配两次，产生重复 id（React key 冲突）。各 ArtisItem 的
+     * parentId / children 由 {@link _assembleOne} 从 VFXItem 自身反推，不依赖递归层级。
+     * @param items VFXItem 列表（composition.items 全量扁平后代）
+     * @param typeTable 可选的类型表
+     * @param result 输出累加的 ArtisItem 列表
+     */
+    private _traverse;
+    /**
+     * 装配单个 VFXItem 为 ArtisItem
+     * @param item VFXItem
+     * @param typeTable 可选的类型表
+     * @returns 装配出的 ArtisItem；无法识别类型时返回 undefined
+     */
+    private _assembleOne;
+    /**
+     * 反推 ArtisItemType。优先用类型表，否则按 VFXItem 兜底。
+     * composition 顶层 → 视作 FRAME 兜底（也可能是 EFFECTS，需类型表区分）；非顶层 composition 跳过。
+     * @param item VFXItem
+     * @param id 元素实例 ID
+     * @param typeTable 可选的类型表
+     * @returns 推断出的 ArtisItemType；无法识别时返回 undefined
+     */
+    private _resolveArtisType;
+    /**
+     * VFXItem.transform → 像素坐标 position/rotation/scale/width/height。
+     * 算法复刻自 ItemSyncService.syncItemTransform（VFXItem→像素的逆向算子）。
+     * @param item VFXItem
+     * @returns 像素坐标系下的 position/rotation/scale/width/height
+     */
+    private _resolveTransform;
+    /**
+     * 反推 parentId（与 ItemSyncService 一致：composition 嵌套时取上上级）
+     * @param item VFXItem
+     * @returns 父元素 ID；无父级时返回 undefined
+     */
+    private _resolveParentId;
+    /**
+     * 读取 VFXItem 子元素 ID 列表
+     * @param item VFXItem
+     * @returns 子元素实例 ID 列表
+     */
+    private _readChildrenIds;
+    /**
+     * 读取 Sprite 图片地址。runtime 上 url 一般挂在 texture，GE 无统一 getter，兜底空串。
+     * TODO: 后续可由 AssetManager 反查 url（按 texture 引用）。
+     * @param item VFXItem
+     * @returns 图片地址；读取失败时返回空串
+     */
+    private _readSpriteImage;
+    /**
+     * 读取 EffectsItem 自适应大小标志。
+     * autoFit 是语义布尔（非几何量），不存于 VFXItem.transform，由 JsonSceneSyncService 写进
+     * placeholder item 的 content.options.autoFit 持久化，故从此读回；旧档无该字段默认 false。
+     * @param item VFXItem
+     * @returns autoFit 标志
+     */
+    private _readAutoFit;
+    /**
+     * 读取 sprite/video 尺寸模式。sizeMode 是语义布尔（非几何量），不存于 VFXItem.transform，
+     * 由 JsonSceneSyncService 写进 item 的 content.options.sizeMode 持久化，故从此读回；
+     * 旧档无该字段默认 'fixed'（旧档尺寸显式给定）。
+     * @param item VFXItem
+     * @returns sizeMode，缺省 'fixed'
+     */
+    private _readSizeMode;
+    /**
+     * 读取 Text 文本属性（GE TextComponent 暴露 text/fontSize/fontFamily 等可读属性）
+     * @param item VFXItem
+     * @returns 文本相关属性；读取失败时返回兜底默认值
+     */
+    private _readTextProps;
+    /**
+     * 读取 Video 属性。url 兜底空串。
+     * @param item VFXItem
+     * @returns 视频相关属性；读取失败时返回兜底默认值
+     */
+    private _readVideoProps;
+    /**
+     * 读取 generatorType。VFXItem 无标记，默认 IMAGE；调用方可通过类型表已知是 GENERATOR，
+     * 具体 generatorType 需外部元数据，此处兜底 IMAGE。
+     * @param _item VFXItem（暂未使用，预留）
+     * @param _id 元素实例 ID（暂未使用，预留）
+     * @param _typeTable 可选的类型表（暂未使用，预留）
+     * @returns 生成器类型，当前兜底返回 IMAGE
+     */
+    private _readGeneratorType;
+    /**
+     * 读取 cardType。同上，兜底空串。
+     * @param _item VFXItem（暂未使用，预留）
+     * @param _id 元素实例 ID（暂未使用，预留）
+     * @param _typeTable 可选的类型表（暂未使用，预留）
+     * @returns 卡片类型，当前兜底返回空串
+     */
+    private _readCardType;
+    /**
+     * 读取 Frame 布局模式。runtime 无标记，兜底 FREE。
+     * @param _item VFXItem（暂未使用，预留）
+     * @returns 布局模式，当前兜底返回 FREE
+     */
+    private _readFrameLayoutMode;
+}

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

@@ -0,0 +1,202 @@
+import { EventEmitter, spec } from '../../shared';
+import { Box2, Vector2 } from '@vvfx/gizmo';
+import type { ViewportFitShiftParam } from '../types';
+/**
+ * 视口状态变更来源：决定 wiring change 监听是否回写相机 viewportMatrix。
+ * - `view`：ViewService 为相机真源（外部主动 setZoom / setRatios / setClipMode / resize 等），需 applyViewportToPlayer。
+ * - `gizmo`：相机已被 gizmo 直写，ViewService 仅记账 + 通知外部，**不**再 apply（避免重复写相机/抖动）。
+ */
+export type ViewportSource = 'view' | 'gizmo';
+/**
+ * 视口状态
+ */
+export type ViewportState = {
+    zoom: number;
+    translation: spec.vec2;
+    contentRatio: number;
+    /** 本次状态变更来源（缺省 view）。供 wiring 决定是否回写相机 matrix。 */
+    source?: ViewportSource;
+};
+/**
+ * 视口补偿比例更新项：全部可选，仅传需要变更的字段，未传字段保持原值。
+ */
+export type ViewportRatios = {
+    widthRatio?: number;
+    heightRatio?: number;
+    pixelRatio?: number;
+};
+/**
+ * ViewService 事件类型
+ */
+export type ViewServiceEventMap = {
+    'change': [state: ViewportState];
+    'resize': [size: spec.vec2];
+};
+/**
+ * ViewService 初始化选项
+ */
+export type ViewServiceOptions = {
+    minZoom?: number;
+    maxZoom?: number;
+    initialZoom?: number;
+    /** 监听 resize 的容器元素。传入后将自动创建 ResizeObserver 监听容器尺寸变化 */
+    container?: HTMLElement;
+    initialTranslation?: Vector2;
+};
+/**
+ * ViewService - 视口服务
+ *
+ * 职责：
+ * 1. 管理 zoom / translation / size 状态
+ * 2. 监听容器 resize，自动更新 size 并触发 resize 事件
+ * 3. 提供 setZoom / setTranslation / pan / fitToBox 方法
+ * 4. 约束 minZoom / maxZoom
+ * 5. 触发 change / resize 事件
+ */
+export declare class ViewService extends EventEmitter<ViewServiceEventMap> {
+    private _zoom;
+    private _translation;
+    private _size;
+    private _minZoom;
+    private _maxZoom;
+    private _clipMode;
+    protected _widthRatio: number;
+    protected _heightRatio: number;
+    /** 保持场景渲染比例，用于确定容器 resize 时，是否需要保持元素相对容器比例不变 */
+    private _keepViewRatio;
+    /** 视口像素与真实像素比例 */
+    private _pixelRatio;
+    private _container;
+    private _resizeObserver;
+    private _disposed;
+    /**
+     * 下一次 emit('change') 携带的变更来源标记。默认 'view'；gizmo 回写入口前置置 'gizmo'，
+     * _emitChange 发出后立即复位为 'view'，保证不污染后续非 gizmo 写入。
+     */
+    private _pendingSource;
+    /**
+     * 初始化视口状态与可选的容器 resize 监听
+     * @param size 初始视口尺寸
+     * @param options 初始化选项
+     */
+    constructor(size: Vector2, options?: ViewServiceOptions);
+    /** 视口尺寸（宽高） */
+    get size(): Vector2;
+    /**
+     * 设置视口尺寸（不触发事件）
+     * @param value 视口尺寸
+     */
+    set size(value: Vector2);
+    /** 视口中心点坐标（size / 2） */
+    get center(): Vector2;
+    /** 当前缩放值 */
+    get zoom(): number;
+    /**
+     * 设置缩放值（经 setZoom 处理，受 minZoom/maxZoom 约束）
+     * @param value 缩放值
+     */
+    set zoom(value: number);
+    /** 当前平移量 */
+    get translation(): Vector2;
+    /**
+     * 设置平移量（经 setTranslation 处理）
+     * @param value 平移量
+     */
+    set translation(value: Vector2);
+    get keepViewRatio(): boolean;
+    set keepViewRatio(value: boolean);
+    /** 容器缩放比（只读，补偿 resize 时 容器变化对元素大小的影响） */
+    get contentRatio(): number;
+    get widthRatio(): number;
+    get heightRatio(): number;
+    get pixelRatio(): number;
+    /** 当前视口状态快照（zoom / translation / contentRatio + source） */
+    get state(): ViewportState;
+    /**
+     * 统一的 change 发射口：payload 携带本次变更来源（`_pendingSource`），发出后复位为 'view'。
+     * 所有写状态后需通知外部的路径统一调本方法，保证来源标记不残留、不污染后续写入。
+     */
+    private _emitChange;
+    /**
+     * 设置缩放值
+     * @param zoom 目标缩放值
+     * @param anchor 缩放锚点 [x, y]（相对容器的坐标），默认中心
+     */
+    setZoom(zoom: number, anchor?: Vector2): void;
+    /**
+     * 批量设置视口补偿比例（widthRatio / heightRatio / pixelRatio）。
+     *
+     * @param ratios 需要变更的比例字段（全部可选）
+     */
+    setRatios(ratios: ViewportRatios): void;
+    /**
+     * 设置相机裁剪模式：决定 contentRatio 取 widthRatio 还是 heightRatio（见 contentRatio getter，
+     * portrait→heightRatio、landscape→widthRatio）。
+     *
+     * 由 wiring 在 sceneLoaded 时从 composition.camera.clipMode 同步（Artis/SceneArtis 共用）。
+     * emit change 触发 renderer applyViewportToPlayer 按 contentRatio 写 viewportMatrix，
+     * 并经 GestureHandler 同步 ResizeSelectionGizmo。
+     */
+    setClipMode(clipMode: spec.CameraClipMode): void;
+    /**
+     * 设置平移
+     * @param translation 目标平移量
+     */
+    setTranslation(translation: Vector2): void;
+    /**
+     * gizmo 视口导航回写入口：相机已被 gizmo（zoomView/panView）直写，ViewService 仅记账 + 通知外部，
+     * 标记 source='gizmo' 使 wiring change 监听跳过 applyViewportToPlayer（不重复写相机，防抖动）。
+     *
+     * 与 {@link setZoom}/{@link setTranslation} 的差异：
+     * 1. 不走 setZoom 的 `resultZoom === _zoom` 早退——gizmo 平移/钳位场景换算后 zoom 可能不变，但 translation
+     *    已变，仍须通知外部（避免外部盲区）。
+     * 2. 钳位 zoom 到 [minZoom, maxZoom] 保持不变，但不以"值未变"为由跳过 emit。
+     * 3. 不重算 translation（不像 setZoom 按 anchor 偏移）——gizmo 已给出最终 translation，直接落值。
+     *
+     * @param zoom gizmo 相机 scale 折算后的 zoom（= camera scale / contentRatio）
+     * @param translation gizmo 视口快照 translation（view-size 变体）
+     */
+    applyGizmoViewport(zoom: number, translation: Vector2): void;
+    /**
+     * 同时设置 zoom 与 translation 的原子写入口：只触发一次 change 事件。
+     *
+     * 收敛 fitToBox（view 源，需 apply）与 applyGizmoViewport（gizmo 源，不 apply）的共性——
+     * 二者都需要"一次性更新 zoom+translation 并只通知外部一次"，避免 setTranslation+setZoom 各 emit 的多次触发。
+     *
+     * @param zoom 目标 zoom（钳位到 [minZoom, maxZoom]；不以"值未变"早退——translation 可能已变仍须通知）
+     * @param translation 目标 translation（锚点变换前的基准值）
+     * @param anchor 缩放锚点（相对容器坐标）；缺省时直接采用传入 translation，不重算（gizmo 路径）
+     * @param source 变更来源，决定 wiring 是否 applyViewportToPlayer
+     */
+    applyViewport(zoom: number, translation: Vector2, anchor: Vector2 | undefined, source: ViewportSource): void;
+    /**
+     * 相对平移，将 delta 累加到当前 translation
+     *
+     * @param delta 平移增量（屏幕坐标系）
+     */
+    pan(delta: Vector2): void;
+    /** 重置视口：zoom 回到 1，translation 归零，并触发 change 事件 */
+    reset(): void;
+    /**
+     * 自适应视口：使传入包围盒完整显示在容器中。
+     *
+     * @param box 目标内容包围盒（像素坐标系）；空 box 时重置视口
+     * @param shiftParam 上下左右内边距偏移（像素），缺省四边为 0
+     * @param contentRatio 内容包围盒放大系数，默认 1.1
+     */
+    fitToBox(box: Box2, shiftParam?: ViewportFitShiftParam): void;
+    /**
+     * 销毁，断开 ResizeObserver
+     *
+     * 边界：重复调用安全，已销毁时直接返回
+     */
+    dispose(): void;
+    /**
+     * 创建并启动容器 ResizeObserver 监听
+     */
+    protected setupResizeObserver(): void;
+    /**
+     * 处理容器 resize：更新尺寸、平移量与 contentRatio，并触发 resize / change 事件
+     */
+    protected handleResize(): void;
+}

package/dist/core/state/base-state.d.ts

@@ -0,0 +1,28 @@
+import { EventEmitter } from '@galacean/effects';
+import type { StateGizmoBinding } from '../gizmo/gizmo-registry';
+import type { BaseStateEventMap, StateGizmoToolConstructor, StateId, StateInteractionDefinition } from './types';
+/** Business state that directly selects its GizmoTool type. */
+export declare class BaseState extends EventEmitter<BaseStateEventMap> {
+    readonly id: StateId;
+    readonly name: string;
+    /** Ordered registered graph used when this State does not provide a Tool type. */
+    readonly gizmos: readonly StateGizmoBinding[];
+    /** Tool type directly owned by this State. */
+    readonly tool: StateGizmoToolConstructor | undefined;
+    isolated: boolean;
+    constructor(id: StateId, name: string, toolOrInteraction?: StateGizmoToolConstructor | StateInteractionDefinition);
+    enter(): void;
+    exit(): void;
+    suspend(): void;
+    resume(): void;
+    onEnter(): void;
+    onExit(): void;
+    onSuspend(): void;
+    onResume(): void;
+    /** Whether navigation to another State should temporarily suspend this State. */
+    shouldSuspendFor(_nextStateId: StateId): boolean;
+    /** Whether a navigation request should restore this State from the suspended stack. */
+    shouldResumeFor(_requestedStateId: StateId): boolean;
+    /** Called after the state's GizmoTool has been activated. */
+    onGizmoToolReady(): void;
+}

package/dist/core/state/index.d.ts

@@ -0,0 +1,6 @@
+export { BaseState } from './base-state';
+export { StateManager } from './state-manager';
+export { HandState, ImageCutState, ImageExpandState, ImageMaskState, ImageTextEditState, ItemCreateState, MoveState, createDefaultStates, createStatesByIds, } from './presets';
+export { OfficialStateId } from './types';
+export type { BaseStateEventMap, StateChangeEvent, StateId, StateInteractionDefinition, StateManagerEventMap, StateTransition, StateNavigator, StateLifecyclePhase, StateGizmoToolConstructor, } from './types';
+export type { StateBundleRegistration, StateBundleHandle, } from './state-manager';

package/dist/core/state/presets.d.ts

@@ -0,0 +1,25 @@
+import { BaseState } from './base-state';
+import { OfficialStateId } from './types';
+export declare class MoveState extends BaseState {
+    constructor();
+}
+export declare class HandState extends BaseState {
+    constructor();
+}
+export declare class ImageCutState extends BaseState {
+    constructor();
+}
+export declare class ImageExpandState extends BaseState {
+    constructor();
+}
+export declare class ImageTextEditState extends BaseState {
+    constructor();
+}
+export declare class ImageMaskState extends BaseState {
+    constructor();
+}
+export declare class ItemCreateState extends BaseState {
+    constructor();
+}
+export declare function createStatesByIds(ids: readonly OfficialStateId[]): BaseState[];
+export declare function createDefaultStates(): BaseState[];