@vvfx/artis 0.0.1-alpha.0

package/dist/core/state/state-manager.d.ts

@@ -0,0 +1,50 @@
+import { EventEmitter } from '@galacean/effects';
+import { BaseState } from './base-state';
+import type { StateId, StateManagerEventMap, StateNavigator, StateTransitionRuntime } from './types';
+import type { GizmoRegistrationId, GizmoRegistry, RegisteredGizmoFactory } from '../gizmo/gizmo-registry';
+export type StateManagerOptions = {
+    readonly runtime?: StateTransitionRuntime;
+    readonly gizmos?: GizmoRegistry;
+    readonly prepareState?: (state: BaseState) => (() => void) | undefined;
+};
+export type StateBundleRegistration = {
+    readonly gizmos?: readonly (readonly [GizmoRegistrationId, RegisteredGizmoFactory])[];
+    readonly states: readonly BaseState[];
+};
+export type StateBundleHandle = {
+    dispose(): void;
+};
+/** Public State registry and navigator. Raw storage mutations stay private. */
+export declare class StateManager extends EventEmitter<StateManagerEventMap> implements StateNavigator {
+    private readonly _states;
+    private readonly _stateStack;
+    private readonly _stateCleanups;
+    private readonly _runtime;
+    private readonly _gizmos;
+    private readonly _prepareState;
+    private _activeState;
+    private _transitioning;
+    constructor(options?: StateManagerOptions);
+    get activeState(): BaseState;
+    get hasSuspendedState(): boolean;
+    get(stateId: StateId): BaseState | undefined;
+    getAll(): readonly BaseState[];
+    register(state: BaseState): void;
+    registerBundle(registration: StateBundleRegistration): StateBundleHandle;
+    replace(state: BaseState, source?: any): void;
+    unregister(stateId: StateId): boolean;
+    activate(stateId: StateId, source?: any): void;
+    push(stateId: StateId, source?: any): void;
+    pop(source?: any): void;
+    reapply(): void;
+    private _runTransition;
+    private _beginTransition;
+    private _invoke;
+    private _emitStateChange;
+    private _reportTransitionError;
+    private _emitRegistryEvent;
+    private _prepareAndStore;
+    private _replaceStoredState;
+    private _removeStoredState;
+    dispose(): void;
+}

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

@@ -0,0 +1,52 @@
+import type { BaseState } from './base-state';
+import type { StateGizmoBinding } from '../gizmo/gizmo-registry';
+import type { GizmoOwner, GizmoTool } from '@vvfx/gizmo';
+export type StateId = OfficialStateId | (string & {});
+export declare enum OfficialStateId {
+    MOVE = "move",
+    HAND = "hand",
+    IMAGE_CUT = "imageCut",
+    IMAGE_EXPAND = "imageExpand",
+    IMAGE_TEXT_EDIT = "imageTextEdit",
+    IMAGE_MASK = "imageMask",
+    ITEM_CREATE = "itemCreate"
+}
+export type StateInteractionDefinition = {
+    readonly gizmos: readonly StateGizmoBinding[];
+};
+export type StateGizmoToolConstructor = new (owner: GizmoOwner) => GizmoTool;
+export type StateChangeEvent = {
+    previousState: BaseState | undefined;
+    currentState: BaseState;
+    transition: StateTransition;
+    /** 触发本次切换的业务入参，由状态入口原样透传。 */
+    source?: any;
+};
+export type StateTransition = 'set' | 'push' | 'pop' | 'replace';
+export type StateManagerEventMap = {
+    stateChange: [event: StateChangeEvent];
+    stateRegistered: [stateId: StateId];
+    stateUnregistered: [stateId: StateId];
+    stateReplaced: [stateId: StateId];
+    transitionError: [error: unknown, stateId: StateId, phase: StateLifecyclePhase];
+};
+export type StateLifecyclePhase = 'exit' | 'enter' | 'suspend' | 'resume' | 'ready' | 'notify';
+export type StateTransitionRuntime = {
+    apply(state: BaseState): void;
+    reapply(state: BaseState): void;
+    registerState(state: BaseState): void;
+    unregisterState(state: BaseState): void;
+};
+export type StateNavigator = {
+    readonly activeState: BaseState;
+    get(stateId: StateId): BaseState | undefined;
+    activate(stateId: StateId, source?: any): void;
+    push(stateId: StateId, source?: any): void;
+    pop(source?: any): void;
+};
+export type BaseStateEventMap = {
+    enter: [];
+    exit: [];
+    suspend: [];
+    resume: [];
+};

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

@@ -0,0 +1,3 @@
+export { Store } from './store';
+export { SceneStore } from './scene-store';
+export type { SceneEntry, SceneEntrySnapshot, SceneStoreEventMap, AdaptConfig } from './scene-store';

package/dist/core/store/scene-store.d.ts

@@ -0,0 +1,194 @@
+import { EventEmitter, type spec } from '../../shared';
+import { type ArtisItem } from '../item';
+/**
+ * 自适应配置：由一个原始 JSONScene 生成场景变体的参数
+ */
+export type AdaptConfig = {
+    /** 目标适配视口尺寸 */
+    viewSize: [number, number];
+    /** 安全区 [top, bottom, left, right] */
+    safeArea: [number, number, number, number];
+    /** 适配方向 */
+    direction?: 'x' | 'y';
+    /** 采样帧（gotoAndStop 冻结帧） */
+    tick?: number;
+};
+/**
+ * 单个场景条目
+ *
+ * 数据区元素：每个场景的纯持久数据 + 编辑模型数据。
+ * - scene 是持久真源（自适应后已落定的 JSON，受编辑回写）
+ * - items 是由 runtime 组装的编辑模型数据（带行为/引用的领域对象）
+ */
+export type SceneEntry = {
+    /** 稳定标识（JSON 的 compositionId 或 generateGUID）—— activeSceneId 用它而非 index，避免增删场景漂移 */
+    id: string;
+    /** 场景 JSON 数据（GE JSONScene），自适应后已落定的持久真源（受编辑回写） */
+    scene: spec.JSONScene;
+    /** 原始 JSON 副本（重做自适应 / 对比用，无则等于 scene 本身） */
+    originScene?: spec.JSONScene;
+    /** 该场景下的 ArtisItem 列表（编辑模型数据，由 SceneDataAssembler 从 runtime 组装） */
+    items: ArtisItem[];
+    /** 产生本场景的自适应配置（无则 origin） */
+    adapt?: AdaptConfig;
+    /** 场景来源 */
+    source: 'origin' | 'adapted' | 'external-json';
+    /** 内容尺寸 [width, height] */
+    contentSize: [number, number];
+    /** 只读标记：true 时仅支持播放 + 选中查看，不可编辑（展示标准产物场景） */
+    readonly?: boolean;
+};
+/**
+ * SceneEntry 的 JSON-safe 快照投影（供错误上报序列化、复现页精确重建）。
+ *
+ * 与 {@link SceneEntry} 的差异：items 不持久化（runtime 复现时直接重新 assemble），
+ * 其余结构字段(id/scene/originScene/adapt/source/contentSize/readonly)全量保留，
+ * 使复现页能绕过 SceneBuilder 重新自适应、按快照原样灌入 entries 保真重建。
+ */
+export type SceneEntrySnapshot = {
+    id: string;
+    /** 场景 JSONScene 深克隆（已含编辑回写） */
+    scene: spec.JSONScene;
+    /** 原 JSONScene 深克隆（sizeAdapt 还原用，无则等于 scene 本身） */
+    originScene?: spec.JSONScene;
+    /** 产生本场景的自适应配置（无则 origin） */
+    adapt?: AdaptConfig;
+    /** 场景来源 */
+    source: 'origin' | 'adapted' | 'external-json';
+    /** 内容尺寸 [width, height] */
+    contentSize: [number, number];
+    /** 只读标记（含此则复现页还原只读态） */
+    readonly?: boolean;
+};
+/**
+ * SceneStore 事件
+ *
+ * - sceneChange / activeSceneChange：当前激活场景变化
+ * - scenesUpdate：场景库增删
+ * - sceneDataMutate：场景数据变更（items / scene 数据被修改），替代缺失的 artisDataChange
+ */
+export type SceneStoreEventMap = {
+    'sceneChange': [info: {
+        prevIndex: number;
+        nextIndex: number;
+    }];
+    'activeSceneChange': [info: {
+        prevId: string | undefined;
+        nextId: string | undefined;
+    }];
+    'scenesUpdate': [];
+    'sceneDataMutate': [info: {
+        sceneId: string;
+        fields: ('items' | 'scene')[];
+    }];
+};
+/**
+ * SceneStore - 多场景数据管理器
+ *
+ * 贯彻「Store 只存数据」原则，内分两区：
+ * - **数据区**：场景库 SceneEntry[]，每场景存持久 JSON（真源）+ 编辑模型 items + 自适应配置
+ * - **会话区**：当前工作台状态——activeSceneId（当前渲染场景 id）/ time（播放游标）/ playing（播放态）
+ *
+ * 元素选择不在此处，由独立 SelectionManager 承担。
+ * 实际副作用（Player 重载、ViewService 更新等）由外部使用者处理。
+ */
+export declare class SceneStore extends EventEmitter<SceneStoreEventMap> {
+    private _scenes;
+    private _activeIndex;
+    /** 会话区：当前播放/编辑游标 */
+    private _time;
+    /** 会话区：播放态 */
+    private _playing;
+    /** 场景库（只读视图，外部不应通过返回值修改内部结构） */
+    get scenes(): readonly SceneEntry[];
+    /** 当前激活场景的索引（-1 表示无激活场景） */
+    get activeIndex(): number;
+    /** 当前激活的场景条目（无激活场景时为 undefined） */
+    get activeScene(): SceneEntry | undefined;
+    /** 场景库中场景的数量 */
+    get sceneCount(): number;
+    /** 当前渲染/编辑场景 id（用 id 而非 index，避免增删场景漂移） */
+    get activeSceneId(): string | undefined;
+    /** 当前播放/编辑游标（会话级，不再落在 entry 内） */
+    get time(): number;
+    /** 设置当前播放/编辑游标值
+     * @param value 游标时间值 */
+    set time(value: number);
+    /** 播放态 */
+    get playing(): boolean;
+    /** 设置播放态
+     * @param value 是否处于播放态 */
+    set playing(value: boolean);
+    /**
+     * 添加场景，返回新场景的索引
+     * @param entry 场景条目
+     * @returns 新场景的索引
+     */
+    addScene(entry: SceneEntry): number;
+    /**
+     * 清空全部场景并重置激活/游标状态，供 run/reproduce 重建前重置。
+     *
+     * addScene 不按 id 去重，重复 run/reproduce 会累积重复场景；故重建路径在灌入前先清空。
+     * 与 {@link dispose} 的区别：本方法仅重置数据、保留实例可用，dispose 用于生命周期终结。
+     */
+    clearScenes(): void;
+    /**
+     * 按 id 取场景条目
+     * @param id 场景 id
+     * @returns 场景条目（无匹配时为 undefined）
+     */
+    getEntry(id: string): SceneEntry | undefined;
+    /**
+     * 移除场景，返回被移除的条目
+     * @param index 场景索引
+     * @returns 被移除的场景条目（索引越界时为 undefined）
+     */
+    removeScene(index: number): SceneEntry | undefined;
+    /**
+     * 以 id 激活场景（推荐入口，避免增删场景导致的 index 漂移）。
+     * 仅修改激活态，不执行副作用（Player 重载等由外部使用者负责）。
+     * activeSceneChange 事件由 setActiveIndex 统一发出。
+     * @param id 待激活场景 id
+     */
+    setActiveScene(id: string): void;
+    /**
+     * 切换活跃场景索引（仅修改索引，不执行副作用）
+     * 副作用由外部使用者的场景切换逻辑负责。
+     * 优先使用 setActiveScene(id)；此方法保留以兼容 index-based 调用。
+     * @param index 目标场景索引
+     */
+    setActiveIndex(index: number): void;
+    /**
+     * 保存当前活跃场景的 items 快照，并发出 sceneDataMutate 事件
+     * @param items 最新的元素列表
+     */
+    saveCurrentItems(items: ArtisItem[]): void;
+    /**
+     * 标记激活场景的 scene（JSON）已被回写修改，发出 sceneDataMutate 事件
+     * @param sceneId 被修改的场景 id
+     */
+    markSceneMutated(sceneId: string): void;
+    /**
+     * 导出指定场景 JSONScene（深克隆保护，避免外部修改污染 Store）。
+     * @param id 场景 id，缺省=当前激活场景
+     * @returns 克隆后的 JSONScene；场景不存在时返回 undefined
+     */
+    exportEntry(id?: string): spec.JSONScene | undefined;
+    /**
+     * 导出全部场景 JSONScene（每个深克隆）
+     * @returns 全部场景克隆后的 JSONScene 数组
+     */
+    exportAll(): spec.JSONScene[];
+    /**
+     * 导出全部场景的 JSON-safe 快照（SceneEntrySnapshot[]，深克隆保护）。
+     *
+     * 与 {@link exportAll} 的差异：回带 SceneEntry 全部结构字段(id/adapt/source/contentSize/readonly/originScene)，
+     * 供错误上报快照和复现页精确重建多场景结构。items 不纳入快照（复现时 runtime 直接重新 assemble）。
+     * @returns 全部场景的快照数组（深克隆，外部可自由修改）
+     */
+    exportEntries(): SceneEntrySnapshot[];
+    /**
+     * 销毁，清空所有数据
+     */
+    dispose(): void;
+}

package/dist/core/store/store.d.ts

@@ -0,0 +1,36 @@
+import type { ArtisData } from '../types';
+import type { ArtisItem } from '../item';
+/**
+ * Store - 编辑器核心数据仓库
+ *
+ * 持有当前场景的 ArtisData（构造时以默认空数据初始化，unbind 重置），
+ * 通过 getter/setter 提供结构化访问（items 等）。
+ *
+ * 注：Store 本身不 extends EventEmitter，数据变更需由 CommandService 的 afterExecute
+ * 回调驱动刷新（与 Gizmo / SelectionManager / ViewService 的事件模式不同）。
+ *
+ * 使用方式：
+ * 1. 通过 store.items 直接读写元素列表
+ * 2. 数据变更的一致性刷新由 CommandService.afterExecute 统一编排
+ */
+export declare class Store {
+    private _data;
+    constructor();
+    /**
+     * 解绑数据源
+     */
+    unbind(): void;
+    /** 当前场景下的全部 ArtisItem 列表 */
+    get items(): ArtisItem[];
+    /**
+     * 设置 items 列表
+     * @param value 新的 ArtisItem 列表
+     */
+    set items(value: ArtisItem[]);
+    /**
+     * 获取绑定的 ArtisData 引用
+     * 用于需要传递完整 ArtisData 的旧接口
+     * @returns 当前绑定数据的深拷贝（不影响内部 _data 引用）
+     */
+    toArtisData(): ArtisData;
+}

package/dist/core/types/artis-config.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Artis 通用配置 / 运行时类型（由 artis/types.ts 下移至此）
+ *
+ * 下移目的：消除 core → artis 的 type-only 反向依赖。这些类型本属 core 数据契约
+ * 且零外部依赖，原定义在 artis/types.ts 导致 core/renderer、core/asset、core/plugin、
+ * core/service 等模块反向 `import type ... from '../../artis/types'`。下移后 artis/types.ts
+ * 反向 re-export 以保持对外公共 API 不变。
+ *
+ */
+import type { spec } from '../../shared';
+/**
+ * 页面功能配置
+ */
+export type PagePreferences = {
+    /** 静态预览功能开关 */
+    staticPreview: boolean;
+    /** 静态预览视图名称 */
+    staticPreviewName: string;
+    /** 需过滤的元素名称 */
+    filterItemNames: string[];
+    /** 需忽略交互的元素名称（仍渲染可见；不可选中/不可更改/不计入公共 items，保留在导出 JSON） */
+    ignoredInteractionNames: string[];
+    /** 成组操作元素显隐 */
+    groupVisible: boolean;
+    /** 缩放最大值 */
+    maxZoom: number;
+    /** 缩放最小值 */
+    minZoom: number;
+};
+/**
+ * 用户偏好设置
+ *
+ * 按功能模块划分（终端用户个人偏好：功能开关 / 功能配置）：
+ * - page: 页面功能配置
+ * - item: 元素配置
+ * - export: 导出功能
+ * - screenshot: 截图功能
+ * - sizeAdapt: 尺寸自适应
+ * - asyncLoad: 异步加载
+ *
+ * 注意：Gizmo 配置（线宽/颜色/笔刷/遮罩开关等）是「平台开发一次性产品配置」，不属于终端用户
+ */
+export type UserPreferences = {
+    /** 页面功能配置 */
+    page: PagePreferences;
+    /** 元素配置 */
+    item: ItemPreferences;
+    /** 导出功能配置 */
+    export: ExportPreferences;
+    /** 截图功能配置 */
+    screenshot: ScreenshotPreferences;
+    /** 尺寸自适应功能配置 */
+    sizeAdapt: SizeAdaptPreferences;
+    /** 异步加载功能配置 */
+    asyncLoad: AsyncLoadPreferences;
+};
+/**
+ * 元素配置
+ */
+export type ItemPreferences = {
+    /** 画板配置 */
+    frame: FrameItemPreferences;
+    /** 卡片配置 */
+    card: CardItemPreferences;
+};
+/**
+ * 画板元素配置
+ */
+export type FrameItemPreferences = {
+    /** 自由布局下画板内边距（≥0，负值行为未定义） */
+    layoutPadding: number;
+    /** 自动布局下画板元素间距（≥0，负值行为未定义） */
+    layoutGap: number;
+    /** 新建画板默认宽度（>0，非正值会生成无效画板） */
+    defaultWidth: number;
+    /** 新建画板默认高度（>0，非正值会生成无效画板） */
+    defaultHeight: number;
+    /** 自由布局画板背景色 */
+    freeLayoutBackgroundColor: spec.vec4;
+    /** 自动布局画板背景色 */
+    autoLayoutBackgroundColor: spec.vec4;
+};
+/**
+ * 卡片元素配置
+ */
+export type CardItemPreferences = {
+    /** 卡片元素背景色 [r, g, b, a] */
+    backgroundColor: [number, number, number, number];
+};
+/**
+ * 导出功能配置
+ */
+export type ExportPreferences = {
+    /** 是否启用导出功能 */
+    enabled: boolean;
+};
+/**
+ * 截图功能配置
+ */
+export type ScreenshotPreferences = {
+    /** 是否启用截图功能 */
+    enabled: boolean;
+    /** 截图默认背景色 [r, g, b, a] */
+    defaultBackgroundColor: [number, number, number, number];
+};
+/**
+ * 尺寸自适应功能配置
+ */
+export type SizeAdaptPreferences = {
+    /** 是否启用尺寸自适应 */
+    enabled: boolean;
+};
+/**
+ * 异步加载功能配置
+ */
+export type AsyncLoadPreferences = {
+    /** 是否启用异步加载 */
+    enabled: boolean;
+    /** 异步加载时显示的过渡纹理 URL */
+    loadingTextureUrl: string;
+};
+/**
+ * 背景配置（联合类型，通过 type 区分具体模式）
+ */
+export type ArtisBackgroundConfig = ColorBackground | ImageBackground | ChessBoardBackground | DotBoardBackground;
+/**
+ * 纯色背景
+ */
+export type ColorBackground = {
+    type: 'color';
+    /** CSS 颜色值，如 '#ffffff'、'rgba(0,0,0,0.5)' */
+    color: string;
+};
+/**
+ * 图片背景
+ */
+export type ImageBackground = {
+    type: 'image';
+    /** 图片 URL */
+    url: string;
+    /** 底色（图片加载前或透明区域的底色） */
+    fallbackColor?: string;
+};
+/**
+ * 棋盘格背景
+ */
+export type ChessBoardBackground = {
+    type: 'chess-board';
+    /** 格子大小（像素），默认 16 */
+    gridSize?: number;
+    /** 格子颜色 A，默认 '#FFFFFF' */
+    colorA?: string;
+    /** 格子颜色 B，默认 '#CCCCCC' */
+    colorB?: string;
+};
+/**
+ * 点阵背景
+ */
+export type DotBoardBackground = {
+    type: 'dot-board';
+    /** 底色，默认 '#F5F5F5' */
+    backgroundColor?: string;
+    /** 点颜色，默认 '#BBBBBB' */
+    dotColor?: string;
+    /** 点间距（像素），默认 16 */
+    spacing?: number;
+    /** 点半径（像素），默认 1 */
+    dotRadius?: number;
+};
+/**
+ * Disposable 接口
+ */
+export type Disposable = {
+    dispose(): void;
+};
+/**
+ * 资源加载结果
+ */
+export type AssetLoadResult = {
+    /** 是否加载成功 */
+    success: boolean;
+    /** 加载成功后的资源 id */
+    assetId?: string;
+    /** 加载失败时的错误信息 */
+    error?: Error;
+};

package/dist/core/types/artis-events.d.ts

@@ -0,0 +1,101 @@
+import type { ItemCreateType } from '@vvfx/gizmo';
+import type { spec } from '../../shared';
+import type { HistoryOperation } from '../command/types';
+import type { ArtisData } from './page';
+import type { AnyArtisErrorInfo } from '../quality/error-monitor/types';
+/**
+ * Artis warning 事件载荷（通用结构）。
+ *
+ * 不绑死某具体场景字段，所有 warning 来源复用同一套：尺寸 0 兜底、viewport resize
+ * 跳过比例更新、未来其它降级场景皆走此类型，仅 code 不同。
+ *
+ * - params：触发 warning 的原始入参快照（各场景自填键名），供复现/排查"给了什么"。
+ * - result：warning 是「已兜底继续执行」语义，此字段带回本次操作实际生效的结果，
+ *   让宿主无需重新查询即知 warning 后真实状态。
+ */
+export type ArtisWarningEventInfo = {
+    /** warning 场景标识，按来源枚举：'zero-size-fallback' | 'viewport-resize-skipped' | ... */
+    code: string;
+    /** 人可读描述 */
+    message: string;
+    /** 相关元素 id（有则填，无则缺省） */
+    itemId?: string;
+    /** 原始入参快照（兼容参数名称，各场景自填键名） */
+    params?: Record<string, unknown>;
+    /** 已执行/已落盘的结果数据（warning 后实际生效状态） */
+    result?: Record<string, unknown>;
+    timestamp: number;
+};
+/**
+ * BaseArtis 公共事件类型。
+ *
+ * 这里只声明所有 Artis 变体共有的稳定事件。具体 Artis 的编辑态事件在
+ * `artis/types.ts` 中通过 ArtisStateEvents 扩展，避免 BaseArtis 与 SceneArtis 被迫暴露。
+ *
+ * 依赖面：@vvfx/gizmo（BaseState/ItemCreateType）、shared（spec）、core/command（HistoryOperation）、
+ * core/types/page（ArtisData）、core/quality/error-monitor（AnyArtisErrorInfo）——均为 core 已有合法依赖方向，无新增反向引用。
+ *
+ * error 事件：真失败场景（Command execute/undo/redo、资源加载失败、异步场景切换、
+ * interactionService 运算抛错被 catch 等），载荷复用
+ * ErrorMonitor 的 AnyArtisErrorInfo（含场景快照 + 最近 5 条 Command，供复现/调试）。
+ * error 事件作业务出口，不依赖 enableErrorMonitor 回调；emit 时经 captureSnapshot 产出载荷。
+ *
+ * warning 事件：可降级场景（尺寸 0 兜底、resize 跳过比例更新等），载荷为通用
+ * ArtisWarningEventInfo（见上）。
+ */
+export type BaseArtisEvents = {
+    'artis.init': [];
+    'artis.ready': [];
+    'artis.dispose': [];
+    'scene.loaded': [];
+    'renderer.contextlost': [];
+    'renderer.contextrestored': [info: {
+        syncFailures: string[];
+    }];
+    'recovery.rebuilding': [info: {
+        attempt: number;
+    }];
+    'recovery.failed': [info: {
+        reason: string;
+    }];
+    'scene.datachange': [pageData: ArtisData];
+    'selection.change': [ids: string[]];
+    'selection.preselectchange': [id: string | undefined];
+    'loading.change': [ids: string[]];
+    'item.propertychange': [info: {
+        id: string;
+        propertyKeys: string[];
+    }];
+    'view.transform': [transform: {
+        zoom: number;
+        translation: [number, number];
+    }];
+    'item.dragstart': [type: string];
+    'item.drag': [type: string];
+    'item.dragend': [type: string];
+    'item.create': [info: {
+        type: ItemCreateType;
+        position: spec.vec2;
+        id: string;
+        width?: number;
+    }];
+    'video.play': [info: {
+        id: string;
+        time: number;
+    }];
+    'spritetext.click': [info: {
+        id: string;
+        index: number;
+        text: string;
+    } | undefined];
+    'history.change': [operation: HistoryOperation];
+    'text.input': [info: {
+        itemId: string;
+        text: string;
+        fontFamily: string;
+    }];
+    /** 真失败场景：载荷为场景快照 + 最近 5 条 Command（AnyArtisErrorInfo），供宿主复现/调试/决策 */
+    'artis.error': [info: AnyArtisErrorInfo];
+    /** 可降级场景：载荷为通用 ArtisWarningEventInfo（code + params + result） */
+    'artis.warning': [info: ArtisWarningEventInfo];
+};

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

@@ -0,0 +1,3 @@
+/** Frame domain types are owned by @vvfx/gizmo's FrameManager. */
+export { FrameLayoutMode } from '@vvfx/gizmo';
+export type { AutoLayoutConfig, LayoutInfo } from '@vvfx/gizmo';

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

@@ -0,0 +1,28 @@
+import type { spec } from '../../shared';
+export type GeneratorExtension = {
+    type: 'generator';
+    generatorType: 'sprite' | 'video';
+    fillColor: [number, number, number, number];
+    iconUrl: string;
+};
+export type SpriteGeneratorResource = {
+    url: string;
+    size?: spec.vec2;
+    itemId: string;
+    extension?: Record<string, any>;
+};
+export type VideoGeneratorResource = {
+    url: string;
+    size?: spec.vec2;
+    muted?: boolean;
+    transparent?: boolean;
+    playbackRate?: number;
+    volume?: number;
+    itemId: string;
+    extension?: Record<string, any>;
+};
+export type GeneratorResource = SpriteGeneratorResource | VideoGeneratorResource;
+export type GeneratorStyleConfig = {
+    fillColor?: spec.vec4;
+    iconUrl?: string;
+};

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

@@ -0,0 +1,15 @@
+export { FrameLayoutMode } from './frame';
+export type { AutoLayoutConfig, LayoutInfo } from './frame';
+export type { PagePreferences, UserPreferences, ItemPreferences, FrameItemPreferences, CardItemPreferences, ExportPreferences, ScreenshotPreferences, SizeAdaptPreferences, AsyncLoadPreferences, ArtisBackgroundConfig, ColorBackground, ImageBackground, ChessBoardBackground, DotBoardBackground, Disposable, AssetLoadResult, } from './artis-config';
+export type { BaseArtisEvents, ArtisWarningEventInfo } from './artis-events';
+export type { BaseItemProperty, SpriteItemProperty, GroupItemProperty, TextItemProperty, VideoItemProperty, GeneratorItemProperty, EffectsItemProperty, CardItemProperty, FrameItemProperty, CardHTML, CardHTMLContent, CardHTMLInlineContent, CardHTMLDOMRendererContent, CardHTMLDocumentContent, CardHTMLDocumentMessage, CardHTMLWindowEventMessage, CardHTMLShellContent, CardHTMLShellRenderer, CardHTMLShellRendererContext, CardHTMLShellRendererResult, CardHTMLRenderCleanup, CardHTMLContentCleanup, CardHTMLDOMRenderer, CardHTMLPatchContext, CardHTMLPatchHandler, CardHTMLRootConfig, CardHTMLRootStyle } from './item-property';
+export type { SpriteCreateInfo, GroupCreateInfo, TextCreateInfo, VideoCreateInfo, CardCreateInfo, CardType, GeneratorCreateInfo, EffectsCreateInfo, FrameCreateInfo, AsyncSpriteCreateInfo, AsyncVideoCreateInfo, ItemCreateInfo, AsyncItemCreateInfo, SceneCreateInfo, CardTypeConfig } from './item-create-info';
+export { GeneratorType } from './item-create-info';
+export type { SpriteItemSchema, TextItemSchema, VideoItemSchema, GroupItemSchema, GeneratorItemSchema, EffectsItemSchema, FrameItemSchema, CardItemSchema, ItemSchema } from './item-schema';
+export { createInfoToItemSchema } from './item-schema';
+export type { BaseItemPropertyKey, BaseItemPropertyValueMap, ItemPropertyMap, SetSingleItemSinglePropertyParam, SetSingleItemMultiplePropertiesParam, SetItemPropertyParam } from './item-set-property';
+export type { PageOptions, ArtisData, InitArtisData, PageAutoLayoutParam, ArtisPageConfig, PageProperty, ActiveData } from './page';
+export type { ViewportFitShiftParam, ExportParam, PreviewSafeAreaParam, ViewParam, ViewProperty } from './view';
+export type { GeneratorExtension, SpriteGeneratorResource, VideoGeneratorResource, GeneratorResource, GeneratorStyleConfig } from './generator';
+export type { SDKBackgroundType, SDKOptions, SDKTemplateInputParam, SDKEditorInputParam, SDKInputParam, SDKInitParam } from './sdk';
+export { ItemOrderAction } from './item-reorder';