@vvfx/artis 0.0.1-alpha.0

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

@@ -0,0 +1,174 @@
+import type { Command, CommandErrorEventHandler, HistoryOperation } from '../command';
+import type { CommandSnapshot, ErrorMonitor, ItemSnapshot } from '../quality/error-monitor';
+/**
+ * HistoryManager - 历史管理器
+ *
+ * 存储已执行的 Command 实例，支持 undo/redo：
+ * - undo: 取栈顶 Command，调用 command.undo()
+ * - redo: 取下一个 Command，调用 command.redo()
+ *
+ * 栈隔离（session）：独立功能状态进入时调用 pushSession 把主栈挂起、清空活动栈，
+ * 切回基础状态时 popSession 丢弃独立功能子栈并还原主栈。
+ */
+export declare class HistoryManager {
+    private _commands;
+    private _currentIndex;
+    private _maxLength;
+    private _enabled;
+    /**
+     * 历史 change 回调集合（多订阅）。
+     *
+     * push/undo/redo/session/clear 均经 {@link _notifyChange} 通知全部订阅者。
+     * 多订阅语义对齐 CommandService._afterExecuteCallbacks：调用方可独立追加而不互相覆盖，
+     * 使 CommandService 能在此桥接 undo/redo（不抢占既有 setOnChange 订阅者）。
+     */
+    private _changeCallbacks;
+    /** session 切换（push/pop）后的通知回调，用于刷新 UI 的 canUndo/canRedo */
+    private _onSessionChangeCallback;
+    /** 挂起的历史快照栈（独立功能状态隔离用） */
+    private _sessionStack;
+    /** 错误监控器（按需注入） */
+    private _errorMonitor?;
+    /** undo/redo 业务错误事件出口 */
+    private _errorEventHandler?;
+    /** 错误快照会探测 undo/redo；防止探测失败再次递归上报。 */
+    private _reportingError;
+    /** 构造历史管理器，配置最大栈长与启用态
+     * @param maxLength 历史栈最大长度，超出后最早记录被丢弃
+     * @param enabled 是否启用历史记录（关闭后 push 不入栈） */
+    constructor(maxLength?: number, enabled?: boolean);
+    /** 注入错误监控器（由 ErrorMonitorFacade 装配）。 */
+    setErrorMonitor(monitor?: ErrorMonitor): void;
+    /** 注入 undo/redo 业务错误事件出口。 */
+    setErrorEventHandler(handler?: CommandErrorEventHandler): void;
+    /** 发散 undo/redo 真异常，并保护错误快照内部历史探测不递归。 */
+    private _reportHistoryError;
+    /**
+     * 设置历史 change 回调（替换式，向后兼容）。
+     *
+     * 会清空已注册的所有 change 回调，仅保留传入的这一个。
+     * 新调用方建议改用 {@link addOnChange} / {@link removeOnChange} 进行多订阅，
+     * 避免新回调无意覆盖既有订阅（如 CommandService 的 undo/redo 桥接）。
+     *
+     * @param callback 操作回调，接收本次操作类型与对应 Command
+     */
+    setOnChange(callback: (operation: HistoryOperation) => void): void;
+    /**
+     * 追加一个历史 change 回调（多订阅中继点）。
+     *
+     * 多个回调按注册顺序依次触发，互不覆盖。返回一个 dispose 函数用于注销该回调，
+     * 便于 CommandService 在 dispose 时精确移除自身桥接订阅。
+     *
+     * @param callback 操作回调，接收本次操作类型与对应 Command
+     * @returns 注销函数，调用后移除该回调
+     */
+    addOnChange(callback: (operation: HistoryOperation) => void): () => void;
+    /**
+     * 移除一个历史 change 回调。
+     *
+     * @param callback 要移除的回调函数
+     */
+    removeOnChange(callback: (operation: HistoryOperation) => void): void;
+    /** 按 push/undo/redo/session/clear 通知全部 change 订阅者 */
+    private _notifyChange;
+    /**
+     * 设置 session 切换（pushSession / popSession）后的通知回调。
+     * session 切换不对应具体 Command，仅用于通知 UI 刷新 canUndo / canRedo 状态。
+     *
+     * @param callback session 切换回调
+     */
+    setOnSessionChange(callback: () => void): void;
+    /**
+     * 推入已执行的 Command
+     * 丢弃当前索引之后的 redo 分支
+     *
+     * @param command 已执行的 Command 实例
+     */
+    push(command: Command): void;
+    /**
+     * 撤销：取栈顶 Command 并执行其 undo()
+     *
+     * @returns 被撤销的 Command，无可撤销时返回 undefined
+     */
+    undo(): Command | undefined;
+    /**
+     * 重做：取下一个 Command 并执行其 redo()
+     *
+     * @returns 被重做的 Command，无可重做时返回 undefined
+     */
+    redo(): Command | undefined;
+    /**
+     * 是否可撤销（当前索引在栈内）
+     *
+     * @returns 当前存在可撤销的 Command 时返回 true
+     */
+    canUndo(): boolean;
+    /**
+     * 是否可重做（当前索引未到栈顶）
+     *
+     * @returns 当前存在可重做的 Command 时返回 true
+     */
+    canRedo(): boolean;
+    /**
+     * 获取历史栈中的所有 Command
+     *
+     * @returns 历史栈中所有 Command 的副本
+     */
+    getHistory(): Command[];
+    /**
+     * 获取当前历史指针位置（-1 表示空栈）
+     *
+     * @returns 当前历史指针索引
+     */
+    getCurrentIndex(): number;
+    /** 清空历史栈与挂起的 session 快照，指针归零 */
+    clear(): void;
+    /**
+     * 进入独立功能状态：把当前活动栈整体快照压入 session 栈，并清空活动栈。
+     *
+     * 之后独立功能产生的 Command 落在一条全新的空栈上，其 undo / redo 只能
+     * 操作自身的 Command，撤不到进入前的基础状态（move）操作。
+     */
+    pushSession(): void;
+    /**
+     * 切回基础状态：丢弃当前独立功能子栈，原样还原上一层挂起的主栈快照。
+     *
+     * 无挂起快照时为 no-op。
+     */
+    popSession(): void;
+    /**
+     * 是否处于独立功能子栈中（存在挂起的主栈快照）
+     */
+    get inSession(): boolean;
+    /**
+     * 获取最近 count 条已执行的 Command 快照（从栈顶往前数）
+     * 用于 ErrorMonitor 上报时附带操作上下文，不影响栈状态
+     *
+     * @param count 需要取的最近 Command 数量
+     * @returns 从栈顶往前的 Command 快照数组
+     */
+    getRecentCommands(count: number): CommandSnapshot[];
+    /**
+     * 探测：撤销最近 count 条已成功入栈的 Command 后取元素快照，再 redo 回正。
+     *
+     * 用于 ErrorMonitor 上报瞬间确定性捕获"交互初始前数据"（preItems），
+     * 替代测试页从 JSON 反推。保证调用前后历史指针与场景态不变（纯读）。
+     *
+     * 实现要点（直接复用 this.undo()/this.redo()）：
+     * - 走公共 undo/redo 才会触发 onChange → 宿主 syncAllItemsFromPlayer，
+     *   把 Player 变更回写到 store；否则 getItemSchemas 读到的是改后态，preItems 失真。
+     *   （故不再用 _suppressOnChange 抑制回调——那会同时吞掉必要的 store 同步。）
+     * - 记录 undo 步数 undone，redo 阶段只 redo 这么多次，绝不越过原始 currentIndex。
+     * - 任意一步 undo 抛错 → 已 undo 的步用 redo 回正（仍受 undone 上界约束），
+     *   回正失败则尽力而为，返回 { ok: false }，由上层决定是否采信 items。
+     * - 成功路径 items 为撤销后态；失败路径 items 为进入前当前态（fallback）。
+     *
+     * @param count    要回溯的步数
+     * @param getItems 取当前元素快照的回调（由调用方提供，避免本类反向依赖 ItemService）
+     * @returns 撤销后的元素态与是否成功
+     */
+    peekBeforeRecent(count: number, getItems: () => ItemSnapshot[]): {
+        items: ItemSnapshot[];
+        ok: boolean;
+    };
+}

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

@@ -0,0 +1 @@
+export { HistoryManager } from './history-manager';

package/dist/core/index.d.ts

@@ -0,0 +1,25 @@
+export * from './item';
+export * from './store';
+export * from './types';
+export * from './gizmo';
+export * from './quality';
+export * from './command';
+export * from './keybinding';
+export * from './element-registry';
+export * from './asset';
+export * from './history';
+export * from './plugin';
+export * from './preferences';
+export * from './renderer';
+export * from './service';
+export * from './predict';
+export * from './state';
+export type { ViewportProvider, CameraProvider, ItemTransformProvider, InteractionConfig, } from './service';
+export type { SceneEntrySnapshot } from './store';
+export type { ErrorMonitorCallback, ArtisErrorInfo, ArtisErrorInfoBase, SceneArtisErrorInfo, AnyArtisErrorInfo, SceneSnapshotBase, ArtisSnapshot, ArtisSnapshotExtras, SceneArtisSnapshot, SceneArtisSnapshotExtras, VariantErrorSnapshot, } from './quality/error-monitor';
+export type { PerfMonitorCallback, PerfReport, PerfMetric } from './quality/perf-monitor';
+export type { StabilityMonitorCallback, HealthState, StabilityReport, RecommendedAction, RecommendedActionToken } from './quality/stability-monitor';
+export type { ElementRegistryDeps } from './element-registry';
+export type { CommandBindingContext, GizmoBridgeEvent, GizmoBridgeEventArgs } from './gizmo';
+export type { CommandErrorEventHandler } from './command';
+export type { BaseStateEventMap, StateChangeEvent, StateId, StateManagerEventMap, StateTransition, StateNavigator, StateGizmoToolConstructor, StateLifecyclePhase, StateBundleRegistration, StateBundleHandle, } from './state';

package/dist/core/item/base-item.d.ts

@@ -0,0 +1,154 @@
+import { type BaseItemProperty, type ItemSchema } from '../types';
+import { spec } from '../../shared';
+import { type ArtisItemOptions, type ArtisItemType } from './types';
+/**
+ * ArtisItem 抽象基类
+ * 支持属性扩展，允许添加任意自定义属性
+ */
+export declare abstract class BaseItem {
+    /**
+     * 元素ID（用户可读，全局唯一，随 Schema 落盘）
+     */
+    id: string;
+    /**
+     * Player 维度 VFXItem ID（GUID，仅运行时、不落盘——决策 D2）
+     *
+     * 与 id 分离：id 是用户可见的元素标识；vfxItemId 是 VFXItem.instanceId 的镜像，
+     * 由 createXxx / loadEffectsAsset 创建 VFXItem 后取 `getInstanceId()` 回填。序列化层
+     * （toJSON/toSchema）不输出此字段。未显式传入时落 `?? id` 兜底， assembler 导入路径
+     * （instanceId === elementId）依赖此兜底长期生效。
+     *
+     * id 基准随身份策略分两种：
+     * - Artis（RegistryIdentityStrategy）：id=schemaId，与 vfxItemId(instanceId) 分离，靠 registry 翻译。
+     * - SceneArtis（IdentityStrategy）：createXxx 经 resolveItemId 把 id 覆盖为 instanceId，
+     *   即 id===vfxItemId===instanceId 三者同值，无需映射；assembler 导入路径本就同值，
+     *   此兜底对导入与 SceneArtis 创建一致生效。
+     */
+    vfxItemId: string;
+    /**
+     * 元素名称
+     */
+    name: string;
+    /**
+     * 父节点ID
+     */
+    parentId?: string;
+    /**
+     * 元素生命周期
+     */
+    duration: number;
+    /**
+     * 元素生命周期延时
+     */
+    delay: number;
+    /**
+     * 元素结束行为
+     */
+    endBehavior: spec.EndBehavior;
+    /**
+     * 是否可见
+     */
+    visible: boolean;
+    /**
+     * 是否处于锁定状态
+     */
+    isLocked: boolean;
+    /**
+     * 核心数据是否支持编辑
+     */
+    isCoreEditable: boolean;
+    /**
+     * 扩展属性存储（与 property 同级）
+     */
+    extension: Map<string, any>;
+    /**
+     * 资源加载错误（运行态，不落盘、不进 undo）。
+     *
+     * loadItemAsset 失败时由 ItemService 注入回调写入（Error | string），成功后清空。
+     * 供 `artis.item.getLoadError(id)` 查询 + loading/failure gizmo 显示，避免静默白板。
+     */
+    _loadError?: Error | string | null;
+    /**
+     * 占位待资源标记（运行态·不落盘·不进 undo）。
+     *
+     * 资源类元素（sprite/video/effects）在「资源属性传空（''）」创建时，由 ItemCreatorService 经
+     * ItemCreatorHooks.markResourcePending 置 true 并挂 LoadingManager；后续 item.replaceSource
+     * 命中本标记时走 loading 闭环补真资源（finally 关 loading + 清标记）；元素在 pending 期间被删
+     * 由 removeItem 兜底关 loading。统一了「传空 → 占位 + loading → replace 闭环」范式。
+     */
+    _pendingResource?: boolean;
+    /**
+     * 元素类型（由子类实现）
+     * 支持 spec.ItemType 或扩展的 ArtisItemType
+     */
+    abstract readonly type: ArtisItemType;
+    /**
+     * 元素属性（由子类实现）
+     */
+    abstract readonly property: BaseItemProperty;
+    constructor(options: ArtisItemOptions);
+    /** 像素宽度（属性宽度乘以 x 轴缩放） */
+    get pixelWidth(): number;
+    /** 像素高度（属性高度乘以 y 轴缩放） */
+    get pixelHeight(): number;
+    /**
+     * 设置扩展属性
+     * @param key 属性名
+     * @param value 属性值
+     */
+    setExtension(key: string, value: any): void;
+    /**
+     * 获取扩展属性
+     * @param key 属性名
+     * @returns 属性值
+     */
+    getExtension(key: string): any;
+    /**
+     * 检查是否存在指定扩展属性
+     * @param key 属性名
+     * @returns 是否存在
+     */
+    hasExtension(key: string): boolean;
+    /**
+     * 删除扩展属性
+     * @param key 属性名
+     * @returns 是否删除成功
+     */
+    deleteExtension(key: string): boolean;
+    /**
+     * 获取所有扩展属性的键名列表
+     * @returns 键名数组
+     */
+    getExtensionKeys(): string[];
+    /**
+     * 获取所有扩展属性
+     * @returns 扩展属性对象
+     */
+    getAllExtension(): Record<string, any>;
+    /**
+     * 批量设置扩展属性
+     * @param extensions 扩展属性对象
+     */
+    setExtensions(extensions: Record<string, any>): void;
+    /**
+     * 清空所有扩展属性
+     */
+    clearExtension(): void;
+    /**
+     * 转换为 ItemSchema（用于元素复制/导出）
+     * @param withParent 是否包含父节点ID
+     * @returns ItemSchema 对象
+     */
+    abstract toSchema(withParent?: boolean): ItemSchema;
+    /**
+     * 克隆 ArtisItem
+     * @returns 新的 ArtisItem 实例
+     */
+    abstract clone(): BaseItem;
+}
+/**
+ * 类型守卫函数：检查对象是否是 BaseItem
+ * @param obj 要检查的对象
+ * @returns 是否是 BaseItem 实例
+ */
+export declare function isBaseItem(obj: any): obj is BaseItem;

package/dist/core/item/card-item.d.ts

@@ -0,0 +1,91 @@
+import type { CardItemProperty, CardHTML } from '..//types';
+import type { CardItemSchema } from '../types';
+import { ArtisItemType, type CardItemOptions } from './types';
+import { BaseItem } from './base-item';
+/**
+ * 卡片元素 ArtisItem 类
+ * 在 Player 中以 SpriteItem 形式渲染（透明占位，无图）
+ * 支持设置卡片类型（cardType）
+ */
+export declare class CardItem extends BaseItem {
+    /**
+     * 元素类型
+     */
+    readonly type = ArtisItemType.CARD;
+    /**
+     * 元素属性（包含 cardType）
+     */
+    property: CardItemProperty;
+    constructor(options: CardItemOptions);
+    /**
+     * 卡片类型
+     */
+    get cardType(): string;
+    /**
+     * 设置卡片类型
+     * @param value 卡片类型
+     */
+    set cardType(value: string);
+    /**
+     * HTML 覆盖层配置
+     */
+    get html(): CardHTML | undefined;
+    /**
+     * 设置 HTML 覆盖层配置
+     * @param value HTML 覆盖层配置
+     */
+    set html(value: CardHTML | undefined);
+    /**
+     * 位置
+     */
+    get position(): [number, number];
+    /**
+     * 设置位置
+     * @param value 位置坐标 [x, y]
+     */
+    set position(value: [number, number]);
+    /**
+     * 宽度
+     */
+    get width(): number;
+    /**
+     * 设置宽度
+     * @param value 宽度
+     */
+    set width(value: number);
+    /**
+     * 高度
+     */
+    get height(): number;
+    /**
+     * 设置高度
+     * @param value 高度
+     */
+    set height(value: number);
+    /**
+     * 旋转（二维旋转角度）
+     */
+    get rotation(): number;
+    /**
+     * 设置旋转角度（二维）
+     * @param value 旋转角度
+     */
+    set rotation(value: number);
+    /**
+     * 转换为 CardItemSchema
+     * @param withParent 是否包含父节点ID
+     * @returns CardItemSchema 对象
+     */
+    toSchema(withParent?: boolean): CardItemSchema;
+    /**
+     * 克隆 ArtisItem
+     * @returns 新的 CardItem 实例
+     */
+    clone(): CardItem;
+}
+/**
+ * 类型守卫：检查是否是 CardItem
+ * @param obj 待检查对象
+ * @returns 是否是 CardItem 实例
+ */
+export declare function isCardItem(obj: any): obj is CardItem;

package/dist/core/item/default-item-schema.d.ts

@@ -0,0 +1,20 @@
+import { spec } from '../../shared';
+import type { ItemSchema } from '../types';
+import { ItemCreateType } from '@vvfx/gizmo';
+/**
+ * 根据 Gizmo 创建类型构建对应的 ItemSchema。
+ *
+ * - text：纯占位文本，给一套默认视觉参数
+ * - sprite-generator：图片生成器占位（无资源 URL，后续异步填充）
+ * - video-generator：视频生成器占位
+ * - frame：画板点击创建的默认尺寸兜底；拖拽 Frame 由 Gizmo Command 绑定按实时尺寸组装 schema
+ * - none：不创建，返回 undefined
+ *
+ * 纯函数（无实例状态依赖），从 BaseArtis 抽离以便独立测试与复用。
+ *
+ * @param type Gizmo 创建类型
+ * @param position 创建位置（像素坐标系）
+ * @param id 预生成的元素 ID
+ * @param textWidth 文字拖拽创建得到的固定宽度；点击创建时缺省为 300
+ */
+export declare function buildItemSchemaByCreateType(type: ItemCreateType, position: spec.vec2, id: string, textWidth?: number): ItemSchema | undefined;

package/dist/core/item/effects-item.d.ts

@@ -0,0 +1,99 @@
+import { type EffectsItemProperty, type EffectsItemSchema } from '../types';
+import { ArtisItemType, EffectsItemOptions } from './types';
+import { BaseItem } from './base-item';
+import { spec } from '../../shared';
+/**
+ * 特效产物 元素 ArtisItem 类
+ */
+export declare class EffectsItem extends BaseItem {
+    /**
+     * 元素类型（独立类型，不属于 spec.ItemType）
+     */
+    readonly type = ArtisItemType.EFFECTS;
+    /**
+     * 预合成元素ID
+     */
+    subCompositionItemId: string;
+    /**
+     * 特效子预合成 JSONScene 缓存（运行时、不落盘——同 vfxItemId 性质）。
+     *
+     * loadEffectsAsset 加载时缓存解析后的子 JSONScene，供 {@link JsonSceneSyncService}
+     * 会话内新建 effects 元素 insert 时 embed 到主 scene.compositions（F1c-effects），
+     * 使 reload 后子预合成可复建。property.effects 仅存 url，无法反向取得 scene，故需此缓存。
+     */
+    effectsScene?: spec.JSONScene;
+    /**
+     * 元素属性
+     */
+    property: EffectsItemProperty;
+    constructor(options: EffectsItemOptions);
+    /**
+     * 特效资源地址
+     */
+    get effects(): string;
+    /**
+     * 设置特效资源地址
+     * @param value 特效资源地址
+     */
+    set effects(value: string);
+    /**
+     * 位置
+     */
+    get position(): [number, number];
+    /**
+     * 设置位置
+     * @param value 位置坐标 [x, y]
+     */
+    set position(value: [number, number]);
+    /**
+     * 宽度
+     */
+    get width(): number;
+    /**
+     * 设置宽度
+     * @param value 宽度
+     */
+    set width(value: number);
+    /**
+     * 高度
+     */
+    get height(): number;
+    /**
+     * 设置高度
+     * @param value 高度
+     */
+    set height(value: number);
+    /**
+     * 是否自适应大小（只读，初值在 create 期锁定后不再改、不暴露 UI、不进 undo）。
+     * true：加载/切换资源时元素大小随新资源主合成 previewSize 变化；
+     * false：加载/切换资源时元素大小不变（create 期定死）。
+     * 故仅提供 getter，不暴露 setter，避免外部改写破坏初值语义。
+     */
+    get autoFit(): boolean;
+    /**
+     * 旋转（二维旋转角度）
+     */
+    get rotation(): number;
+    /**
+     * 设置旋转角度（二维）
+     * @param value 旋转角度
+     */
+    set rotation(value: number);
+    /**
+     * 转换为 EffectsItemSchema
+     * @param withParent 是否包含父节点ID
+     * @returns EffectsItemSchema 对象
+     */
+    toSchema(withParent?: boolean): EffectsItemSchema;
+    /**
+     * 克隆 ArtisItem
+     * @returns 新的 EffectsItem 实例
+     */
+    clone(): EffectsItem;
+}
+/**
+ * 类型守卫：检查是否是 EffectsItem
+ * @param obj 待检查对象
+ * @returns 是否是 EffectsItem 实例
+ */
+export declare function isEffectsItem(obj: any): obj is EffectsItem;