@vvfx/artis 0.0.1-alpha.0

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

@@ -0,0 +1,106 @@
+import type { AnyArtisErrorInfo, ErrorMonitorCallback, ErrorMonitorDeps, ErrorPhase } from './types';
+/**
+ * ErrorMonitor - Artis 错误监控核心
+ *
+ * 职责：
+ * 1. 被 CommandService / GestureHandler / Artis 门面层 / Renderer 注入
+ * 2. 在各注入点 try/catch 中调用 report() 上报错误
+ * 3. 收集场景快照（轻量，无 GPU/渲染数据）
+ * 4. 节流去重：同一 errorKey 在 500ms 内只触发一次 onError 回调
+ */
+export declare class ErrorMonitor {
+    private _deps;
+    private _callback?;
+    /** 节流记录：errorKey → 最近上报时间戳 */
+    private _throttleMap;
+    /**
+     * 稳定性监测钩子：节流之前注入，记录全量原始错误流（含被节流丢弃的同 key 重复）。
+     * 由 StabilityMonitorFacade 注入，作出错率/同因聚集的原始信号源。
+     */
+    private _stabilityHook?;
+    /**
+     * 构造错误监控器，注入依赖
+     *
+     * @param deps 依赖注入（历史/场景/视口等只读引用）
+     */
+    constructor(deps: ErrorMonitorDeps);
+    /**
+     * 设置/更新错误回调
+     *
+     * @param callback 错误上报回调
+     */
+    setCallback(callback: ErrorMonitorCallback): void;
+    /**
+     * 注入稳定性计数钩子（在 report() 节流之前触发，故记录到全量原始错误流）。
+     * 不动既有节流逻辑；未注入（undefined）时无副作用。
+     *
+     * @param cb 钩子回调；传 undefined 可解绑
+     */
+    setStabilityHook(cb?: (info: {
+        errorKey: string;
+        timestamp: number;
+        phase: string;
+    }) => void): void;
+    /**
+     * 上报错误 - 所有注入点调用此方法。
+     *
+     * 与 {@link captureSnapshot} 的区别：本方法走「节流去重 + 触发 callback」的误差回调通道，
+     * 受「未装配 callback」短路（无回调时直接 return，不抓快照、不触发）。节流与稳定性钩子
+     * 仅在 report 路径生效；captureSnapshot 不节流、不依赖 callback，供 error 事件按需逐条产出载荷。
+     *
+     * @param error     原始错误（任意类型，内部统一转为 Error）
+     * @param phase     错误阶段
+     * @param ctx       附加上下文（gizmoType / commandId / methodName）
+     * @param capturedInfo 可选的已捕获载荷，供业务事件与监控回调复用同一份快照
+     */
+    report(error: unknown, phase: ErrorPhase, ctx?: {
+        gizmoType?: string;
+        commandId?: string;
+        methodName?: string;
+    }, capturedInfo?: AnyArtisErrorInfo): void;
+    /**
+     * 产出错误快照 - 不节流、不依赖 callback，任何时候调都返回完整 {@link AnyArtisErrorInfo}。
+     *
+     * 供 `ArtisEvents['error']` 事件出口复用：error 事件作业务出口，不依赖 enableErrorMonitor
+     * 回调（误差回调通道默认关闭），emit('error') 时调用本方法产出「场景快照 + 最近 5 条 Command」
+     * 载荷。节流/去重归误差回调通道（{@link report}）独有，事件通道按需逐条 emit、去重由宿主自定。
+     *
+     * 各 getter 经 _safeGet 兜底：上报/emit 瞬间任一 getter 抛错都不阻断整条快照，退化为安全默认值。
+     *
+     * @param error     原始错误（任意类型，内部统一转为 Error）
+     * @param phase     错误阶段
+     * @param ctx       附加上下文（gizmoType / commandId / methodName）
+     * @param timestamp 可选时间戳（report 路径传入其节流判定后的 now；省略时取调用瞬间）
+     */
+    captureSnapshot(error: unknown, phase: ErrorPhase, ctx?: {
+        gizmoType?: string;
+        commandId?: string;
+        methodName?: string;
+    }, timestamp?: number): AnyArtisErrorInfo;
+    /**
+     * 清理节流记录与回调引用（dispose 时调用）
+     */
+    dispose(): void;
+    /**
+     * 捕获最近 5 条 Command 快照
+     *
+     * @returns 最近 Command 的快照列表
+     */
+    private _captureRecentCommands;
+    /**
+     * 捕获场景轻量快照的共有部分（视图大小 / 视口参数 / 还原数据 preItems）。
+     * items / selectedItems / 变体专属字段由 getArtisErrorSnapshot 在 report 时合并（各子类产出），
+     * 本方法只负责基类/Artis/SceneArtis 共有的部分。
+     *
+     * 所有 getter 经 _safeGet 兜底：上报瞬间任一 getter 抛错都不阻断整条快照，
+     * 退化为安全默认值（sceneSize 0、viewport zoom 1 / 位移 0 / contentRatio 1）。
+     *
+     * @returns 共有场景快照
+     */
+    private _captureBaseSnapshot;
+    /**
+     * 安全调用可选 getter：取值或捕获异常返回 undefined。供变体专属快照与共有 getter 取值兜底，
+     * 避免上报瞬间某个 getter 抛错导致整条快照丢失。
+     */
+    private _safeGet;
+}

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

@@ -0,0 +1,4 @@
+export { ErrorMonitor } from './error-monitor';
+export type { ArtisErrorInfo, ArtisErrorInfoBase, AnyArtisErrorInfo, SceneArtisErrorInfo, ErrorPhase, CommandSnapshot, SceneSnapshotBase, ArtisSnapshot, ArtisSnapshotExtras, SceneArtisSnapshot, SceneArtisSnapshotExtras, VariantErrorSnapshot, ItemSnapshot, ErrorMonitorCallback, ErrorMonitorDeps, } from './types';
+export { ErrorMonitorFacade } from './error-monitor-facade';
+export type { ErrorMonitorContext, ErrorMonitorFacadeTarget } from './error-monitor-facade';

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

@@ -0,0 +1,198 @@
+import type { spec } from '../../../shared';
+import type { SceneEntrySnapshot } from '../../store';
+/**
+ * 元素完整数据快照（直接用 toSchema 序列化，类型为 ItemSchema 的 JSON-safe 子集）
+ */
+export type ItemSnapshot = Record<string, unknown>;
+/**
+ * 错误发生的阶段
+ */
+export type ErrorPhase = 'gizmo-init' | 'gizmo-actionstart' | 'gizmo-actionupdate' | 'gizmo-actioncommit' | 'gizmo-key' | 'gizmo-draw' | 'command-execute' | 'command-undo' | 'command-redo' | 'method' | 'renderer' | 'item-create' | 'resource-load' | 'interaction';
+/**
+ * 最近 Command 的快照
+ * commandId: command 类型标识
+ * stackIndex: 在历史栈中的位置（0 = 最新）
+ * params: command 执行时携带的关键参数（从 command 实例上提取，可能为空）
+ * args: 工厂入参的 JSON-safe 序列化（用于复现页正向重放，不可序列化项以 null 占位）
+ * replayable: args 是否完整可重放（含函数/循环引用/实例引用等不可序列化项时为 false）
+ */
+export type CommandSnapshot = {
+    commandId: string;
+    stackIndex: number;
+    /** Command 执行时的关键参数（从实例上 _params / params 字段提取，无则为空对象） */
+    params: Record<string, unknown>;
+    /** 工厂入参序列化结果（单参对象，key-value），供复现页按 commandId + args 正向重放 */
+    args: Record<string, unknown>;
+    /** args 是否完整可重放；false 时复现页跳过执行并标注，仅展示上报时态 */
+    replayable: boolean;
+};
+/**
+ * 场景快照共有部分 - 只保存核心数据，不含实时渲染/GPU 数据。
+ * BaseArtis / Artis / SceneArtis 共享；items / selectedItems 等元素数据下沉到
+ * {@link ArtisSnapshot} / {@link SceneArtisSnapshot} 各子类专属扩展。
+ */
+export type SceneSnapshotBase = {
+    /** 视图大小（画布内容区域的宽高，由 ViewService.size 提供） */
+    sceneSize: {
+        width: number;
+        height: number;
+    };
+    /** 视图参数（缩放 / 位移 / 内容缩放比）。contentRatio 由 ViewService 提供，子类各自覆盖。 */
+    viewport: {
+        zoom: number;
+        translation: [number, number];
+        size: [number, number];
+        contentRatio: number;
+    };
+    /**
+     * 还原数据：撤销最近 N 条已成功入栈 Command 后的元素态（交互初始前数据）。
+     * 由 ErrorMonitor 上报瞬间用活的 HistoryManager 撤销取快照再 redo 回正得到，
+     * 比测试页从 JSON 反推更确定性。撤销失败或不可用时缺省。
+     */
+    preItems?: ItemSnapshot[];
+};
+/**
+ * Artis（编辑数据驱动）相对共有部分的增量字段（hook payload）。
+ * 由 Artis._captureErrorSnapshot 产出；ErrorMonitor 合并 SceneSnapshotBase 后得完整 {@link ArtisSnapshot}。
+ */
+export type ArtisSnapshotExtras = {
+    /** 场景中所有元素的完整数据（ItemSchema，toSchema 序列化，不含 GPU/纹理对象） */
+    items: ItemSnapshot[];
+    /** 当前选中元素 ID 列表（激活数据=选中元素） */
+    selectedItems: string[];
+};
+/**
+ * Artis（编辑数据驱动）完整场景错误快照 = 共有部分 + Artis 增量。
+ * 与 `variant: 'Artis'` tag 绑定。消费方 narrow 到 ArtisErrorInfo 后即得本类型
+ * （含 sceneSize/viewport/preItems/items，无需再与 SceneSnapshotBase 求交）。
+ */
+export type ArtisSnapshot = SceneSnapshotBase & ArtisSnapshotExtras;
+/**
+ * SceneArtis（多场景播放）相对共有部分的增量字段（hook payload）。
+ * 由 SceneArtis._captureErrorSnapshot 产出；ErrorMonitor 合并 SceneSnapshotBase 后得完整 {@link SceneArtisSnapshot}。
+ * items 不纳入(复现时 runtime 直接重新 assemble，走 scenes/entries 重建)。
+ *
+ * 注：内容缩放比 contentRatio 落在共有层 {@link SceneSnapshotBase.viewport}，
+ * 不在此重复（复现侧按 clipMode 经 widthRatio/heightRatio 经 setRatios 还原即可）。
+ */
+export type SceneArtisSnapshotExtras = {
+    /**
+     * 所有视图的 JSONScene 深克隆数组（兼容后备路径，无结构字段）。
+     */
+    scenes?: spec.JSONScene[];
+    /**
+     * 所有视图的结构快照(SceneEntrySnapshot[])，回带 source/adapt/originScene/readonly/id 等结构字段，
+     * 供复现页走 SceneArtis.reproduce 保真重建。与 scenes 并存(后者做兼容后备)。
+     */
+    sceneEntries?: SceneEntrySnapshot[];
+    /** 当前激活 Scene id，供复现页还原激活场景。 */
+    activeSceneId?: string;
+    /** 当前选中元素 ID 列表。 */
+    selectedItems: string[];
+    /** 视图参数：宽度轴缩放比（供复现 refreshContentScale 还原）。 */
+    widthRatio: number;
+    /** 视图参数：高度轴缩放比（供复现 refreshContentScale 还原）。 */
+    heightRatio: number;
+    /** 报错时播放游标，供复现页 goto 还原游标。 */
+    sceneTime?: number;
+    /** 报错时播放态，供复现页还原播放/停止态。 */
+    scenePlaying?: boolean;
+    /** 首个 origin 是否只读(展示标准产物)，供复现页还原只读态。 */
+    standardProduct?: boolean;
+};
+/**
+ * SceneArtis（多场景播放）完整场景错误快照 = 共有部分 + SceneArtis 增量。
+ * 与 `variant: 'SceneArtis'` tag 绑定。
+ */
+export type SceneArtisSnapshot = SceneSnapshotBase & SceneArtisSnapshotExtras;
+/**
+ * 变体专属错误快照 payload（tag 与 snapshot 增量形态由判别联合编译期绑定）。
+ * 由 BaseArtis._captureErrorSnapshot 产出（基类返回 undefined，Artis / SceneArtis 各自 override），
+ * 仅含变体增量字段（{@link ArtisSnapshotExtras} / {@link SceneArtisSnapshotExtras}）。
+ *
+ * 共有部分（sceneSize/viewport/preItems）由 ErrorMonitor 独立鲁棒捕获后合并，故意不纳入 hook 产出：
+ * 变体 hook 在上报瞬间可能抛错，独立捕获保证 base（关键复现上下文）不丢。
+ * tag 与对应增量形态一一对应，杜绝"变体标识与快照形态不一致"的标签撒谎。
+ */
+export type VariantErrorSnapshot = {
+    variant: 'Artis';
+    snapshot: ArtisSnapshotExtras;
+} | {
+    variant: 'SceneArtis';
+    snapshot: SceneArtisSnapshotExtras;
+};
+/**
+ * 错误上报信息共有部分（BaseArtis / Artis / SceneArtis 共享）。
+ * artisVariant 落在共有层供消费方判别走 Artis / SceneArtis 复现路径。
+ */
+export type ArtisErrorInfoBase = {
+    phase: ErrorPhase;
+    error: Error;
+    gizmoType?: string;
+    commandId?: string;
+    methodName?: string;
+    /**
+     * 报错时实际运行的 Artis 变体（取对应类名），供复现页据此选择对应类初始化场景。
+     * - 'BaseArtis'：基类（不应被直接实例化，仅为类型完备保留）
+     * - 'Artis'：编辑器场景（Artis 类，elementId 与 vfxItemId 分离）
+     * - 'SceneArtis'：多场景播放场景（SceneArtis 类，id===vfxItemId）
+     * 缺省 'Artis'（向后兼容无该字段的旧快照）
+     */
+    artisVariant?: 'BaseArtis' | 'Artis' | 'SceneArtis';
+    /** 最近执行的 5 条 Command（含执行参数摘要） */
+    recentCommands: CommandSnapshot[];
+    /** 顶层别名，便于复现页直接取交互初始前元素态（同 snapshot.preItems） */
+    preItems?: ItemSnapshot[];
+    timestamp: number;
+};
+/**
+ * Artis（编辑数据驱动）错误上报信息：snapshot 为完整 ArtisSnapshot（含共有 + items/selectedItems）。
+ */
+export type ArtisErrorInfo = ArtisErrorInfoBase & {
+    artisVariant?: 'Artis';
+    snapshot: ArtisSnapshot;
+};
+/**
+ * SceneArtis（多场景播放）错误上报信息：snapshot 为完整 SceneArtisSnapshot
+ * （含共有 + scenes/entries/激活场景/selectedItems/视图 ratios 等）。
+ */
+export type SceneArtisErrorInfo = ArtisErrorInfoBase & {
+    artisVariant: 'SceneArtis';
+    snapshot: SceneArtisSnapshot;
+};
+/**
+ * 完整错误上报信息（判别联合）：消费方按 artisVariant narrow 出子类专属字段。
+ */
+export type AnyArtisErrorInfo = ArtisErrorInfo | SceneArtisErrorInfo;
+/** 错误监听回调类型（接收判别联合，回调内按 artisVariant narrow） */
+export type ErrorMonitorCallback = (info: AnyArtisErrorInfo) => void;
+/**
+ * ErrorMonitor 依赖注入接口（由 Artis 提供只读引用）。
+ * 共有 getter 由基类提供；变体 tag 与专属快照扩展统一经 getArtisErrorSnapshot 一次性产出
+ * （Artis / SceneArtis 各自注入，tag 与 snapshot 形态由 {@link VariantErrorSnapshot} 绑定）。
+ */
+export type ErrorMonitorDeps = {
+    getRecentCommands: (count: number) => CommandSnapshot[];
+    getSceneSize: () => {
+        width: number;
+        height: number;
+    };
+    getViewport: () => {
+        zoom: number;
+        translation: [number, number];
+        size: [number, number];
+        contentRatio: number;
+    };
+    /**
+     * 撤销最近 count 条已成功入栈 Command 后取元素快照，再 redo 回正。
+     * 用于上报瞬间确定性捕获"交互初始前数据"（还原数据）。撤销失败或不可用时返回 undefined。
+     * 必须保证调用前后历史指针与场景态不变（纯读）。
+     */
+    snapshotBeforeRecentCommands: (count: number) => ItemSnapshot[] | undefined;
+    /**
+     * 取变体专属错误快照（variant tag + 对应形态 snapshot），由 Artis / SceneArtis 各自注入。
+     * 基类不注入（返回 undefined），快照仅含共有字段、artisVariant 兜底为 'Artis'。
+     * 返回 undefined / 抛错时同上兜底，不丢整条快照。
+     */
+    getArtisErrorSnapshot?: () => VariantErrorSnapshot | undefined;
+};

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

@@ -0,0 +1,3 @@
+export * from './error-monitor';
+export * from './perf-monitor';
+export * from './stability-monitor';

package/dist/core/quality/perf-monitor/index.d.ts

@@ -0,0 +1,5 @@
+export { PerfMonitor } from './perf-monitor';
+export { PerfPhase } from './types';
+export type { PerfPhaseToken, PerfMetric, PerfReport, PerfMonitorCallback, PerfMonitorDeps, } from './types';
+export { PerfMonitorFacade } from './perf-monitor-facade';
+export type { PerfMonitorContext } from './perf-monitor-facade';

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

@@ -0,0 +1,45 @@
+import { PerfMonitor } from './perf-monitor';
+import type { PerfMonitorCallback } from './types';
+/**
+ * PerfMonitorFacade 装配所需的最小上下文：被监测实例引用。
+ *
+ * perf-monitor 不反向依赖业务服务，时间源由 facade 内部用 performance.now() 提供，
+ * 故上下文远比 ErrorMonitorFacade 轻，无需注入 history/command/item 等服务。
+ */
+export type PerfMonitorContext = {
+    readonly target: Record<string, unknown>;
+};
+/**
+ * PerfMonitorFacade - 性能监测门面协作者。
+ *
+ * 从 BaseArtis 抽离，承载 PerfMonitor 的创建与回调注入，对齐 ErrorMonitorFacade 模式。
+ *
+ * 双开关：
+ * - 构造开关 options.perf → BaseArtis 构造期调 install() 预装配（采得到 INIT 段，无 callback 仅累积）
+ * - 运行期开关 enablePerfMonitor(cb) → 任何时候装配/换回调；与构造装配共享同一实例
+ *
+ * 未装配时 monitor 为 undefined，BaseArtis 各阶段经可选链短路，零开销。
+ * 与 ErrorMonitorFacade 不同：perf-monitor 是主动 mark/measure，故 facade 暴露 monitor 取用器。
+ */
+export declare class PerfMonitorFacade {
+    private _monitor?;
+    /**
+     * 取底层 PerfMonitor（供 BaseArtis 各阶段 mark/measure）。
+     * 未装配时返回 undefined，调用方用可选链短路。
+     */
+    get monitor(): PerfMonitor | undefined;
+    /**
+     * 装配 PerfMonitor（幂等）。
+     * 构造开关场景无 callback，仅装配采集器；运行期开关场景带 callback 一并设置。
+     */
+    install(callback?: PerfMonitorCallback): void;
+    /**
+     * 开启/换上报回调。已装配只更新回调，未装配才新建。
+     * 与 install() 共用同一实例：构造期已 install 过时此处仅 setCallback。
+     */
+    enable(callback: PerfMonitorCallback): void;
+    /**
+     * 销毁监测器（清标记/度量/回调）。
+     */
+    dispose(): void;
+}

package/dist/core/quality/perf-monitor/perf-monitor.d.ts

@@ -0,0 +1,60 @@
+import type { PerfMetric, PerfMonitorCallback, PerfMonitorDeps, PerfPhaseToken } from './types';
+/**
+ * PerfMonitor - Artis 性能监测核心
+ *
+ * 职责：
+ * 1. 提供 mark/measure 两级 API：mark 打起始标记、measure 结算耗时并生成 metric
+ * 2. 累积 metrics，供 report() 聚合后回调上报
+ * 3. 零反向依赖：不引用业务服务，时间来源经 deps 注入
+ *
+ * 设计参照 ErrorMonitor：被 PerfMonitorFacade 持有，由 BaseArtis 各阶段
+ * 经可选链调用 mark/measure（未 enable 时 facade 不存在，自动短路零开销）。
+ */
+export declare class PerfMonitor {
+    private _deps;
+    private _callback?;
+    /** markId → 起始时间戳 */
+    private _marks;
+    /** 已结算的度量累积区，report() 一并吐出后清空 */
+    private _metrics;
+    /**
+     * 构造性能监测器，注入时间依赖
+     *
+     * @param deps 依赖注入（时间源 now）
+     */
+    constructor(deps: PerfMonitorDeps);
+    /**
+     * 设置/更新上报回调
+     *
+     * 构造开关开启但 callback 未补时 metric 仍累积，待 enablePerfMonitor
+     * 补回调后由 report() 一并吐出，保证"先 new(perf:true) 后 enable(cb)"顺序下 INIT 不丢。
+     *
+     * @param callback 性能上报回调
+     */
+    setCallback(callback: PerfMonitorCallback): void;
+    /**
+     * 打起始标记
+     *
+     * @param id 标记唯一 id（由调用方自定，如 'init'、'scene-build'）
+     */
+    mark(id: string): void;
+    /**
+     * 结算标记并生成度量，存入累积区
+     *
+     * @param id      mark 时用的 id
+     * @param phase   性能阶段
+     * @param context 附加上下文（资源 url / assetType 等）
+     * @returns 度量记录；id 未 mark 过则返回 undefined
+     */
+    measure(id: string, phase: PerfPhaseToken, context?: Record<string, unknown>): PerfMetric | undefined;
+    /**
+     * 主动上报当前累积度量（如 emit('ready') 时整体上报）
+     *
+     * 无 callback 或无累积度量时静默返回；回调异常静默处理，不污染主流程。
+     */
+    report(): void;
+    /**
+     * 清理标记 / 度量 / 回调（dispose 时调用）
+     */
+    dispose(): void;
+}

package/dist/core/quality/perf-monitor/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 性能监测阶段
+ *
+ * 对应 Artis 生命周期可打点的耗时节点：
+ * - INIT           BaseArtis 构造（base-artis.ts:138 构造首行 → :207 emit('init')）
+ * - RESOURCE_LOAD  资源加载（image/video/effects/frame，item-asset-service.ts）
+ * - SCENE_BUILD    SceneArtis.run 阶段 A（scene-artis.ts:131 build）
+ * - SCENE_ASSEMBLE SceneArtis.run 阶段 C（scene-artis.ts:147 反向装配）
+ * - SCENE_RENDER   阶段 B Player 加载 + 阶段 D 首帧（scene-artis.ts:143 / :158）
+ * - GIZMO_PREPARE  prepareGizmo（scene-artis.ts:151）
+ * - READY          new Artis() → emit('ready') 总时长（base-artis.ts:492）
+ * - METHOD         门面公开方法耗时（可选，对齐 error-monitor wrap）
+ */
+export declare enum PerfPhase {
+    INIT = "init",
+    RESOURCE_LOAD = "resource-load",
+    SCENE_BUILD = "scene-build",
+    SCENE_ASSEMBLE = "scene-assemble",
+    SCENE_RENDER = "scene-render",
+    GIZMO_PREPARE = "gizmo-prepare",
+    READY = "ready",
+    METHOD = "method"
+}
+/**
+ * 性能阶段标识：枚举常量 + 容纳外部自定义阶段
+ *
+ * 用 `Enum | (string & {})` 形式：保留 IDE 补全 + 允许业务方扩展自有阶段，
+ * 不写死纯 union（与 CLAUDE.md 枚举集合规范一致）。
+ */
+export type PerfPhaseToken = PerfPhase | (string & {});
+/**
+ * 单条性能度量记录
+ */
+export type PerfMetric = {
+    /** 性能阶段 */
+    phase: PerfPhaseToken;
+    /** 耗时 ms（end - start） */
+    duration: number;
+    /** 起始时间戳（performance.now 域） */
+    startTime: number;
+    /** 附加上下文：如资源 url / assetType / itemId / commandId */
+    context?: Record<string, unknown>;
+};
+/**
+ * 一次上报聚合信息
+ */
+export type PerfReport = {
+    /** 本次上报的度量集合 */
+    metrics: PerfMetric[];
+    /** 关键总耗时（READY 阶段才填，从构造到 ready 的总时长） */
+    totalDuration?: number;
+    /** 上报时间戳（performance.now 域） */
+    timestamp: number;
+};
+/** 性能上报回调类型 */
+export type PerfMonitorCallback = (report: PerfReport) => void;
+/**
+ * PerfMonitor 依赖注入接口（纯读 + 时间源）
+ *
+ * perf-monitor 不反向依赖任何业务服务：仅通过 now() 取时间戳，
+ * 场景/历史等上下文由打点调用方经 context 字段透传，避免循环依赖。
+ */
+export type PerfMonitorDeps = {
+    /** 时间源，便于测试注入；生产用 () => performance.now() */
+    now: () => number;
+};

package/dist/core/quality/stability-monitor/index.d.ts

@@ -0,0 +1,5 @@
+export { StabilityMonitor } from './stability-monitor';
+export { StabilitySignal } from './types';
+export type { StabilitySignalToken, HealthState, StabilityReport, StabilityMonitorCallback, StabilityMonitorDeps, RecommendedAction, RecommendedActionToken, } from './types';
+export { StabilityMonitorFacade } from './stability-monitor-facade';
+export type { StabilityMonitorContext } from './stability-monitor-facade';

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

@@ -0,0 +1,50 @@
+import type { ErrorMonitor } from '../error-monitor';
+import type { StabilityMonitorCallback } from './types';
+import type { Renderer } from '../../renderer';
+/**
+ * StabilityMonitorFacade 装配所需的最小上下文。
+ *
+ * - renderer：取 playerAdapter 订阅 'contextLost'（独立信号，不依赖 error）
+ * - getErrorMonitor：可选，返回当前 ErrorMonitor（用于注入节流前错误钩子）；
+ *                    error 未开启时返回 undefined，error 类信号不工作
+ */
+export type StabilityMonitorContext = {
+    readonly renderer: Renderer;
+    readonly getErrorMonitor: () => ErrorMonitor | undefined;
+};
+/**
+ * StabilityMonitorFacade - 稳定性监测门面协作者。
+ *
+ * 装配照 BaseArtis _errorFacade / _perfFacade 模式（按需创建 + dispose 清理），
+ * 但内部是 stateful 聚合器：订阅 error 节流前钩子 + playerAdapter 'contextLost'
+ * → StabilityMonitor 维护 1 分钟滑动窗口 → onHealthChange 事件外达宿主。
+ *
+ * 形态与 error/perf 不同：
+ * - context-lost / fps 独立信号，error 未开启也能工作；
+ * - error 类信号靠 injectError 接入节流前钩子（注意 enable 顺序：先 stability 后 error 时由 BaseArtis 补连）。
+ */
+export declare class StabilityMonitorFacade {
+    private _monitor?;
+    private readonly _ctx;
+    private _unsubContextLost?;
+    constructor(ctx: StabilityMonitorContext);
+    /**
+     * 开启稳定性监测。创建 StabilityMonitor → 注入 error 钩子（若 error 已开启）→
+     * 订阅 contextLost → 设置回调。重复调用仅更新回调。
+     */
+    enable(callback: StabilityMonitorCallback): void;
+    /**
+     * 补连 error 钩子（error 延迟开启时由 BaseArtis.enableErrorMonitor 调用）。
+     * 若监测器未启用或已接入 error，则为空操作。
+     */
+    attachError(): void;
+    /** 销毁监测器（清窗口/订阅/回调） */
+    dispose(): void;
+    /**
+     * 经 ErrorMonitor.setStabilityHook 把节流前错误流接入监测器。
+     * error 未开启（monitor 为 undefined）时跳过——由 attachError 在 error 开启后补连。
+     */
+    private _injectError;
+    /** 订阅 playerAdapter 'contextLost'/'contextRestored' → monitor 降权/恢复（P0 瞬态信号） */
+    private _subscribeContextLost;
+}

package/dist/core/quality/stability-monitor/stability-monitor.d.ts

@@ -0,0 +1,61 @@
+import type { StabilityMonitorCallback, StabilityMonitorDeps } from './types';
+/**
+ * StabilityMonitor - Artis 稳定性监测核心（stateful 聚合器）
+ *
+ * 形态与 ErrorMonitor / PerfMonitor 不同：非被动逐条上报，
+ * 而是「订阅 error 节流前钩子 + 独立采样新信号 → 1 分钟滑动窗口聚合 → onHealthChange」。
+ *
+ * context-lost / fps 等独立信号不依赖 error 订阅，error 未开启时仍工作。
+ * 由 StabilityMonitorFacade 持有并注入 deps；未 enable 时不存在，零开销。
+ */
+export declare class StabilityMonitor {
+    private _deps;
+    private _callback?;
+    /** errorKey → 窗口内时间戳数组（落地过期） */
+    private _errorWindow;
+    private _health;
+    private _unsubError?;
+    private _disposed;
+    /**
+     * 构造稳定性监测器，注入时间源与可选 error 订阅
+     *
+     * @param deps 依赖注入（now 时间源；onError 可选 error 节流前钩子订阅）
+     */
+    constructor(deps: StabilityMonitorDeps);
+    /** 设置/更新健康度变化回调 */
+    setCallback(callback: StabilityMonitorCallback): void;
+    /**
+     * 接入 error 节流前错误流（幂等）。
+     * 构造期 deps.onError 已接入时可跳过；亦供 facade 在 error 延迟开启时补连。
+     *
+     * @param subscribe 订阅函数，返回取消订阅
+     */
+    attachError(subscribe: (cb: (info: {
+        errorKey: string;
+        timestamp: number;
+        phase: string;
+    }) => void) => () => void): void;
+    /**
+     * reportContextLost - P0：WebGL 上下文丢失，立即降健康度到 0 并上报。
+     *
+     * effects Player 已 opt-in 自恢复（doNotHandleContextLost:false），engine 在 webglcontextrestored
+     * 上就地重建 GPU 资源——故 context-lost 现为瞬态抖动而非永久事故：降权后随 {@link reportContextRestored}
+     * 恢复。recommendedAction 仍标 'recreate' 仅供宿主在自恢复失败时手动 recreate() 兜底，非自动触发。
+     */
+    reportContextLost(): void;
+    /**
+     * reportContextRestored：engine 已就地重建 GPU 资源、Player 存活，移除 CONTEXT_LOST 信号并
+     * 按当前 error 窗口重算健康度（恢复到 1 减惩罚）。瞬态抖动收口，非永久事故。
+     */
+    reportContextRestored(): void;
+    /**
+     * 清理窗口/订阅/回调（dispose 时调用，防回调重入）
+     */
+    dispose(): void;
+    /** 记录一条原始错误：推入窗口 + 落地过期 + 重算健康度 */
+    private _recordError;
+    /** 按当前窗口重算健康度（error-rate / error-cluster） */
+    private _recompute;
+    /** 上报一次健康度变化（回调异常静默，防递归） */
+    private _emit;
+}