@vvfx/artis 0.0.1-alpha.0

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

@@ -0,0 +1,386 @@
+import { BaseArtis } from './base-artis';
+import { spec } from '../shared';
+import { SceneStore, SceneDataAssembler, JsonSceneSyncService, IdentityStrategy, BaseState, type SceneEntry, type SceneEntrySnapshot, type VariantErrorSnapshot, type ArtisItemTypeTable, type ArtisItem } from '../core';
+import { type SceneSourceInput, type SceneView } from '../helper';
+import type { ArtisOptions } from './types';
+import type { Operations } from './operations/operations';
+declare global {
+    interface Window {
+        artis?: () => unknown;
+    }
+}
+/**
+ * 播放态：仅保留可见的 ViewportOverlayGizmo（边框/安全区），消除所有编辑类 Gizmo 的渲染与交互。
+ *
+ * 编辑类（transform/text/picture-cut/picture-expand/sprite-text-edit/mask/item-create/
+ * frame/auto-layout/selection snapping 等）不由 createGizmos 创建，因此不会进入当前实例图。
+ * 选区交互（选中/hover/框选）同样由 createGizmos 不创建选区子图而缺席；换图会先清 hover，
+ * 缺少 ChangeSelection 的新图不会按缓存指针重新提交命中，无需运行期 selectionEnabled flag。
+ * 非独立功能（isolated=false）：不隔离 History 栈，
+ * stop 后切回原 State 恢复编辑能力。
+ */
+export declare class PlayState extends BaseState {
+    constructor();
+}
+/** Scene-specific Move State with Preference rendering in its Tool graph. */
+export declare class SceneMoveState extends BaseState {
+    constructor();
+}
+export type { SceneSourceInput, SceneView };
+/**
+ * SceneArtis 运行输入
+ *
+ * 三场景映射：
+ * - a 单产物直初始化：`sources: [{ url }]`
+ * - b 单产物 + 多视图 + 安全区：`sources: [{ url, views: [...] }]`
+ * - c 多产物直初始化：`sources: [{ url }, { url }, ...]`
+ */
+export type SceneArtisRunInput = {
+    /** Galacean/effects 产物源列表 */
+    sources: SceneSourceInput[];
+    /** 初始激活场景 id（缺省=第一个） */
+    activeSceneId?: string;
+    /** 可选：id→ArtisItemType 类型表，消除 GENERATOR/CARD/EFFECTS 歧义 */
+    typeTable?: ArtisItemTypeTable;
+    /** 展示标准产物：true 时首个 origin 场景只读（仅播放+选中查看，不可编辑） */
+    showStandardProduct?: boolean;
+};
+/**
+ * SceneArtis 复现输入：用错误快照内的 sceneEntries 直接灌入重建多场景，绕过 SceneBuilder
+ * 重新自适应，保真还原 source/adapt/originScene/readonly/id 关联。
+ */
+export type SceneArtisReproduceInput = {
+    /** 快照场景数组（SceneEntrySnapshot 反序列化形态），至少一条 */
+    entries: SceneEntrySnapshot[];
+    /** 激活场景 id（缺省=首个 entry） */
+    activeSceneId?: string;
+    /** 首个 origin 标记只读（与 run 同语义，覆盖快照内 readonly 决策） */
+    showStandardProduct?: boolean;
+    /** 初始游标（缺省=0） */
+    sceneTime?: number;
+    /** 初始播放态（缺省=false） */
+    scenePlaying?: boolean;
+};
+/**
+ * SceneArtis - effects-JSON 原生、场景驱动的画布编辑器
+ *
+ * 与编辑数据驱动的 {@link Artis} 平级，继承 {@link BaseArtis}。差异在数据层与初始化：
+ * - 数据真源是 {@link spec.JSONScene}（持久 + 动画），ArtisItem[] 是 runtime 组装的编辑模型
+ * - 一 JSON 可按自适应参数生成多场景；多 JSON 各成独立场景，同时只激活一个
+ * - 编辑经 Command 双向同步：先写 runtime VFXItem，再回写场景 JSON（{@link JsonSceneSyncService}）
+ * - 导出 = 取已同步的当前场景 JSON
+ *
+ * 仅未播放态（stop）可编辑。
+ */
+export declare class SceneArtis extends BaseArtis<SceneArtisRunInput> {
+    /** 多场景数据 + 会话状态中枢 */
+    readonly sceneStore: SceneStore;
+    /** JSON + runtime → ArtisItem 装配器 */
+    readonly sceneDataAssembler: SceneDataAssembler;
+    /** ArtisItem → JSONScene 回写服务 */
+    readonly jsonSceneSync: JsonSceneSyncService;
+    /**
+     * 编辑类命令清单（PlayState 等非编辑态须拦截）。系统类（scene.switch / selection.set /
+     * viewport.move/zoom / item.updateProperty 仅 name 等）放行——审计确认它们在播放/只读态也合法。
+     * 仅 item.updateProperty 的 name 改写归系统类放行，其余 item.updateProperty 字段属编辑类。
+     */
+    private static readonly EDITABLE_COMMANDS;
+    private _sceneBuilder;
+    private _jsonSyncInstalled;
+    /** 在途场景切换链（序列化互斥：避免快速切场景时并发 apply 交错竞态，S15）。 */
+    private _switchChain;
+    /** JSON 回写 afterExecute 订阅的注销函数 */
+    private _disposeJsonSyncAfterExecute;
+    /** 播放进度同步订阅的注销函数（progress → SceneStore.time） */
+    private _disposeProgressSync;
+    /** 容器 resize 订阅注销函数（resize → 重算 contentRatio/pixelRatio 并刷新注入） */
+    private _disposeResizeSync;
+    /** play 前激活 State id，stop 时恢复（Play 态切换的内务记录） */
+    private _stateBeforePlay;
+    /** run/reproduce 进行中标志：互斥两者并发，防止 sceneStore/viewService 被并发写入串台 */
+    private _running;
+    /** undo/redo → JSON 回写的具名 handler（稳定引用，供 dispose 时 off 解绑，不依赖基类清空 listeners 的脆弱实现） */
+    private readonly _undoRedoJsonSyncHandler;
+    /**
+     * @override 一次性产出 SceneArtis 变体专属快照（与 variant: 'SceneArtis' tag 绑定返回）：
+     * 全场景 JSONScene(scenes) + 结构快照(sceneEntries) + 激活场景 id + 选中元素 +
+     * 视图参数(widthRatio/heightRatio) + 播放游标/态 + 只读标记。
+     *
+     * 始终返回 SceneArtis tag（哪怕无场景数据），确保 info.artisVariant 与实际变体一致——
+     * 复现页据 hasEntries/hasScenes 自行决定能否重建。任一字段取值异常不阻断其余（尽力而为），
+     * 仅当整体抛错才由 ErrorMonitor._safeGet 兜底为缺省（退回 Artis 兜底）。
+     */
+    protected _captureErrorSnapshot(): VariantErrorSnapshot;
+    /**
+     * 构造 SceneArtis 实例，初始化场景 store、装配器、JSON 回写服务与场景切换 Command。
+     * @param container 画布挂载的 DOM 容器。
+     * @param options 初始化选项（缺省取默认）。
+     */
+    constructor(container: HTMLElement, options?: ArtisOptions);
+    /**
+     * 可编辑态守卫（S7）：非编辑态（PlayState）下，编辑类命令抛 {@link IgnoredInteractionError} 拒绝。
+     * item.updateProperty 按 args 分流：改 name（args[1]==='name'）放行，其余字段按编辑类拦截。
+     */
+    protected _assertEditable(commandId: string, args?: unknown[]): void;
+    /** 注册只读查看态 / 播放态。 */
+    protected _registerExtraStates(): void;
+    /** 当前渲染场景 id */
+    get activeSceneId(): string | undefined;
+    /** 当前播放游标 */
+    get time(): number;
+    /** 播放态 */
+    get playing(): boolean;
+    /**
+     * 获取当前激活场景的 entry（含 scene + items）。
+     * @returns 当前激活场景 entry；若无激活场景返回 `undefined`。
+     */
+    getActiveScene(): SceneEntry | undefined;
+    /**
+     * 加载场景并启动渲染（入口方法）
+     *
+     * 阶段A：多场景构建（SceneBuilder）
+     * 阶段B：激活首个场景
+     * 阶段C：清旧注册表（首屏专属）+ _prepareGizmo（首屏一次性）
+     * 阶段D：统一加载收口 loadSceneEntry（加载+装配+视口+只读+Gizmo刷新+游标恢复，与切场景同路径）
+     * 阶段E：安装 JSON 同步 + _onReady
+     */
+    run(input?: SceneArtisRunInput): Promise<void>;
+    /**
+     * 阶段A 公共：按需把首个 origin 标记只读（showStandardProduct），再把 entries 灌入 SceneStore，
+     * 统一打 scene-build 性能埋点。run（builder 产出 entries）与 reproduce（快照 entries）共享，
+     * 避免两路 addScene 循环 + 只读标记 + 埋点重复。
+     */
+    private _hydrateScenes;
+    /**
+     * 阶段B~E 公共装配：激活指定场景 → 主 Player 加载 → 装配编辑模型 items → _prepareGizmo →
+     * resolver/主视口/只读态 → goto 游标 → 安装 JSON/进度/resize 同步 → _onReady。
+     *
+     * 抽离自 {@link run} 供 {@link reproduce} 复现入口共享，避免两条初始化路径重复装配逻辑
+     * 与重复安装同步订阅。
+     *
+     * @param activeId 激活场景 id（须已 addScene 进 store）
+     * @param typeTable 元素类型表（assemble 消歧用）
+     * @param time 初始游标；run 传 0，reproduce 传快照游标还原
+     * @param playing 初始播放态；run 传 false，reproduce 传快照播放态还原
+     */
+    private _bootstrapActiveScene;
+    /**
+     * 复现入口：用快照内 sceneEntries 直接灌入 SceneStore 重建多场景，绕过 SceneBuilder.build
+     * 重新自适应，保真还原 source/adapt/originScene/readonly/id 关联。items 不从快照取——
+     * runtime 直接重新 assemble（与 run 一致路径）。
+     *
+     * 与 {@link run} 的区别：阶段A 由 SceneBuilder.build 改为快照 entries 直接灌入（无自适应重排、
+     * 原样保留结构字段）；阶段B~E 复用 {@link _bootstrapActiveScene}。游标/播放态按快照还原
+     * （run 始终为 0/false）。
+     *
+     * 适用于 BugRepro 等复现工具：错误快照带了 sceneEntries 时走本方法保真复现；
+     * 快照仅有 scenes(JSONScene[]) 无结构字段时退回 {@link run}。
+     */
+    reproduce(input: SceneArtisReproduceInput): Promise<void>;
+    /**
+     * 切换激活场景（通过 Command 纳入历史栈，支持 undo/redo）。
+     * 边界：目标 id 不存在或已是当前激活场景时直接返回，不产生 Command。
+     * @param sceneId 目标场景 id。
+     */
+    switchScene(sceneId: string): void;
+    refreshContentScale(previewSize: spec.vec2, clipMode: spec.CameraClipMode): void;
+    /**
+     * 场景切换入口（被 SceneSwitchCommand 回调，index-based）。
+     *
+     * 经序列化互斥连到在途切换链尾：SceneSwitchCommand.execute/undo 为 sync 接口却触发异步 apply，
+     * 快速连发会并发交错 saveCurrentItems/setActiveIndex/loadSceneEntry 损坏状态。此处保证同一时刻
+     * 只有一个切换在执行，后续请求排队到前一个完成后串行执行。
+     * @param targetIndex 目标场景下标。
+     */
+    private applySwitchSceneByIndex;
+    /**
+     * 实际执行场景切换（已由 {@link applySwitchSceneByIndex} 串行化保护，此处为单次切换本体）。
+     *
+     * 视口重初始化：ViewService 跨场景复用，须在加载新场景前清掉旧场景编辑会话遗留的 zoom/translation
+     * （assemble 经 getPixelSizeByViewSize 读 effectiveScale=zoom·contentRatio，zoom 残留会污染新场景
+     * items 装配）。ratios 无需手动归位——_initRendererWithScene 内 refreshContentScale 会按新场景
+     * contain-fit 几何同时落定两轴 ratio（contentRatio 取 clipMode 对应轴，由 sceneLoaded→setClipMode
+     * 维护），不残留旧场景值。reset 的 emit('change') 经 wiring 应用到 Player 与 ResizeSelectionGizmo，配
+     * _applyPreferenceViewport 重灌 ViewportOverlayGizmo；Gizmo 整体刷新由原生 pre-render 帧入口完成。
+     * @param targetIndex 目标场景下标。
+     */
+    private _doApplySwitch;
+    /**
+     * 取当前激活场景的 items；无激活场景时回退到 store.items。
+     * @returns 当前激活场景的 ArtisItem 数组。
+     */
+    protected _getActiveItems(): ArtisItem[];
+    /** context-lost 重建工厂：new 同类型 SceneArtis 实例 */
+    protected _createInstance(container: HTMLElement, options: ArtisOptions): SceneArtis;
+    /**
+     * 重载身份策略：SceneArtis 以 VFXItemId 为基准——artisItem.id 跟随 Player 分配的 instanceId，
+     * 即 id === vfxItemId === instanceId 全程成立，无需 registry 映射（加载 assemble / 恢复 reload /
+     * 会话内 createItem 三条路径一致）。Artis 保留基类默认的 RegistryIdentityStrategy。
+     */
+    protected _createIdentityStrategy(): IdentityStrategy;
+    /**
+     * @override SceneArtis 用 SceneOperations 扩展基础 Operations——继承全部基础操作门面能力，
+     * 并追加 Scene 专属「导出场景 JSON」家族（基于 SceneStore 实时回写）。getter 类型仍为基类
+     * Operations（基类声明），消费侧需 Scene 专属方法时按 SceneOperations 取用。
+     */
+    protected _createOperations(): Operations;
+    /**
+     * 从指定时间开始播放；缺省则从当前游标继续。进入播放态后禁止编辑。
+     * @param time 起始时间（秒）；传 `undefined` 使用当前游标。
+     */
+    play(time?: number): void;
+    /**
+     * 停止播放并跳转到指定时间（gotoAndStop），进入可编辑态。
+     * @param time 停止后停留的时间（秒）；传 `undefined` 使用当前游标。
+     */
+    stop(time?: number): void;
+    /**
+     * 跳转到指定时间，保持当前播放/停止态不变。
+     * @param time 目标时间（秒）。
+     */
+    seek(time: number): void;
+    /**
+     * 切换播放态：`true` 调用 `play()`，`false` 调用 `stop()`（均使用当前游标）。
+     * @param playing 是否进入播放态。
+     */
+    setPlaying(playing: boolean): void;
+    /**
+     * 开关：出血安全区显隐（联动 ViewportOverlayGizmo 的 safeArea 边带绘制）。
+     *
+     * 安全区数据由当前激活场景的 `adapt.safeArea` 提供（{@link _applyPreferenceViewport} 写入 viewProperty），
+     * 显隐由本开关统一控制。经 GizmoManager.setPreference 设置（配置真源下沉 GizmoManager，
+     * 变更事件下放到 ViewportOverlayGizmo 实例）。
+     * @param enabled 是否显示安全区
+     */
+    setSafeAreaEnabled(enabled: boolean): void;
+    /**
+     * 导出当前激活场景 JSON（已由 JsonSceneSyncService 实时回写，浅克隆保护）。
+     * @returns 当前激活场景 JSON；无激活场景时返回 `undefined`。
+     */
+    exportScene(): spec.JSONScene | undefined;
+    /**
+     * 按 id 导出指定场景 JSON。
+     * @param id 目标场景 id。
+     * @returns 目标场景 JSON；id 不存在时返回 `undefined`。
+     */
+    exportSceneById(id: string): spec.JSONScene | undefined;
+    /**
+     * 按 index 导出指定场景 JSON。
+     * @param index 目标场景下标。
+     * @returns 目标场景 JSON；越界时返回 `undefined`。
+     */
+    exportSceneByIndex(index: number): spec.JSONScene | undefined;
+    /**
+     * 导出全部场景 JSON。
+     * @returns 全部场景 JSON 数组（按 store 顺序）。
+     */
+    exportAllScenes(): spec.JSONScene[];
+    /**
+     * 主 Player 加载场景并按 previewSize contain-fit 适配进当前容器。
+     *
+     * @param entry 待加载的场景条目（取其 scene + previewSize）。
+     */
+    private _initRendererWithScene;
+    /**
+     * 统一加载场景条目（首屏 run 与切场景 applySwitchSceneByIndex 的共享收口）。
+     *
+     * 对齐 run 现有正确顺序，把"主 Player 加载 → 装配 items → resolver/视口/只读态 → Gizmo 刷新 → 游标恢复"
+     * 收口为单一流程，保证任何一次加载 JSON 走同一链路。仅剔除首屏专属的 _prepareGizmo / clearElementRegistry /
+     * install* / _onReady（这些留在 run）；切场景由调用方各自完成前置（saveCurrentItems / clearSelection /
+     * setActiveIndex / viewService.reset）后调本方法。
+     *
+     * 4B：末尾显式 syncAllItemsFromPlayer，不依赖 afterExecute 钩子隐式触发；Gizmo 由原生 pre-render 刷新。
+     *
+     * @param entry 待加载场景条目（取 scene + previewSize + clipMode）。
+     * @param typeTable 类型表（首屏 run 透传；切场景缺省走默认）。
+     * @param gotoTime 加载后恢复游标（首屏传 0；切场景缺省=当前 sceneStore.time）。
+     */
+    private loadSceneEntry;
+    /**
+     * 解析场景的主视口预览尺寸。
+     *
+     * adapted 场景取自适应 viewSize；其余取 `compositions[0].previewSize`，回退 contentSize。
+     * @param entry 场景条目
+     * @returns [宽, 高]
+     */
+    private _resolvePreviewSize;
+    /**
+     * 解析场景主合成的相机裁剪模式，供 refreshContentScale 决定 contentRatio 取宽/高轴。
+     *
+     * 取 `compositions[0].camera.clipMode`（createMaskScene 原样透传主合成 camera，故与
+     * player 加载、wiring setClipMode 同源），缺省回退 portrait（与 wiring.ts setClipMode 同口径）。
+     * @param entry 场景条目
+     * @returns portrait | landscape
+     */
+    private _resolveClipMode;
+    /**
+     * 注入主视口展示参数到 ViewportOverlayGizmo：viewProperty（size/safeArea）。
+     *
+     * 主视口 box 不再由外部 provider 手算——{@link _addSceneMaskFrame} 加的遮罩画板 item 已使
+     * ViewportOverlayGizmo.onPreRender 走 isFramePlayerItem 分支，用 getItemViewBox(遮罩画板) 投影
+     * 算 box（与 loading/transform 同源），红框/安全区随相机/视口变换跟随。此处仅设 viewProperty，
+     * 供 safeArea/previewSafeAreas 的比例分母。
+     * @param entry 当前激活场景条目
+     */
+    private _applyPreferenceViewport;
+    /**
+     * State 切换(play/stop 等)经 rebuildGizmos 重建 preference 实例后,按当前激活场景重灌
+     * viewProperty。preference 实例为全新、viewProperty 丢失,出血/安全区数据需现算重注入;
+     * box 仍由蒙版 item 投影(不依赖 viewProperty),故红框不受影响。无激活场景时跳过。
+     */
+    private _reapplyPreferenceViewport;
+    /**
+     * 按场景只读标记切换交互态：只读场景切 ViewOnlyState（禁编辑手柄，仅播放+选中查看），
+     * 非只读场景从只读态退回默认 move 态。
+     * @param entry 当前激活场景条目
+     */
+    private _applyReadonlyState;
+    /**
+     * 在已加载冻结的 composition 上装配 ArtisItem[]（同步：主 Player 已 loadScene）。
+     * @param _scene 已加载的场景 JSON（实际从 runtime 取，参数仅作占位）。
+     * @returns 装配得到的 ArtisItem 数组。
+     */
+    private _assembleScene;
+    /**
+     * 解析 JSON 源（对象直返，字符串按 URL fetch）。
+     * @param source JSON 对象或 URL 字符串。
+     * @returns 解析得到的 JSONScene。
+     */
+    private _resolveScene;
+    /**
+     * 注入 SelectionManager resolver（指向激活场景 items）+ 同步 store.items。
+     * resolver 使选中 id 解析到当前激活场景的 ArtisItem，切场景时重新注入。
+     * @param entry 当前激活场景 entry。
+     */
+    private _injectResolver;
+    /**
+     * 安装 JSON 回写：通过 afterExecute 多回调中继点追加 JSON 同步 + 监听 history.change。
+     *
+     * CommandService 支持 addAfterExecute 多订阅，基类的 syncAllItemsFromPlayer 与此处的
+     * JSON 回写互不覆盖。undo/itemDragEnd 走事件。
+     */
+    private _installJsonSync;
+    /**
+     * 把当前 store.items（编辑模型）回写到激活场景 JSON
+     */
+    private _syncActiveItemsToJson;
+    /**
+     * 安装播放进度同步：Player 播放时经 PlayerAdapter <code>progress</code> 事件上报 composition.time，
+     * 实时写回 {@link sceneStore}.time，使 stop()/seek() 取到的是实时游标而非初始 0。
+     *
+     * progress 仅在 PlayerAdapter 内部 <code>_playing=true</code> 时发出（stop 态早退），
+     * SceneStore.time setter 纯写无副作用——故无需额外 playing 守卫，无回环风险。
+     * 切场景时 Player 重新 loadScene，progress 继续按新 composition.time 上报，自动跟随。
+     */
+    private _installProgressSync;
+    /**
+     * 安装容器 resize 同步：容器尺寸变化时重算 contentRatio/pixelRatio（contain-fit 比
+     * 依赖容器宽高）并刷新注入 ResizeSelectionGizmo，使 size 标签在 resize 后仍正确。
+     * 切场景/初始化由 _initRendererWithScene → refreshContentScale 已算首帧，此处覆盖 resize。
+     */
+    private _installResizeSync;
+    /**
+     * 释放场景 store 资源并调用基类 dispose。
+     */
+    dispose(): void;
+}

package/dist/artis/screenshot-service.d.ts

@@ -0,0 +1,83 @@
+import type { spec } from '../shared';
+/** 创建局部截图场景时的选项。 */
+export type ScreenshotSceneOptions = {
+    /**
+     * 生成场景的预览尺寸 `[width, height]`。
+     *
+     * 缺省时由所选元素的像素包围盒自动计算；传入时用于固定场景宽高比和截图画布尺寸。
+     */
+    sceneSize?: [number, number];
+    /** HTML Card 栅格化像素比，默认 2。 */
+    cardPixelRatio?: number;
+};
+/** 渲染已有 JSONScene 时的选项。 */
+export type ScreenshotRenderOptions = {
+    /**
+     * 截图播放器画布尺寸 `[width, height]`。
+     *
+     * 缺省时读取场景主合成的 `previewSize`，场景未声明时回退为 `[750, 1624]`。
+     */
+    containerSize?: [number, number];
+    /** 输出图片尺寸 `[width, height]`，缺省与 `containerSize` 相同。 */
+    size?: [number, number];
+    /** 截图时刻（秒），默认 0。 */
+    time?: number;
+    /** 输出背景色 `[r, g, b, a]`，缺省为透明。 */
+    backgroundColor?: spec.vec4;
+};
+/** 按元素 ID 直接生成截图时的选项。 */
+export type ScreenshotGenerateOptions = ScreenshotSceneOptions & Omit<ScreenshotRenderOptions, 'containerSize'>;
+/**
+ * Artis 截图服务。
+ *
+ * 该服务是截图流程的正式编排层：
+ * 1. 校验、去重并解析元素 ID；
+ * 2. 串行栅格化不属于 JSONScene 渲染树的 HTML Card；
+ * 3. 委托 {@link IOPlugin.createSceneByItemIds} 组装局部 JSONScene；
+ * 4. 使用独立的 {@link ScreenShot} Player 将 JSONScene 渲染为 PNG data URL。
+ *
+ * 推荐通过 `artis.screenshot` 使用。实例由 BaseArtis 持有并随 Artis 一起销毁，
+ * 业务方无需手动创建或释放底层 ScreenShot。
+ */
+export declare class ScreenshotService {
+    private readonly options;
+    private renderer?;
+    /**
+     * 根据元素 ID 创建可独立渲染的 JSONScene。
+     *
+     * 输入 ID 会去重，不存在的元素会被忽略；若最终没有有效元素则返回 `undefined`。
+     * HTML Card 会先按输入尺寸串行栅格化，并以 Sprite 快照写入场景。任一卡片
+     * 栅格化失败时整次创建失败，避免返回内容不完整但表面成功的场景。
+     *
+     * @param ids 单个元素 ID 或元素 ID 数组
+     * @param options 场景尺寸与 HTML Card 栅格化选项
+     * @returns 可独立渲染的 JSONScene；无有效元素或卡片栅格化失败时返回 `undefined`
+     */
+    createSceneByItemIds(ids: string | string[], options?: ScreenshotSceneOptions): Promise<spec.JSONScene | undefined>;
+    /**
+     * 将已有 JSONScene 渲染为 PNG data URL。
+     *
+     * 截图使用服务内部懒创建的独立 Player，不会改变主 Artis Player 的播放时间、尺寸或状态。
+     * 同一 ScreenshotService 会复用该 Player，避免连续截图时重复初始化渲染上下文。
+     *
+     * @param scene 要渲染的 JSONScene
+     * @param options 截图播放器尺寸、输出尺寸、时间和背景色
+     * @returns PNG data URL
+     */
+    generateScene(scene: spec.JSONScene, options?: ScreenshotRenderOptions): Promise<string>;
+    /**
+     * 根据元素 ID 创建局部场景并直接生成 PNG data URL。
+     *
+     * 这是常规元素截图的推荐入口，等价于依次调用
+     * {@link createSceneByItemIds} 与 {@link generateScene}。
+     *
+     * @param ids 单个元素 ID 或元素 ID 数组
+     * @param options 场景尺寸、输出尺寸、时间、背景色与卡片像素比
+     * @returns PNG data URL；无有效元素或 HTML Card 栅格化失败时返回 `undefined`
+     */
+    generateByItemIds(ids: string | string[], options?: ScreenshotGenerateOptions): Promise<string | undefined>;
+    /** 释放截图 Player；重复调用安全。 */
+    dispose(): void;
+    /** 获取截图 Player 包装器，首次生成截图时才创建。 */
+    private getRenderer;
+}

package/dist/artis/types.d.ts

@@ -0,0 +1,130 @@
+import type { ItemSchema, PagePreferences, ArtisBackgroundConfig, UserPreferences } from '../core/types';
+import type { BaseArtisEvents } from '../core/types/artis-events';
+import type { BaseState } from '../core/state';
+import type { Box2 } from '@vvfx/gizmo';
+import type { GizmoConfigOverride } from '../core/gizmo/gizmo-config-override';
+import { BaseArtis } from './base-artis';
+/** Artis 编辑态专属事件；不属于 BaseArtis 或 SceneArtis 的公共契约。 */
+export type ArtisStateEvents = {
+    /** 任意编辑状态切换；source 为触发切换的业务入参。 */
+    'state.change': [previousState: BaseState | undefined, currentState: BaseState, source: any];
+    /** 图片裁切框变化。 */
+    'picture-cut.change': [info: {
+        box: Box2;
+    }];
+    /** 图片扩图框变化。 */
+    'picture-expand.change': [info: {
+        box: Box2;
+    }];
+};
+/** Artis 完整事件表：BaseArtis 公共事件与编辑态专属事件的组合。 */
+export type ArtisEvents = BaseArtisEvents & ArtisStateEvents;
+/**
+ * context-lost 恢复配置（同实例轻同步，非整实例重建）。
+ *
+ * 供 ArtisOptions.contextRecovery 声明式启用与 enableContextRecovery 编程式启用共用同一形状。
+ * Player 已 opt-in 自恢复，故无重试/退避参数——engine 在 webglcontextrestored 上就地重建 GPU 资源。
+ */
+export type ContextRecoveryOptions = {
+    /** context 丢失时的通知回调（同实例 this，引用未变）——lost 冷冻期已拦截 run 等写入，宿主可据此提示"正在恢复…" */
+    onLost?: (self: BaseArtis) => void;
+    /** 恢复就绪回调（同实例 this，引用未变，无需重接 monitor）；contextRestored 事件负载含轻同步失败步骤 syncFailures */
+    onRecovered?: (self: BaseArtis) => void;
+};
+/**
+ * Artis 初始化选项
+ */
+export type ArtisOptions = {
+    /**
+     * 画布宽度（占位，未生效）。
+     * @deprecated 已声明但 BaseArtis/Renderer 从未读取（画布尺寸实际取容器 offsetWidth）。
+     * 如需固定尺寸请改容器 CSS；本字段后续将移除，勿依赖。
+     */
+    width?: number;
+    /**
+     * 画布高度（占位，未生效）。
+     * @deprecated 同 {@link width}，已声明但从未读取，后续将移除。
+     */
+    height?: number;
+    /** 背景配置 */
+    background?: ArtisBackgroundConfig;
+    /**
+     * 是否启用线框渲染（占位，未生效）。
+     * @deprecated 已声明但从未读取（线框渲染未接线），后续将移除，勿依赖。
+     */
+    enableWireframe?: boolean;
+    /** 是否启用历史记录，默认 true */
+    enableHistory?: boolean;
+    /** 历史记录最大长度，正整数（≥1），默认 100；非正数行为未定义，建议宿主自行钳位 */
+    maxHistoryLength?: number;
+    /** 要注册的 State ID 列表，对应官方预置状态，默认注册全部 */
+    states?: string[];
+    /** 初始状态 ID，默认 'move' */
+    defaultState?: string;
+    /**
+     * 插件列表（占位，未生效）。
+     * @deprecated 已声明但从未读取（插件经 PluginSystem 内部装配，非按此名称列表），后续将移除。
+     */
+    plugins?: string[];
+    /** 偏好设置预配置（终端用户个人偏好：page/item/export 等，不含 gizmo 配置） */
+    preferences?: Partial<UserPreferences>;
+    /** Gizmo 配置初始化覆盖（平台/产品级默认），构造期一次性注入。 */
+    gizmoConfigs?: readonly GizmoConfigOverride[];
+    /** 是否开启性能监测（构造期即装配，采得到 INIT 段与完整 READY 总时长），默认 false。运行期亦可用 enablePerfMonitor 开启 */
+    perf?: boolean;
+    /**
+     * 元素尺寸 0 兜底尺寸 [width, height]，默认 1024×1024。
+     *
+     * 外部传入显式 0 的 width/height 创建元素时，createItemCore 用此尺寸兜底（回写 property 落盘）
+     * 并 emit warning，避免 0 透传给 LoadingGizmo/interactionService 导致除零 NaN 挂死。运行期亦可用
+     * `artis.item...`（经 ItemService.setFallbackSize）调整。两分量均须 > 0。
+     */
+    fallbackSize?: [number, number];
+    /**
+     * 编辑操作（建/删/改/加载资源）后 goto 的 playing 参数：
+     * `true`=gotoAndPlay（Artis 默认，编辑后继续播放），
+     * `false`=gotoAndStop（SceneArtis 默认，保持 stop 态可编辑）。
+     * 由 BaseArtis 透传给 Renderer 作为「编辑后渲染刷新」单一真源，服务层经 `renderer.gotoEdit()` 调用。缺省 true。
+     */
+    editGotoPlaying?: boolean;
+    /**
+     * 自动恢复（WebGL context-lost）声明式配置。传入即在构造期自动启用 enableContextRecovery（同实例轻同步），
+     * 免去宿主单独调用；不传则不自动启用。形状与 enableContextRecovery 编程式入参一致（{@link ContextRecoveryOptions}）。
+     * 恢复就绪事件 contextRestored 带轻同步失败步骤 syncFailures；onLost/onRecovered 见该类型。
+     */
+    contextRecovery?: ContextRecoveryOptions;
+    /**
+     * @deprecated 旧名字，语义误导（实际为同实例轻同步非 recreate）。别名指向 {@link contextRecovery}，
+     * 构造期读取时 `contextRecovery ?? autoRecreate` 兼容旧宿主，后续版本将移除。
+     */
+    autoRecreate?: ContextRecoveryOptions;
+};
+/**
+ * run() 方法的输入参数
+ */
+export type ArtisRunInput = {
+    /** 页面选项覆盖 */
+    options?: Partial<PagePreferences>;
+    /** 初始元素数据 */
+    items?: ItemSchema[];
+    /** 视口参数列表 */
+    viewParams?: ArtisViewParam[];
+};
+/**
+ * 视口参数（对应原 ViewParam）
+ */
+export type ArtisViewParam = {
+    /** 画布尺寸 [width, height]，均须 >0（非正值会让下游 layout/viewport 计算产生 NaN/负 box） */
+    size: [number, number];
+    /** 导出配置 */
+    export?: {
+        /** 导出帧时间（秒，≥0；负值行为未定义） */
+        time?: number;
+        /** 是否包含音频 */
+        audioEnable?: boolean;
+        /** 导出文件名 */
+        name?: string;
+    };
+    /** 出血安全区 [top, right, bottom, left]，各分量 ≥0；超出画布的值由下游裁剪，建议 0~size */
+    safeArea?: [number, number, number, number];
+};

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

@@ -0,0 +1,17 @@
+/**
+ * Artis 装配胶水层（wiring）。
+ *
+ * 这里只做「把 BaseArtis 已建好的核心服务接起来」的胶水工作——注册命令、激活插件、
+ * 绑定事件转发——不持有状态，也不构造任何服务，故所有函数都必须在 BaseArtis 构造装配完成后调用。
+ *
+ * 与 `register-commands`（把 core 的 Command 类按对外 id 绑进 CommandService）同属装配层，
+ * 一起收口在本子目录，使 `artis/` 顶层只剩门面、变体与对外契约。
+ */
+export { setupCommands } from './setup-commands';
+export { setupPlugins } from './setup-plugins';
+export { setupCoreEventBindings, setupSelectionBindings } from './setup-event-bindings';
+export { registerCommands } from './register-commands';
+export type { RegisterCommandsContext } from './register-commands';
+export { setupKeyBindings } from './setup-keybindings';
+export type { KeyBindingWiringContext } from './setup-keybindings';
+export type { WiringContext } from './wiring-context';

package/dist/artis/wiring/register-commands.d.ts

@@ -0,0 +1,44 @@
+import type { ItemCreateType, Selection } from '@vvfx/gizmo';
+import { CommandService, ItemService, ViewService, type Store, type StateManager } from '../../core';
+/**
+ * 命令目标元素 id 提取器注册表（单一真源，F1）。
+ *
+ * 供 ignored-interaction 守卫按 commandId 查询命令携带的目标元素 id，使命令 args 形状与
+ * 守卫所需 id 提取同源维护——新增/改命令时只需在此登记一次，避免守卫侧另硬编码一份平行表
+ * （漏登记则守卫对该命令静默跳过，与未携带目标元素的命令行为一致）。
+ *
+ * 键受 {@link CommandRegistry} 约束（防 drift / typo），未登记命令缺省 undefined → 守卫跳过。
+ * 值读取对象 args 的具名字段（itemId / itemIds / childrenIds / groupId / newSelectedIds / frameId 等）。
+ * 模块加载即静态就绪（不依赖 registerCommands() 调用），消除初始化顺序耦合与多实例冗余填充。
+ * 返回 undefined 表示该命令不携带可校验的元素目标（如新建/视口操作），守卫跳过。
+ */
+export declare const COMMAND_TARGET_ID_EXTRACTORS: Partial<Record<string, (args: unknown) => string[] | undefined>>;
+/**
+ * 注册命令所需的上下文依赖
+ */
+export type RegisterCommandsContext = {
+    /** 命令注册目标 */
+    commandService: CommandService;
+    /** 使用 getter 延迟获取，确保 itemService 初始化后可用 */
+    getItemService: () => ItemService;
+    /** 编辑数据 store */
+    store: Store;
+    /** 选中态真源 getter：Selection 由 GizmoManager 装配后才存在，命令工厂在装配后执行时按需求值 */
+    getSelection: () => Selection;
+    /** 视口服务 */
+    viewService: ViewService;
+    /** 交互状态管理器 getter：供 item.createInteractive 等切态命令用，gestureHandler 就绪后取值 */
+    getStateManager: () => StateManager;
+    getItemCreateType: () => ItemCreateType;
+    setItemCreateType: (value: ItemCreateType) => void;
+};
+/**
+ * 注册所有预置 Commands 到 CommandService
+ *
+ * 将 Artis 构造函数中的 Command 注册逻辑抽离，便于维护与阅读。
+ * 工厂入参为<b>单参对象</b>（与 {@link ../../core/command/registry.ts | CommandRegistry} args 形状同源），
+ * 字段名与各 Command 的 XxxCommandArgs 对齐，工厂体可 spread 透传 `new XxxCommand({ ...args, deps })`，
+ * 删除原位置参数 `args[N] as T` cast 群。内部依赖（itemService/store/stateManager/applyXxx 等）由 wiring 注入。
+ * @param context 注册命令所需的上下文依赖。
+ */
+export declare function registerCommands(context: RegisterCommandsContext): void;

package/dist/artis/wiring/setup-commands.d.ts

@@ -0,0 +1,5 @@
+import type { WiringContext } from './wiring-context';
+/**
+ * 注册内置 Command，并配置命令执行后、历史变化后的同步与事件转发。
+ */
+export declare function setupCommands(ctx: WiringContext): void;