@vvfx/artis 0.0.1-alpha.0

package/dist/core/plugin/io-plugin.d.ts

@@ -0,0 +1,167 @@
+import { spec } from '../../shared';
+import { type Store } from '../store';
+import { type AssetManager } from '../asset';
+import { type ArtisPlugin } from './plugin-system';
+import { Renderer } from '../renderer';
+import { type ViewService } from '../service';
+/**
+ * IOPlugin - JSON 序列化/反序列化插件
+ *
+ * 职责：
+ * 1. 从 Store.items + AssetManager + Player VFXItems → 生成完整 JSONScene（exportScene）
+ * 2. 单个 item 序列化（用于复制粘贴等场景）
+ *
+ * ItemService 不再直接操作 Scene JSON，所有 JSON 的生成统一在此处完成。
+ */
+export declare class IOPlugin implements ArtisPlugin {
+    /** 插件 ID 常量（供非实例处引用，如 SceneArtis 通过 pluginSystem.getPlugin 取实例） */
+    static readonly pluginId = "io-plugin";
+    readonly id = "io-plugin";
+    readonly name = "IO Plugin";
+    readonly version = "1.0.0";
+    readonly description = "Handles JSON scene serialization/deserialization";
+    private _store;
+    private _assetManager;
+    private _renderer;
+    private _viewService;
+    /**
+     * 激活插件，注入 Store / AssetManager / Renderer / ViewService 依赖
+     *
+     * @param host 宿主提供的依赖集合
+     */
+    activate(host: {
+        store: Store;
+        assetManager: AssetManager;
+        renderer: Renderer;
+        viewService: ViewService;
+    }): void;
+    /** 停用插件，清空所有依赖引用 */
+    deactivate(): void;
+    /**
+     * 从 Store + AssetManager + Renderer 状态导出完整的 JSONScene
+     *
+     * 遍历 Store.items，结合 AssetManager 中的资源信息和 Renderer 中的 VFXItem 变换数据，
+     * 生成标准的 spec.JSONScene 结构。
+     *
+     * @returns 完整的 JSONScene 数据
+     */
+    exportScene(): spec.JSONScene;
+    /**
+     * 序列化单个 item 为 JSON 数据（用于复制粘贴）
+     *
+     * @param id 目标元素 ID
+     * @returns 元素 JSON 与组件数据，未激活/无合成/无元素时返回 undefined
+     */
+    serializeItem(id: string): {
+        item: spec.VFXItemData;
+        components: spec.ComponentData[];
+    } | undefined;
+    /**
+     * 序列化单个 item 为 **含资源** 的完整 JSON 片段（item + components + images/videos/textures）。
+     *
+     * 与 {@link serializeItem} 的区别：后者只返回 item+components、丢弃资源数组；
+     * 本方法把资源数组一并返回，供 {@link JsonSceneSyncService} 会话内新建元素 insert 时
+     * 联动并入 scene.images/videos/textures，保证 reload 后图/视频资源可复建。
+     *
+     * @param id 目标元素 ID
+     * @returns item+components+resources；未激活/无合成/无元素时返回 undefined
+     */
+    serializeItemWithAssets(id: string): {
+        item: spec.VFXItemData;
+        components: spec.ComponentData[];
+        images: spec.ImageSource[];
+        videos: spec.VideoInfo[];
+        textures: spec.SerializedTextureSource[];
+    } | undefined;
+    /**
+     * 序列化单个元素为 JSON 数据（含图片/视频/纹理资源收集）。
+     *
+     * 不再读 playerItem.transform——世界坐标口径由调用方通过 {@link SerializeItemTransform} 传入：
+     * - exportScene / serializeItem / serializeItemWithAssets 透传 playerItem.transform（local 口径）
+     * - createSceneByItemIds 用 artisItem 绝对像素 + interactionService 换算
+     *
+     * @param artisItem 业务层元素
+     * @param transform 已算好的世界坐标 transform（见 {@link SerializeItemTransform}）
+     * @param assetManager 资源管理器
+     * @param images 输出：图片资源列表
+     * @param videos 输出：视频资源列表
+     * @param textures 输出：纹理资源列表
+     * @param itemSnapshotUrls 元素 ID 到图片快照 URL 的映射；命中时优先序列化为 Sprite
+     * @returns 元素 JSON 信息，类型不支持时返回 undefined
+     */
+    private serializeItemToJSON;
+    /**
+     * 从 playerItem.transform 透传构造序列化 transform（local 口径）。
+     *
+     * 供 exportScene / serializeItem / serializeItemWithAssets 维持原"读 playerItem.transform"行为：
+     * 这些场景导出整个场景或单元素快照，元素仍处于原 parent 下的 local transform。
+     */
+    private _playerItemTransformToSerialize;
+    /**
+     * 根据 ArtisItem ID 列表创建 spec.JSONScene
+     *
+     * 三步流程：
+     * 1. 取元素 → 算所选元素基准像素 unionBox → previewSize → 建基础场景取相机，算 world-per-pixel 比例
+     * 2. 逐元素按「像素属性 + VP 矩阵比例」算世界坐标 transform → 序列化为 ItemJSON
+     * 3. 组装 JSONScene 导出
+     *
+     * 坐标口径：不依赖 InteractionService（其相机/视口参数取自源场景，与新场景不一致）。改为结合新场景
+     * 尺寸（previewSize）+ 新场景相机 + 元素像素属性：用 getBasicScene(previewSize).camera 建 VP 矩阵，
+     * unproject 得 world-per-pixel 比例 (xRatio, yRatio)；元素世界尺寸 = 像素尺寸 × 比例，元素世界位置 =
+     *（盒心 - union 盒心）× (xRatio, -yRatio)（union 盒心对应新场景世界原点，Y 翻转）。
+     * 原生支持 SPRITE/TEXT/VIDEO 序列化；提供图片快照的元素会以 Sprite 替身导出，
+     * 其余类型跳过（GROUP/Frame 仍参与 unionBox 计算）。
+     *
+     * @param ids 要导出的 ArtisItem ID（单个或多个）
+     * @param options 可选参数
+     * @param options.sceneSize 场景预览尺寸，不传则根据元素包围盒自动计算
+     * @param options.name 合成名称
+     * @param options.itemSnapshotUrls 元素 ID 到图片快照 URL 的映射；命中时以 Sprite 替代原元素序列化
+     */
+    createSceneByItemIds(ids: string | string[], options?: {
+        sceneSize?: [number, number];
+        name?: string;
+        itemSnapshotUrls?: ReadonlyMap<string, string>;
+    }): spec.JSONScene;
+    /**
+     * 按新场景相机 VP 矩阵算 world-per-pixel 比例 (xRatio, yRatio)。
+     *
+     * 用 camera.position 建 viewMatrix（仅平移、旋转/缩放单位）、camera.fov+previewSize 比例 建 perspective，
+     * 组成 vpMatrix 后 unproject NDC (0,0,z)~(2,2,z)（z 为世界原点投影后的 NDC z）得到世界两点，
+     * 其差 / previewSize 即每像素对应的世界单位（z=0 平面）。与 json-data-utils.calcWorldSizeByCamera 同口径，
+     * 但输出比例供逐元素复用。perspective 第 5 参（clipMode===1 → portrait）与 interaction-service 一致。
+     *
+     * @param camera 合成相机配置（spec.CameraOptions，含 fov/near/far/clipMode/position）
+     * @param previewSize 合成预览尺寸（像素），其宽高比作 aspect
+     * @returns { xRatio, yRatio } 每像素对应的世界单位
+     */
+    private _computeWorldPixelRatios;
+    /**
+     * 按 artisItem 像素属性 + (xRatio, yRatio) 换算导出用世界坐标 transform。
+     *
+     * - position：(itemBox.center - unionBox.center) × (xRatio, -yRatio)。unionBox 中心对应新场景世界原点，
+     *   Y 取负（场景 Y 朝上、像素 Y 朝下）。落在 z=0 平面（VP 比例的计算平面）。
+     * - size：像素尺寸 (width, height) × (xRatio, yRatio)（TEXT 高度缺省取 lineHeight）。不含 scale。
+     * - rotation：Z 轴取负（与 createItemCore 一致）
+     * - scale：直接取 property.scale
+     *
+     * GROUP 等空节点 / 缺宽高元素返回 undefined（serializeItemToJSON 也会跳过）。
+     *
+     * @param artisItem 业务层元素
+     * @param unionBox 所选元素并集盒（中心对应新场景世界原点）
+     * @param xRatio / yRatio world-per-pixel 比例（由 _computeWorldPixelRatios 算出）
+     * @returns 世界坐标 transform；空节点/缺尺寸返回 undefined
+     */
+    private _computeExportTransform;
+    /**
+     * 按所选元素的基准设计像素包裹盒求并集。
+     *
+     * 直接从 Store 取 artisItem 还原为 ItemSchema（toSchema），再调纯函数 `getPixelBoxBySchemas`
+     * （utils/pixel-box-utils）按元素实际数据（position + width/height 补乘 scale + rotation）算盒
+     * （GROUP 等空节点按子元素 union），最后对结果取并集。返回空盒表示无有效元素（由上层走 previewSize 兜底）。
+     *
+     * @param itemIds 所选元素 id 列表
+     * @returns 并集基准设计像素包围盒；无有效元素时返回空盒
+     */
+    private _computeSelectedItemsPixelBox;
+}

package/dist/core/plugin/plugin-system.d.ts

@@ -0,0 +1,77 @@
+import type { Disposable } from '../types';
+/**
+ * ArtisPlugin - 插件接口
+ * activate/deactivate 接收宿主实例（使用泛型避免循环依赖）
+ */
+export type ArtisPlugin<Host = unknown> = {
+    id: string;
+    name: string;
+    version: string;
+    description?: string;
+    dependencies?: string[];
+    activate(host: Host): void | Promise<void>;
+    deactivate(): void | Promise<void>;
+};
+/**
+ * PluginSystem - 插件管理器
+ */
+export declare class PluginSystem<Host = unknown> implements Disposable {
+    private _plugins;
+    private _activePlugins;
+    /**
+     * 注册插件
+     *
+     * @param plugin 插件对象
+     * 边界：同 id 的插件会覆盖旧注册项，不会触发激活
+     */
+    registerPlugin(plugin: ArtisPlugin<Host>): void;
+    /**
+     * 注销插件
+     *
+     * @param pluginId 插件 ID
+     * 边界：若该插件已激活，会先调用其 deactivate 再移除
+     */
+    unregisterPlugin(pluginId: string): void;
+    /**
+     * 激活插件，调用插件 activate 并将其加入已激活集合
+     *
+     * @param pluginId 插件 ID
+     * @param host 宿主实例，透传给插件 activate
+     * @returns 激活完成的 Promise
+     * 边界：插件不存在时抛错；activate 抛错则不会被标记为已激活
+     */
+    activatePlugin(pluginId: string, host: Host): Promise<void>;
+    /**
+     * 停用插件，调用插件 deactivate 并将其移出已激活集合
+     *
+     * @param pluginId 插件 ID
+     * @returns 停用完成的 Promise
+     * 边界：插件不存在或未激活时直接返回，不抛错
+     */
+    deactivatePlugin(pluginId: string): Promise<void>;
+    /**
+     * 按 ID 获取插件。
+     *
+     * @param pluginId 插件 ID
+     * @returns 插件对象；未注册返回 undefined
+     */
+    getPlugin(pluginId: string): ArtisPlugin<Host> | undefined;
+    /**
+     * 获取所有已注册插件（含未激活）。
+     *
+     * @returns 全部已注册插件数组
+     */
+    getAllPlugins(): ArtisPlugin<Host>[];
+    /**
+     * 获取当前已激活的插件列表。
+     *
+     * @returns 已激活插件数组
+     */
+    getActivePlugins(): ArtisPlugin<Host>[];
+    /**
+     * 销毁插件系统
+     *
+     * 边界：先依次停用所有已激活插件，再清空注册表
+     */
+    dispose(): Promise<void>;
+}

package/dist/core/predict/align-predict.d.ts

@@ -0,0 +1,20 @@
+import type { Box2 } from '@vvfx/gizmo';
+import type { AlignType } from '../../utils/types';
+/**
+ * item.align 的离线预测算法（在 {@link ItemAlignCommand} 内的同源实现）。
+ *
+ * 以所有元素像素包围盒的并集为基准，每个元素按对齐类型沿单一轴向平移，使其包围盒对应边/中线
+ * 与整体并集对齐（另一轴向保持不变）。纯函数、无 Player 依赖——Command 实现（执行真相）与
+ * Agent predictor（预测真相）共用本函数，避免两份几何发散。
+ */
+export type BoxInput = {
+    id: string;
+    box: Box2;
+};
+/**
+ * 计算各元素对齐后的中心位置。
+ * @param inputs 元素 ID + 像素包围盒列表
+ * @param alignType 对齐类型（left/right/horizontal-center/top/bottom/vertical-center）
+ * @returns 元素 ID → 对齐后中心 [x, y]；元素数少于 2 时返回空映射（与命令 execute 守卫一致）
+ */
+export declare function computeAlignedPositions(inputs: BoxInput[], alignType: AlignType): Map<string, [number, number]>;

package/dist/core/predict/base/box-ops.d.ts

@@ -0,0 +1,40 @@
+import { Box2 } from '@vvfx/gizmo';
+/**
+ * 原子包围盒运算基础方法（box-ops）。
+ *
+ * 语义薄包装层——权威盒运算在 @vvfx/gizmo 的 Box2，此处不重写 union/rotate 等几何，
+ * 只把「命令实现 / Agent 预测」反复重抄的盒运算收敛成统一语义入口，使执行真相与预测真相同源。
+ *
+ * 纯函数、无 Player / Store / 命令依赖，可离线单测。
+ */
+/**
+ * 计算多个包围盒的并集。
+ *
+ * 收编此前散落在 {@link ItemAlignCommand._computeUnionBox}（item-align-command.ts:154）等命令内
+ * 的重抄实现。空数组返回空盒（与 Box2 默认一致）。
+ * @param boxes 参与并集的包围盒
+ * @returns 并集包围盒（新实例，不污染入参）
+ */
+export declare function unionBoxes(boxes: Box2[]): Box2;
+/**
+ * 取包围盒中心 [x, y]。空盒返回 [0, 0]（与 Box2.getCenter 空盒语义一致）。
+ */
+export declare function boxCenter(box: Box2): [number, number];
+/**
+ * 取包围盒尺寸 [width, height]。空盒返回 [0, 0]。
+ */
+export declare function boxSize(box: Box2): [number, number];
+/**
+ * 按新中心位置 / 旋转 / 缩放重算包围盒。
+ *
+ * 以入参 box 的尺寸为基础（width/height），先乘 scale，再以 pos 为中心、rot（角度）旋转，
+ * 得到变换后包围盒。复用 {@link Box2.setFromCenterAndSize} + {@link Box2.rotate} 的口径，
+ * 与 `getPixelBoxBySchema`（utils/pixel-box-utils.ts:32）保持一致，避免两份变换真相。
+ *
+ * @param box 基础尺寸盒（仅取其 width/height，不关心其当前位置/旋转）
+ * @param pos 新中心位置
+ * @param rot 旋转角度（度），缺省 0
+ * @param scale [sx, sy] 缩放，缺省 [1, 1]
+ * @returns 变换后包围盒（新实例）
+ */
+export declare function transformBox(box: Box2, pos: [number, number], rot?: number, scale?: [number, number]): Box2;

package/dist/core/predict/base/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 基础计算方法层 base —— 原子几何收敛入口。
+ *
+ * 包围盒运算、schema↔box 映射、父级坐标换算等被命令实现 / Agent 预测反复使用的原子计算
+ * 收敛于此。层级自底向上：base（原子）→ `core/predict/*-predict`（算法组合）→
+ * 同时被 Command 实现（算几何后写副作用）与 Agent predictor（纯预测）消费，
+ * 使执行真相 = 预测真相，无需事后对账。
+ *
+ * 全部纯函数、无 Player / Store / 命令依赖，可离线单测。
+ */
+export { unionBoxes, boxCenter, boxSize, transformBox, } from './box-ops';
+export { getPixelBoxBySchema, getPixelBoxBySchemas, schemaToBoxMap, } from './schema-box';
+export type {} from './schema-box';
+export { worldToLocalBox, localToWorldBox } from './parent-coord';

package/dist/core/predict/base/parent-coord.d.ts

@@ -0,0 +1,29 @@
+import { Box2 } from '@vvfx/gizmo';
+/**
+ * 父级局部坐标换算基础方法。
+ *
+ * 供 group / ungroup / frame.moveIn / frame.moveOut 等命令的离线预测：元素在进出父级
+ * （Frame / Group）时，其世界包围盒需换算到父级局部空间或反之，以保持视觉位置不变
+ * （与运行时 `getItemTransformUnderParent` 的「Frame reparent 变换保持」语义对齐）。
+ *
+ * 本轮只提供基于包围盒的换算（非矩阵精确变换）；精确父子变换保持仍由运行时
+ * ItemService / Player 路径承担，此处仅服务于 Agent 的包围盒级 dry-run 预测。纯函数、可离线单测。
+ */
+/**
+ * 父级局部坐标基于其包围盒中心换算：把子元素的世界盒换算为以父级中心为原点的局部盒。
+ *
+ * 即 `childBox.translate(-parentCenter)`。父级空盒时原样返回子盒（无父级信息可依）。
+ * @param childBox 子元素世界包围盒
+ * @param parentBox 父级包围盒（取其中心作为局部原点）
+ * @returns 父级局部空间下的子盒（新实例）
+ */
+export declare function worldToLocalBox(childBox: Box2, parentBox: Box2): Box2;
+/**
+ * 局部坐标反算回世界：把父级局部空间下的子盒换算回世界空间。
+ *
+ * 即 `childBox.translate(+parentCenter)`。父级空盒时原样返回。
+ * @param childBox 父级局部空间下的子盒
+ * @param parentBox 父级包围盒（取其中心作为局部原点）
+ * @returns 世界空间下的子盒（新实例）
+ */
+export declare function localToWorldBox(childBox: Box2, parentBox: Box2): Box2;

package/dist/core/predict/base/schema-box.d.ts

@@ -0,0 +1,21 @@
+import type { Box2 } from '@vvfx/gizmo';
+import { getPixelBoxBySchema, getPixelBoxBySchemas } from '../../../utils/pixel-box-utils';
+import type { ItemSchema } from '../../types';
+/**
+ * ItemSchema ↔ 像素包围盒映射的基础方法入口。
+ *
+ * 本轮收敛 + 重导出现有的纯计算器（utils/pixel-box-utils），让 `core/predict/base` 成为统一入口；
+ * 旧 utils 文件不删，留待后续轮次迁移。权威实现仍在像素盒计算器处，base 不重写算法。
+ */
+/**
+ * 按单个 ItemSchema 计算像素包围盒（离线、无 Player）。重导出便于统一入口。
+ * @see utils/pixel-box-utils.ts:getPixelBoxBySchema
+ */
+export { getPixelBoxBySchema, getPixelBoxBySchemas };
+/**
+ * 批量按 ItemSchema 算包围盒，返回 元素ID → Box2 映射。
+ *
+ * 复用 {@link getPixelBoxBySchemas}（含 GROUP 空节点按 children union 收敛、环防护），
+ * 作为 base 的便捷封装：predictor 与命令算法都经此取盒，保证口径一致。
+ */
+export declare function schemaToBoxMap(schemas: ItemSchema[]): Map<string, Box2>;

package/dist/core/predict/distribute-predict.d.ts

@@ -0,0 +1,19 @@
+import type { DistributeType } from '../../utils/types';
+/**
+ * item.distribute 的离线预测算法（在 {@link ItemDistributeCommand} 内的同源实现）。
+ *
+ * 沿分布方向按元素中心排序，固定首尾两个元素，将中间元素的中心点等间距铺开；与分布方向正交的
+ * 轴保持不变。纯函数、无 Player 依赖——Command 实现（执行真相）与 Agent predictor（预测真相）
+ * 共用本函数，避免两份几何发散。
+ */
+export type CenterInput = {
+    id: string;
+    center: [number, number];
+};
+/**
+ * 计算各元素分布后的中心位置。
+ * @param inputs 元素 ID + 当前中心 [x, y] 列表
+ * @param distributeType 分布类型（horizontal-spacing / vertical-spacing）
+ * @returns 元素 ID → 分布后中心 [x, y]；空列表返回空映射
+ */
+export declare function computeDistributedPositions(inputs: CenterInput[], distributeType: DistributeType): Map<string, [number, number]>;

package/dist/core/predict/frame-layout-predict.d.ts

@@ -0,0 +1,24 @@
+import type { FrameLayoutItem, FrameAutoLayoutOptions, FrameAutoLayoutResult } from '@vvfx/gizmo';
+import { computeFrameAutoLayout } from '@vvfx/gizmo';
+import type { ItemSchema, FrameItemSchema } from '../types';
+/**
+ * frame.autoLayout 的离线预测入口。
+ *
+ * 布局算法本体（`computeFrameAutoLayout`）已在 @vvfx/gizmo/frame-auto-layout 内为纯函数，
+ * 此处直接 re-export 暴露为 Artis 侧统一入口，并补一个把子元素 ItemSchema + Frame schema
+ * 组装成纯布局输入的适配器。不重写算法，避免两份布局真相。
+ *
+ * Command 实现（FrameService → FrameModule.computeAutoLayout）与 Agent predictor 经此入口
+ * 调同一份 gizmo 纯算法。
+ */
+export { computeFrameAutoLayout, type FrameLayoutItem, type FrameAutoLayoutOptions, type FrameAutoLayoutResult, };
+/**
+ * 从子元素 ItemSchema + 画板 schema 组装离线布局输入。
+ * @param childrenSchemas 画板子元素 schema 列表
+ * @param frame 画板 schema（取其 autoLayoutConfig 作为布局配置）
+ * @returns { items: 含包围盒的布局项, options: padding/gap/config }
+ */
+export declare function buildFrameLayoutInput(childrenSchemas: ItemSchema[], frame: FrameItemSchema): {
+    items: FrameLayoutItem[];
+    options?: FrameAutoLayoutOptions;
+};

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

@@ -0,0 +1,12 @@
+/**
+ * 离线计算方法层（base 原子 + *-predict 算法组合）。
+ *
+ * - `base/`：原子几何（盒运算 / schema↔box / 父级坐标），纯函数。
+ * - `*-predict`：在 base 之上的算法组合（align / distribute / frame-layout）。
+ *
+ * 两者同时被 Command 实现（执行真相）与 Agent predictor（预测真相）消费——同源即一致。
+ */
+export * from './base';
+export * from './align-predict';
+export * from './distribute-predict';
+export * from './frame-layout-predict';

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

@@ -0,0 +1,2 @@
+export { UserPreferencesManager } from './user-preferences-manager';
+export type { UserPreferencesEvents } from './user-preferences-manager';

package/dist/core/preferences/user-preferences-manager.d.ts

@@ -0,0 +1,130 @@
+import { EventEmitter } from '../../shared';
+import type { UserPreferences, ItemPreferences, ExportPreferences, ScreenshotPreferences, SizeAdaptPreferences, AsyncLoadPreferences, CardTypeConfig, PagePreferences } from '../types';
+/**
+ * UserPreferencesManager 事件
+ *
+ * 本管理器只管终端用户个人偏好（page/item/export/screenshot/sizeAdapt/asyncLoad），
+ */
+export type UserPreferencesEvents = Record<string, never>;
+/**
+ * UserPreferencesManager - 个人偏好管理器
+ *
+ * 仅管理终端用户个人偏好（页面/元素/导出/截图等终端用户功能开关），不再持有 Gizmo 配置。
+ */
+export declare class UserPreferencesManager extends EventEmitter<UserPreferencesEvents> {
+    private _preferences;
+    /** 已注册的卡片类型列表（对应原 SDKConfig.itemConfig.cardConfig.cardTypes） */
+    private _cardTypes;
+    /**
+     * 初始化配置管理器。卡片类型由业务或 Demo 显式注册。
+     *
+     * @param initial 初始偏好片段（可选，未传则全量使用默认值）
+     */
+    constructor(initial?: Partial<UserPreferences>);
+    /** 页面级偏好（静态预览/缩放/分组可见等） */
+    get page(): PagePreferences;
+    /**
+     * 局部更新页面偏好，与现有值浅合并。
+     *
+     * @param config 待合并的字段
+     */
+    setPage(config: Partial<PagePreferences>): void;
+    /** 元素（frame/card）相关偏好 */
+    get item(): ItemPreferences;
+    /**
+     * 局部更新元素偏好，frame 与 card 分别浅合并。
+     *
+     * @param config 待合并的元素偏好片段
+     */
+    setItem(config: Partial<ItemPreferences>): void;
+    /** 导出功能偏好 */
+    get export(): ExportPreferences;
+    /**
+     * 局部更新导出偏好，与现有值浅合并。
+     *
+     * @param config 待合并的字段
+     */
+    setExport(config: Partial<ExportPreferences>): void;
+    /** 截图功能偏好 */
+    get screenshot(): ScreenshotPreferences;
+    /**
+     * 局部更新截图偏好，与现有值浅合并。
+     *
+     * @param config 待合并的字段
+     */
+    setScreenshot(config: Partial<ScreenshotPreferences>): void;
+    /** 尺寸自适应偏好 */
+    get sizeAdapt(): SizeAdaptPreferences;
+    /**
+     * 局部更新尺寸自适应偏好，与现有值浅合并。
+     *
+     * @param config 待合并的字段
+     */
+    setSizeAdapt(config: Partial<SizeAdaptPreferences>): void;
+    /** 异步加载偏好 */
+    get asyncLoad(): AsyncLoadPreferences;
+    /**
+     * 局部更新异步加载偏好，与现有值浅合并。
+     *
+     * @param config 待合并的字段
+     */
+    setAsyncLoad(config: Partial<AsyncLoadPreferences>): void;
+    /**
+     * 注册单个卡片类型（已存在则忽略）。
+     *
+     * @param cardTypeConfig 卡片类型配置
+     * @returns 是否注册成功（type 已存在时返回 false）
+     */
+    registerCardType(cardTypeConfig: CardTypeConfig): boolean;
+    /**
+     * 批量注册卡片类型。
+     *
+     * @param configs 卡片类型配置数组
+     * @returns 成功注册的数量
+     */
+    registerCardTypes(configs: CardTypeConfig[]): number;
+    /**
+     * 注销卡片类型。
+     *
+     * @param type 卡片类型标识
+     * @returns 是否注销成功（type 不存在时返回 false）
+     */
+    unregisterCardType(type: string): boolean;
+    /**
+     * 获取所有已注册的卡片类型（只读副本）。
+     *
+     * @returns 卡片类型配置数组的浅拷贝
+     */
+    getRegisteredCardTypes(): CardTypeConfig[];
+    /**
+     * 判断卡片类型是否已注册。
+     *
+     * @param type 卡片类型标识
+     * @returns 是否已注册
+     */
+    isCardTypeRegistered(type: string): boolean;
+    /**
+     * 获取完整偏好设置。
+     *
+     * @returns 当前全量偏好对象
+     */
+    getPreferences(): UserPreferences;
+    /**
+     * 批量更新偏好设置，在现有偏好基础上重新合并默认值。
+     *
+     * @param preferences 待合并的偏好片段
+     */
+    setPreferences(preferences: Partial<UserPreferences>): void;
+    /**
+     * 重置为默认配置
+     */
+    reset(): void;
+    /**
+     * 将局部偏好与默认值合并，未传字段回退到默认。
+     *
+     * @param partial 局部偏好片段（可选）
+     * @param base 合并基底（可选，缺省时使用深拷贝的默认偏好）
+     * @returns 合并后的完整偏好
+     */
+    private mergeDefaults;
+}

package/dist/core/quality/error-monitor/error-monitor-facade.d.ts

@@ -0,0 +1,73 @@
+import { ErrorMonitor } from './error-monitor';
+import type { ErrorMonitorCallback, VariantErrorSnapshot } from './types';
+import type { HistoryManager } from '../../history';
+import type { CommandService } from '../../command';
+import type { Selection } from '@vvfx/gizmo';
+import type { ViewService } from '../../service';
+import type { ItemService } from '../../service';
+import type { Renderer } from '../../renderer';
+import type { GestureHandler } from '@vvfx/gizmo';
+/**
+ * 被监控实例的最小结构：可按方法名读取/覆写方法（用于高阶函数包装）。
+ * BaseArtis 实例结构化兼容，传入时显式 cast 即可。
+ */
+export type ErrorMonitorFacadeTarget = Record<string, ((...args: any[]) => unknown) | undefined>;
+/**
+ * ErrorMonitorFacade 装配所需的最小上下文：核心只读服务 + 被监控实例。
+ *
+ * selection 由 GizmoManager 装配后才存在，且 enableErrorMonitor 可在 run 之前调用，
+ * 故以 getter 注入（在读取选中态时按需求值，避免提前访问未装配的 GizmoManager）。
+ */
+export type ErrorMonitorContext = {
+    readonly historyManager: HistoryManager;
+    readonly commandService: CommandService;
+    readonly getSelection: () => Selection | undefined;
+    readonly viewService: ViewService;
+    readonly itemService: ItemService;
+    readonly container: HTMLElement;
+    readonly renderer: Renderer;
+    readonly gestureHandler: GestureHandler;
+    readonly target: ErrorMonitorFacadeTarget;
+    /**
+     * 取变体专属错误快照（variant tag + 对应形态 snapshot），由 Artis / SceneArtis 上下文注入。
+     * 基类不注入。供 ErrorMonitor 在 capture 时按 tag 合并出含子类专属字段的完整快照。
+     * 失败 / 缺省时返回 undefined，artisVariant 兜底为 'Artis'、变体字段缺省。
+     */
+    readonly getArtisErrorSnapshot?: () => VariantErrorSnapshot | undefined;
+};
+/**
+ * ErrorMonitorFacade - 错误监控门面协作者。
+ *
+ * 从 BaseArtis 抽离，承载 ErrorMonitor 的创建、注入、渲染错误监听与公开方法包装。
+ * 重复 enable 只更新回调，不重复注入监控器 / 不重复包装方法。
+ */
+export declare class ErrorMonitorFacade {
+    private readonly ctx;
+    private _monitor?;
+    private _methodsWrapped;
+    constructor(ctx: ErrorMonitorContext);
+    /** 底层 ErrorMonitor（供 StabilityFacade 注入节流前错误钩子；未开启时为 undefined） */
+    get monitor(): ErrorMonitor | undefined;
+    /**
+     * 开启错误监控：创建 ErrorMonitor → 注入 CommandService/GestureHandler →
+     * 绑定渲染错误监听 → 包装门面层公开方法。重复调用仅更新回调。
+     * @param callback 错误上报回调
+     */
+    enable(callback: ErrorMonitorCallback): void;
+    /**
+     * 尝试绑定 Player 渲染错误监听。
+     * 在 enable 与 run（renderer 就绪）阶段各调一次，确保两种调用顺序都能正确绑定。
+     */
+    tryBindRendererErrorListener(): void;
+    /**
+     * 销毁监控器（清除节流记录与回调引用）。
+     */
+    dispose(): void;
+    /** 若监控器与 Player 已就绪，则绑定渲染错误监听；否则安全跳过。 */
+    private _tryBindRendererErrorListener;
+    /**
+     * 使用高阶函数包装门面层公开方法，报错时自动上报 ErrorMonitor。
+     * 包装后方法行为不变（错误继续向上抛），仅额外触发 monitor.report。
+     */
+    private _wrapPublicMethods;
+}