@vvfx/artis 0.0.1-alpha.0

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

@@ -0,0 +1,124 @@
+/**
+ * Command - 指令接口
+ *
+ * 所有涉及数据变换的操作都封装为 Command，支持：
+ * 1. 执行 (execute) - 修改数据并完成回调
+ * 2. 撤销 (undo) - 恢复到执行前的状态
+ * 3. 重做 (redo) - 默认等于再次执行
+ * 4. 交互态合并 (merge) - 连续拖拽时合并为一个 Command，交互结束后再入 History
+ */
+export type Command = {
+    /** Command 唯一标识（如 'item.create_1716000000'） */
+    readonly id: string;
+    /** Command 类型 ID（如 'item.create'） */
+    readonly commandId: string;
+    /**
+     * 是否入历史栈（默认 true 入栈，可 undo/redo）。
+     *
+     * 设为 false 的 Command（如静默资源热替换 `item.replaceSource`）经 CommandService 执行后
+     * 不进入 History——它是资源回流/在线热替换，非用户编辑动作，不该被 undo/redo。
+     * 判断收口在 {@link CommandService._pushToHistory} 咽喉处，所有入史路径（execute/record/batch）
+     * 统一尊重。缺省 true 保持既有命令行为不变。
+     */
+    readonly isHistorical?: boolean;
+    /**
+     * Command 执行时携带的关键参数（可选）。
+     * 各具体 Command 实现可将关键入参赋值到此字段，用于错误上报时携带操作上下文。
+     * 未赋值时默认为空对象，不影响 execute / undo / redo 逻辑。
+     */
+    params?: Record<string, unknown>;
+    /**
+     * 可重放信息（可选，由 CommandService 在入 History 咽喉处统一填充）。
+     * args: 该命令的纯数据重建入参（对象 key-value，JSON-safe）；replayable: 是否完整可重放。
+     * 用于错误上报快照，使复现页能按 commandId + args 正向重放该指令。
+     * 不影响 execute / undo / redo 逻辑。
+     *
+     * args 为**单参对象**（破坏性变更：原按位置数组）；与命令对外 args 形状同源（同一组具名字段），
+     * 由 {@link ./registry.ts | CommandRegistry} 经重载反推类型。对象 key 比位置数组更适合 replay
+     * 收集/解构（无下标约定耦合）。
+     */
+    replay?: {
+        args: Record<string, unknown>;
+        replayable: boolean;
+    };
+    /**
+     * 外部事件 payload（可选，纯数据，由各 Command 在 execute 时自填）。
+     *
+     * 供 {@link CommandService.onCommandLifecycle} 中央监听统一读取：undo/redo 时调用方
+     * 工厂已退场，只有实例上的 payload 可读。各 Command 视需要填充业务上下文（如 itemId/
+     * propertyKey/newValue/oldValue）；未填则 lifecycle 事件 payload 为 undefined，不影响
+     * execute/undo/redo 逻辑。纯数据（不含服务引用/函数），可随 replay 序列化。
+     */
+    eventPayload?: Record<string, unknown>;
+    /**
+     * 命令自序列化为可重放入参（可选）。
+     *
+     * 各 Command 可视情况实现：返回**纯数据**重建入参（不含 ItemService/Store 等服务引用），
+     * 由 CommandService 在统一咽喉（history.push）处调用并缓存到 {@link replay}。
+     * 未实现时该命令在快照中标 replayable=false（复现页跳过执行，仅展示上报时态）。
+     *
+     * 注意：含函数入参（如 viewport.zoom 的 applyZoom）或非 JSON-safe 类实例的命令
+     * 应返回 replayable=false，避免重放时崩在方法丢失上。
+     */
+    serializeReplay?(): {
+        args: Record<string, unknown>;
+        replayable: boolean;
+    };
+    /** 执行数据修改 */
+    execute(): void;
+    /** 撤销操作，恢复数据到执行前 */
+    undo(): void;
+    /** 重做操作，默认实现等于 execute */
+    redo(): void;
+    /**
+     * 交互态合并：判断是否可以与另一个同类型 Command 合并
+     * 返回 true 表示成功合并（当前 Command 已吸收 other 的变更）
+     *
+     * @param other 待合并的另一 Command
+     * @returns 是否合并成功
+     */
+    merge?(other: Command): boolean;
+};
+/**
+ * CommandFactory - Command 工厂函数
+ * 注册时提供，执行时由 CommandService 调用来创建 Command 实例
+ *
+ * 入参为<b>单参对象</b>（破坏性变更：原位置数组 `...args: unknown[]`）。泛型 `A` 即命令对外暴露的
+ * 入参对象形状，由 {@link ./registry.ts | CommandRegistry} 经 `registerCommand`/`execute` 四入口
+ * 重载反推；外部自定义命令可经 `registerCommand<A>` 显式/隐式填充，缺省 `unknown`。工厂体可
+ * spread 透传 `new XxxCommand({ ...args, deps })`。
+ */
+export type CommandFactory<A = unknown> = (args: A) => Command;
+/**
+ * 历史记录操作方向
+ *
+ * - undo / redo / push 携带对应 Command（push 为刚入栈的命令）
+ * - session（pushSession/popSession 栈切换）/ clear（清空）无具体 Command，command 缺省
+ */
+export type HistoryOperation = {
+    type: 'push' | 'undo' | 'redo' | 'session' | 'clear';
+    command?: Command;
+};
+/**
+ * Command 生命周期事件触发时机（中央监听）。
+ *
+ * - execute：命令正向执行（含 batch endBatch 聚合后的代表命令）
+ * - undo：历史撤销
+ * - redo：历史重做
+ */
+export type CommandPhase = 'execute' | 'undo' | 'redo';
+/**
+ * Command 生命周期事件（由 {@link CommandService.onCommandLifecycle} 统一发出）。
+ *
+ * 横切订阅（埋点/自动保存/UI 刷新触发）经此一处即可覆盖 execute/undo/redo 全生命周期，
+ * 不必分别订阅 afterExecute(execute 侧) 与 history.setOnChange(undo/redo 侧)。
+ *
+ * - phase：触发时机
+ * - command：来源 Command 实例（undo/redo 时为 history 持有的同一实例）
+ * - payload：Command 自填的 {@link Command.eventPayload}，未填则 undefined
+ */
+export type CommandLifecycleEvent = {
+    phase: CommandPhase;
+    command: Command;
+    payload?: Record<string, unknown>;
+};

package/dist/core/element-registry/element-facade.d.ts

@@ -0,0 +1,35 @@
+import type { ArtisItem } from '../item';
+import type { ItemSchema } from '../types';
+import type { ItemService } from '../service';
+/**
+ * artis.element 对外门面（决策 D3/D4）
+ *
+ * 对外统一入口：所有入参/出参仅见元素ID（D4），**不暴露 vfxItemId**。
+ * 内部委托 ItemService 既有方法，不重写 CRUD——门面只做「按元素ID 的稳定入口 + 委托」。
+ *
+ * 与 {@link ItemService} 的区别：ItemService 是底层服务（含 vfxItemId 等内部细节），
+ * 本门面只暴露以元素ID 为语义的稳定 API，供业务侧使用。
+ */
+export declare class ElementFacade {
+    private readonly _itemService;
+    constructor(itemService: ItemService);
+    /** 按元素ID 取 ArtisItem；不存在时返回 undefined */
+    get(id: string): ArtisItem | undefined;
+    /** 批量按元素ID 取 ArtisItem；跳过不存在的 id */
+    getMany(ids: string[]): ArtisItem[];
+    /** 批量取 Schema（落盘只含元素ID，不含 vfxItemId——D2）；ids 缺省取全部 */
+    getSchemas(ids?: string[]): ItemSchema[];
+    /** 元素ID 是否已占用（创建前预检） */
+    exists(id: string): boolean;
+    /** 按元素ID 预检查重（决策 D1）：冲突抛 DuplicateElementIdError 带 suggestedId */
+    assertUnique(id: string): void;
+    /**
+     * 创建元素，冲突时透传 DuplicateElementIdError（error.suggestedId 可用于重试）。
+     * 返回新建元素的元素ID（D4：对外只见元素ID）。
+     */
+    create(schema: ItemSchema): Promise<string>;
+    /** 批量按 Schema 改属性，返回成功改动的元素ID 列表 */
+    updateMany(schemas: ItemSchema[]): Promise<string[]>;
+    /** 单个按 Schema 改属性（updateMany 的单元素便捷入口） */
+    updateById(schema: ItemSchema): Promise<string[]>;
+}

package/dist/core/element-registry/element-identity-strategy.d.ts

@@ -0,0 +1,75 @@
+import type { VFXItem } from '../../shared';
+import { ElementRegistry } from './element-registry';
+/**
+ * 元素身份策略（统一承载「id 基准」与「registry 映射」两个共变决策）
+ *
+ * - **id 基准**（B）：{@link resolveItemId} 决定 artisItem.id 取自 schemaId 还是
+ *   Player 维度的 vfxItem.instanceId。Artis 取 schemaId（与 vfxItemId 分离，走映射）；
+ *   SceneArtis 取 instanceId（id===vfxItemId，无需映射）。
+ * - **registry 映射**（ii）：register/unregister/vfxItemIdOf/elementIdOf/assertUnique/clear
+ *   委托给具体实现。Artis 走真实 {@link ElementRegistry}；SceneArtis 走 identity（空转）。
+ *
+ * 二者合并为单一策略，避免 ItemService 协调两个独立注入点。
+ */
+export type ElementIdentityStrategy = {
+    /**
+     * 决定新建元素的 artisItem.id。
+     * @param schemaId 来自 ItemSchema.id（或 generateGUID 兜底）
+     * @param vfxItem  已创建的 Player 维度 VFXItem（其 instanceId 即 vfxItemId）
+     * @returns 实际写入 artisItem.id 的值
+     */
+    resolveItemId(schemaId: string, vfxItem: VFXItem): string;
+    /** 注册 elementId ↔ vfxItemId 映射（创建时调用） */
+    registerMapping(elementId: string, vfxItemId: string): void;
+    /** 注销元素映射（删除时调用） */
+    unregister(elementId: string): void;
+    /** 元素ID → vfxItemId；未注册返回 undefined（调用方兜底原值） */
+    vfxItemIdOf(elementId: string): string | undefined;
+    /** vfxItemId → 元素ID（反向同步翻译用）；未注册返回 undefined */
+    elementIdOf(vfxItemId: string): string | undefined;
+    /** 元素ID 查重；命中抛 DuplicateElementIdError（携带 suggestedId） */
+    assertUnique(elementId: string): void;
+    /** 清空所有映射（场景重建/销毁时） */
+    clear(): void;
+};
+/**
+ * 基于真实 {@link ElementRegistry} 的策略（Artis 用）
+ *
+ * - `resolveItemId` 直返 schemaId：artisItem.id(schemaId) ≠ vfxItemId(instanceId)，
+ *   二者分离，靠 registry 翻译。遵守 D2（不 setInstanceId，artis 只读 instanceId）。
+ * - 其余委托内部 registry。
+ */
+export declare class RegistryIdentityStrategy implements ElementIdentityStrategy {
+    /** 内部 registry（Artis 唯一映射真源） */
+    readonly registry: ElementRegistry;
+    constructor(registry: ElementRegistry);
+    resolveItemId(schemaId: string, _vfxItem: VFXItem): string;
+    registerMapping(elementId: string, vfxItemId: string): void;
+    unregister(elementId: string): void;
+    vfxItemIdOf(elementId: string): string | undefined;
+    elementIdOf(vfxItemId: string): string | undefined;
+    assertUnique(elementId: string): void;
+    clear(): void;
+}
+/**
+ * identity 策略（SceneArtis 用，B：以 VFXItemId 为基准）
+ *
+ * - `resolveItemId` 返回 `vfxItem.getInstanceId()`：artisItem.id 跟随 Player 分配的 instanceId，
+ *   即 id === vfxItemId === instanceId 全程成立，无需映射表。
+ * - `vfxItemIdOf`/`elementIdOf` 返回原值（identity）：findPlayerItemById 的 `?? id` fallback
+ *   直接命中（id 即 instanceId）。
+ * - `assertUnique`/`registerMapping`/`unregister`/`clear` 全空转：id 由 Player 分配，
+ *   无 artis 侧查重需求；映射自洽无需维护。
+ *
+ * SceneArtis 加载（assemble 取 getInstanceId 当 id）/恢复（JSONScene 重载 instanceId 复生）
+ * 路径本就 id===instanceId；会话内 createItem 经 resolveItemId 亦对齐 instanceId，全程一致。
+ */
+export declare class IdentityStrategy implements ElementIdentityStrategy {
+    resolveItemId(_schemaId: string, vfxItem: VFXItem): string;
+    registerMapping(_elementId: string, _vfxItemId: string): void;
+    unregister(_elementId: string): void;
+    vfxItemIdOf(elementId: string): string | undefined;
+    elementIdOf(vfxItemId: string): string | undefined;
+    assertUnique(_elementId: string): void;
+    clear(): void;
+}

package/dist/core/element-registry/element-registry.d.ts

@@ -0,0 +1,72 @@
+import { VFXItem } from '../../shared';
+import type { ElementRegistryDeps } from './types';
+/**
+ * 元素注册表错误码（字符串值 enum，作为对外 error.code 契约）
+ */
+export declare enum ElementRegistryErrorCode {
+    DUPLICATE_ELEMENT_ID = "DUPLICATE_ELEMENT_ID"
+}
+/**
+ * 元素ID 重复错误（决策 D1）
+ *
+ * 创建元素时命中已存在的元素ID 即抛此错。错误对象携带：
+ * - conflictId：冲突的元素ID（即调用方传入的 id）
+ * - suggestedId：一个全新的可用候选 GUID，调用方可拿它重试
+ *
+ * **不自动改名、不创建**——只"抛错 + 告知候选"，由调用方决定是否重试。
+ */
+export declare class DuplicateElementIdError extends Error {
+    readonly code = ElementRegistryErrorCode.DUPLICATE_ELEMENT_ID;
+    /** 冲突的元素ID（即调用方传入的 id） */
+    readonly conflictId: string;
+    /** 全新可用的候选元素ID（generateGUID 生成，保证不与已注册元素冲突） */
+    readonly suggestedId: string;
+    constructor(conflictId: string, suggestedId: string);
+}
+/**
+ * 元素注册表（决策 D3：独立模块）
+ *
+ * 维护「用户可读元素ID ↔ Player 维度 VFXItem id」的双向映射：
+ * - 元素ID：用户可见、全局唯一、随 Schema 落盘
+ * - vfxItemId：Player GUID，**仅运行时、不落盘**（D2）；重建/重载时重新生成
+ *
+ * 本模块只负责「映射 + 查重 + 翻译」，CRUD 委托 ItemService，不重写。
+ */
+export declare class ElementRegistry {
+    /** elementId → vfxItemId */
+    private readonly _map;
+    /** vfxItemId → elementId（反向查，反向同步翻译用） */
+    private readonly _reverse;
+    private readonly _deps;
+    constructor(deps?: ElementRegistryDeps);
+    /**
+     * 注册一对 elementId ↔ vfxItemId（创建时调用）
+     * 重复注册同一元素ID 会覆盖旧映射（创建链路应先 assertUnique 拦截）
+     */
+    register(elementId: string, vfxItemId: string): void;
+    /** 注销元素（删除时调用） */
+    unregister(elementId: string): void;
+    /** 清空所有映射（场景重建/销毁时） */
+    clear(): void;
+    /**
+     * 查重（决策 D1）：元素ID 未占用 → 正常返回；命中 → 抛 DuplicateElementIdError
+     *
+     * 抛出的错误携带 suggestedId（一个不与现有元素ID 冲突的全新 GUID），供调用方重试。
+     */
+    assertUnique(elementId: string): void;
+    /** 元素ID → vfxItemId */
+    vfxItemIdOf(elementId: string): string | undefined;
+    /** vfxItemId → 元素ID（反向，反向同步翻译用） */
+    elementIdOf(vfxItemId: string): string | undefined;
+    /** 元素ID 是否已注册（创建前预检） */
+    has(elementId: string): boolean;
+    /**
+     * 翻译并解析 VFXItem（元素ID → vfxItemId → VFXItem）
+     * 依赖构造时注入的 resolveVfxItemById 回调；未注入或元素未注册时返回 undefined
+     */
+    resolveVFXItem(elementId: string): VFXItem | undefined;
+    /** 获取只读映射（调试/快照用） */
+    getAll(): ReadonlyMap<string, string>;
+    /** 已注册元素数量 */
+    get size(): number;
+}

package/dist/core/element-registry/index.d.ts

@@ -0,0 +1,5 @@
+export { ElementRegistry, DuplicateElementIdError, ElementRegistryErrorCode } from './element-registry';
+export type { ElementRegistryDeps } from './types';
+export { ElementFacade } from './element-facade';
+export { RegistryIdentityStrategy, IdentityStrategy } from './element-identity-strategy';
+export type { ElementIdentityStrategy } from './element-identity-strategy';

package/dist/core/element-registry/types.d.ts

@@ -0,0 +1,15 @@
+import type { VFXItem } from '../../shared';
+/**
+ * 元素注册表运行时依赖（构造注入，走回调避开与 ItemService 的循环依赖）
+ */
+export type ElementRegistryDeps = {
+    /**
+     * 按 vfxItemId 查 VFXItem。由 ItemService 注入（回调解耦，不持有 player 引用）。
+     * 可选——缺省时 resolveVFXItem 永远返回 undefined。
+     */
+    resolveVfxItemById?: (vfxItemId: string) => VFXItem | undefined;
+    /**
+     * 查重冲突时生成候选元素ID。默认 generateGUID；可注入 mock 便于单测。
+     */
+    generateId?: () => string;
+};

package/dist/core/gizmo/gizmo-bootstrap.d.ts

@@ -0,0 +1,70 @@
+import type { GestureHandler } from '@vvfx/gizmo';
+import type { CommandBindingContext, GizmoBridgeEvent, GizmoBridgeEventArgs } from './gizmo-command-binder';
+import { ItemService } from '../service';
+import type { ViewService, InteractionService } from '../service';
+import type { Store } from '../store';
+import type { CommandService } from '../command';
+/**
+ * GizmoBootstrap 装配所需的最小上下文。
+ *
+ * 核心服务由 BaseArtis 直接注入（commandService / store / itemService / viewService /
+ * interactionService），元素创建由 Command 绑定直接完成；
+ * emitGizmoEvent 委托到 BaseArtis._handleGizmoEvent，统一转发到 Artis 事件系统。
+ */
+export type GizmoBootstrapContext = {
+    readonly commandService: CommandService;
+    readonly store: Store;
+    readonly itemService: ItemService;
+    readonly viewService: ViewService;
+    readonly interactionService: InteractionService;
+    readonly gestureHandler: GestureHandler;
+    readonly enterMoveState: () => void;
+    readonly notifyItemCreated: CommandBindingContext['notifyItemCreated'];
+    emitGizmoEvent<K extends GizmoBridgeEvent>(event: K, ...args: GizmoBridgeEventArgs<K>): void;
+};
+/**
+ * GizmoBootstrap - Gizmo 子系统装配协作者。
+ *
+ * 从 BaseArtis 抽离，统一承载 GizmoCommandBinder、GestureHandler 事件转发
+ * 与 Resize Gizmo 视口配置同步。
+ *
+ * 装配幂等：assemble() 第二次调用起跳过装配分支（与原 initGizmo 守卫语义一致）。
+ */
+export declare class GizmoBootstrap {
+    private readonly ctx;
+    private _assembled;
+    private _binder?;
+    /** Hand 平移行为 action 订阅解绑函数 */
+    private _viewportNavigationOff?;
+    /** Resize Gizmo 视口配置同步解绑函数。 */
+    private _viewServiceOff?;
+    /** Command 之外的 GestureHandler 事件转发解绑函数。 */
+    private _eventOffs;
+    constructor(ctx: GizmoBootstrapContext);
+    /**
+     * 装配 Gizmo 子系统并触发 Gizmo 实例创建。
+     *
+     * 幂等：二次调用直接返回（仅靠调用方先刷新 InteractionService 数据）。
+     */
+    assemble(): void;
+    /**
+     * 视口导航 action 同步：把 GestureHandler 派发的 scale/center/translation 写入
+     * ViewService 与 InteractionService。从原数据适配器 setViewParam 内联移入——
+     * gizmo 包不依赖 InteractionService/ViewService，故由本装配层落地。
+     */
+    private setViewParam;
+    /**
+     * 构建 Command 绑定上下文（供 GizmoCommandBinder 调用绑定工厂时使用）。
+     *
+     * 核心服务由装配上下文直接透传，emit 委托 emitGizmoEvent →
+     * BaseArtis._handleGizmoEvent 转发到 Artis 事件系统。
+     *
+     * @returns 当前装配上下文构造出的 Command 绑定上下文对象
+     */
+    private createCommandBindingContext;
+    /**
+     * 销毁 Gizmo 子系统的统一 Action 订阅与事件转发订阅。
+     * 未装配时为空操作。
+     */
+    dispose(): void;
+}

package/dist/core/gizmo/gizmo-command-binder.d.ts

@@ -0,0 +1,55 @@
+import type { Box2, GestureHandler, GizmoActionEvent, GizmoFrameRefreshChildrenEvent, GizmoPlacementChangeEvent, Selection } from '@vvfx/gizmo';
+import type { CommandService } from '../command';
+import type { ItemService } from '../service';
+import type { Store } from '../store';
+import type { BaseArtisEvents } from '../types/artis-events';
+type GizmoBridgeEvents = BaseArtisEvents & {
+    'picture-cut.change': [info: {
+        box: Box2;
+    }];
+    'picture-expand.change': [info: {
+        box: Box2;
+    }];
+};
+/** Services available to command-side Gizmo action handlers. */
+export type CommandBindingContext = {
+    selection: Selection;
+    commandService: CommandService;
+    itemService: ItemService;
+    store: Store;
+    emit: <K extends GizmoBridgeEvent>(event: K, ...args: GizmoBridgeEventArgs<K>) => void;
+    /** 元素已由绑定层创建后，仅向 SDK 使用方派发完成事件。 */
+    notifyItemCreated: (info: BaseArtisEvents['item.create'][0]) => void;
+    /** Text / Frame 创建完成后切回默认选择工具。 */
+    enterMoveState: () => void;
+    /** Text 实时创建首帧后进入当前单选文字的编辑态。 */
+    beginCreatedTextEditing: () => void;
+    /** 实时创建 Text 被取消时退出对应编辑态。 */
+    finishCreatedTextEditing: () => void;
+};
+export type GizmoBridgeEvent = 'item.create' | 'item.dragstart' | 'item.drag' | 'item.dragend' | 'item.propertychange' | 'loading.change' | 'spritetext.click' | 'text.input' | 'video.play' | 'picture-cut.change' | 'picture-expand.change';
+export type GizmoBridgeEventArgs<K extends GizmoBridgeEvent> = GizmoBridgeEvents[K];
+/** Command behavior for one Gizmo type on the unified GestureHandler action stream. */
+export type CommandActionBinding = {
+    actionstart?: (event: GizmoActionEvent) => void;
+    actionupdate?: (event: GizmoActionEvent) => void;
+    actioncommit?: (event: GizmoActionEvent) => void;
+    placementchange?: (event: GizmoPlacementChangeEvent) => void;
+    framerefreshchildren?: (event: GizmoFrameRefreshChildrenEvent) => void;
+    dispose?: () => void;
+};
+/** Creates one long-lived command handler for a Gizmo type. */
+export type CommandBindingFactory = (context: CommandBindingContext) => CommandActionBinding;
+/**
+ * Routes the single GestureHandler action stream to command handlers by semantic Gizmo type.
+ * It never subscribes to concrete Gizmo instances and is therefore independent of graph rebuilds.
+ */
+export declare class GizmoCommandBinder {
+    private readonly _contextProvider;
+    private readonly _bindings;
+    private readonly _offs;
+    constructor(gestureHandler: GestureHandler, _contextProvider: () => CommandBindingContext);
+    register(type: string, factory: CommandBindingFactory): void;
+    dispose(): void;
+}
+export {};

package/dist/core/gizmo/gizmo-config-override.d.ts

@@ -0,0 +1,24 @@
+import type { AnyConfigDefinition, ConfigValue, GizmoManager } from '@vvfx/gizmo';
+/**
+ * 一条 Gizmo 配置初始化覆盖：[配置定义, 要合并的部分值]。
+ *
+ * 供 {@link "artis/types".ArtisOptions.gizmoConfigs} 在构造期一次性注入产品级 Gizmo 默认配置
+ * （线宽/颜色/笔刷/遮罩开关等）。config 定义本身（token 与默认值）仍由 `@vvfx/gizmo` 提供
+ * （见 `builtin-configs`，如 `maskConfig`、`viewportOverlayConfig`）；本模块只负责把
+ * 「token + partial」打包成元组，属 Artis 初始化入参形状，非 Gizmo 核心能力，故归置于 Artis 侧。
+ */
+export type GizmoConfigOverride<D extends AnyConfigDefinition = AnyConfigDefinition> = readonly [definition: D, partial: Partial<ConfigValue<D>>];
+/**
+ * 构造一条 Gizmo 配置初始化覆盖，供 `ArtisOptions.gizmoConfigs` 在构造期一次性注入。
+ * 调用点对 partial 的键/值类型依 definition 推断并校验，例如：
+ * ```ts
+ * gizmoConfig(maskConfig, { brushSize: 30 })
+ * ```
+ */
+export declare function gizmoConfig<D extends AnyConfigDefinition>(definition: D, partial: Partial<ConfigValue<D>>): GizmoConfigOverride<D>;
+/**
+ * 把宿主声明的 Gizmo 配置初始化覆盖逐条合并进 ConfigManager。
+ * 复用 `ConfigManager.set` 的默认合并 / 校验 / 事件语义；无 overrides 时为 no-op。
+ * 引擎无关纯函数，供构造器与单测共用（避免把「可测性」泄漏成 BaseArtis 的公开方法）。
+ */
+export declare function applyGizmoConfigs(gizmoManager: GizmoManager, overrides?: readonly GizmoConfigOverride[]): void;

package/dist/core/gizmo/gizmo-registry.d.ts

@@ -0,0 +1,39 @@
+import type { Gizmo, GizmoOwner } from '@vvfx/gizmo';
+import type { BaseState } from '../state';
+import type { StateId } from '../state';
+export type GizmoRegistrationId = string & {};
+export declare enum BuiltinGizmoId {
+    HAND = "hand",
+    ICON = "icon",
+    LOADING = "loading",
+    VIEWPORT_OVERLAY = "viewport-overlay",
+    READONLY_SELECTION = "readonly-selection",
+    PICTURE_CUT = "picture-cut",
+    PICTURE_EXPAND = "picture-expand",
+    SPRITE_TEXT_EDIT = "sprite-text-edit",
+    MASK = "mask",
+    ITEM_CREATE = "item-create"
+}
+export type GizmoFactoryContext = {
+    readonly owner: GizmoOwner;
+    readonly state: BaseState;
+    readonly registry: GizmoRegistry;
+};
+export type RegisteredGizmoFactory = (context: GizmoFactoryContext) => Gizmo | readonly Gizmo[];
+export type StateGizmoBinding = GizmoRegistrationId | RegisteredGizmoFactory;
+export type GizmoRegistryOptions = {
+    readonly onReplace?: (id: GizmoRegistrationId) => void;
+};
+/** Artis-owned registry used by extension states to compose ordered Gizmo sets. */
+export declare class GizmoRegistry {
+    private readonly _options;
+    private readonly _factories;
+    private readonly _consumers;
+    constructor(_options?: GizmoRegistryOptions);
+    register(id: GizmoRegistrationId, factory: RegisteredGizmoFactory): void;
+    replace(id: GizmoRegistrationId, factory: RegisteredGizmoFactory): void;
+    unregister(id: GizmoRegistrationId): void;
+    has(id: GizmoRegistrationId): boolean;
+    getConsumers(id: GizmoRegistrationId): readonly StateId[];
+    createSet(bindings: readonly StateGizmoBinding[], owner: GizmoOwner, state: BaseState): Gizmo[];
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Gizmo 子系统（core/gizmo）
+ *
+ * Frame data is owned by FrameManager; this layer only bridges commands, selection, and Artis services.
+ * Command 绑定（GizmoCommandBinder）与宿主 State 交互图装配（GizmoBootstrap）。
+ *
+ * 设计：本模块属于编辑器核心，不依赖 GestureHandler（手势事件层），后者注入消费本模块。
+ * gizmo 与宿主（GestureHandler）经 GizmoOwner 接口契约通信——GestureHandler 实现 GizmoOwner，
+ * State 创建 gizmo 时把 owner 与 Gizmo 依赖显式传入构造；共享态由 GestureHandler 与 FrameManager 持有，
+ * 输入态由 GestureHandler 持有，gizmo 经 owner 统一读取，不再有"数据袋子" ctx。
+ */
+export { GizmoCommandBinder } from './gizmo-command-binder';
+export type { CommandBindingContext, CommandBindingFactory, CommandActionBinding, GizmoBridgeEvent, GizmoBridgeEventArgs, } from './gizmo-command-binder';
+export { GizmoBootstrap } from './gizmo-bootstrap';
+export type { GizmoBootstrapContext } from './gizmo-bootstrap';
+export { BuiltinGizmoId, GizmoRegistry } from './gizmo-registry';
+export type { GizmoFactoryContext, GizmoRegistrationId, RegisteredGizmoFactory, StateGizmoBinding, } from './gizmo-registry';
+export { gizmoConfig, applyGizmoConfigs } from './gizmo-config-override';
+export type { GizmoConfigOverride } from './gizmo-config-override';

package/dist/core/gizmo/register-gizmo-command-bindings.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Gizmo Command 绑定注册
+ *
+ * 本文件将各 Gizmo 的 Command 绑定逻辑从 Gizmo 类中抽离，
+ * 集中到 Artis 层注册，使得 Gizmo 包不依赖任何 Artis 内部类型。
+ *
+ * 各 Gizmo 只负责发事件，Artis 层通过 GizmoCommandBinder.register 注册绑定工厂。
+ */
+import { type CommandBindingFactory, type GizmoCommandBinder } from './index';
+export declare const registerResizeSelectionCommandBinding: CommandBindingFactory;
+export declare const registerCornerRotationCommandBinding: CommandBindingFactory;
+export declare const registerMoveSelectionCommandBinding: CommandBindingFactory;
+/**
+ * 固定宽度 Text 的首个有效拖拽立即 beginInteraction 创建真实元素并进入编辑态，
+ * 后续帧更新同一命令，mouseup 只把最终 schema 入 History。Frame 与纯点击在 commit 创建一次。
+ */
+export declare const createItemCreateCommandBinding: CommandBindingFactory;
+/** Bind point and box selection commits to Artis history. */
+export declare const registerSelectionGizmoCommandBinding: CommandBindingFactory;
+export declare function registerBuiltinCommandBindings(binder: GizmoCommandBinder): void;

package/dist/core/gizmo/state-gizmo-controller.d.ts

@@ -0,0 +1,20 @@
+import type { GestureHandler } from '@vvfx/gizmo';
+import { ItemCreateType } from '@vvfx/gizmo';
+import type { BaseState } from '../state';
+import type { StateTransitionRuntime } from '../state/types';
+import { GizmoRegistry } from './gizmo-registry';
+/** Converts the active Artis State into an ordered GizmoTool runtime projection. */
+export declare class StateGizmoController implements StateTransitionRuntime {
+    private readonly _gestureHandler;
+    readonly registry: GizmoRegistry;
+    private _itemCreateType;
+    constructor(_gestureHandler: GestureHandler, registry: GizmoRegistry);
+    get itemCreateType(): ItemCreateType;
+    set itemCreateType(value: ItemCreateType);
+    apply(state: BaseState): void;
+    reapply(state: BaseState): void;
+    registerState(state: BaseState): void;
+    unregisterState(state: BaseState): void;
+    private _createGizmoTool;
+    private _registerBuiltins;
+}