@vvfx/artis 0.0.1-alpha.0

package/dist/artis-sdk/index.d.ts

@@ -0,0 +1 @@
+export { ArtisSDK } from './artis-sdk';

package/dist/core/asset/asset-manager.d.ts

@@ -0,0 +1,288 @@
+import type { Texture } from '../../shared';
+import { spec } from '../../shared';
+import type { Disposable } from '../types';
+/**
+ * 资源类型标识
+ */
+export declare enum AssetType {
+    IMAGE = "image",
+    VIDEO = "video",
+    AUDIO = "audio",
+    FONT = "font",
+    EFFECT = "effect"
+}
+/**
+ * 资源加载状态
+ */
+export declare enum AssetLoadState {
+    PENDING = "pending",
+    LOADING = "loading",
+    LOADED = "loaded",
+    ERROR = "error"
+}
+/**
+ * 资源条目基础字段
+ */
+export type BaseAssetEntry = {
+    /** 资源唯一 ID */
+    id: string;
+    /** 资源名称 */
+    name: string;
+    /** 资源 URL */
+    url: string;
+    /** 加载状态 */
+    state: AssetLoadState;
+    /** 引用该资源的元素 ID 列表 */
+    users: string[];
+};
+/**
+ * 图片资源条目
+ * texture 对应 Player 初始化的 GPU ImageTexture
+ */
+export type ImageAssetEntry = BaseAssetEntry & {
+    type: 'image';
+    /** 图片宽度 */
+    width: number;
+    /** 图片高度 */
+    height: number;
+    /** GPU ImageTexture（Player 层创建） */
+    texture: Texture | null;
+};
+/**
+ * 视频资源条目
+ * gpuAsset 对应 Player 初始化的 GPU VideoTexture
+ */
+export type VideoAssetEntry = BaseAssetEntry & {
+    type: 'video';
+    /** 视频宽度 */
+    width: number;
+    /** 视频高度 */
+    height: number;
+    /** 视频时长（秒） */
+    duration: number;
+    /** GPU VideoTexture（Player 层创建） */
+    gpuAsset: Texture | null;
+};
+/**
+ * 音频资源条目
+ */
+export type AudioAssetEntry = BaseAssetEntry & {
+    type: 'audio';
+    /** 音频时长（秒） */
+    duration: number;
+};
+/**
+ * 字体资源条目
+ */
+export type FontAssetEntry = BaseAssetEntry & {
+    type: 'font';
+    /** 字体家族名 */
+    family: string;
+    /** 字体是否已注册到文档 */
+    registered: boolean;
+};
+/**
+ * 特效资源条目
+ */
+export type EffectAssetEntry = BaseAssetEntry & {
+    type: 'effect';
+    /** 特效 JSON 数据（已 patch 主合成 endBehavior 的 JSONScene） */
+    effectData: unknown;
+    /** 特效主合成尺寸 [w,h]（来自解析后 JSON 的主合成 previewSize，兜底 [750,1624]） */
+    mainCompositionSize: [number, number];
+};
+/**
+ * 资源条目（联合类型，通过 type 区分）
+ */
+export type AssetEntry = ImageAssetEntry | VideoAssetEntry | AudioAssetEntry | FontAssetEntry | EffectAssetEntry;
+/**
+ * 加载资源的选项
+ */
+export type LoadAssetOptions = {
+    /** 资源名称（不传则从 URL 推断） */
+    name?: string;
+    /** 资源类型（不传则从 URL 后缀推断） */
+    type?: AssetType;
+    /** 图片/视频尺寸 */
+    width?: number;
+    /** 图片/视频尺寸 */
+    height?: number;
+    /** 视频/音频时长 */
+    duration?: number;
+    /** 字体家族名 */
+    fontFamily?: string;
+    /** 特效 JSON 数据 */
+    effectData?: unknown;
+    /** 特效主合成尺寸 */
+    mainCompositionSize?: [number, number];
+    /** GPU Texture（由 Player 层传入） */
+    texture?: Texture;
+};
+/**
+ * AssetManager - 资源管理器
+ *
+ * 职责：
+ * 1. 资源的注册/加载/卸载生命周期管理
+ * 2. 资源与元素的绑定关系维护
+ * 3. 引用计数，无引用时可选自动卸载
+ * 4. GPU Texture 的持有与释放
+ */
+export declare class AssetManager implements Disposable {
+    private _assets;
+    private _elementBindings;
+    /**
+     * 注册并加载资源，按类型构造条目并写入资源表。
+     *
+     * @param url 资源 URL
+     * @param options 加载选项（类型/尺寸/Texture 等，缺省时按 URL 推断类型）
+     * @returns 新建的资源 ID
+     */
+    registerAsset(url: string, options?: LoadAssetOptions): string;
+    /**
+     * 加载特效资源（URL → fetch → 解析 → patch 主合成 endBehavior → 缓存）。
+     *
+     * - URL 命中已 LOADED 条目则直接复用（切换同 URL 不重复 fetch）。
+     * - 否则 fetch + json 解析：取主合成 previewSize 作 mainCompositionSize；
+     *   patch 主合成 endBehavior（forward 无限 / restart 重播 不动；destroy / freeze → restart）。
+     * - patch 存于条目 effectData；patch 幂等（forward/restart 不变），多元素共享同 URL 安全。
+     * - 状态机推进：LOADING → LOADED（成功）/ ERROR（失败，抛出且不残留半成品条目）。
+     *
+     * @param url 特效文件 URL
+     * @returns 已加载的特效资源条目（effectData 为 patched JSONScene，mainCompositionSize 为主合成尺寸）
+     */
+    loadEffectAsset(url: string): Promise<EffectAssetEntry>;
+    /**
+     * 按 URL 查找已加载（LOADED）的特效资源。
+     *
+     * 与 {@link findLoadedAssetByUrl} 对齐，补 effect 分支，供 loadEffectAsset 命中复用。
+     * @param url 特效文件 URL
+     * @returns 命中的特效条目；未命中或仍在加载中返回 undefined
+     */
+    findLoadedEffectByUrl(url: string): EffectAssetEntry | undefined;
+    /**
+     * 取特效 JSONScene 的主合成尺寸 [w,h]。
+     *
+     * 主合成 = compositionId 命中或 compositions[0]；尺寸取其 previewSize。
+     * 无有效 previewSize 时兜底 [750,1624]（对齐 artis-sdk.ts 的 previewSize 兜底）。
+     * @param scene 特效 JSONScene
+     * @returns [width, height]
+     */
+    getMainCompositionSize(scene: spec.JSONScene): [number, number];
+    /**
+     * 解析主合成：compositionId 命中或 compositions[0]。
+     */
+    private _findMainComposition;
+    /**
+     * 卸载资源，释放其持有的 GPU Texture 并清理与元素的绑定关系
+     *
+     * @param assetId 资源 ID
+     * 边界：资源不存在时直接返回
+     */
+    unloadAsset(assetId: string): void;
+    /**
+     * 按 ID 获取资源条目。
+     *
+     * @param assetId 资源 ID
+     * @returns 资源条目；未找到返回 undefined
+     */
+    getAsset(assetId: string): AssetEntry | undefined;
+    /**
+     * 按 URL 查找已加载且持有 GPU Texture 的资源
+     *
+     * 用于资源复用：创建/修改带资源的元素时，若相同 URL 的 Texture 已存在，
+     * 可直接复用，避免重复加载。
+     *
+     * @param url 资源 URL
+     * @param type 资源类型（image / video）
+     * @returns 命中的资源条目；未命中返回 undefined
+     */
+    findLoadedAssetByUrl(url: string, type: 'image' | 'video'): ImageAssetEntry | VideoAssetEntry | undefined;
+    /**
+     * 获取指定类型的全部资源
+     *
+     * @param type 资源类型
+     * @returns 该类型对应的资源条目数组（类型收窄到对应联合分支）
+     */
+    getAssetsByType<T extends AssetType>(type: T): Extract<AssetEntry, {
+        type: T;
+    }>[];
+    /**
+     * 获取所有资源条目（含已加载与加载中）。
+     *
+     * @returns 全部资源条目数组
+     */
+    getAllAssets(): AssetEntry[];
+    /**
+     * 绑定资源到元素，建立 element→asset 引用关系
+     *
+     * @param assetId 资源 ID
+     * @param elementId 元素 ID
+     * 边界：重复绑定不会重复添加 users；资源不存在时只记录绑定关系
+     */
+    bindAssetToElement(assetId: string, elementId: string): void;
+    /**
+     * 解绑元素的所有资源，移除该元素的全部绑定关系
+     *
+     * @param elementId 元素 ID
+     */
+    unbindElement(elementId: string): void;
+    /**
+     * 解绑元素的指定资源
+     *
+     * @param assetId 资源 ID
+     * @param elementId 元素 ID
+     * 边界：绑定集合清空后会移除该元素的绑定条目
+     */
+    unbindAssetFromElement(assetId: string, elementId: string): void;
+    /**
+     * 获取元素绑定的所有资源
+     *
+     * @param elementId 元素 ID
+     * @returns 资源条目数组；元素无绑定时返回空数组
+     */
+    getAssetsByElementId(elementId: string): AssetEntry[];
+    /**
+     * 获取无引用的资源列表（users 为空，可用于手动清理）。
+     *
+     * @returns 无引用资源条目数组
+     */
+    getUnusedAssets(): AssetEntry[];
+    /**
+     * 清理无引用的资源（释放 GPU Texture 并移除条目）。
+     *
+     * @param type 可选资源类型过滤；传 EFFECT 时仅释放特效 JSON 缓存，不触碰 image/video 纹理。
+     *   元素删除时按类型 purge，避免误伤仍可能被外部引用的纹理。
+     */
+    purgeUnused(type?: AssetType): void;
+    /**
+     * 更新资源的 GPU Texture（Player 重建场景后需要重新绑定）
+     *
+     * @param assetId 资源 ID
+     * @param texture 新的 Texture
+     * 边界：仅 image / video 类型生效；资源不存在时直接返回
+     */
+    updateTexture(assetId: string, texture: Texture): void;
+    /**
+     * 销毁，释放所有资源
+     */
+    dispose(): void;
+    /**
+     * 释放资源持有的 GPU Texture，仅对 image / video 类型生效。
+     *
+     * @param asset 资源条目
+     */
+    private releaseGpuResource;
+    /**
+     * 生成唯一资源 ID。
+     *
+     * @returns 形如 asset_<timestamp>_<rand> 的 ID 字符串
+     */
+    private generateId;
+    /**
+     * 根据 URL 后缀推断资源类型，无法识别时回退为 EFFECT。
+     *
+     * @param url 资源 URL
+     * @returns 推断出的资源类型
+     */
+    private inferType;
+}

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

@@ -0,0 +1,3 @@
+export { AssetManager } from './asset-manager';
+export { AssetType, AssetLoadState } from './asset-manager';
+export type { BaseAssetEntry, ImageAssetEntry, VideoAssetEntry, AudioAssetEntry, FontAssetEntry, EffectAssetEntry, AssetEntry, LoadAssetOptions, } from './asset-manager';

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

@@ -0,0 +1,315 @@
+import type { HistoryManager } from '../history';
+import type { Command, CommandFactory, CommandLifecycleEvent } from './types';
+import type { CommandRegistry } from './registry';
+import type { AnyArtisErrorInfo, ErrorMonitor, ErrorPhase } from '../quality/error-monitor';
+/**
+ * Command 执行前置守卫：(commandId, args) => void；抛错即拒绝执行。
+ * 供 artis 注入「忽略交互」等前置校验，在 Command 创建并执行前调用。
+ *
+ * args 为<b>单参对象</b>（与执行/注册入口同源，形状由 CommandRegistry 反推），守卫侧按具名字段
+ * 提取目标元素 id 等（如 args.itemId / args.itemIds）。
+ */
+export type CommandGuard = (commandId: string, args: unknown) => void;
+/** Command 失败事件出口；返回已捕获载荷供 ErrorMonitor 复用，避免重复抓取快照。 */
+export type CommandErrorEventHandler = (error: unknown, phase: ErrorPhase, ctx: {
+    commandId: string;
+}) => AnyArtisErrorInfo | undefined;
+/**
+ * CommandService - 指令服务中心
+ *
+ * 所有数据修改必须通过指令执行，支持：
+ * 1. 注册/注销 Command 工厂
+ * 2. 执行 Command 并自动注入 History
+ * 3. 交互态（beginInteraction / updateInteraction / endInteraction）：
+ *    拖拽过程中持续修改同一个 Command，交互结束后才加入 History
+ * 4. 批量态（beginBatch / endBatch / cancelBatch）：
+ *    单次交互产生的多个 record 子 Command 聚合为一个历史条目，统一 undo/redo
+ */
+export declare class CommandService {
+    private _factories;
+    private _historyManager;
+    /** 交互态中的 Command（尚未入 History） */
+    private _interactionCommand;
+    /** 是否正在交互态中 */
+    private _isInInteraction;
+    /** Command 执行后的回调集合（用于刷新 Store 数据等） */
+    private _afterExecuteCallbacks;
+    /**
+     * Command 生命周期事件订阅集合（中央监听，多订阅）。
+     *
+     * 统一覆盖 execute/undo/redo 三时机：execute 侧由 {@link _triggerAfterExecute} 同点发，
+     * undo/redo 侧桥接 {@link HistoryManager.addOnChange}（command-service 构造时订阅）。
+     * 横切订阅者（埋点/自动保存/UI 刷新）经此一处即可，无需分别订 afterExecute + history。
+     */
+    private _lifecycleListeners;
+    /** 桥接 history change → lifecycle 的订阅 dispose（dispose 时移除，避免泄漏） */
+    private _disposeHistoryBridge;
+    /** 是否正在批量态中（record 的子命令会被缓冲，endBatch 时统一入 History） */
+    private _isInBatch;
+    /** 批量态缓冲的子 Command */
+    private _batchBuffer;
+    /**
+     * 批量态是否挂起了 afterExecute 回调。
+     *
+     * 批量态下各子命令不再逐个触发 afterExecute（此前 N 个 record 让 syncAllItemsFromPlayer /
+     * JSON 回写同帧跑 N 次——D5），改为在 endBatch 时用聚合后的代表命令（composite 或单子）
+     * 触发一次。安全性：批内数据新鲜度由调用方在子命令间的手动 syncAllItemsFromPlayer 保证
+     * （见 register-gizmo-command-bindings onMouseUp），不依赖 afterExecute；现有 afterExecute
+     * 订阅者（wiring 同步 / SceneArtis JSON 回写）均忽略 command 入参，为纯 flush，聚合安全。
+     */
+    private _batchNeedsAfterExecuteFlush;
+    /** 错误监控器（按需注入，未注入时不生效） */
+    private _errorMonitor?;
+    /** 业务错误事件出口（BaseArtis 注入，默认无需 enableErrorMonitor 即可工作） */
+    private _errorEventHandler?;
+    /** 执行前置守卫（按需注入；创建并执行 Command 前调用，抛错即拒绝执行） */
+    private _guard?;
+    /** 可编辑守卫（第二前置守卫槽，SceneArtis PlayState 拦编辑类命令；S7） */
+    private _editableGuard?;
+    /**
+     * 构造 CommandService，绑定历史管理器
+     *
+     * @param historyManager 历史记录管理器，用于 push/undo/redo Command
+     */
+    constructor(historyManager: HistoryManager);
+    /**
+     * 设置 Command 执行后的回调（替换式，向后兼容）
+     *
+     * 会清空已注册的所有 afterExecute 回调，仅保留传入的这一个。
+     * 新调用方建议改用 {@link addAfterExecute} / {@link removeAfterExecute} 进行多订阅，
+     * 避免新回调无意覆盖既有订阅。
+     *
+     * 在 execute / endInteraction / record 后触发，用于根据 playerItem 刷新 store 数据。
+     *
+     * @param callback 执行后回调函数，入参为刚执行的 Command
+     */
+    setAfterExecute(callback: (command: Command) => void): void;
+    /**
+     * 追加一个 Command 执行后的回调（多回调中继点）
+     *
+     * 多个回调按注册顺序依次触发，互不覆盖。返回一个 dispose 函数用于注销该回调，
+     * 便于子模块在 dispose 时精确移除自身订阅。
+     *
+     * @param callback 执行后回调函数，入参为刚执行的 Command
+     * @returns 注销函数，调用后移除该回调
+     */
+    addAfterExecute(callback: (command: Command) => void): () => void;
+    /**
+     * 移除一个 Command 执行后的回调
+     *
+     * @param callback 要移除的回调函数
+     */
+    removeAfterExecute(callback: (command: Command) => void): void;
+    /**
+     * 订阅 Command 生命周期事件（中央监听，多订阅）。
+     *
+     * 统一覆盖 execute / undo / redo 三时机，横切订阅者（埋点/自动保存/UI 刷新触发）经此一处即可。
+     * execute 侧与 afterExecute 同点触发（含 batch endBatch 聚合后的代表命令）；
+     * undo/redo 侧桥接 history change。payload 取 {@link Command.eventPayload}（Command 自填）。
+     *
+     * 与 afterExecute 分轨：afterExecute 驱动内部数据回写管线（syncAllItemsFromPlayer +
+     * Player→Store 同步），lifecycle 供外部横切订阅，两者职责不重叠；Gizmo 由原生 pre-render 刷新。
+     *
+     * @param listener 生命周期事件监听器
+     * @returns 注销函数，调用后移除该监听器
+     */
+    onCommandLifecycle(listener: (event: CommandLifecycleEvent) => void): () => void;
+    /** 按 phase 发 lifecycle 事件给全部订阅者，payload 取 command.eventPayload */
+    private _emitLifecycle;
+    /**
+     * 触发所有 afterExecute 回调（按注册顺序）
+     *
+     * @param command 刚执行/入史的 Command
+     */
+    private _triggerAfterExecute;
+    /**
+     * 注入错误监控器（由 Artis.enableErrorMonitor() 调用，未注入时不影响现有行为）
+     *
+     * @param monitor 错误监控器实例
+     */
+    setErrorMonitor(monitor?: ErrorMonitor): void;
+    /** 注入 Command 业务错误事件出口；与 ErrorMonitor 共用其返回的错误快照。 */
+    setErrorEventHandler(handler?: CommandErrorEventHandler): void;
+    /**
+     * 释放资源：移除构造时桥接 history change → lifecycle 的订阅，避免泄漏。
+     *
+     * 供 Artis dispose 阶段调用。未调用则在 CommandService 与 HistoryManager 同生命周期
+     * 场景下随实例一并回收，无遗留泄漏。
+     */
+    dispose(): void;
+    /**
+     * 注入执行前置守卫。守卫在 execute / beginInteraction / updateInteraction 创建并执行
+     * Command 前调用，抛错即拒绝执行对应 Command。未注入时不影响现有行为。
+     *
+     * @param guard 守卫函数，入参为 commandId 与透传给工厂的 args
+     */
+    setCommandGuard(guard?: CommandGuard): void;
+    /**
+     * 统一执行前置守卫链：先可编辑守卫（拦截非编辑态的编辑类命令），再命令守卫（ignoredInteraction）。
+     * 用于 execute / beginInteraction / updateInteraction 三入口；record 故意不走（post-execution）。
+     */
+    private _runGuards;
+    /**
+     * 命令执行异常是否应进入业务错误事件与 errorMonitor。
+     *
+     * IgnoredInteractionError（code='IGNORED_INTERACTION'）是 guard 抛出的业务级「忽略」而非真错误——
+     * 上报会污染错误指标，使合法拒绝淹没真异常，故跳过。鸭子判别 code 字段，避免 core 反向
+     * import artis 的 IgnoredInteractionError 类。
+     */
+    private _isReportableCommandError;
+    /** 统一发散 Command 真异常：业务事件逐条发，监控通道复用同一快照后自行节流。 */
+    private _reportCommandError;
+    /**
+     * 注入可编辑守卫（第二前置守卫槽，与 setCommandGuard 独立共存）。
+     *
+     * 同样在 execute / beginInteraction / updateInteraction 三入口创建并执行 Command 前调用
+     * （先于 _guard），抛错即拒绝。专供 SceneArtis 在 PlayState 等非编辑态拦截编辑类命令
+     * （S7）。**故意不覆盖 record**：record 接收的是 gizmo 已执行完毕的命令，post-execution
+     * 守卫无法阻止且抛错会破坏已发生变更。
+     *
+     * @param guard 可编辑守卫函数；传 undefined 清空（dispose 用）
+     */
+    setEditableGuard(guard?: CommandGuard): void;
+    /**
+     * 唯一咽喉：把 Command 入历史栈前统一标注可重放信息。
+     *
+     * 所有入 History 的路径（execute / endInteraction / record / endBatch 单条与复合）
+     * 都经此方法，确保每个进入历史的 Command 都带上 replay 供 ErrorMonitor 快照使用。
+     * - Command 实现了 {@link Command.serializeReplay} → 用其纯数据结果（命令最懂自己
+     *   累加合并后的真实状态，优先级高于 execute 时按工厂 args 推得的结果）
+     * - 否则保留 execute 时按工厂 args 推得的 replay；若两者皆无 → replayable=false
+     *
+     * @param command 待入历史栈的 Command
+     */
+    private _pushToHistory;
+    /**
+     * 注册 Command 工厂（三套强类型入口并存）
+     *
+     * ① 内置命令走 `<K extends keyof CommandRegistry>` 重载：commandId 经 {@link CommandRegistry}
+     *   反推 args 对象形状，factory 收到强类型单参对象；result 也强类型。注册与执行侧均强类型。
+     * ② 外部自定义命令走 `<A = unknown>` 泛型重载：`registerCommand<MyArgs>('x', fn)` 或由 TS 从
+     *   factory 实参反推 `A`，factory 即得强类型入参；不标注时 A 用缺省 `unknown`。**仅约束注册侧**，
+     *   执行侧 `execute('x', ...)` 仍兜底 unknown（需 `declare module` 增强 Registry 才两端强类型）。
+     * ③ 对外公共命令走 `declare module '@vvfx/artis' { interface CommandRegistry {...} }` 合并：
+     *   注册与执行侧均强类型，适合对外暴露给多调用方（见 {@link ./registry.ts} 头部示例）。
+     *
+     * @param commandId Command 类型 ID
+     * @param factory 创建 Command 实例的工厂函数，入参为单参对象
+     */
+    registerCommand<K extends keyof CommandRegistry>(commandId: K, factory: CommandFactory<CommandRegistry[K]['args']>): void;
+    registerCommand<A = unknown>(commandId: string, factory: CommandFactory<A>): void;
+    /**
+     * 注销 Command
+     *
+     * @param commandId 要注销的 Command 类型 ID
+     */
+    unregisterCommand(commandId: string): void;
+    /**
+     * 执行 Command：创建实例 → execute() → 入 History
+     *
+     * 批量态下不直接入 History，而是缓冲到 _batchBuffer，
+     * 待 endBatch 时聚合为一个历史条目（execute 仍会立即执行以修改数据）。
+     *
+     * 内置命令走强类型重载：commandId 经 {@link CommandRegistry} 反推 args 对象形状与 result 类型，
+     * 调用方获得编译期校验 + IDE 具名提示。外部/动态派发命中 string 兜底重载（args 为 unknown）。
+     *
+     * @param commandId Command 类型 ID
+     * @param args 透传给工厂函数的单参对象
+     * @returns 创建并执行后的 Command 实例
+     */
+    execute<K extends string>(commandId: K, args: K extends keyof CommandRegistry ? CommandRegistry[K]['args'] : unknown): K extends keyof CommandRegistry ? CommandRegistry[K]['result'] : Command;
+    /**
+     * 开始交互态
+     * 创建 Command 并立即执行，但不入 History（等 endInteraction 时再入）
+     *
+     * 内置命令走强类型重载（commandId 反推 args 对象形状）；外部命中 string 兜底。
+     *
+     * @param commandId Command 类型 ID
+     * @param args 透传给工厂函数的单参对象
+     * @returns 创建并执行后的交互 Command 实例
+     */
+    beginInteraction<K extends string>(commandId: K, args: K extends keyof CommandRegistry ? CommandRegistry[K]['args'] : unknown): K extends keyof CommandRegistry ? CommandRegistry[K]['result'] : Command;
+    /**
+     * 交互态中更新：创建新 Command 尝试合并到当前交互 Command
+     * 如果不支持合并，则替换为新 Command
+     *
+     * 内置命令走强类型重载（commandId 反推 args 对象形状）；外部命中 string 兜底。
+     *
+     * @param commandId Command 类型 ID
+     * @param args 透传给工厂函数的单参对象
+     * @returns 合并或替换后的交互 Command；非交互态或工厂未注册时返回 undefined
+     */
+    updateInteraction<K extends string>(commandId: K, args: K extends keyof CommandRegistry ? CommandRegistry[K]['args'] : unknown): (K extends keyof CommandRegistry ? CommandRegistry[K]['result'] : Command) | undefined;
+    /**
+     * 取消当前交互态（不入 History，撤销已执行的变更）
+     * 用于交互中 Command 类型切换场景：先 cancel 旧的，再 begin 新的
+     *
+     * @returns 被取消的 Command（可用于提取旧数据继承到新 Command），如果无交互态则返回 undefined
+     */
+    cancelInteraction(): Command | undefined;
+    /**
+     * 结束交互态，将最终 Command 入 History
+     *
+     * @returns 入 History 的交互 Command；非交互态时返回 undefined
+     */
+    endInteraction(): Command | undefined;
+    /**
+     * 记录已执行的 Command 到 History（不调用 execute）
+     *
+     * 用于 Gizmo 交互场景：Gizmo 自身已完成数据修改，
+     * 此处只需将 Command（含 old/new 快照）入 History 以支持 undo/redo。
+     *
+     * 批量态下不直接入 History，而是缓冲到 _batchBuffer，
+     * 待 endBatch 时聚合为一个历史条目。
+     *
+     * @param command 已执行完毕、待入历史的 Command
+     */
+    record(command: Command): void;
+    /**
+     * 开始批量态
+     *
+     * 开启后，期间所有 record 的子 Command 会被缓冲，不立即入 History。
+     * 调用方需保证最终调用 endBatch 或 cancelBatch 收尾。
+     */
+    beginBatch(): void;
+    /**
+     * 结束批量态，将缓冲的子 Command 聚合入 History
+     *
+     * - 0 个子命令：不入 History
+     * - 1 个子命令：直接入该子命令（历史更干净，不包裹 Composite）
+     * - 多个子命令：包成 CompositeCommand 入 History
+     *
+     * @param commandId 可选的复合命令显示 ID（仅多子命令时生效）
+     * @returns 入 History 的 Command；无子命令时返回 undefined
+     */
+    endBatch(commandId?: string): Command | undefined;
+    /**
+     * 取消批量态：丢弃缓冲的子 Command（不入 History）
+     *
+     * 注意：子命令的数据变更已经发生，此处不做回滚，仅放弃历史记录。
+     * 如需回滚请由调用方自行处理。
+     */
+    cancelBatch(): void;
+    /**
+     * 收尾所有未完成的交互态 / 批量态。
+     *
+     * 用于独立功能状态隔离（pushSession）前调用：确保挂起主栈前，
+     * 任何进行中的交互态（拖拽未结束）或批量态（batch 未关闭）先正常入 History，
+     * 避免快照里混入半成品 Command。
+     */
+    flush(): void;
+    /**
+     * 是否正在交互态中
+     */
+    get isInInteraction(): boolean;
+    /**
+     * 是否正在批量态中
+     */
+    get isInBatch(): boolean;
+    /**
+     * 获取所有已注册的 Command ID
+     *
+     * @returns 已注册 Command ID 的数组（拷贝）
+     */
+    getRegisteredCommands(): string[];
+}

package/dist/core/command/commands/composite-command.d.ts

@@ -0,0 +1,45 @@
+import type { Command } from '../types';
+export type CompositeCommandArgs = {
+    /** 子 Command 列表（按执行先后顺序排列） */
+    children: Command[];
+    /** 可选的复合命令显示 ID（如 'transform.frameMove'），默认 'composite' */
+    commandId?: string;
+};
+/**
+ * CompositeCommand - 复合命令
+ *
+ * 将单次交互产生的多个子 Command 聚合为一个历史条目，使其在 History 中
+ * 表现为「一次操作」：撤销一次即可还原全部子操作。
+ *
+ * 顺序约定：
+ * - children 按执行先后顺序排列（先发生的在前）
+ * - execute / redo：正序遍历（先发生的先执行）
+ * - undo：逆序遍历（后发生的先撤销），保证依赖关系正确
+ *   例如「自动布局重排(layout) → 元素移动(move)」，撤销时必须先撤 move 再撤 layout。
+ *
+ * 注意：在 Gizmo 交互场景中，子 Command 进入复合命令前通常已被各自 execute 过
+ * （配合 CommandService.record 语义）。CompositeCommand 入 History 时不重复执行，
+ * 仅在后续 undo / redo 时统一驱动子命令。
+ */
+export declare class CompositeCommand implements Command {
+    readonly id: string;
+    readonly commandId: string;
+    private _children;
+    /**
+     * 初始化复合命令，拷贝子命令列表并生成命令 ID
+     * @param args 子命令列表与可选 commandId
+     */
+    constructor(args: CompositeCommandArgs);
+    /** 子命令数量 */
+    get size(): number;
+    /** 是否不含任何子命令 */
+    get isEmpty(): boolean;
+    /** 子命令列表（只读副本） */
+    get children(): Command[];
+    /** 正序执行所有子命令 */
+    execute(): void;
+    /** 逆序撤销所有子命令，保证依赖关系正确还原 */
+    undo(): void;
+    /** 正序重做所有子命令 */
+    redo(): void;
+}