@vvfx/artis 0.0.1-alpha.0

package/dist/core/command/commands/frame-layout-command.d.ts

@@ -0,0 +1,81 @@
+import type { Command } from '../types';
+import type { ItemService } from '../../service';
+import type { Store } from '../../store';
+import type { LayoutInfo } from '../../types';
+/**
+ * 单元素行列变更（拖拽交互产生的语义化输入）。
+ *
+ * 仅用于交互层（gizmo / gesture-handler）计算完整 layoutInfos 的中间表达，
+ * 不再作为 FrameLayoutCommand 的直接入参。
+ */
+export type LayoutOrderChange = {
+    draggedItemId: string;
+    fromRow: number;
+    fromColumn: number;
+    toRow: number;
+    toColumn: number;
+};
+export type FrameLayoutCommandArgs = {
+    /** 目标 Frame ID */
+    frameId: string;
+    /**
+     * 新的完整 layoutInfos（由调用方算好整份再传入）。
+     *
+     * 不传时表示纯 re-layout（沿用 Frame 现有 layoutInfos 重新排布），
+     * 用于 moveIn / moveOut 后的画板重排场景。
+     */
+    newLayoutInfos?: Record<string, LayoutInfo>;
+    itemService: ItemService;
+    store: Store;
+};
+/**
+ * frame.autoLayout - 对 Frame 内子元素执行自动布局 Command
+ *
+ * 快照策略（选项1）：只快照 Frame 的 layoutInfos（行列信息）。
+ * 子元素 position 与 Frame 尺寸均不快照，undo/redo 时统一通过
+ * applyFrameAutoLayout 基于 layoutInfos 重算（重算幂等）。
+ *
+ * execute: 写入新 layoutInfos（如有）→ applyFrameAutoLayout 重排
+ * undo:    写回旧 layoutInfos → applyFrameAutoLayout 重排
+ * redo:    写回新 layoutInfos → applyFrameAutoLayout 重排
+ */
+export declare class FrameLayoutCommand implements Command {
+    readonly id: string;
+    readonly commandId = "frame.autoLayout";
+    private _frameId;
+    private _newLayoutInfos;
+    private _itemService;
+    private _store;
+    /** 执行前的 layoutInfos 快照（首次 execute 时拍摄） */
+    private _oldLayoutInfos;
+    /** 执行后的 layoutInfos 快照（execute 后拍摄，供 redo 复用） */
+    private _afterLayoutInfos;
+    private _captured;
+    /**
+     * 初始化 Frame 自动布局命令，保存目标 Frame 与新 layoutInfos 副本
+     * @param args Frame ID、新 layoutInfos 及依赖的 service/store
+     */
+    constructor(args: FrameLayoutCommandArgs);
+    /** 首次执行时快照旧 layoutInfos 并按新 layoutInfos 重排 Frame 子元素 */
+    execute(): void;
+    /** 用执行前的 layoutInfos 快照重排，还原 Frame 布局 */
+    undo(): void;
+    /** 用执行后的 layoutInfos 快照重排，重新应用目标布局 */
+    redo(): void;
+    /**
+     * 写回指定 layoutInfos 并重排（undo/redo 共用）
+     * @param layoutInfos 要写入的 layoutInfos 快照；undefined 表示清除并纯 re-layout
+     */
+    private _applyLayoutInfos;
+    /**
+     * 从 store 中查找目标 Frame 元素
+     * @returns 命中的 FrameItem；不存在时返回 undefined
+     */
+    private _getFrameItem;
+    /**
+     * 深拷贝 layoutInfos 映射，避免快照与运行态共享引用
+     * @param source 源 layoutInfos
+     * @returns 拷贝后的 layoutInfos
+     */
+    private _cloneLayoutInfos;
+}

package/dist/core/command/commands/frame-layout-mode-command.d.ts

@@ -0,0 +1,55 @@
+import type { Command } from '../types';
+import type { ItemService } from '../../service';
+import type { Store } from '../../store';
+export type FrameLayoutModeCommandArgs = {
+    /** Frame ID */
+    frameId: string;
+    /** 目标布局模式 */
+    targetMode: 'auto' | 'free';
+    itemService: ItemService;
+    store: Store;
+};
+/**
+ * frame.layoutMode - 切换画板布局模式 Command
+ *
+ * execute: 快照（子元素位置 + Frame 尺寸/位置 + layoutInfos + oldMode），
+ *          再通过 updateFrameLayoutMode 切换模式（切到 AUTO 会触发自动布局）
+ * undo:    通过 updateFrameLayoutMode 还原模式，并还原子元素位置、Frame 尺寸/位置、layoutInfos
+ * redo:    重新切换模式
+ */
+export declare class FrameLayoutModeCommand implements Command {
+    readonly id: string;
+    readonly commandId = "frame.layoutMode";
+    private _frameId;
+    private _targetMode;
+    private _itemService;
+    private _store;
+    private _oldSnapshot;
+    /**
+     * 初始化布局模式切换命令，保存目标 Frame 与目标模式
+     * @param args Frame ID、目标模式及依赖的 service/store
+     */
+    constructor(args: FrameLayoutModeCommandArgs);
+    /** 首次执行时拍摄快照并切换到目标布局模式 */
+    execute(): void;
+    /** 还原模式、Frame 尺寸/位置、子元素位置与 layoutInfos 至快照状态 */
+    undo(): void;
+    /** 重新切换到目标布局模式 */
+    redo(): void;
+    /**
+     * 拍摄模式、子元素位置、Frame 尺寸/位置与 layoutInfos 快照
+     * @returns 布局模式快照（Frame 不存在时返回默认零值快照）
+     */
+    private _captureSnapshot;
+    /**
+     * 从 store 中查找目标 Frame 元素
+     * @returns 命中的 FrameItem，未找到时返回 undefined
+     */
+    private _getFrameItem;
+    /**
+     * 深拷贝 layoutInfos 映射
+     * @param source 源 layoutInfos
+     * @returns 拷贝后的 layoutInfos
+     */
+    private _cloneLayoutInfos;
+}

package/dist/core/command/commands/frame-move-in-command.d.ts

@@ -0,0 +1,54 @@
+import type { Command } from '../types';
+import type { ItemService } from '../../service';
+import type { Store } from '../../store';
+export type FrameMoveInCommandArgs = {
+    /** 要移入的元素 ID 列表 */
+    itemIds: string[];
+    /** 目标 Frame ID */
+    frameId: string;
+    itemService: ItemService;
+    store: Store;
+};
+/**
+ * frame.moveIn - 将元素移入 Frame Command
+ *
+ * execute: 调用 ItemService.moveItemsToFrame（数据层 + Player 层 + transform 补偿）
+ * undo: 恢复元素 parentId / position 与 Frame.children 快照
+ * redo: 重新移入
+ */
+export declare class FrameMoveInCommand implements Command {
+    readonly id: string;
+    readonly commandId = "frame.moveIn";
+    private _itemIds;
+    private _frameId;
+    private _itemService;
+    private _store;
+    private _oldSnapshot;
+    /**
+     * 初始化移入 Frame 命令，保存目标元素与目标 Frame
+     * @param args 元素 ID 列表、目标 Frame ID 及依赖的 service/store
+     */
+    constructor(args: FrameMoveInCommandArgs);
+    /** 首次执行时拍摄快照并将指定元素移入目标 Frame */
+    execute(): void;
+    /** 恢复元素 parentId、位置及受影响 Frame 的 children 至快照状态 */
+    undo(): void;
+    /** 重新将元素移入目标 Frame */
+    redo(): void;
+    /**
+     * 拍摄元素位置、parentId 与受影响 Frame 的 children 快照
+     * @returns 包含位置、parentId 与 Frame children 的快照对象
+     */
+    private _captureSnapshot;
+    /**
+     * 记录指定 Frame 的 children 副本到 target，已记录则跳过
+     * @param frameId Frame ID
+     * @param target 收集目标 Map
+     */
+    private _recordFrameChildren;
+    /**
+     * 按快照还原元素 parentId、位置与受影响 Frame 的 children
+     * @param snapshot 要还原的快照对象
+     */
+    private _restoreSnapshot;
+}

package/dist/core/command/commands/frame-move-out-command.d.ts

@@ -0,0 +1,54 @@
+import type { Command } from '../types';
+import type { ItemService } from '../../service';
+import type { Store } from '../../store';
+export type FrameMoveOutCommandArgs = {
+    /** 要移出的元素 ID 列表 */
+    itemIds: string[];
+    /** 源 Frame ID（可选，不传则从元素当前 parentId 推断） */
+    frameId?: string;
+    itemService: ItemService;
+    store: Store;
+};
+/**
+ * frame.moveOut - 将元素从 Frame 移出到主场景 Command
+ *
+ * execute: 调用 ItemService.moveItemsOutOfFrame（数据层 + Player 层 + transform 补偿）
+ * undo: 把元素移回各自原 Frame，并恢复 parentId / position / Frame.children
+ * redo: 重新移出
+ */
+export declare class FrameMoveOutCommand implements Command {
+    readonly id: string;
+    readonly commandId = "frame.moveOut";
+    private _itemIds;
+    private _frameId;
+    private _itemService;
+    private _store;
+    private _oldSnapshot;
+    /**
+     * 初始化移出 Frame 命令，保存目标元素与可选源 Frame
+     * @param args 元素 ID 列表、可选源 Frame ID 及依赖的 service/store
+     */
+    constructor(args: FrameMoveOutCommandArgs);
+    /** 首次执行时拍摄快照并将指定元素移出 Frame 到主场景 */
+    execute(): void;
+    /** 将元素移回各自原 Frame，并恢复 parentId、位置与 Frame 的 children */
+    undo(): void;
+    /** 重新将元素移出 Frame */
+    redo(): void;
+    /**
+     * 拍摄元素位置、parentId 与源 Frame 的 children 快照
+     * @returns 包含 positions / parentIds / frameChildren 的快照对象
+     */
+    private _captureSnapshot;
+    /**
+     * 记录指定 Frame 的 children 副本到 target，已记录则跳过
+     * @param frameId Frame ID
+     * @param target 收集目标 Map
+     */
+    private _recordFrameChildren;
+    /**
+     * 按快照将元素移回原 Frame 并还原 parentId、位置与 Frame 的 children
+     * @param snapshot 移出前拍摄的快照
+     */
+    private _restoreSnapshot;
+}

package/dist/core/command/commands/group-children-detach-command.d.ts

@@ -0,0 +1,28 @@
+import type { Command } from '../types';
+import type { ItemService } from '../../service';
+import type { Store } from '../../store';
+export type GroupChildrenDetachCommandArgs = {
+    groupId: string;
+    itemIds: string[];
+    itemService: ItemService;
+    store: Store;
+};
+/**
+ * 将 Group 的部分直属子元素分离到主场景根节点。
+ *
+ * execute/redo 通过 ItemService 同步修改 Store 与 Player；undo 恢复原始 children 顺序，
+ * reparent 前后都进行世界变换补偿。
+ */
+export declare class GroupChildrenDetachCommand implements Command {
+    readonly id: string;
+    readonly commandId = "group.detachChildren";
+    private readonly _groupId;
+    private readonly _itemIds;
+    private readonly _itemService;
+    private readonly _store;
+    private _oldChildren;
+    constructor(args: GroupChildrenDetachCommandArgs);
+    execute(): void;
+    undo(): void;
+    redo(): void;
+}

package/dist/core/command/commands/index.d.ts

@@ -0,0 +1,98 @@
+export { CompositeCommand } from './composite-command';
+export type { CompositeCommandArgs } from './composite-command';
+export { ItemCreateCommand } from './item-create-command';
+export type { ItemCreateCommandArgs } from './item-create-command';
+export { ItemDeleteCommand } from './item-delete-command';
+export type { ItemDeleteCommandArgs } from './item-delete-command';
+export { ItemTransformCommand } from './item-transform-command';
+export type { ItemTransformCommandArgs, TransformData } from './item-transform-command';
+export { ItemUpdatePropertyCommand } from './item-update-property-command';
+export type { ItemUpdatePropertyCommandArgs } from './item-update-property-command';
+export { ItemReorderCommand, ReorderType } from './item-reorder-command';
+export type { ItemReorderCommandArgs } from './item-reorder-command';
+export { ItemGroupCommand } from './item-group-command';
+export type { ItemGroupCommandArgs } from './item-group-command';
+export { ItemUngroupCommand } from './item-ungroup-command';
+export type { ItemUngroupCommandArgs } from './item-ungroup-command';
+export { ItemAlignCommand } from './item-align-command';
+export type { ItemAlignCommandArgs } from './item-align-command';
+export { ItemDistributeCommand } from './item-distribute-command';
+export type { ItemDistributeCommandArgs } from './item-distribute-command';
+export { ItemUpdatePropertyBySchemaCommand } from './item-update-property-by-create-info-command';
+export type { ItemUpdatePropertyBySchemaCommandArgs } from './item-update-property-by-create-info-command';
+export { ItemSetFontFamilyCommand } from './item-set-font-family-command';
+export type { ItemSetFontFamilyCommandArgs } from './item-set-font-family-command';
+export { ItemSetGeneratorResourceCommand } from './item-set-generator-resource-command';
+export type { ItemSetGeneratorResourceCommandArgs } from './item-set-generator-resource-command';
+export { TransformMoveCommand } from './transform-move-command';
+export type { TransformMoveCommandArgs } from './transform-move-command';
+export { TransformScaleCommand } from './transform-scale-command';
+export type { TransformScaleCommandArgs, ScaleSnapshot } from './transform-scale-command';
+export { TransformRotateCommand } from './transform-rotate-command';
+export type { TransformRotateCommandArgs, RotateSnapshot } from './transform-rotate-command';
+export { TransformMoveWithLayoutCommand } from './transform-move-with-layout-command';
+export type { TransformMoveWithLayoutCommandArgs } from './transform-move-with-layout-command';
+export { TransformMoveWithFrameChangeCommand } from './transform-move-with-frame-change-command';
+export type { TransformMoveWithFrameChangeCommandArgs, FrameChangeSnapshot } from './transform-move-with-frame-change-command';
+export { GroupChildrenDetachCommand } from './group-children-detach-command';
+export type { GroupChildrenDetachCommandArgs } from './group-children-detach-command';
+export { TextMoveCommand } from './text-move-command';
+export type { TextMoveCommandArgs } from './text-move-command';
+export { TextScaleCommand } from './text-scale-command';
+export type { TextScaleCommandArgs, TextScaleSnapshot } from './text-scale-command';
+export { TextRotateCommand } from './text-rotate-command';
+export type { TextRotateCommandArgs } from './text-rotate-command';
+export { TextUpdateContentCommand } from './text-update-content-command';
+export type { TextUpdateContentCommandArgs, TextContentData } from './text-update-content-command';
+export { SelectionSetCommand } from './selection-set-command';
+export type { SelectionSetCommandArgs } from './selection-set-command';
+export { FrameMoveInCommand } from './frame-move-in-command';
+export type { FrameMoveInCommandArgs } from './frame-move-in-command';
+export { FrameMoveOutCommand } from './frame-move-out-command';
+export type { FrameMoveOutCommandArgs } from './frame-move-out-command';
+export { FrameLayoutCommand } from './frame-layout-command';
+export type { FrameLayoutCommandArgs, LayoutOrderChange } from './frame-layout-command';
+export { FrameLayoutModeCommand } from './frame-layout-mode-command';
+export type { FrameLayoutModeCommandArgs } from './frame-layout-mode-command';
+export { MaskCommitCommand } from './mask-commit-command';
+export type { MaskCommitCommandArgs, MaskLine } from './mask-commit-command';
+export { PictureCutCommitCommand } from './picture-cut-commit-command';
+export type { PictureCutCommitCommandArgs, NormalizedBox } from './picture-cut-commit-command';
+export { PictureExpandCommitCommand } from './picture-expand-commit-command';
+export type { PictureExpandCommitCommandArgs } from './picture-expand-commit-command';
+export { SpriteImageCommand } from './sprite-image-command';
+export type { SpriteImageCommandArgs } from './sprite-image-command';
+export { VideoSourceCommand } from './video-source-command';
+export type { VideoSourceCommandArgs } from './video-source-command';
+export { StateSwitchCommandBase } from './state-switch-command-base';
+export { StateItemCreateCommand } from './state-item-create-command';
+export type { StateItemCreateCommandArgs } from './state-item-create-command';
+export { StateMoveCommand } from './state-move-command';
+export type { StateMoveCommandArgs } from './state-move-command';
+export { StateHandCommand } from './state-hand-command';
+export type { StateHandCommandArgs } from './state-hand-command';
+export { StateImageCutCommand } from './state-image-cut-command';
+export type { StateImageCutCommandArgs } from './state-image-cut-command';
+export { StateImageExpandCommand } from './state-image-expand-command';
+export type { StateImageExpandCommandArgs } from './state-image-expand-command';
+export { StateImageMaskCommand } from './state-image-mask-command';
+export type { StateImageMaskCommandArgs } from './state-image-mask-command';
+export { StateImageTextEditCommand } from './state-image-text-edit-command';
+export type { StateImageTextEditCommandArgs } from './state-image-text-edit-command';
+export { ItemReplaceSourceCommand } from './item-replace-source-command';
+export type { ItemReplaceSourceCommandArgs } from './item-replace-source-command';
+export { SpriteTextEditCommitCommand } from './sprite-text-edit-commit-command';
+export type { SpriteTextEditCommitCommandArgs, SpriteTextInfo } from './sprite-text-edit-commit-command';
+export { ViewportMoveCommand } from './viewport-move-command';
+export type { ViewportMoveCommandArgs } from './viewport-move-command';
+export { ViewportZoomCommand } from './viewport-zoom-command';
+export type { ViewportZoomCommandArgs } from './viewport-zoom-command';
+export { ViewportFitToBoxCommand } from './viewport-fit-to-box-command';
+export type { ViewportFitToBoxCommandArgs } from './viewport-fit-to-box-command';
+export { ViewportFitToItemsCommand } from './viewport-fit-to-items-command';
+export type { ViewportFitToItemsCommandArgs } from './viewport-fit-to-items-command';
+export { VideoPlayCommand } from './video-play-command';
+export type { VideoPlayCommandArgs } from './video-play-command';
+export { SceneSwitchCommand } from './scene-switch-command';
+export { PageAutoLayoutCommand } from './page-auto-layout-command';
+export type { PageAutoLayoutCommandArgs } from './page-auto-layout-command';

package/dist/core/command/commands/item-align-command.d.ts

@@ -0,0 +1,52 @@
+import type { Command } from '../types';
+import type { ItemService } from '../../service';
+import type { AlignType } from '../../../utils/types';
+export type ItemAlignCommandArgs = {
+    alignType: AlignType;
+    itemIds: string[];
+    itemService: ItemService;
+};
+/**
+ * item.align - 多元素对齐 Command
+ *
+ * 以「选中元素的整体包围盒」为基准，将每个元素按对齐类型贴到整体包围盒的对应边或中线。
+ * 多个元素的位移聚合为同一条 Command —— 一次 undo 即可整体还原。
+ *
+ * execute: 计算并应用每个元素的新中心位置（首次执行时快照旧位置）
+ * undo: 批量还原到旧位置
+ * redo: 批量重新应用新位置
+ */
+export declare class ItemAlignCommand implements Command {
+    readonly id: string;
+    readonly commandId = "item.align";
+    private _alignType;
+    private _itemIds;
+    private _itemService;
+    /** 首次 execute 时快照的旧中心位置：itemId → [x, y] */
+    private _oldPositions;
+    /** 计算出的新中心位置：itemId → [x, y] */
+    private _newPositions;
+    /**
+     * 初始化对齐命令，保存对齐类型与目标元素列表
+     * @param args 对齐类型、元素 ID 列表及依赖的 service
+     */
+    constructor(args: ItemAlignCommandArgs);
+    /** 元素数少于 2 时跳过；否则快照旧位置并按对齐类型应用新位置 */
+    execute(): void;
+    /** 应用旧位置快照，整体还原对齐前状态 */
+    undo(): void;
+    /** 重新应用对齐后的位置 */
+    redo(): void;
+    /**
+     * 采集各元素当前中心位置快照
+     * @returns 元素 ID 到当前中心位置 [x, y] 的映射；缺失元素被跳过
+     */
+    private _snapshotCurrentPositions;
+    /** 收集所有非空像素包围盒的元素列表 */
+    private _collectItemBoxes;
+    /**
+     * 批量应用元素中心位置
+     * @param positions 元素 ID 到位置的映射
+     */
+    private _applyPositions;
+}

package/dist/core/command/commands/item-create-command.d.ts

@@ -0,0 +1,66 @@
+import type { Command } from '../types';
+import type { ItemService } from '../../service';
+import type { ItemSchema } from '../../types';
+export type ItemCreateCommandArgs = {
+    /** 单个或多个 schema */
+    schemas: ItemSchema | ItemSchema[];
+    itemService: ItemService;
+};
+/**
+ * item.create - 创建元素 Command（支持单个/批量「先子后父」拓扑序创建）
+ *
+ * execute: 按拓扑序(先子后父)创建元素，同步捕获真实 id；_createdIds 按输入顺序回填
+ * undo: 删除所有已创建的元素
+ * redo: 重新创建所有元素，同步重捕真实 id
+ *
+ * id 契约（B + ii）：真实 id 由 {@link ItemService.createItemCore} 经身份策略决定——
+ * Artis 下 id=schemaId（固定），SceneArtis 下 id=instanceId（每次重建会变）。
+ * 故 _createdIds 在 execute/redo 同步重捕，undo 用最近一次捕获的真实 id 删除。
+ * 同步捕获是 ArtisSDK._createByInfo（execute 后即取 createdIds[0] 同步返回）的前提。
+ *
+ * 拓扑序（D9）：批量创建时，容器（GROUP/FRAME）创建会按其 property.children 主动挂载子元素，
+ * 故 children 必须先于容器创建。构造期按 schemas 间的 children 引用算稳定的拓扑序 buildOrder，
+ * execute/redo 按 buildOrder 创建；_createdIds 仍按输入顺序回填，保证 createdIds getter 与入参
+ * schemas 逐项一一对应（SDK 与新调用方依赖此契约）。出现父子循环依赖时构造期直接抛错——
+ * 此时 execute 未执行，无副作用、无需回滚，与既有 assertElementIdUnique「构造期失败」策略一致。
+ */
+export declare class ItemCreateCommand implements Command {
+    readonly id: string;
+    readonly commandId = "item.create";
+    private _schemas;
+    private _itemService;
+    private _createdIds;
+    /** 构造期算出的「先子后父」拓扑执行序（元素为 schemas 输入下标） */
+    private _buildOrder;
+    private _resourcePromises;
+    /**
+     * 初始化创建命令，规范化 schemas 为数组、预生成种子 ID、查重，并算出拓扑执行序
+     * @param args 单个/多个 schema 及依赖的 service
+     */
+    constructor(args: ItemCreateCommandArgs);
+    /** 按拓扑序创建所有元素，_createdIds 按输入顺序回填；同步收集 resourcePromise 供门面 await */
+    execute(): void;
+    /** 逆序删除所有已创建的元素（用最近一次捕获的真实 id） */
+    undo(): void;
+    /** 重新创建所有元素，同步重捕真实 id（SceneArtis 下 instanceId 会变，需重捕维系 undo 链）；重捕 resourcePromise */
+    redo(): void;
+    /**
+     * 更新拖拽创建中的同一个元素，并把最终 schema 保存在本 Command 中供 undo/redo 使用。
+     * 仅支持 Gizmo 固定宽度 Text 的实时创建；元素 ID 在整个交互内保持不变。
+     * @param schema 当前拖拽几何对应的完整 schema
+     */
+    updateInteractive(schema: ItemSchema): void;
+    /** 交互更新后由入史咽喉读取，确保错误复现记录使用最终 schema 而不是首帧尺寸。 */
+    serializeReplay(): {
+        args: ItemCreateCommandArgs;
+        replayable: true;
+    };
+    /** 获取本次创建的所有元素 ID（最近一次 execute/redo 捕获的真实 id，与入参 schemas 逐项对应） */
+    get createdIds(): string[];
+    /** 获取拓扑执行序（输入下标数组，先子后父）—供测试/调试观察 */
+    get buildOrder(): number[];
+    /** 获取本次创建的异步资源加载 promise（供上层门面 await，对齐 master「创建即资源就绪」语义） */
+    get resourcePromises(): Promise<void>[];
+    /** 异步资源失败回流 artis.error，同时保留原 Promise 的 rejection 供显式 await 的调用方处理。 */
+    private _trackResourcePromise;
+}

package/dist/core/command/commands/item-delete-command.d.ts

@@ -0,0 +1,40 @@
+import { type Command } from '../types';
+import { type ItemService } from '../../service';
+import { type Store } from '../../store';
+export type ItemDeleteCommandArgs = {
+    itemId: string;
+    itemService: ItemService;
+    store: Store;
+};
+/**
+ * item.delete - 删除元素 Command
+ *
+ * execute: 删除元素（保存快照用于恢复）
+ * undo: 恢复元素
+ * redo: 再次删除
+ */
+export declare class ItemDeleteCommand implements Command {
+    readonly id: string;
+    readonly commandId = "item.delete";
+    private _itemId;
+    private _itemService;
+    private _store;
+    private _schemaSnapshot;
+    /**
+     * 初始化删除命令，保存目标元素 ID 与依赖项
+     * @param args 元素 ID 及依赖的 service/store
+     */
+    constructor(args: ItemDeleteCommandArgs);
+    /** 拍摄元素 schema 快照后删除元素 */
+    execute(): void;
+    /** 基于快照重新创建被删除的元素，同步重捕真实 id（SceneArtis 下 instanceId 会变） */
+    undo(): void;
+    /** 再次删除该元素 */
+    redo(): void;
+    /**
+     * 将 ArtisItem 实例序列化为可重建的 ItemSchema 快照
+     * @param item 待序列化的元素
+     * @returns 元素 schema
+     */
+    private itemToSchema;
+}

package/dist/core/command/commands/item-distribute-command.d.ts

@@ -0,0 +1,53 @@
+import type { Command } from '../types';
+import type { ItemService } from '../../service';
+import type { DistributeType } from '../../../utils/types';
+export type ItemDistributeCommandArgs = {
+    distributeType: DistributeType;
+    itemIds: string[];
+    itemService: ItemService;
+};
+/**
+ * item.distribute - 多元素等间距分布 Command
+ *
+ * 沿分布方向按元素中心排序，固定首尾两个元素，将中间元素的中心点等间距铺开。
+ * 至少需要 3 个元素才有意义；不足 3 个时不做任何处理。
+ * 多个元素的位移聚合为同一条 Command —— 一次 undo 即可整体还原。
+ *
+ * execute: 计算并应用每个元素的新中心位置（首次执行时快照旧位置）
+ * undo: 批量还原到旧位置
+ * redo: 批量重新应用新位置
+ */
+export declare class ItemDistributeCommand implements Command {
+    readonly id: string;
+    readonly commandId = "item.distribute";
+    private _distributeType;
+    private _itemIds;
+    private _itemService;
+    /** 首次 execute 时快照的旧中心位置：itemId → [x, y] */
+    private _oldPositions;
+    /** 计算出的新中心位置：itemId → [x, y] */
+    private _newPositions;
+    /**
+     * 初始化分布命令，保存分布类型与目标元素列表
+     * @param args 分布类型、元素 ID 列表及依赖的 service
+     */
+    constructor(args: ItemDistributeCommandArgs);
+    /** 元素数少于 3 时跳过；否则快照旧位置并按分布类型应用新位置 */
+    execute(): void;
+    /** 应用旧位置快照，整体还原分布前状态 */
+    undo(): void;
+    /** 重新应用分布后的位置 */
+    redo(): void;
+    /**
+     * 采集各元素当前中心位置快照
+     * @returns 元素 ID 到当前中心位置 [x, y] 的映射
+     */
+    private _snapshotCurrentPositions;
+    /** 收集所有非空包围盒元素的 ID 与中心点 */
+    private _collectItemCenters;
+    /**
+     * 批量应用元素中心位置
+     * @param positions 元素 ID 到位置的映射
+     */
+    private _applyPositions;
+}

package/dist/core/command/commands/item-group-command.d.ts

@@ -0,0 +1,41 @@
+import type { Command } from '../types';
+import type { ItemService } from '../../service';
+export type ItemGroupCommandArgs = {
+    childrenIds: string[];
+    itemService: ItemService;
+};
+/**
+ * item.group - 打组 Command
+ *
+ * execute: 创建 Group 元素，将选中元素作为 children
+ * undo: 删除 Group 元素
+ * redo: 重新创建 Group
+ *
+ * id 契约（B + ii）：execute/redo 用 createItemCore 同步捕获真实 id 写回 _groupId。
+ * Artis 下 id=schemaId（固定）；SceneArtis 下 id=instanceId（每次重建会变，需重捕维系 undo 链）。
+ */
+export declare class ItemGroupCommand implements Command {
+    readonly id: string;
+    readonly commandId = "item.group";
+    private _childrenIds;
+    private _itemService;
+    private _groupId;
+    /**
+     * 构造打组 Command
+     * @param args 包含待打组子元素 ID 列表与 ItemService
+     */
+    constructor(args: ItemGroupCommandArgs);
+    /** 创建 Group 元素并将选中元素挂为 children，同步捕获真实 id */
+    execute(): void;
+    /** 撤销打组：删除已创建的 Group 元素 */
+    undo(): void;
+    /** 重做：复用上次 id 作种子重新创建 Group 元素，同步重捕真实 id */
+    redo(): void;
+    /**
+     * 按子元素像素包围盒并集中心确定新组位置（替代硬编码 [540,960]）。
+     * 子元素无有效盒（全空节点）时回退默认位置。组为空节点，位置仅作 origin，
+     * 子元素最终落点由 createGroupItem 的世界 transform 烘焙保证。
+     * @returns 组像素位置 [x, y]
+     */
+    private _resolveGroupPosition;
+}