@vvfx/artis 0.0.1-alpha.0

package/dist/core/command/commands/transform-rotate-command.d.ts

@@ -0,0 +1,51 @@
+import type { Command } from '../types';
+import type { ItemService } from '../../service';
+import type { Store } from '../../store';
+export type RotateSnapshot = {
+    position: [number, number];
+    rotation: number;
+};
+export type TransformRotateCommandArgs = {
+    itemIds: string[];
+    newSnapshots: Map<string, RotateSnapshot>;
+    itemService: ItemService;
+    store: Store;
+};
+/**
+ * transform.rotate - 旋转元素 Command（支持多选）
+ *
+ * execute: 应用新的 rotation + position（多元素绕中心旋转时 position 也变）
+ * undo: 恢复到旋转前的快照
+ * redo: 重新应用旋转后的快照
+ * merge: 同一批元素连续旋转合并（保留最初 old，更新 new）
+ */
+export declare class TransformRotateCommand implements Command {
+    readonly id: string;
+    readonly commandId = "transform.rotate";
+    private _itemIds;
+    private _newSnapshots;
+    private _oldSnapshots;
+    private _itemService;
+    private _store;
+    /**
+     * 初始化旋转命令，记录目标元素与新旧旋转快照
+     * @param args 命令参数（itemIds、新快照映射、itemService、store）
+     */
+    constructor(args: TransformRotateCommandArgs);
+    /** 返回受影响的元素 ID 列表 */
+    get itemIds(): string[];
+    /** 返回各元素旋转前的原始快照 */
+    get oldSnapshots(): Map<string, RotateSnapshot>;
+    /** 应用新旋转快照，首次执行时捕获各元素原始 position/rotation */
+    execute(): void;
+    /** 撤销旋转，将各元素恢复到原始快照 */
+    undo(): void;
+    /** 重做旋转，重新应用新旋转快照 */
+    redo(): void;
+    /**
+     * 合并连续的同批元素旋转命令，保留最初旧快照、更新新快照为目标值
+     * @param other 后续命令
+     * @returns 是否合并成功
+     */
+    merge(other: Command): boolean;
+}

package/dist/core/command/commands/transform-scale-command.d.ts

@@ -0,0 +1,54 @@
+import type { Command } from '../types';
+import type { ItemService } from '../../service';
+import type { Store } from '../../store';
+export type ScaleSnapshot = {
+    position: [number, number];
+    scale: [number, number];
+    rotation: number;
+    width: number;
+    height: number;
+};
+export type TransformScaleCommandArgs = {
+    itemIds: string[];
+    newSnapshots: Map<string, ScaleSnapshot>;
+    itemService: ItemService;
+    store: Store;
+};
+/**
+ * transform.scale - 缩放元素 Command（支持多选）
+ *
+ * execute: 应用新的 position/scale/rotation/size 快照
+ * undo: 恢复到缩放前的快照
+ * redo: 重新应用缩放后的快照
+ * merge: 同一批元素连续缩放合并（保留最初 old，更新 new）
+ */
+export declare class TransformScaleCommand implements Command {
+    readonly id: string;
+    readonly commandId = "transform.scale";
+    private _itemIds;
+    private _newSnapshots;
+    private _oldSnapshots;
+    private _itemService;
+    private _store;
+    /**
+     * 初始化缩放命令，记录目标元素与新旧缩放快照
+     * @param args 命令参数（itemIds、新快照映射、itemService、store）
+     */
+    constructor(args: TransformScaleCommandArgs);
+    /** 返回受影响的元素 ID 列表 */
+    get itemIds(): string[];
+    /** 返回各元素缩放前的原始快照 */
+    get oldSnapshots(): Map<string, ScaleSnapshot>;
+    /** 应用新缩放快照，首次执行时捕获各元素原始 position/scale/rotation/size */
+    execute(): void;
+    /** 撤销缩放，将各元素恢复到原始快照 */
+    undo(): void;
+    /** 重做缩放，重新应用新缩放快照 */
+    redo(): void;
+    /**
+     * 合并连续的同批元素缩放命令，保留最初旧快照、更新新快照为目标值
+     * @param other 后续命令
+     * @returns 是否合并成功
+     */
+    merge(other: Command): boolean;
+}

package/dist/core/command/commands/video-play-command.d.ts

@@ -0,0 +1,28 @@
+import type { Command } from '../types';
+export type VideoPlayCommandArgs = {
+    itemId: string;
+    applyPlay: (itemId: string) => void;
+};
+/**
+ * video.play - 触发视频播放 Command（不入 History）
+ *
+ * execute: 触发指定视频元素的播放
+ * undo/redo: 空操作（播放行为无需撤销）
+ */
+export declare class VideoPlayCommand implements Command {
+    readonly id: string;
+    readonly commandId = "video.play";
+    private _itemId;
+    private _applyPlay;
+    /**
+     * 初始化视频播放命令
+     * @param args 命令参数（itemId、播放回调 applyPlay）
+     */
+    constructor(args: VideoPlayCommandArgs);
+    /** 触发指定视频元素的播放 */
+    execute(): void;
+    /** 空操作：播放行为无需撤销 */
+    undo(): void;
+    /** 空操作：播放行为无需重做 */
+    redo(): void;
+}

package/dist/core/command/commands/video-source-command.d.ts

@@ -0,0 +1,39 @@
+import type { Command } from '../types';
+import type { ItemService } from '../../service';
+import type { Store } from '../../store';
+export type VideoSourceCommandArgs = {
+    itemId: string;
+    newVideoUrl: string;
+    itemService: ItemService;
+    store: Store;
+};
+/**
+ * video.source - 修改 Video 元素视频源 Command
+ *
+ * execute: 将元素视频源替换为新 URL（auto 状态下顺带按新资源原生尺寸收敛）
+ * undo: 恢复旧 URL（auto 状态下顺带按旧资源原生尺寸收敛——尺寸随换源实时算，故 URL 与尺寸原子回退）
+ * redo: 重新应用新 URL
+ *
+ * 对齐 {@link SpriteImageCommand}：换源尺寸由 {@link ItemService.applyAutoSizeByElementAsset}
+ * 在资源就绪后按当前资源实时算，而非命令 snapshot，故 undo/redo 仅回退 URL、尺寸随之自动收敛。
+ */
+export declare class VideoSourceCommand implements Command {
+    readonly id: string;
+    readonly commandId = "video.source";
+    private _itemId;
+    private _newVideoUrl;
+    private _oldVideoUrl;
+    private _itemService;
+    private _store;
+    /**
+     * 构造视频源修改命令，并从 store 中快照旧视频 URL
+     * @param args 命令参数（含元素 id、新视频 URL、ItemService、Store）
+     */
+    constructor(args: VideoSourceCommandArgs);
+    /** 将元素视频源替换为新 URL */
+    execute(): void;
+    /** 恢复旧视频源 */
+    undo(): void;
+    /** 重新应用新视频源 */
+    redo(): void;
+}

package/dist/core/command/commands/viewport-fit-to-box-command.d.ts

@@ -0,0 +1,37 @@
+import type { Box2 } from '@vvfx/gizmo';
+import type { ViewportFitShiftParam } from '../../types';
+import type { Command } from '../types';
+export type ViewportFitToBoxCommandArgs = {
+    box?: Box2;
+    shiftParam?: ViewportFitShiftParam;
+    contentRatio?: number;
+    applyFitToBox: (box?: Box2, shiftParam?: ViewportFitShiftParam) => void;
+};
+/**
+ * viewport.fitToBox - 视图自适应包围盒 Command（不入 History）
+ *
+ * execute: 使目标内容包围盒完整显示在容器中
+ * undo/redo: 空操作（视口操作无需撤销）
+ *
+ * isHistorical=false：视口适配非编辑动作，不进 History（收口在 CommandService._pushToHistory 咽喉）。
+ */
+export declare class ViewportFitToBoxCommand implements Command {
+    readonly id: string;
+    readonly commandId = "viewport.fitToBox";
+    /** 不入 History：视口适配非编辑动作 */
+    readonly isHistorical = false;
+    private _box;
+    private _shiftParam?;
+    private _applyFitToBox;
+    /**
+     * 初始化视图自适应命令
+     * @param args 命令参数（包围盒 box、内边距 shiftParam、放大系数 contentRatio、应用回调 applyFitToBox）
+     */
+    constructor(args: ViewportFitToBoxCommandArgs);
+    /** 使目标内容包围盒完整显示在容器中 */
+    execute(): void;
+    /** 空操作：视口操作无需撤销 */
+    undo(): void;
+    /** 空操作：视口操作无需重做 */
+    redo(): void;
+}

package/dist/core/command/commands/viewport-fit-to-items-command.d.ts

@@ -0,0 +1,43 @@
+import type { ViewportFitShiftParam } from '../../types';
+import type { Command } from '../types';
+export type ViewportFitToItemsCommandArgs = {
+    /** 目标元素 ID 集合；缺省/空数组时聚焦所有元素（由 applyFitToItems 内部兜底） */
+    itemIds?: string[];
+    shiftParam?: ViewportFitShiftParam;
+    /**
+     * 视口适配应用回调：由调用方(wiring)负责按 itemIds 取盒并执行 fitToBox。
+     * - itemIds 未传/为空 → 聚焦所有元素；
+     * - 否则取这些元素的包围盒并集后 fit。
+     * 命令只持有入参，取盒/坐标系换算收口在 wiring（与 ViewportFitToBox 一致：命令不依赖运行时服务）。
+     */
+    applyFitToItems: (itemIds: string[] | undefined, shiftParam?: ViewportFitShiftParam) => void;
+};
+/**
+ * viewport.fitToItems - 按元素 ID 集合自适应视口 Command（不入 History）
+ *
+ * execute: 取指定元素包围盒并集 / 缺省取全部元素，使整体完整显示在容器中
+ * undo/redo: 空操作（视口操作无需撤销）
+ *
+ * isHistorical=false：与 viewport.fitToBox 同属视口适配非编辑动作，不进 History
+ * （收口在 CommandService._pushToHistory 咽喉）。
+ */
+export declare class ViewportFitToItemsCommand implements Command {
+    readonly id: string;
+    readonly commandId = "viewport.fitToItems";
+    /** 不入 History：视口适配非编辑动作 */
+    readonly isHistorical = false;
+    private _itemIds;
+    private _shiftParam?;
+    private _applyFitToItems;
+    /**
+     * 初始化按元素集合自适应命令
+     * @param args 命令参数（元素 ID 集合 itemIds、内边距 shiftParam、应用回调 applyFitToItems）
+     */
+    constructor(args: ViewportFitToItemsCommandArgs);
+    /** 取指定元素包围盒并集（缺省全部元素）后自适应视口 */
+    execute(): void;
+    /** 空操作：视口操作无需撤销 */
+    undo(): void;
+    /** 空操作：视口操作无需重做 */
+    redo(): void;
+}

package/dist/core/command/commands/viewport-move-command.d.ts

@@ -0,0 +1,34 @@
+import type { Command } from '../types';
+export type ViewportMoveCommandArgs = {
+    deltaX: number;
+    deltaY: number;
+    applyMove: (dx: number, dy: number) => void;
+};
+/**
+ * viewport.move - 视图平移 Command（不入 History）
+ *
+ * execute: 按 delta 平移视图
+ * undo/redo: 空操作（视口操作无需撤销）
+ *
+ * isHistorical=false：视口平移非编辑动作，不进 History（收口在 CommandService._pushToHistory 咽喉）。
+ */
+export declare class ViewportMoveCommand implements Command {
+    readonly id: string;
+    readonly commandId = "viewport.move";
+    /** 不入 History：视口平移非编辑动作 */
+    readonly isHistorical = false;
+    private _deltaX;
+    private _deltaY;
+    private _applyMove;
+    /**
+     * 初始化视图平移命令
+     * @param args 命令参数（deltaX、deltaY、平移回调 applyMove）
+     */
+    constructor(args: ViewportMoveCommandArgs);
+    /** 按 delta 平移视图 */
+    execute(): void;
+    /** 空操作：视口操作无需撤销 */
+    undo(): void;
+    /** 空操作：视口操作无需重做 */
+    redo(): void;
+}

package/dist/core/command/commands/viewport-zoom-command.d.ts

@@ -0,0 +1,35 @@
+import { Vector2 } from '@vvfx/gizmo';
+import type { Command } from '../types';
+export type ViewportZoomCommandArgs = {
+    zoomDelta: number;
+    center: Vector2;
+    applyZoom: (zoomDelta: number, center: Vector2) => void;
+};
+/**
+ * viewport.zoom - 视图缩放 Command（不入 History）
+ *
+ * execute: 以指定中心点进行缩放
+ * undo/redo: 空操作（视口操作无需撤销）
+ *
+ * isHistorical=false：视口缩放非编辑动作，不进 History（收口在 CommandService._pushToHistory 咽喉）。
+ */
+export declare class ViewportZoomCommand implements Command {
+    readonly id: string;
+    readonly commandId = "viewport.zoom";
+    /** 不入 History：视口缩放非编辑动作 */
+    readonly isHistorical = false;
+    private _zoomDelta;
+    private _center;
+    private _applyZoom;
+    /**
+     * 初始化视图缩放命令
+     * @param args 命令参数（zoomDelta、center、缩放回调 applyZoom）
+     */
+    constructor(args: ViewportZoomCommandArgs);
+    /** 以指定中心点进行缩放 */
+    execute(): void;
+    /** 空操作：视口操作无需撤销 */
+    undo(): void;
+    /** 空操作：视口操作无需重做 */
+    redo(): void;
+}

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

@@ -0,0 +1,5 @@
+export { CommandService } from './command-service';
+export type { CommandErrorEventHandler } from './command-service';
+export type { Command, CommandFactory, HistoryOperation, CommandPhase, CommandLifecycleEvent } from './types';
+export type { CommandRegistry } from './registry';
+export * from './commands';

package/dist/core/command/registry.d.ts

@@ -0,0 +1,246 @@
+/**
+ * CommandRegistry —— commandId → 工厂入参(args) / 返回 Command 子类(result) 的类型映射表。
+ *
+ * CommandRegistry 用 <b>interface</b> 而非 type alias：interface 是 module augmentation 的硬性前提——
+ * 外部使用者经 `declare module '@vvfx/artis' { interface CommandRegistry {...} }` 合并自定义命令后，
+ * 其命令即获得 execute / registerCommand 两端的强类型推断（commandId 字面量反推 args 对象形状 +
+ * result 类型）。type alias 不支持声明合并。
+ *
+ * 这是 {@link CommandService.execute} / {@link CommandService.registerCommand} / beginInteraction /
+ * updateInteraction 四入口 `<K extends keyof CommandRegistry>` 重载的<b>类型真源</b>：由 commandId
+ * 字面量反推 args 对象形状与 result 类型，使静态调用点获得编译期校验 + IDE 具名提示。
+ *
+ * args 为<b>单参对象</b>（破坏性变更：原为位置参数 `...args: unknown[]`），形状源自各 Command 的
+ * `XxxCommandArgs` 去掉内部依赖（itemService/store/stateManager/gizmoManager/applyXxx 回调等由 wiring
+ * 工厂注入），故工厂体可 spread 透传 `new XxxCommand({ ...args, deps })`，删除原 `args[N] as T` cast 群。
+ *
+ * 无参命令（state.move 等）的 args 为 `Record<string, never>`，调用方传 `{}`（如 `execute('state.move', {})`）。
+ *
+ * <b>外部自定义命令的强类型</b>：经 module augmentation 合并本 interface 即可让命令获得同样两端类型——
+ * ```ts
+ * declare module '@vvfx/artis' {
+ *   interface CommandRegistry {
+ *     'myCmd': { args: { count: number; label: string }; result: MyCmd }
+ *   }
+ * }
+ * artis.command.execute('myCmd', { count: 1, label: 'x' })  // 有具名提示
+ * ```
+ * 未增强的自定义命令命中 string 兜底重载，仍可调用但无静态校验。
+ *
+ * 注意：本表与 {@link ../../artis/wiring/register-commands.ts | registerCommands} 注册集合、
+ * `COMMAND_TARGET_ID_EXTRACTORS`（ignored-interaction 守卫目标 id 提取器）应同源维护；新增命令三处
+ * 都要登记，否则 execute 命中 `unknown` 兜底（静默 drift）。
+ */
+import type { Box2, Vector2, ItemCreateType } from '@vvfx/gizmo';
+import type { ItemCreateCommand, ItemDeleteCommand, ItemTransformCommand, ItemUpdatePropertyCommand, ItemReorderCommand, ItemGroupCommand, ItemUngroupCommand, ItemAlignCommand, ItemDistributeCommand, ItemUpdatePropertyBySchemaCommand, ItemSetFontFamilyCommand, ItemSetGeneratorResourceCommand, SpriteImageCommand, VideoSourceCommand, StateItemCreateCommand, StateMoveCommand, StateHandCommand, StateImageCutCommand, StateImageExpandCommand, StateImageMaskCommand, StateImageTextEditCommand, ItemReplaceSourceCommand, FrameMoveInCommand, FrameMoveOutCommand, FrameLayoutCommand, FrameLayoutModeCommand, SelectionSetCommand, PageAutoLayoutCommand, ViewportMoveCommand, ViewportZoomCommand, ViewportFitToBoxCommand, ViewportFitToItemsCommand, SceneSwitchCommand, ReorderType, TransformData } from './commands';
+import type { ItemSchema, PageAutoLayoutParam, ViewportFitShiftParam, LayoutInfo } from '../types';
+import type { AlignType, DistributeType } from '../../utils/types';
+export interface CommandRegistry {
+    'item.create': {
+        args: {
+            schemas: ItemSchema | ItemSchema[];
+        };
+        result: ItemCreateCommand;
+    };
+    'item.delete': {
+        args: {
+            itemId: string;
+        };
+        result: ItemDeleteCommand;
+    };
+    'item.transform': {
+        args: {
+            itemId: string;
+            newTransform: TransformData;
+        };
+        result: ItemTransformCommand;
+    };
+    'item.updateProperty': {
+        args: {
+            itemId: string;
+            propertyKey: string;
+            newValue: unknown;
+        };
+        result: ItemUpdatePropertyCommand;
+    };
+    'item.reorder': {
+        args: {
+            itemId: string;
+            reorderType: ReorderType;
+        };
+        result: ItemReorderCommand;
+    };
+    'item.group': {
+        args: {
+            childrenIds: string[];
+        };
+        result: ItemGroupCommand;
+    };
+    'item.ungroup': {
+        args: {
+            groupId: string;
+        };
+        result: ItemUngroupCommand;
+    };
+    'item.align': {
+        args: {
+            alignType: AlignType;
+            itemIds: string[];
+        };
+        result: ItemAlignCommand;
+    };
+    'item.distribute': {
+        args: {
+            distributeType: DistributeType;
+            itemIds: string[];
+        };
+        result: ItemDistributeCommand;
+    };
+    'item.updatePropertyBySchema': {
+        args: {
+            schema: ItemSchema | ItemSchema[];
+        };
+        result: ItemUpdatePropertyBySchemaCommand;
+    };
+    'item.setFontFamily': {
+        args: {
+            itemId: string;
+            fontFamily: string;
+            fontUrl?: string;
+        };
+        result: ItemSetFontFamilyCommand;
+    };
+    'item.setGeneratorResource': {
+        args: {
+            itemId: string;
+            resourceUrl: string;
+        };
+        result: ItemSetGeneratorResourceCommand;
+    };
+    'sprite.image': {
+        args: {
+            itemId: string;
+            newImageUrl: string;
+        };
+        result: SpriteImageCommand;
+    };
+    'video.source': {
+        args: {
+            itemId: string;
+            newVideoUrl: string;
+        };
+        result: VideoSourceCommand;
+    };
+    'item.replaceSource': {
+        args: {
+            itemId: string;
+            newUrl: string;
+        };
+        result: ItemReplaceSourceCommand;
+    };
+    'state.move': {
+        args: Record<string, never>;
+        result: StateMoveCommand;
+    };
+    'state.hand': {
+        args: Record<string, never>;
+        result: StateHandCommand;
+    };
+    'state.imageCut': {
+        args: Record<string, never>;
+        result: StateImageCutCommand;
+    };
+    'state.imageExpand': {
+        args: Record<string, never>;
+        result: StateImageExpandCommand;
+    };
+    'state.imageMask': {
+        args: Record<string, never>;
+        result: StateImageMaskCommand;
+    };
+    'state.imageTextEdit': {
+        args: Record<string, never>;
+        result: StateImageTextEditCommand;
+    };
+    'state.itemCreate': {
+        args: {
+            createType?: ItemCreateType;
+        };
+        result: StateItemCreateCommand;
+    };
+    'frame.moveIn': {
+        args: {
+            itemIds: string[];
+            frameId: string;
+        };
+        result: FrameMoveInCommand;
+    };
+    'frame.moveOut': {
+        args: {
+            itemIds: string[];
+            frameId?: string;
+        };
+        result: FrameMoveOutCommand;
+    };
+    'frame.autoLayout': {
+        args: {
+            frameId: string;
+            newLayoutInfos?: Record<string, LayoutInfo>;
+        };
+        result: FrameLayoutCommand;
+    };
+    'frame.layoutMode': {
+        args: {
+            frameId: string;
+            targetMode: 'auto' | 'free';
+        };
+        result: FrameLayoutModeCommand;
+    };
+    'selection.set': {
+        args: {
+            newSelectedIds: string[];
+        };
+        result: SelectionSetCommand;
+    };
+    'page.autoLayout': {
+        args: {
+            param: PageAutoLayoutParam;
+        };
+        result: PageAutoLayoutCommand;
+    };
+    'viewport.zoom': {
+        args: {
+            zoomDelta: number;
+            center?: Vector2;
+        };
+        result: ViewportZoomCommand;
+    };
+    'viewport.move': {
+        args: {
+            deltaX: number;
+            deltaY: number;
+        };
+        result: ViewportMoveCommand;
+    };
+    'viewport.fitToBox': {
+        args: {
+            box?: Box2;
+            shiftParam?: ViewportFitShiftParam;
+            contentRatio?: number;
+        };
+        result: ViewportFitToBoxCommand;
+    };
+    'viewport.fitToItems': {
+        args: {
+            itemIds?: string[];
+            shiftParam?: ViewportFitShiftParam;
+        };
+        result: ViewportFitToItemsCommand;
+    };
+    'scene.switch': {
+        args: {
+            targetIndex: number;
+        };
+        result: SceneSwitchCommand;
+    };
+}