@vvfx/artis 0.0.1-alpha.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT LICENSE
+
+Copyright (c) 2019-present Ant Group Co., Ltd. https://www.antgroup.com/
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/artis/artis.d.ts

@@ -0,0 +1,44 @@
+import { BaseArtis } from './base-artis';
+import { ElementFacade } from '../core';
+import type { ArtisItem } from '../core/item';
+import type { VariantErrorSnapshot } from '../core';
+import type { ArtisEvents, ArtisOptions } from './types';
+/**
+ * Artis - 编辑数据驱动的编辑器
+ *
+ * 继承 {@link BaseArtis}，数据层以编辑场景数据（InitArtisData / ArtisItem[]）为真源，
+ * 生命周期与核心服务装配由基类承担，本类仅声明编辑数据契约。
+ *
+ * 与 SceneArtis 的身份策略差异：Artis 沿用基类默认的 RegistryIdentityStrategy——
+ * artisItem.id(schemaId) ≠ vfxItemId(instanceId)，靠 registry 翻译（D2）。
+ * 故 `artis.element` 门面仅 Artis 暴露（SceneArtis 以 instanceId 为基准，无需该门面）。
+ *
+ * 顶层操作门面 `artis.operations`（addSprite / deleteItem / 截图 / 导出 / gizmo 开关 …）由基类
+ * {@link BaseArtis.operations} getter 提供，Artis 直接继承使用，无需本类再次声明。
+ */
+export declare class Artis extends BaseArtis<unknown, ArtisEvents> {
+    /** artis.element 对外门面（D3/D4：按元素ID 的统一入口，懒初始化） */
+    private _elementFacade?;
+    /**
+     * @override Artis 专属错误快照：场景所有元素(ItemSchema) + 当前选中元素(激活数据)，
+     * 与 variant: 'Artis' tag 绑定返回。上报时由 ErrorMonitor 合并到共有快照。
+     * 取值异常不阻断（兜底空数组）。
+     */
+    protected _captureErrorSnapshot(): VariantErrorSnapshot;
+    /**
+     * 当前激活场景的编辑元素集合（编辑数据驱动：即 store.items）
+     */
+    protected _getActiveItems(): ArtisItem[];
+    /** context-lost 重建工厂：new 同类型 Artis 实例 */
+    protected _createInstance(container: HTMLElement, options: ArtisOptions): Artis;
+    /**
+     * 命名空间：元素（artis.element）
+     *
+     * 决策 D3/D4：独立于 `artis.item` 的对外门面，所有入参/出参仅见元素ID，不暴露 vfxItemId。
+     * 委托 ItemService 既有实现，不重写 CRUD。懒初始化。
+     *
+     * 仅 Artis 暴露：Artis 的 artisItem.id 与 vfxItemId 分离，需门面按元素ID 收口；
+     * SceneArtis 以 instanceId 为基准（id===vfxItemId），不暴露此门面。
+     */
+    get element(): ElementFacade;
+}

package/dist/artis/base-artis.d.ts

@@ -0,0 +1,520 @@
+import { Operations } from './operations/operations';
+import { EventEmitter, Player } from '../shared';
+import { ViewService, ItemService, GizmoRegistry, StateManager, HistoryManager, CommandService, ArtisBackgroundConfig, UserPreferencesManager, type ArtisItem, type Disposable, type BaseArtisEvents, type PerfMonitorCallback, type ErrorMonitorCallback, type ElementIdentityStrategy, type StabilityMonitorCallback, type StateChangeEvent } from '../core';
+import { HTMLCardService } from '../helper/html-overlay';
+import { ScreenshotService } from './screenshot-service';
+import type { Selection, FrameManager, TextEditActivation } from '@vvfx/gizmo';
+import { Vector2, GizmoManager } from '@vvfx/gizmo';
+import { ArtisOptions, ContextRecoveryOptions } from './types';
+import type { KeyBindingController } from '../core/keybinding/key-binding-controller';
+/**
+ * BaseArtis - 编辑器核心基类
+ *
+ * 承载与数据来源无关的核心服务装配与生命周期模板方法：
+ * Renderer / PlayerAdapter / ItemService / CommandService / HistoryManager /
+ * AssetManager / PluginSystem / UserPreferences / ViewService /
+ * InteractionService / GestureHandler / StateManager / ScreenshotService。
+ * 选中态（Selection）由 GestureHandler 持有，经 gestureHandler.getSelection() 暴露。
+ *
+ * 子类（如编辑数据驱动的 Artis、JSON 驱动的 SceneArtis）继承本类，
+ * 仅差异在数据层（_getActiveItems）与初始化流程（_loadSceneData），
+ * 以及编辑守卫策略（_assertEditable）。
+ *
+ * 设计原则：
+ * 1. 事件采用 extends EventEmitter 模式（与 Store / StateManager 一致）
+ * 2. 所有数据修改通过 CommandService 驱动
+ * 3. 插件化架构，功能可插拔
+ * 4. 支持模式扩展（继承派生 InfiniteArtis / SceneArtis 等）
+ */
+/**
+ * 命令层「忽略交互」拒绝错误。
+ *
+ * 当通过 commandService 对命中 ignoredInteractionNames 名称的元素执行修改类命令时，
+ * 由 {@link BaseArtis._installIgnoredInteractionGuard} 注入的守卫抛出，表示该元素被配置为
+ * 忽略交互（不可更改）。`code` 为对外错误契约。
+ */
+export declare class IgnoredInteractionError extends Error {
+    readonly code: "IGNORED_INTERACTION";
+    /** 被拒绝的命令 ID */
+    readonly commandId: string;
+    /** 被拒绝操作的目标元素 ID */
+    readonly itemId: string;
+    /** 命中忽略名单的元素名称 */
+    readonly itemName: string;
+    constructor(commandId: string, itemId: string, itemName: string);
+}
+export declare abstract class BaseArtis<TRunInput = unknown, TEvents extends BaseArtisEvents = BaseArtisEvents> extends EventEmitter<TEvents> implements Disposable {
+    /** State 注册、查询、切换和临时状态栈的唯一公开入口。 */
+    readonly states: StateManager;
+    /** 二开 Gizmo 工厂注册表；未直接提供 Tool 的 State 可按注册 ID 声明有序图。 */
+    readonly gizmos: GizmoRegistry;
+    /** HTML 卡片解析、刷新与跨文档通信命名空间。 */
+    readonly htmlCard: HTMLCardService;
+    /** 局部场景创建与 PNG 截图命名空间。 */
+    readonly screenshot: ScreenshotService;
+    /** operations 操作门面（懒初始化；getter 调用时经 _createOperations 工厂创建）。 */
+    private _operations?;
+    /** 画布容器 */
+    readonly container: HTMLElement;
+    private _disposed;
+    /** 最近一次 run 入参，recreate 时重放 */
+    protected _runInputSnapshot?: TRunInput;
+    /** 重建进行中标志（冷冻态），重建期间拦截对外 API */
+    protected _rebuilding: boolean;
+    /** context-restored 轻同步重入保护。 */
+    private _restoring;
+    /** 当前是否处于 context-lost 冷冻态（engine 自恢复期）。lost 期间拦截 run 等写入，避免落到正在重建的 GL 句柄。*/
+    private _contextLost;
+    /** Context recovery callbacks are stored instead of subscribing to the public event bus. */
+    private _contextRecoveryOptions?;
+    /** Gizmo 选择事件转发是否已绑定（setupSelectionBindings 仅应装配一次，重复 run 不应累积 selectionchange 监听器）*/
+    private _gizmoPrepared;
+    /** Frame metadata source of truth owned by the current GestureHandler. */
+    get frameManager(): FrameManager;
+    /**
+     * 构造 Artis 实例，按序装配核心服务并启动初始化流程
+     *
+     * @param container 画布挂载的 DOM 容器
+     * @param options 实例配置（偏好 / 历史 / 状态 / 渲染背景等）
+     */
+    constructor(container: HTMLElement, options?: ArtisOptions);
+    /**
+     * 创建元素身份策略（统一 id 基准与映射翻译）。
+     *
+     * 默认返回基于真实 ElementRegistry 的策略：artisItem.id 取 schemaId，与 vfxItemId(instanceId)
+     * 分离，靠 registry 翻译，遵守 D2（不 setInstanceId，artis 只读 instanceId）。Artis 沿用此默认。
+     * SceneArtis override 为 identity 策略：id 跟随 instanceId，映射空转。
+     *
+     * 在 ItemService 构造前（BaseArtis ctor step 5）调用，此时 renderer(step 3) 已就绪，
+     * resolveVfxItemById 回调惰性求值，注册时不触发。
+     */
+    protected _createIdentityStrategy(): ElementIdentityStrategy;
+    /** BaseArtis 只能从自己的稳定事件表发事件，子类扩展事件由子类自行发布。 */
+    protected _emitBase<K extends keyof BaseArtisEvents>(event: K, ...args: BaseArtisEvents[K]): void;
+    /**
+     * operations 操作门面工厂（懒初始化）。子类可 override 以返回扩展门面
+     * （如 SceneArtis 返回 `new SceneOperations(this)`）。默认 `new Operations(this)`。
+     */
+    protected _createOperations(): Operations;
+    /**
+     * 命名空间：操作门面（artis.operations）
+     *
+     * 常用基础功能类型化入口：`artis.operations.addSprite(info)` / `deleteItem(id)` / `hitTest(x,y)` /
+     * 截图 / 导出 / 对齐 / gizmo 开关 …。内部委托 command/item/view/preferences 等，保留撤销/守卫/batch/
+     * 资源回流（N10/C3）。懒初始化。装配后可用（item/view 等需 gestureHandler/sceneStore 就绪）。
+     */
+    get operations(): Operations;
+    /**
+     * 编辑可编辑态守卫：在 execute / beginInteraction / updateInteraction 三入口前置调用，
+     * 非编辑态（如 SceneArtis PlayState）拦截编辑类命令。基类 no-op（Artis 线始终可编辑），
+     * SceneArtis override 按命令分类（编辑类拦截 / 系统类放行）执行。S7。
+     *
+     * @param _commandId 命令 ID（用于编辑/系统分类）
+     */
+    protected _assertEditable(_commandId: string): void;
+    /**
+     * 创建 ViewService 的工厂方法，子类可 override 替换实现
+     *
+     * @param containerSize 容器尺寸（用于初始化视口大小）
+     * @param container 画布 DOM 容器
+     * @returns ViewService 实例
+     */
+    protected _createViewService(containerSize: Vector2, container: HTMLElement): ViewService;
+    /**
+     * 创建 InteractionService，注入视口、相机、元素 transform 三个 Provider
+     *
+     * Provider 工厂已抽离到 core/service/interaction-providers，本方法仅做组装。
+     *
+     * @returns InteractionService 实例
+     */
+    private _createInteractionService;
+    /**
+     * 按配置注册初始 State，并为「独立功能」状态绑定历史栈隔离
+     *
+     * @param options 实例配置（取 states 字段决定状态集合）
+     */
+    private _initStates;
+    /**
+     * 注册 BaseArtis 之外的额外 State（如 SceneArtis 的 ViewOnly/Play）。
+     *
+     * base 默认无额外 State；子类 override 追加。初始化时由 _initStates 末尾调用。
+     */
+    protected _registerExtraStates(): void;
+    /**
+     * 注册内置 Command 并配置命令执行后、历史变化后的同步与事件转发
+     * 实现已抽离到 artis/wiring（setupCommands），本方法仅做转发。
+     */
+    private _registerCommands;
+    /** 注册内置快捷键：订阅 GestureHandler 转发的 runtime Control keyDown，命中后 accept。 */
+    private _registerKeyBindings;
+    /**
+     * 注册并激活内置插件（当前为 IOPlugin）
+     * 实现已抽离到 artis/wiring（setupPlugins），本方法仅做转发。
+     */
+    private _setupPlugins;
+    /**
+     * 绑定各核心服务事件转发（视口 / 渲染 / 选区 / 状态）
+     * 实现已抽离到 artis/wiring（setupCoreEventBindings），本方法仅做转发。
+     */
+    private _setupEventBindings;
+    /**
+     * 开启错误监控（按需调用，未调用时零开销）
+     *
+     * 调用后，以下环节的错误将触发 callback：
+     * - Gizmo 交互（init / onMouseDown / onMouseMove / onMouseUp / onKeyDown）
+     * - Command 执行（execute / beginInteraction / updateInteraction / endInteraction / record）
+     * - Artis 门面层公开方法
+     * - Player 渲染错误（player.on('error')）
+     *
+     * 重复调用只更新回调，不重复注入监控器。
+     *
+     * 实现已抽离到 ErrorMonitorFacade，本方法负责首次按需创建 facade 并转发。
+     *
+     * @param callback 错误回调，接收包含错误信息和场景快照的 AnyArtisErrorInfo
+     */
+    enableErrorMonitor(callback: ErrorMonitorCallback): void;
+    /**
+     * 开启稳定性监测。
+     *
+     * 订阅 error 节流前钩子（error 已开启时自动接入）+ playerAdapter 'contextLost'，
+     * 维护 1 分钟滑动窗口，健康度变化经回调外达宿主。context-lost/fps 等独立信号
+     * 不依赖 error，error 未开启时仍工作。
+     *
+     * @param callback 健康度变化回调
+     */
+    enableStabilityMonitor(callback: StabilityMonitorCallback): void;
+    /**
+     * 开启性能监测上报。
+     *
+     * 与构造开关 options.perf 共享同一 facade 实例：构造期已预装配时仅补回调，
+     * 未装配则此时新建。开启后各阶段 mark/measure 采集的耗时经 PerfReport 回调上报。
+     *
+     * @param callback 性能上报回调
+     */
+    enablePerfMonitor(callback: PerfMonitorCallback): void;
+    /**
+     * 整实例重建：dispose 当前实例 → 委托 _createInstance new 同类型实例 → 重放缓存入参 →
+     * 还原 viewport/selection → 返回新实例。宿主须以返回的新实例替换旧引用。
+     *
+     * 设计为委托式：BaseArtis 抽象不能自 new，dispose 后 this 已废，新实例由子类工厂产出。
+     * 历史栈、已注册的 monitor/恢复监听均随 dispose 丢失——宿主需在新实例上重接。
+     *
+     * 与 {@link enableContextRecovery} 的区别：后者是同实例轻同步（context-restored 自恢复，
+     * 引用不变、监听不丢）；本方法是真正的整实例替换（dispose 旧 + new 新，宿主须替换引用）。
+     *
+     * @returns 重建后的新实例（旧实例已 dispose，不可再用）
+     */
+    recreate(): Promise<BaseArtis>;
+    /**
+     * context-restored 后的轻同步。
+     *
+     * doNotHandleContextLost:false 下，effects engine 在 webglcontextrestored 上就地重建全部 GPU
+     * 资源（含 artis 自建 Texture.fromImage 纹理、gizmo 自有纹理），Player/composition/选中/视口/播放态/
+     * 历史栈全部存活——故无需整体重建容器/换 Player/reinitGizmo/reload 场景/快照还原。此处仅做防御性
+     * items 同步 + 相机刷新 + gizmo 重绘（触发用已 restore 的纹理重画一帧），并外达 renderer.contextrestored 通知宿主。
+     *
+     * 失败均忽略：自恢复下数据层与 Player 一致，同步纯粹兜底，不应阻断恢复。
+     *
+     * @param onRecovered  恢复就绪回调（同实例，引用未变）
+     */
+    private _onContextRestored;
+    /**
+     * 开启 context-lost 自动恢复（同实例轻同步）。底层 context lost/restored 由 wiring 直接调用内部入口，后者触发
+     * {@link _onContextRestored} 轻同步后通知宿主。
+     *
+     * 保留 history/command/selection/items/sceneStore/monitor/listener 全部——宿主**无需**替换实例引用、
+     * **无需**重接 monitor、**无需**重新调用本方法（同实例，监听仍在）。
+     *
+     * @param options.onLost      context 丢失时的通知回调（同实例 this），供宿主提示"正在恢复…"
+     * @param options.onRecovered 恢复就绪回调（同实例 this，引用未变），事件负载含轻同步失败步骤 syncFailures
+     */
+    enableContextRecovery(options?: ContextRecoveryOptions): void;
+    /**
+     * @deprecated 历史遗留方法名（早期确会整实例 recreate，现仅同实例轻同步）。推荐改用语义准确的
+     * {@link enableContextRecovery}，入参形状与回调契约完全一致。
+     */
+    enableAutoRecreate(options?: ContextRecoveryOptions): void;
+    private _enableContextRecovery;
+    /** 具体 Artis 变体可覆写并发布自己的状态事件。 */
+    protected _handleStateChange(_event: StateChangeEvent): void;
+    /**
+     * 当前是否已销毁
+     */
+    get disposed(): boolean;
+    /**
+     * 当前是否处于 context-lost 冷冻态（WebGL 上下文丢失、engine 自恢复期间）。
+     *
+     * 进入 lost 态后至 renderer.contextrestored 完成轻同步期间为 true。宿主可据此在 UI 上提示
+     * "正在恢复…"并暂停业务写入；run/命令层已在内部据此次级拦截，业务方一般无需自查。
+     */
+    get isContextLost(): boolean;
+    /**
+     * 获取底层 Player 实例（高级逃生舱）。
+     *
+     * 注意：此 getter 绕过 `shared` 唯一 import 面的封装意图（见分析 T2），直接暴露
+     * `@galacean/effects` Player 句柄。仅用于本包未覆盖的高级场景；常规操作请走命名空间
+     * API（artis.view / artis.item / artis.command 等）。
+     */
+    get player(): Player;
+    /** @Gizmo 生命周期管理器（装配后可用，逻辑上非空） */
+    get gizmoManager(): GizmoManager;
+    /**
+     * 命名空间：元素增删改查
+     *
+     * 推荐用法（新接口）：`artis.item.getArtisItem(id)`、`artis.item.createItem(schema)`。
+     *
+     * 注意：所有「写数据」的操作请优先通过 {@link command} 执行（走 Command 以支持撤销/重做），
+     * `item` 命名空间主要用于「读数据」与底层服务能力的直接访问。
+     */
+    get item(): ItemService;
+    /**
+     * 命名空间：命令与撤销重做
+     *
+     * 推荐用法（新接口）：`artis.command.execute('item.create', { schemas: schema })`。
+     * 复合操作可结合 {@link beginBatch} / {@link endBatch} 聚合为单条历史。
+     */
+    get command(): CommandService;
+    /**
+     * 命名空间：选区管理
+     *
+     * 推荐用法（新接口）：`artis.selection.getSelectedIds()`。
+     * 「设置选区」的写操作请通过 `artis.command.execute('selection.set', { newSelectedIds: ids })` 执行以支持撤销。
+     *
+     * Selection 由 GestureHandler 持有（init 时创建，装配后可用，逻辑上非空，与 gestureHandler 同生命周期）。
+     * 仅在 run() 完成后访问。
+     */
+    get selection(): Selection;
+    /**
+     * @deprecated 使用 {@link states}。仅保留同一 StateManager 实例的兼容别名。
+     */
+    get stateManager(): StateManager;
+    /** Enter the GestureHandler-owned TextEditMode after selecting one text item. */
+    enterTextEditing(activation?: TextEditActivation): boolean;
+    /** Leave the GestureHandler-owned TextEditMode. */
+    leaveTextEditing(): void;
+    /**
+     * 命名空间：视口（缩放 / 平移 / fitToBox）
+     *
+     * 推荐用法（新接口）：`artis.view.zoom`、`artis.view.fitToBox(...)`。
+     */
+    get view(): ViewService;
+    /**
+     * 命名空间：历史栈（撤销 / 重做）
+     *
+     * 推荐用法（新接口）：`artis.history.undo()`、`artis.history.redo()`。
+     */
+    get history(): HistoryManager;
+    /**
+     * 命名空间：偏好配置（对应原 SDKConfig）
+     *
+     * 推荐用法（新接口）：`artis.preferences.setPage({ groupVisible: false })`。
+     * 便捷开关见 {@link setGroupVisibleEnabled} 等快捷 setter。
+     */
+    get preferences(): UserPreferencesManager;
+    /**
+     * 命名空间：快捷键（注册 / 改键 / 临时禁用 / 多 profile）
+     *
+     * 推荐用法（新接口）：`artis.keybinding.register({ id, combo, handler })`、
+     * `artis.keybinding.disable('item.delete')`、`artis.keybinding.switchProfile('mac-default')`。
+     * 内置指令（item.delete / edit.undo / viewport.zoom 等）已在装配期注册，
+     * 可通过 setKey 改键、disable 临时关闭、unregister 移除（内置降级为 disable）。
+     * 同一 combo 在同一 scope 被其它 id 占用时 register/setKey 抛 DuplicateComboError。
+     */
+    get keybinding(): KeyBindingController;
+    /**
+     * 加载场景并启动渲染（入口方法）
+     * 拆分为四个阶段，子类可 override 各阶段方法以自定义行为
+     *
+     * @param artisData 可选的场景初始化数据，透传给 _loadSceneData
+     */
+    run(artisData?: TRunInput): Promise<void>;
+    /**
+     * 阶段1：初始化渲染引擎，调用 renderer.run() 创建 Player 场景
+     * 渲染引擎就绪后尝试绑定 Player 错误监听（enableErrorMonitor 在 run 之前调用时生效）
+     */
+    protected _initRenderer(): Promise<void>;
+    /**
+     * 阶段2：准备 Gizmo 交互层，创建并初始化 GestureHandler，绑定事件
+     *
+     * initGizmo 内部的 assemble 会创建 GizmoManager（及其 Selection）。装配完成后需：
+     * 1. 把 Selection 回填给构造早于装配的 ItemService；
+     * 2. 订阅 Selection 事件转发（装配前 Selection 尚不存在，无法在构造期订阅）。
+     */
+    protected _prepareGizmo(): void;
+    /**
+     * 阶段3：加载场景数据。子类 override 以自定义数据来源（编辑数据 / JSON）。
+     * 默认实现：识别 InitArtisData.items，逐条 createItem。
+     *
+     * @param artisData 可选的场景初始化数据，需符合 InitArtisData 结构
+     */
+    protected _loadSceneData(artisData?: TRunInput): Promise<void>;
+    /**
+     * 阶段4：初始化完成，触发 ready 事件
+     */
+    protected _onReady(): void;
+    /**
+     * 返回当前激活场景的编辑元素集合。
+     * 编辑数据驱动的 Artis 返回 store.items；JSON 驱动的 SceneArtis 返回激活 SceneEntry.items。
+     */
+    protected abstract _getActiveItems(): ArtisItem[];
+    /**
+     * 设置背景
+     *
+     * @param config 背景配置
+     */
+    setBackground(config: ArtisBackgroundConfig): void;
+    /**
+     * 开关：成组元素的可见性联动
+     *
+     * 等价于 `artis.preferences.setPage({ groupVisible: enabled })`。
+     *
+     * @param enabled 是否开启成组元素可见性联动
+     */
+    setGroupVisibleEnabled(enabled: boolean): void;
+    /**
+     * 追加「需要被过滤的元素名称」列表（去重追加）
+     *
+     * 等价于向 `artis.preferences.page.filterItemNames` 追加。
+     *
+     * @param itemNames 单个名称或名称数组
+     */
+    addFilterItemNames(itemNames: string | string[]): void;
+    /**
+     * 追加「需忽略交互的元素名称」（去重追加）。
+     *
+     * 等价于向 `artis.preferences.page.ignoredInteractionNames` 追加，并同步下发到 gizmo Selection，
+     * 使指定名称的元素不参与点选/框选（仍渲染可见）。命令层守卫在构造期已注入，无需重复安装。
+     *
+     * @param itemNames 单个名称或名称数组
+     */
+    addIgnoredInteractionNames(itemNames: string | string[]): void;
+    /**
+     * 把当前 ignoredInteractionNames 下发到 gizmo Selection（命中名称的元素不参与点选/框选）。
+     * 在构造期、_prepareGizmo 与 addIgnoredInteractionNames 后调用，保证 Selection 始终持有最新名单。
+     */
+    private _syncIgnoreNamesToSelection;
+    /**
+     * 注入命令层守卫：在 execute / beginInteraction / updateInteraction 创建并执行 Command 前，
+     * 提取目标元素 id，命中 ignoredInteractionNames 名称即抛 {@link IgnoredInteractionError} 拒绝执行。
+     * 守卫内名单为空时直接 return，避免每次命令执行都解析名称。
+     */
+    private _installIgnoredInteractionGuard;
+    /**
+     * 开关：静态预览
+     *
+     * 等价于 `artis.preferences.setPage({ staticPreview: enabled })`。
+     *
+     * @param enabled 是否开启静态预览
+     */
+    setStaticPreviewEnabled(enabled: boolean): void;
+    /**
+     * 设置静态预览名称
+     *
+     * 等价于 `artis.preferences.setPage({ staticPreviewName: name })`。
+     *
+     * @param name 静态预览名称
+     */
+    setStaticPreviewName(name: string): void;
+    /**
+     * 开关：异步资源加载
+     *
+     * 等价于 `artis.preferences.setAsyncLoad({ enabled })`。
+     *
+     * @param enabled 是否开启异步资源加载
+     */
+    setAsyncEnabled(enabled: boolean): void;
+    /**
+     * 开关：尺寸自适应
+     *
+     * 等价于 `artis.preferences.setSizeAdapt({ enabled })`。
+     *
+     * @param enabled 是否开启尺寸自适应
+     */
+    setSizeAdaptEnabled(enabled: boolean): void;
+    /**
+     * 开关：截图功能
+     *
+     * 等价于 `artis.preferences.setScreenshot({ enabled })`。
+     *
+     * @param enabled 是否开启截图功能
+     */
+    setScreenShotEnabled(enabled: boolean): void;
+    /**
+     * 开关：导出功能
+     *
+     * 等价于 `artis.preferences.setExport({ enabled })`。
+     *
+     * @param enabled 是否开启导出功能
+     */
+    setExportEnabled(enabled: boolean): void;
+    /**
+     * 开始批量态
+     *
+     * 用于「单次交互产生多个 Command」的场景：在 beginBatch 与 endBatch 之间
+     * 通过 commandService.execute / record 产生的所有子 Command 会被缓冲，
+     * endBatch 时聚合为一个历史条目，撤销一次即可整体还原。
+     *
+     * 典型用法（如切换画板为自动布局）：
+     * ```ts
+     * artis.beginBatch()
+     * try {
+     *   artis.commandService.execute('frame.layoutMode', { frameId, targetMode: 'auto' })
+     *   artis.commandService.execute('item.transform', { itemId, newTransform })
+     * } finally {
+     *   artis.endBatch('frame.setAutoLayout')
+     * }
+     * ```
+     */
+    beginBatch(): void;
+    /**
+     * 结束批量态，将缓冲的子 Command 聚合入 History
+     *
+     * - 0 个子命令：不入 History
+     * - 1 个子命令：直接入该子命令（不包裹 Composite，历史更干净）
+     * - 多个子命令：聚合为一个 CompositeCommand 入 History
+     *
+     * @param commandId 可选的复合命令显示 ID（仅多子命令时生效）
+     */
+    endBatch(commandId?: string): void;
+    /**
+     * 取消批量态：丢弃缓冲的子 Command（不入 History）
+     *
+     * 注意：子命令的数据变更已经发生，此处不做回滚。
+     */
+    cancelBatch(): void;
+    /**
+     * 销毁实例，释放所有资源
+     */
+    dispose(): void;
+    /**
+     * 根据 Gizmo 创建类型构建对应 ItemSchema 的工厂已抽离到
+     * core/item/default-item-schema（pure function）。
+     */
+    /**
+     * 处理 GestureHandler / Command 绑定层转发来的 gizmo 事件，统一触发到 Artis 事件系统。
+     *
+     * 取代旧 _gizmoEmitter 中转层：不再经第二个 EventEmitter，GH/Command 绑定直接回调本方法。
+     * - item.create：先建 schema 跑 command（支持撤销），再 emit
+     * - item.dragend：transform 拖拽结束后同步 VFXItem transform → ArtisItem.property + Scene JSON
+     * - 其余事件直接转发
+     *
+     * @param event 事件名（ArtisEvents 的 key）
+     * @param args 事件参数
+     */
+    private _handleGizmoEvent;
+    /** 具体变体按需把 Gizmo 专属事件适配到自己的公开事件表。 */
+    protected _handleVariantGizmoEvent(_event: string, _args: unknown[]): void;
+    /**
+     * 为「独立功能」状态（isolated = true）绑定 History 栈隔离。
+     *
+     * - 进入时（enter）：先 flush 收尾未完成的交互态 / 批量态，再 pushSession 挂起主栈，
+     *   给独立功能一条干净的空栈，其 undo / redo 只能操作自身 Command。
+     * - 离开时（exit）：popSession 丢弃独立功能子栈并原样还原主栈。
+     *
+     * enter / exit 由 BaseState 在 onEnter / onExit 中 emit，时机早于 StateManager 的
+     * 'stateChange' 事件，因此切回基础状态后业务方补的 Command 会归属到已还原的目标栈。
+     *
+     * @param state 需要隔离 History 栈的状态，仅 isolated 为 true 时生效
+     */
+    private _bindIsolatedStateHistorySession;
+}

package/dist/artis/canvas-layer-order.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Artis 画布 DOM 层级契约。
+ *
+ * HTML 卡片层必须位于承载 runtime Control 的 Effects canvas 之上：HTML 根层本身不接收事件，
+ * 只有被 HTMLCardService 激活的内容节点会改为 pointer-events:auto；其余区域会
+ * 穿透到 canvas。层级由 Artis 装配层统一分配，子模块不得各自假设固定值。
+ */
+export declare const ARTIS_CANVAS_LAYER_Z_INDEX: {
+    readonly gesture: 1;
+    readonly htmlCard: 2;
+};
+export type ArtisCanvasLayers = {
+    gesture: HTMLElement;
+    htmlCard: HTMLElement;
+};
+/**
+ * 应用 Artis 画布层级，并标记具名层以便调试与集成测试定位。
+ */
+export declare function applyArtisCanvasLayerOrder({ gesture, htmlCard }: ArtisCanvasLayers): void;

package/dist/artis/create-info-to-schema.d.ts

@@ -0,0 +1,21 @@
+import type { ItemSchema, ItemCreateInfo } from '../core';
+/**
+ * 旧 CreateInfo 模型 → 新 ItemSchema 模型转换器。
+ *
+ * 背景：旧 SDK 的元素创建使用 `XxxCreateInfo`（type 为 ArtisItemType 枚举），
+ * 新架构统一使用 `ItemSchema`（type 为字符串字面量）。两者 property 字段高度一致，
+ * ArtisItemType 枚举值本身即为对应字符串（sprite/text/...），故大部分字段可直接透传。
+ *
+ * 差异处理：
+ * - CardCreateInfo.property.cardType（CardType 类型）→ schema.cardType（string）
+ * - FrameCreateInfo.property.layoutMode（FrameLayoutMode 枚举，值已是 'auto'/'free'）直接透传
+ * - CreateInfo 上的 html / autoLayoutConfig / layoutInfos 等扩展字段不在 ItemSchema 中，忽略
+ *
+ * @param createInfo 旧元素创建信息
+ * @returns 新元素 Schema
+ */
+export declare function createInfoToSchema(createInfo: ItemCreateInfo): ItemSchema;
+/**
+ * 批量转换。
+ */
+export declare function createInfosToSchemas(createInfos: ItemCreateInfo[]): ItemSchema[];

package/dist/artis/index.d.ts

@@ -0,0 +1,15 @@
+export { Artis } from './artis';
+export type { ArtisEvents, ArtisStateEvents } from './types';
+export type { BaseArtisEvents, ArtisWarningEventInfo } from '../core';
+export type { AnyArtisErrorInfo } from '../core';
+export { gizmoConfig } from '../core/gizmo/gizmo-config-override';
+export type { GizmoConfigOverride } from '../core/gizmo/gizmo-config-override';
+export { SceneArtis } from './scene-artis';
+export type { SceneArtisRunInput, SceneArtisReproduceInput } from './scene-artis';
+export { BaseArtis, IgnoredInteractionError } from './base-artis';
+export { HTMLCardService } from '../helper/html-overlay';
+export { ScreenshotService } from './screenshot-service';
+export type { ScreenshotSceneOptions, ScreenshotRenderOptions, ScreenshotGenerateOptions } from './screenshot-service';
+export type { ArtisOptions, ArtisRunInput, ArtisViewParam, } from './types';
+export * from './operations';
+export * from './wiring';

package/dist/artis/operations/index.d.ts

@@ -0,0 +1,3 @@
+export { Operations } from './operations';
+export { SceneOperations } from './scene-operations';
+export type { ViewportFitParam, ViewportFitToBoxParam, ViewportFitToItemsParam, InitPositionOptions } from './types';