miaoda-game-devkit 0.2.16 → 0.2.19

package/README.md

@@ -7,8 +7,23 @@
 - React 游戏的生产/手动时钟、Strict Mode 安全 Controller ownership、JSDOM
   Vitest 配置和自动收集运行错误的 Testing Library setup，分别从 `miaoda-game-devkit/react`、
   `miaoda-game-devkit/react/testing` 和 `miaoda-game-devkit/react/vitest-config` 导入；
-- React 的 `playthroughTest` 与项目级 reporter 自动验证生产入口、真实 DOM 输入、
-  有界推进和结果断言；聚焦运行只提示未检查，完整运行缺少有效流程时失败；
+- React 的 `playthroughTest` 与项目级 reporter 自动验证独立的 entry/primary DOM
+  输入、有界推进、结果断言及前后权威 snapshot 变化；聚焦运行只提示未检查，
+  完整运行缺少有效流程时失败；
+
+`playthroughTest` 的主流程回调从参数接收 `user`、`performInput`、`checkpoint`、
+`stepUntil` 和绑定当前测试的 `expect`。按 entry 输入、entered snapshot、primary 输入、
+有界等待、使用回调提供的 `expect` 断言结果、
+progress/terminal snapshot 的顺序记录最低证据。大型游戏仍只保留一条最短关键流程；
+分支、关卡规则和恢复清理由专门测试覆盖。不要再次调用 `userEvent.setup()`。
+时间、帧或自定义 scheduler 流程必须显式传入确定性 `step`；精确物理时间、暂停恢复
+或调度清理测试可使用 `ManualGameClock`。
+
+Vitest 的 fake timers（包括 `vi.advanceTimersToNextFrame()`）适合在 devkit 自身的
+专门 scheduler 合约中使用，但不在所有 production playthrough 中全局启用；React
+Testing Library 的 `asyncWrapper` 和 user-event 内部 timer 会因此互相影响。使用自定义
+scheduler、Worker 或未通过浏览器 timer 接入的引擎时，应传显式 `step` 并通过
+`diagnostics` 暴露权威状态。
 
 - React Vitest 在项目声明 Phaser 3 时使用其 browser bundle，并提供仅供模块能力探测的
   最小 Canvas 2D 边界，使 Phaser 3 代码不会阻断普通 JSDOM 测试；Storage 使用 JSDOM
@@ -33,10 +48,11 @@ Scene 生命周期。开发工具包只规定最小
 控制方法名和 Core 适配由游戏负责，controls 必须调用与生产输入共享的权威命令。Telemetry
 不会复制 `host.stepFrames()`、DOM 输入或 Scene 生命周期 API。
 
-`createHeadlessGame` 还记录测试期间真实发生的输入、完整帧、物理步、Scene 注册与访问、
-Scene 命令、restart、业务 checkpoint 和销毁。玩法测试可以调用
-`host.assertGameplayEvidence()` 把这些客观事实设为门禁；它不推断业务语义，
-authoritative state 仍必须由测试显式断言。
+`createHeadlessGame` 分别记录测试请求和 Phaser 公开事件确认的执行结果。输入必须被
+InputPlugin 消费，完整帧必须由活动 Scene 收到 `UPDATE`，Arcade 单步必须产生
+`WORLD_STEP`，Scene 转场和 restart 必须进入目标生命周期，才能满足对应的
+`host.assertGameplayEvidence()` 门禁。业务 checkpoint 和 authoritative state 仍必须由
+测试显式断言，devkit 不从引擎事件推断玩法语义。
 
 HEADLESS host 会把 Phaser 自身的 warning/error、Loader 文件失败、漏掉 `load.start()` 的队列、
 未注册 Scene 命令和可见对象的 `__MISSING` 纹理升级为测试失败。只有经过确认的引擎

package/dist/{gameplay-audit-DmbBA0M_.d.mts → gameplay-audit-CKgNYw2r.d.mts}

@@ -2,6 +2,31 @@ import * as Phaser from 'phaser';
 
 type EngineWarningMatcher = string | RegExp;
 
+type HeadlessSceneTransitionMethod = "start" | "launch" | "switch" | "sleep" | "wake";
+interface HeadlessSceneTransitionEvidence {
+    from: string;
+    to: string;
+    method: HeadlessSceneTransitionMethod;
+}
+interface HeadlessEngineEvidence {
+    /** Phaser Scene Systems 实际发出的 START 次数。 */
+    sceneStarts: Record<string, number>;
+    /** Phaser SceneManager 完成 create 后实际发出的 CREATE 次数。 */
+    sceneCreates: Record<string, number>;
+    /** 活跃 Scene 在完整游戏帧内实际收到的 UPDATE 次数。 */
+    sceneUpdates: Record<string, number>;
+    /** Phaser Scene Systems 实际完成的 SHUTDOWN 次数。 */
+    sceneShutdowns: Record<string, number>;
+    /** Phaser InputPlugin 消费并发布的指针事件数。 */
+    processedPointerEvents: number;
+    /** Phaser 命中可交互 Game Object 后发布的输入事件数。 */
+    processedGameObjectEvents: number;
+    /** Phaser KeyboardPlugin 消费并发布的键盘事件数。 */
+    processedKeyboardEvents: number;
+    /** Arcade World 实际完成并发布的 WORLD_STEP 次数。 */
+    arcadeWorldSteps: number;
+}
+
 interface HeadlessGameHost<TScene extends Phaser.Scene> {
     /** 当前隔离的 Phaser 游戏实例。 */
     game: Phaser.Game;
@@ -36,8 +61,12 @@ interface HeadlessGameHost<TScene extends Phaser.Scene> {
 interface HeadlessGameplayEvidence {
     /** 通过 host 公共 API 推进的完整 Phaser 帧数。 */
     frames: number;
+    /** host 推进期间至少被一个活动 Scene 实际观察到的帧数。 */
+    observedFrames: number;
     /** 显式执行的 Arcade Physics 单步数。 */
     physicsSteps: number;
+    /** 显式单步期间由 Arcade World 实际确认的物理步数。 */
+    observedPhysicsSteps: number;
     /** 投递到 Phaser canvas 的 DOM 鼠标事件数。 */
     mouseEvents: number;
     /** 投递到 Phaser 配置目标的 DOM 键盘事件数。 */
@@ -46,36 +75,40 @@ interface HeadlessGameplayEvidence {
     touchEvents: number;
     /** 通过输入辅助方法投递的复合 click 次数。 */
     clicks: number;
+    /** 同一次 DOM dispatch 内被 Phaser InputPlugin 实际消费的事件数。 */
+    consumedInputEvents: number;
+    /** Phaser 公开事件确认的生命周期、输入和物理执行证据。 */
+    engine: HeadlessEngineEvidence;
     /** 当前 host 注册过的全部 Scene key。 */
     registeredScenes: string[];
-    /** 至少进入过 Active 或 Paused 状态的 Scene key。 */
+    /** 实际收到过 Phaser START 生命周期事件的 Scene key。 */
     visitedScenes: string[];
-    /** 通过 Scene Plugin 的 restart 命令重启过的 Scene key。 */
+    /** 通过生产 restart 命令发出过重启请求的 Scene key。 */
+    restartRequests: string[];
+    /** restart 请求后实际进入了新 START 生命周期轮次的 Scene key。 */
     restartedScenes: string[];
     /** 测试显式记录的玩法检查点。 */
     checkpoints: string[];
     /** host 是否完成了游戏销毁流程。 */
     destroyed: boolean;
-    /** 通过 Scene Plugin 公共 API 观察到的 Scene 操作。 */
-    transitions: ReadonlyArray<{
-        from: string;
-        to: string;
-        method: "start" | "launch" | "switch" | "sleep" | "wake";
-    }>;
+    /** 通过 Scene Plugin 公共 API 发出的 Scene 操作请求。 */
+    transitionRequests: ReadonlyArray<HeadlessSceneTransitionEvidence>;
+    /** 请求后由目标 Scene 生命周期事件确认完成的 Scene 操作。 */
+    transitions: ReadonlyArray<HeadlessSceneTransitionEvidence>;
 }
 /** 一个玩法契约可以要求 host 必须留下的客观证据。 */
 interface HeadlessGameplayEvidenceRequirements {
-    /** 至少要求一次真实 DOM 鼠标、键盘或触摸事件。 */
+    /** 要求真实 DOM 输入被投递，且由 Phaser InputPlugin 实际消费。 */
     requireInput?: boolean;
-    /** 至少要求推进一个完整 Phaser 帧。 */
+    /** 要求 host 推进完整帧，且至少一个 Scene 实际收到 UPDATE。 */
     requireFrameAdvance?: boolean;
-    /** 至少要求执行一次显式 Arcade Physics 单步。 */
+    /** 要求显式推进 Arcade Physics，且 World 实际发布 WORLD_STEP。 */
     requirePhysicsStep?: boolean;
-    /** 要求发生一个或多个目标 key 匹配的 Scene 转场。 */
+    /** 要求转场请求已由目标 Scene 的实际生命周期事件确认。 */
     requireTransition?: string | string[];
     /** 要求一个或多个 Scene 至少进入过 Active 或 Paused 状态。 */
     requireScene?: string | string[];
-    /** 要求一个或多个 Scene 通过生产 restart 命令重启。 */
+    /** 要求 restart 请求后实际开始新的 Scene 生命周期轮次。 */
     requireRestart?: string | string[];
     /** 要求记录一个或多个由玩法测试定义的检查点。 */
     requireCheckpoint?: string | string[];

package/dist/{gameplay-audit-DmbBA0M_.d.ts → gameplay-audit-CKgNYw2r.d.ts}

@@ -2,6 +2,31 @@ import * as Phaser from 'phaser';
 
 type EngineWarningMatcher = string | RegExp;
 
+type HeadlessSceneTransitionMethod = "start" | "launch" | "switch" | "sleep" | "wake";
+interface HeadlessSceneTransitionEvidence {
+    from: string;
+    to: string;
+    method: HeadlessSceneTransitionMethod;
+}
+interface HeadlessEngineEvidence {
+    /** Phaser Scene Systems 实际发出的 START 次数。 */
+    sceneStarts: Record<string, number>;
+    /** Phaser SceneManager 完成 create 后实际发出的 CREATE 次数。 */
+    sceneCreates: Record<string, number>;
+    /** 活跃 Scene 在完整游戏帧内实际收到的 UPDATE 次数。 */
+    sceneUpdates: Record<string, number>;
+    /** Phaser Scene Systems 实际完成的 SHUTDOWN 次数。 */
+    sceneShutdowns: Record<string, number>;
+    /** Phaser InputPlugin 消费并发布的指针事件数。 */
+    processedPointerEvents: number;
+    /** Phaser 命中可交互 Game Object 后发布的输入事件数。 */
+    processedGameObjectEvents: number;
+    /** Phaser KeyboardPlugin 消费并发布的键盘事件数。 */
+    processedKeyboardEvents: number;
+    /** Arcade World 实际完成并发布的 WORLD_STEP 次数。 */
+    arcadeWorldSteps: number;
+}
+
 interface HeadlessGameHost<TScene extends Phaser.Scene> {
     /** 当前隔离的 Phaser 游戏实例。 */
     game: Phaser.Game;
@@ -36,8 +61,12 @@ interface HeadlessGameHost<TScene extends Phaser.Scene> {
 interface HeadlessGameplayEvidence {
     /** 通过 host 公共 API 推进的完整 Phaser 帧数。 */
     frames: number;
+    /** host 推进期间至少被一个活动 Scene 实际观察到的帧数。 */
+    observedFrames: number;
     /** 显式执行的 Arcade Physics 单步数。 */
     physicsSteps: number;
+    /** 显式单步期间由 Arcade World 实际确认的物理步数。 */
+    observedPhysicsSteps: number;
     /** 投递到 Phaser canvas 的 DOM 鼠标事件数。 */
     mouseEvents: number;
     /** 投递到 Phaser 配置目标的 DOM 键盘事件数。 */
@@ -46,36 +75,40 @@ interface HeadlessGameplayEvidence {
     touchEvents: number;
     /** 通过输入辅助方法投递的复合 click 次数。 */
     clicks: number;
+    /** 同一次 DOM dispatch 内被 Phaser InputPlugin 实际消费的事件数。 */
+    consumedInputEvents: number;
+    /** Phaser 公开事件确认的生命周期、输入和物理执行证据。 */
+    engine: HeadlessEngineEvidence;
     /** 当前 host 注册过的全部 Scene key。 */
     registeredScenes: string[];
-    /** 至少进入过 Active 或 Paused 状态的 Scene key。 */
+    /** 实际收到过 Phaser START 生命周期事件的 Scene key。 */
     visitedScenes: string[];
-    /** 通过 Scene Plugin 的 restart 命令重启过的 Scene key。 */
+    /** 通过生产 restart 命令发出过重启请求的 Scene key。 */
+    restartRequests: string[];
+    /** restart 请求后实际进入了新 START 生命周期轮次的 Scene key。 */
     restartedScenes: string[];
     /** 测试显式记录的玩法检查点。 */
     checkpoints: string[];
     /** host 是否完成了游戏销毁流程。 */
     destroyed: boolean;
-    /** 通过 Scene Plugin 公共 API 观察到的 Scene 操作。 */
-    transitions: ReadonlyArray<{
-        from: string;
-        to: string;
-        method: "start" | "launch" | "switch" | "sleep" | "wake";
-    }>;
+    /** 通过 Scene Plugin 公共 API 发出的 Scene 操作请求。 */
+    transitionRequests: ReadonlyArray<HeadlessSceneTransitionEvidence>;
+    /** 请求后由目标 Scene 生命周期事件确认完成的 Scene 操作。 */
+    transitions: ReadonlyArray<HeadlessSceneTransitionEvidence>;
 }
 /** 一个玩法契约可以要求 host 必须留下的客观证据。 */
 interface HeadlessGameplayEvidenceRequirements {
-    /** 至少要求一次真实 DOM 鼠标、键盘或触摸事件。 */
+    /** 要求真实 DOM 输入被投递，且由 Phaser InputPlugin 实际消费。 */
     requireInput?: boolean;
-    /** 至少要求推进一个完整 Phaser 帧。 */
+    /** 要求 host 推进完整帧，且至少一个 Scene 实际收到 UPDATE。 */
     requireFrameAdvance?: boolean;
-    /** 至少要求执行一次显式 Arcade Physics 单步。 */
+    /** 要求显式推进 Arcade Physics，且 World 实际发布 WORLD_STEP。 */
     requirePhysicsStep?: boolean;
-    /** 要求发生一个或多个目标 key 匹配的 Scene 转场。 */
+    /** 要求转场请求已由目标 Scene 的实际生命周期事件确认。 */
     requireTransition?: string | string[];
     /** 要求一个或多个 Scene 至少进入过 Active 或 Paused 状态。 */
     requireScene?: string | string[];
-    /** 要求一个或多个 Scene 通过生产 restart 命令重启。 */
+    /** 要求 restart 请求后实际开始新的 Scene 生命周期轮次。 */
     requireRestart?: string | string[];
     /** 要求记录一个或多个由玩法测试定义的检查点。 */
     requireCheckpoint?: string | string[];

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { a as GameplayContractMetadata, H as HeadlessGameHost, b as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-DmbBA0M_.mjs';
-export { E as EngineWarningMatcher, c as GameplayAuditContract, G as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-DmbBA0M_.mjs';
+import { a as GameplayContractMetadata, H as HeadlessGameHost, b as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-CKgNYw2r.mjs';
+export { E as EngineWarningMatcher, c as GameplayAuditContract, G as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-CKgNYw2r.mjs';
 import * as Phaser from 'phaser';
 import { TestContext, TestOptions } from 'vitest';
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as GameplayContractMetadata, H as HeadlessGameHost, b as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-DmbBA0M_.js';
-export { E as EngineWarningMatcher, c as GameplayAuditContract, G as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-DmbBA0M_.js';
+import { a as GameplayContractMetadata, H as HeadlessGameHost, b as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-CKgNYw2r.js';
+export { E as EngineWarningMatcher, c as GameplayAuditContract, G as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-CKgNYw2r.js';
 import * as Phaser from 'phaser';
 import { TestContext, TestOptions } from 'vitest';