miaoda-game-devkit 0.1.0 → 0.2.0

package/README.md

@@ -1,24 +1,26 @@
 # miaoda-game-devkit
 
-妙搭 Phaser 3.90+ 和 Phaser 4 游戏模板的共享开发基础设施。
+妙搭 Phaser 4 游戏模板的共享开发基础设施。
 
 该开发工具包提供：
 
-- 支持 DOM 鼠标输入的确定性 Phaser 无头测试宿主；
+- 支持 DOM 鼠标、键盘和触摸输入的确定性 Phaser 无头测试宿主；
 - 不依赖渲染器的运行时、交互区域和文字健康检查；
 - 由模板平台维护的通用 Vitest 契约测试；
 - 统一的 `miaoda-game-lint` 命令，聚合 TypeScript、Biome、Tailwind、
   Oxlint 和 Phaser 通用契约检查。
 - 统一的 `defineGameVitestConfig` 配置工厂，固定 Phaser 无头测试依赖的基础配置，
-  同时允许每个游戏配置自身的测试范围、覆盖率和超时等业务选项。
+  同时允许每个游戏声明玩法审计清单，并配置额外 alias、setup 文件和超时。
 
-`createHeadlessGame` 还记录测试期间真实发生的输入、完整帧、物理步和 Scene 切换。
-玩法测试可以调用 `host.assertGameplayEvidence()` 把这些客观事实设为门禁；它不推断
-业务语义，authoritative state 仍必须由测试显式断言。
+`createHeadlessGame` 还记录测试期间真实发生的输入、完整帧、物理步、Scene 注册与访问、
+Scene 命令、restart、业务 checkpoint 和销毁。玩法测试可以调用
+`host.assertGameplayEvidence()` 把这些客观事实设为门禁；它不推断业务语义，
+authoritative state 仍必须由测试显式断言。
 
-需要将证据绑定到 Vitest 单测试时，使用 `registerGameplayContract` 并传入测试上下文
-中的 `task` 和 `onTestFinished`。验证在测试完成生命周期执行，支持与模板通用
-`afterEach` cleanup 配合；contract id 和 evidence 摘要只通过可序列化 metadata 传递。
+玩法测试应优先使用 `gameplayTest`。它在 Vitest 收集阶段写入静态 contract metadata，
+在执行阶段绑定 HEADLESS host，并在 `onTestFinished` 校验 Ledger。`gameplayAudit` reporter
+会在测试执行前报告未声明或重复的 contract，在测试结束后汇总缺失、失败、证据不足、
+Scene 未访问和 registry 不一致。`registerGameplayContract` 保留为不参加执行前预检的低层接口。
 
 模板直接调用开发工具包提供的命令行程序：
 
@@ -33,8 +35,8 @@
 开发工具包自行维护工具版本，并从自身依赖中解析可执行文件，使用方不需要重复声明
 Biome、Oxlint 或 tsgo。仓库中保留稳定的命令入口，因此 `dist/` 尚未生成时，pnpm
 也能正确建立命令链接；工作区开发状态下由 Nx 在模板检查前构建开发工具包，发布包则
-直接携带运行时 `dist/`。`dist/lint/**/*.test.*` 仅供开发工具包自身的契约测试使用，
-由发布文件清单排除，不会进入 npm 包。
+直接携带运行时 `dist/`。开发工具包内部的 `*.test.*` 测试不会进入 npm 包；随包运行的
+通用契约测试以 `*.contract.mjs` 形式发布。
 
 monorepo 中的模板可以放置只包含 `extends: ["miaoda-game-devkit/biome"]` 的薄配置，
 用于让 Biome 从模板 package.json 判断依赖声明。规则本身仍由本开发工具包维护；生成后的
@@ -49,11 +51,39 @@ monorepo 中的模板可以放置只包含 `extends: ["miaoda-game-devkit/biome"
 同步帧逻辑使用 `stepFrames()`；`update()` 返回 Promise 时使用
 `await stepFramesAsync()`，其他同步操作启动生命周期 Promise 后使用 `await settle()`。
 
+输入驱动会把 DOM 兼容事件发送到 Phaser 实际配置的输入目标，并在每次事件后检查异步
+错误和运行时健康状态。坐标参数使用 Phaser 游戏坐标：
+
+```ts
+host.stepFrames();
+await host.input.mouse.click(100, 80);
+
+await host.input.keyboard.down(Phaser.Input.Keyboard.KeyCodes.RIGHT);
+host.stepFrames(10);
+await host.input.keyboard.up(Phaser.Input.Keyboard.KeyCodes.RIGHT);
+
+await host.input.touch.start(40, 40);
+await host.input.touch.move(100, 80);
+await host.input.touch.end(100, 80);
+```
+
+`click`、`press` 和 `tap` 适合离散命令。需要验证按住、拖动或滑动时，应分别调用开始和
+结束方法，并在两者之间推进完整 Phaser 帧。JSDOM 没有布局和真实渲染器；这些驱动验证
+DOM 到 Phaser 的输入、命中测试和游戏状态变化，不验证 Canvas/WebGL 像素、CSS 布局、
+浏览器焦点或真实触摸策略。
+
 模板的 `vitest.config.ts` 应从 `miaoda-game-devkit/vitest-config` 导入
 `defineGameVitestConfig`。JSDOM 环境、Phaser 浏览器构建别名、通用 setup 和 mock 隔离
-以及 Scene coverage 均由开发工具包统一维护。模板只传入 `projectRoot`；确有需要时，可以
-通过 `aliases`、`additionalSetupFiles`、`testTimeout` 和 `hookTimeout` 增加安全的项目配置，
-不能覆盖测试范围、运行环境或 coverage 基线。
+以及 Scene coverage 均由开发工具包统一维护。模板必须传入 `projectRoot` 和
+`gameplayAudit`；清单列出生产 Scene、关键 contract、负责的测试文件和证据要求。
+确有需要时，可以通过 `aliases`、`additionalSetupFiles`、`testTimeout` 和 `hookTimeout`
+增加安全的项目配置，不能覆盖测试范围、运行环境、审计 reporter 或 coverage 基线。
+
+`gameplayTest` 会自动要求访问其声明的 Scene 并完成 host 销毁。玩法进展、恢复和终局应在
+断言 authoritative state 后调用 `host.checkpoint("progress")`、
+`host.checkpoint("recovery")` 等稳定检查点，并在清单中通过 `requireCheckpoint` 声明。
+运行结束会输出稳定的 `GAMEPLAY_AUDIT: ALL CONTRACTS PASSED` 或
+`GAMEPLAY_AUDIT: ... FAILED` 标识。
 
 ## 发布顺序
 

package/bin/miaoda-game-lint.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
 
-require("../dist/cli/lint.js");
+require('../dist/cli/lint.js');

package/dist/cli/lint.js

@@ -43,7 +43,7 @@ async function runContracts() {
     "vitest",
     "vitest",
     "vitest",
-    ["run", "--config", (0, import_node_path.join)(devkitRoot, "dist/lint/vitest.config.mjs")]
+    ["run", "--config", (0, import_node_path.join)(devkitRoot, "dist/lint/contracts.config.mjs")]
   );
 }
 async function runAllChecks() {

package/dist/gameplay-audit-CYqLL8gY.d.mts

@@ -0,0 +1,193 @@
+import * as Phaser from 'phaser';
+
+interface HeadlessGameHost<TScene extends Phaser.Scene> {
+    /** 当前隔离的 Phaser 游戏实例。 */
+    game: Phaser.Game;
+    /** 作为测试入口启动的 Scene 实例。 */
+    scene: TScene;
+    /** 通过生产 DOM 目标驱动 Phaser 的输入工具。 */
+    input: HeadlessInputDriver;
+    /** 当前隔离 host 实际执行过的客观操作证据。 */
+    readonly evidence: Readonly<HeadlessGameplayEvidence>;
+    /** 当缺少声明的客观操作证据时抛出错误。 */
+    assertGameplayEvidence(requirements?: HeadlessGameplayEvidenceRequirements): void;
+    /** 等待同步操作触发的异步生命周期和错误检查完成。 */
+    settle(): Promise<void>;
+    /** 推进指定数量的完整 Phaser 帧。 */
+    stepFrames(count?: number): void;
+    /** 推进完整 Phaser 帧并等待异步 update 或生命周期完成。 */
+    stepFramesAsync(count?: number): Promise<void>;
+    /** 在限定帧数内推进游戏，直到条件成立。 */
+    stepUntil(condition: () => boolean, maxFrames?: number): number;
+    /** 精确推进指定次数的 Arcade Physics 单步。 */
+    stepPhysics(steps?: number): void;
+    /** 记录由测试定义的可序列化玩法检查点。 */
+    checkpoint(id: string): void;
+    /** 立即检查入口 Scene 的文字健康状态。 */
+    assertTextHealth(): void;
+    /** 幂等销毁游戏并记录清理证据。 */
+    destroy(): void;
+}
+/** 单个 HEADLESS host 在测试期间记录的只读玩法 Ledger。 */
+interface HeadlessGameplayEvidence {
+    /** 通过 host 公共 API 推进的完整 Phaser 帧数。 */
+    frames: number;
+    /** 显式执行的 Arcade Physics 单步数。 */
+    physicsSteps: number;
+    /** 投递到 Phaser canvas 的 DOM 鼠标事件数。 */
+    mouseEvents: number;
+    /** 投递到 Phaser 配置目标的 DOM 键盘事件数。 */
+    keyboardEvents: number;
+    /** 投递到 Phaser 配置目标的 DOM 触摸事件数。 */
+    touchEvents: number;
+    /** 通过输入辅助方法投递的复合 click 次数。 */
+    clicks: number;
+    /** 当前 host 注册过的全部 Scene key。 */
+    registeredScenes: string[];
+    /** 至少进入过 Active 或 Paused 状态的 Scene key。 */
+    visitedScenes: string[];
+    /** 通过 Scene Plugin 的 restart 命令重启过的 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";
+    }>;
+}
+/** 一个玩法契约可以要求 host 必须留下的客观证据。 */
+interface HeadlessGameplayEvidenceRequirements {
+    /** 至少要求一次真实 DOM 鼠标、键盘或触摸事件。 */
+    requireInput?: boolean;
+    /** 至少要求推进一个完整 Phaser 帧。 */
+    requireFrameAdvance?: boolean;
+    /** 至少要求执行一次显式 Arcade Physics 单步。 */
+    requirePhysicsStep?: boolean;
+    /** 要求发生一个或多个目标 key 匹配的 Scene 转场。 */
+    requireTransition?: string | string[];
+    /** 要求一个或多个 Scene 至少进入过 Active 或 Paused 状态。 */
+    requireScene?: string | string[];
+    /** 要求一个或多个 Scene 通过生产 restart 命令重启。 */
+    requireRestart?: string | string[];
+    /** 要求记录一个或多个由玩法测试定义的检查点。 */
+    requireCheckpoint?: string | string[];
+    /** 要求测试清理阶段完成 host 销毁。 */
+    requireDestroy?: boolean;
+}
+/** 用于把游戏坐标转换为 DOM 坐标的合成显示边界。 */
+interface HeadlessCanvasBounds {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** 由 Phaser 游戏坐标转换得到的 DOM 客户区坐标。 */
+interface HeadlessInputPoint {
+    clientX: number;
+    clientY: number;
+}
+/** 通过 Phaser 已配置鼠标目标投递事件的 DOM 鼠标控制器。 */
+interface HeadlessMouseInput {
+    /** 移动鼠标指针，并可指定当前按键位掩码。 */
+    move(x: number, y: number, buttons?: number): Promise<void>;
+    /** 按下鼠标主键并保持按下状态。 */
+    down(x: number, y: number): Promise<void>;
+    /** 释放鼠标主键。 */
+    up(x: number, y: number): Promise<void>;
+    /** 连续投递移动、按下和释放事件，完成一次离散点击。 */
+    click(x: number, y: number): Promise<void>;
+}
+/** 附加到 Phaser 数字键码上的可选 DOM KeyboardEvent 字段。 */
+interface HeadlessKeyboardEventOptions {
+    key?: string;
+    code?: string;
+    repeat?: boolean;
+    altKey?: boolean;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    shiftKey?: boolean;
+}
+/** 通过 Phaser 已配置键盘目标投递事件的 DOM 键盘控制器。 */
+interface HeadlessKeyboardInput {
+    /** 按下按键并保持，直到调用匹配的 up。 */
+    down(keyCode: number, options?: HeadlessKeyboardEventOptions): Promise<void>;
+    /** 释放之前保持按下的按键。 */
+    up(keyCode: number, options?: HeadlessKeyboardEventOptions): Promise<void>;
+    /** 不推进 Phaser 帧，连续投递一次离散的按下和释放。 */
+    press(keyCode: number, options?: HeadlessKeyboardEventOptions): Promise<void>;
+}
+/** 通过 Phaser 已配置触摸目标投递兼容 DOM 事件的触摸控制器。 */
+interface HeadlessTouchInput {
+    /** 使用在整个手势中保持稳定的标识开始一次触摸。 */
+    start(x: number, y: number, identifier?: number): Promise<void>;
+    /** 移动一次仍处于活动状态的触摸。 */
+    move(x: number, y: number, identifier?: number): Promise<void>;
+    /** 正常结束一次活动触摸。 */
+    end(x: number, y: number, identifier?: number): Promise<void>;
+    /** 取消一次活动触摸。 */
+    cancel(x: number, y: number, identifier?: number): Promise<void>;
+    /** 连续投递触摸开始和结束，完成一次离散轻触。 */
+    tap(x: number, y: number, identifier?: number): Promise<void>;
+}
+/** 确定性 DOM 到 Phaser 测试使用的公开输入边界。 */
+interface HeadlessInputDriver {
+    /** Phaser HEADLESS 为输入系统创建的 Canvas。 */
+    readonly canvas: HTMLCanvasElement;
+    /** DOM 鼠标事件驱动器。 */
+    readonly mouse: HeadlessMouseInput;
+    /** DOM 键盘事件驱动器。 */
+    readonly keyboard: HeadlessKeyboardInput;
+    /** DOM 触摸事件驱动器。 */
+    readonly touch: HeadlessTouchInput;
+    /** 设置用于坐标换算和 JSDOM 命中模拟的 Canvas 显示边界。 */
+    setCanvasBounds(bounds: HeadlessCanvasBounds): void;
+    /** 把 Phaser 游戏坐标换算为 DOM 客户区坐标。 */
+    gameToClient(x: number, y: number): HeadlessInputPoint;
+    /** 等待输入回调触发的异步任务并重新执行运行时健康检查。 */
+    settle(): Promise<void>;
+}
+/** 创建 HEADLESS 游戏时允许覆盖的 Phaser 配置和测试专用选项。 */
+type HeadlessGameOptions = Omit<Phaser.Types.Core.GameConfig, "type" | "scene" | "callbacks"> & {
+    /** 等待 Scene 完成创建的最长时间。 */
+    bootTimeoutMs?: number;
+    /** 初始 Scene 启动前必须注册的其他 Scene 类型。 */
+    additionalScenes?: Phaser.Types.Scenes.SceneType[];
+};
+/** 创建隔离的 Phaser 游戏，并在入口 Scene 完成 create 后返回。 */
+declare function createHeadlessGame<TScene extends Phaser.Scene>(scene: TScene, options?: HeadlessGameOptions): Promise<HeadlessGameHost<TScene>>;
+
+/** 一个必须由指定测试文件证明的玩法契约。 */
+interface GameplayAuditContract extends HeadlessGameplayEvidenceRequirements {
+    /** 在整个游戏项目中唯一且稳定的契约标识。 */
+    id: string;
+    /** 相对于游戏项目根目录的 Vitest 测试文件。 */
+    testFile: string;
+    /** 该契约负责证明的生产 Scene key。 */
+    scenes: string[];
+}
+/** 游戏项目在一次 Vitest 运行中必须完成的玩法审计清单。 */
+interface GameplayAuditOptions {
+    /** 生产 Scene registry 中预期出现的全部 Scene key。 */
+    scenes: string[];
+    /** 必须定义、执行并满足证据要求的玩法契约。 */
+    contracts: GameplayAuditContract[];
+}
+/** 通过 Vitest task metadata 在 worker 与 reporter 之间传递的契约数据。 */
+interface GameplayContractMetadata {
+    /** 契约唯一标识。 */
+    id: string;
+    /** 契约负责证明的生产 Scene key。 */
+    scenes: string[];
+    /** 已规范化的客观证据要求。 */
+    requirements: HeadlessGameplayEvidenceRequirements;
+    /** 测试完成后从 HEADLESS host 复制出的可序列化证据。 */
+    evidence?: HeadlessGameplayEvidence;
+    /** worker 是否已完成单测试证据校验。 */
+    verified?: boolean;
+}
+
+export { type GameplayContractMetadata as G, type HeadlessGameHost as H, type HeadlessGameplayEvidenceRequirements as a, type GameplayAuditContract as b, type GameplayAuditOptions as c, type HeadlessCanvasBounds as d, type HeadlessGameOptions as e, type HeadlessGameplayEvidence as f, type HeadlessInputDriver as g, type HeadlessInputPoint as h, type HeadlessKeyboardEventOptions as i, type HeadlessKeyboardInput as j, type HeadlessMouseInput as k, type HeadlessTouchInput as l, createHeadlessGame as m };

package/dist/gameplay-audit-CYqLL8gY.d.ts

@@ -0,0 +1,193 @@
+import * as Phaser from 'phaser';
+
+interface HeadlessGameHost<TScene extends Phaser.Scene> {
+    /** 当前隔离的 Phaser 游戏实例。 */
+    game: Phaser.Game;
+    /** 作为测试入口启动的 Scene 实例。 */
+    scene: TScene;
+    /** 通过生产 DOM 目标驱动 Phaser 的输入工具。 */
+    input: HeadlessInputDriver;
+    /** 当前隔离 host 实际执行过的客观操作证据。 */
+    readonly evidence: Readonly<HeadlessGameplayEvidence>;
+    /** 当缺少声明的客观操作证据时抛出错误。 */
+    assertGameplayEvidence(requirements?: HeadlessGameplayEvidenceRequirements): void;
+    /** 等待同步操作触发的异步生命周期和错误检查完成。 */
+    settle(): Promise<void>;
+    /** 推进指定数量的完整 Phaser 帧。 */
+    stepFrames(count?: number): void;
+    /** 推进完整 Phaser 帧并等待异步 update 或生命周期完成。 */
+    stepFramesAsync(count?: number): Promise<void>;
+    /** 在限定帧数内推进游戏，直到条件成立。 */
+    stepUntil(condition: () => boolean, maxFrames?: number): number;
+    /** 精确推进指定次数的 Arcade Physics 单步。 */
+    stepPhysics(steps?: number): void;
+    /** 记录由测试定义的可序列化玩法检查点。 */
+    checkpoint(id: string): void;
+    /** 立即检查入口 Scene 的文字健康状态。 */
+    assertTextHealth(): void;
+    /** 幂等销毁游戏并记录清理证据。 */
+    destroy(): void;
+}
+/** 单个 HEADLESS host 在测试期间记录的只读玩法 Ledger。 */
+interface HeadlessGameplayEvidence {
+    /** 通过 host 公共 API 推进的完整 Phaser 帧数。 */
+    frames: number;
+    /** 显式执行的 Arcade Physics 单步数。 */
+    physicsSteps: number;
+    /** 投递到 Phaser canvas 的 DOM 鼠标事件数。 */
+    mouseEvents: number;
+    /** 投递到 Phaser 配置目标的 DOM 键盘事件数。 */
+    keyboardEvents: number;
+    /** 投递到 Phaser 配置目标的 DOM 触摸事件数。 */
+    touchEvents: number;
+    /** 通过输入辅助方法投递的复合 click 次数。 */
+    clicks: number;
+    /** 当前 host 注册过的全部 Scene key。 */
+    registeredScenes: string[];
+    /** 至少进入过 Active 或 Paused 状态的 Scene key。 */
+    visitedScenes: string[];
+    /** 通过 Scene Plugin 的 restart 命令重启过的 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";
+    }>;
+}
+/** 一个玩法契约可以要求 host 必须留下的客观证据。 */
+interface HeadlessGameplayEvidenceRequirements {
+    /** 至少要求一次真实 DOM 鼠标、键盘或触摸事件。 */
+    requireInput?: boolean;
+    /** 至少要求推进一个完整 Phaser 帧。 */
+    requireFrameAdvance?: boolean;
+    /** 至少要求执行一次显式 Arcade Physics 单步。 */
+    requirePhysicsStep?: boolean;
+    /** 要求发生一个或多个目标 key 匹配的 Scene 转场。 */
+    requireTransition?: string | string[];
+    /** 要求一个或多个 Scene 至少进入过 Active 或 Paused 状态。 */
+    requireScene?: string | string[];
+    /** 要求一个或多个 Scene 通过生产 restart 命令重启。 */
+    requireRestart?: string | string[];
+    /** 要求记录一个或多个由玩法测试定义的检查点。 */
+    requireCheckpoint?: string | string[];
+    /** 要求测试清理阶段完成 host 销毁。 */
+    requireDestroy?: boolean;
+}
+/** 用于把游戏坐标转换为 DOM 坐标的合成显示边界。 */
+interface HeadlessCanvasBounds {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** 由 Phaser 游戏坐标转换得到的 DOM 客户区坐标。 */
+interface HeadlessInputPoint {
+    clientX: number;
+    clientY: number;
+}
+/** 通过 Phaser 已配置鼠标目标投递事件的 DOM 鼠标控制器。 */
+interface HeadlessMouseInput {
+    /** 移动鼠标指针，并可指定当前按键位掩码。 */
+    move(x: number, y: number, buttons?: number): Promise<void>;
+    /** 按下鼠标主键并保持按下状态。 */
+    down(x: number, y: number): Promise<void>;
+    /** 释放鼠标主键。 */
+    up(x: number, y: number): Promise<void>;
+    /** 连续投递移动、按下和释放事件，完成一次离散点击。 */
+    click(x: number, y: number): Promise<void>;
+}
+/** 附加到 Phaser 数字键码上的可选 DOM KeyboardEvent 字段。 */
+interface HeadlessKeyboardEventOptions {
+    key?: string;
+    code?: string;
+    repeat?: boolean;
+    altKey?: boolean;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    shiftKey?: boolean;
+}
+/** 通过 Phaser 已配置键盘目标投递事件的 DOM 键盘控制器。 */
+interface HeadlessKeyboardInput {
+    /** 按下按键并保持，直到调用匹配的 up。 */
+    down(keyCode: number, options?: HeadlessKeyboardEventOptions): Promise<void>;
+    /** 释放之前保持按下的按键。 */
+    up(keyCode: number, options?: HeadlessKeyboardEventOptions): Promise<void>;
+    /** 不推进 Phaser 帧，连续投递一次离散的按下和释放。 */
+    press(keyCode: number, options?: HeadlessKeyboardEventOptions): Promise<void>;
+}
+/** 通过 Phaser 已配置触摸目标投递兼容 DOM 事件的触摸控制器。 */
+interface HeadlessTouchInput {
+    /** 使用在整个手势中保持稳定的标识开始一次触摸。 */
+    start(x: number, y: number, identifier?: number): Promise<void>;
+    /** 移动一次仍处于活动状态的触摸。 */
+    move(x: number, y: number, identifier?: number): Promise<void>;
+    /** 正常结束一次活动触摸。 */
+    end(x: number, y: number, identifier?: number): Promise<void>;
+    /** 取消一次活动触摸。 */
+    cancel(x: number, y: number, identifier?: number): Promise<void>;
+    /** 连续投递触摸开始和结束，完成一次离散轻触。 */
+    tap(x: number, y: number, identifier?: number): Promise<void>;
+}
+/** 确定性 DOM 到 Phaser 测试使用的公开输入边界。 */
+interface HeadlessInputDriver {
+    /** Phaser HEADLESS 为输入系统创建的 Canvas。 */
+    readonly canvas: HTMLCanvasElement;
+    /** DOM 鼠标事件驱动器。 */
+    readonly mouse: HeadlessMouseInput;
+    /** DOM 键盘事件驱动器。 */
+    readonly keyboard: HeadlessKeyboardInput;
+    /** DOM 触摸事件驱动器。 */
+    readonly touch: HeadlessTouchInput;
+    /** 设置用于坐标换算和 JSDOM 命中模拟的 Canvas 显示边界。 */
+    setCanvasBounds(bounds: HeadlessCanvasBounds): void;
+    /** 把 Phaser 游戏坐标换算为 DOM 客户区坐标。 */
+    gameToClient(x: number, y: number): HeadlessInputPoint;
+    /** 等待输入回调触发的异步任务并重新执行运行时健康检查。 */
+    settle(): Promise<void>;
+}
+/** 创建 HEADLESS 游戏时允许覆盖的 Phaser 配置和测试专用选项。 */
+type HeadlessGameOptions = Omit<Phaser.Types.Core.GameConfig, "type" | "scene" | "callbacks"> & {
+    /** 等待 Scene 完成创建的最长时间。 */
+    bootTimeoutMs?: number;
+    /** 初始 Scene 启动前必须注册的其他 Scene 类型。 */
+    additionalScenes?: Phaser.Types.Scenes.SceneType[];
+};
+/** 创建隔离的 Phaser 游戏，并在入口 Scene 完成 create 后返回。 */
+declare function createHeadlessGame<TScene extends Phaser.Scene>(scene: TScene, options?: HeadlessGameOptions): Promise<HeadlessGameHost<TScene>>;
+
+/** 一个必须由指定测试文件证明的玩法契约。 */
+interface GameplayAuditContract extends HeadlessGameplayEvidenceRequirements {
+    /** 在整个游戏项目中唯一且稳定的契约标识。 */
+    id: string;
+    /** 相对于游戏项目根目录的 Vitest 测试文件。 */
+    testFile: string;
+    /** 该契约负责证明的生产 Scene key。 */
+    scenes: string[];
+}
+/** 游戏项目在一次 Vitest 运行中必须完成的玩法审计清单。 */
+interface GameplayAuditOptions {
+    /** 生产 Scene registry 中预期出现的全部 Scene key。 */
+    scenes: string[];
+    /** 必须定义、执行并满足证据要求的玩法契约。 */
+    contracts: GameplayAuditContract[];
+}
+/** 通过 Vitest task metadata 在 worker 与 reporter 之间传递的契约数据。 */
+interface GameplayContractMetadata {
+    /** 契约唯一标识。 */
+    id: string;
+    /** 契约负责证明的生产 Scene key。 */
+    scenes: string[];
+    /** 已规范化的客观证据要求。 */
+    requirements: HeadlessGameplayEvidenceRequirements;
+    /** 测试完成后从 HEADLESS host 复制出的可序列化证据。 */
+    evidence?: HeadlessGameplayEvidence;
+    /** worker 是否已完成单测试证据校验。 */
+    verified?: boolean;
+}
+
+export { type GameplayContractMetadata as G, type HeadlessGameHost as H, type HeadlessGameplayEvidenceRequirements as a, type GameplayAuditContract as b, type GameplayAuditOptions as c, type HeadlessCanvasBounds as d, type HeadlessGameOptions as e, type HeadlessGameplayEvidence as f, type HeadlessInputDriver as g, type HeadlessInputPoint as h, type HeadlessKeyboardEventOptions as i, type HeadlessKeyboardInput as j, type HeadlessMouseInput as k, type HeadlessTouchInput as l, createHeadlessGame as m };

package/dist/index.d.mts

@@ -1,111 +1,75 @@
+import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-CYqLL8gY.mjs';
+export { b as GameplayAuditContract, c 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-CYqLL8gY.mjs';
 import * as Phaser from 'phaser';
+import { TestContext, TestOptions } from 'vitest';
 
-interface HeadlessGameHost<TScene extends Phaser.Scene> {
-    game: Phaser.Game;
-    scene: TScene;
-    input: HeadlessInputDriver;
-    /** 当前隔离 host 实际执行过的客观操作证据。 */
-    readonly evidence: Readonly<HeadlessGameplayEvidence>;
-    /** 当缺少所要求的输入、时间、物理或转场证据时失败。 */
-    assertGameplayEvidence(requirements?: HeadlessGameplayEvidenceRequirements): void;
-    settle(): Promise<void>;
-    stepFrames(count?: number): void;
-    stepFramesAsync(count?: number): Promise<void>;
-    stepUntil(condition: () => boolean, maxFrames?: number): number;
-    stepPhysics(steps?: number): void;
-    assertTextHealth(): void;
-    destroy(): void;
-}
-interface HeadlessGameplayEvidence {
-    /** 通过 host 公共 API 推进的完整 Phaser 帧数。 */
-    frames: number;
-    /** 显式执行的 Arcade Physics 单步数。 */
-    physicsSteps: number;
-    /** 投递到 Phaser canvas 的 DOM 鼠标事件数。 */
-    mouseEvents: number;
-    /** 通过输入辅助方法投递的复合 click 次数。 */
-    clicks: number;
-    /** 通过 Scene Plugin 公共 API 观察到的 Scene 操作。 */
-    transitions: ReadonlyArray<{
-        from: string;
-        to: string;
-        method: "start" | "launch" | "switch" | "sleep" | "wake";
-    }>;
-}
-interface HeadlessGameplayEvidenceRequirements {
-    /** 至少要求一次真实 DOM 鼠标事件。 */
-    requireInput?: boolean;
-    /** 至少要求推进一个完整 Phaser 帧。 */
-    requireFrameAdvance?: boolean;
-    /** 至少要求执行一次显式 Arcade Physics 单步。 */
-    requirePhysicsStep?: boolean;
-    /** 要求发生一个或多个目标 key 匹配的 Scene 转场。 */
-    requireTransition?: string | string[];
-}
-interface HeadlessCanvasBounds {
-    left: number;
-    top: number;
-    width: number;
-    height: number;
-}
-interface HeadlessInputPoint {
-    clientX: number;
-    clientY: number;
-}
-interface HeadlessMouseInput {
-    move(x: number, y: number, buttons?: number): Promise<void>;
-    down(x: number, y: number): Promise<void>;
-    up(x: number, y: number): Promise<void>;
-    click(x: number, y: number): Promise<void>;
-}
-interface HeadlessInputDriver {
-    readonly canvas: HTMLCanvasElement;
-    readonly mouse: HeadlessMouseInput;
-    setCanvasBounds(bounds: HeadlessCanvasBounds): void;
-    gameToClient(x: number, y: number): HeadlessInputPoint;
-    settle(): Promise<void>;
-}
-type HeadlessGameOptions = Omit<Phaser.Types.Core.GameConfig, "type" | "scene" | "callbacks"> & {
-    /** Maximum time to wait for Scene creation to complete. */
-    bootTimeoutMs?: number;
-    /** Scene types that must be registered before the initial Scene starts. */
-    additionalScenes?: Phaser.Types.Scenes.SceneType[];
-};
-/** Creates one isolated Phaser game and resolves after the scene has run create(). */
-declare function createHeadlessGame<TScene extends Phaser.Scene>(scene: TScene, options?: HeadlessGameOptions): Promise<HeadlessGameHost<TScene>>;
-
+/** 将单个 Vitest 测试绑定到玩法 Ledger 的契约选项。 */
 interface GameplayContractOptions extends HeadlessGameplayEvidenceRequirements {
-    /** 生产玩法清单中稳定且可读的 contract 标识。 */
+    /** 生产玩法清单中稳定且唯一的 contract 标识。 */
     id: string;
+    /** 当前契约负责证明的生产 Scene key。 */
+    scenes?: string[];
+}
+/** 在收集阶段声明静态 metadata 的 gameplayTest 选项。 */
+interface GameplayTestOptions extends GameplayContractOptions {
+    /** 当前契约必须负责至少一个生产 Scene。 */
+    scenes: string[];
+    /** 透传给 Vitest 的非 metadata 测试选项。 */
+    testOptions?: Omit<TestOptions, "meta">;
 }
+/** 单个玩法测试用于绑定 host 和主动校验证据的句柄。 */
 interface GameplayContractHandle<TScene extends Phaser.Scene> {
     /** 将当前 contract 绑定到实际创建的 HEADLESS host。 */
     attachHost(host: HeadlessGameHost<TScene>): void;
-    /** 立即验证证据；通常由生命周期回调自动执行。 */
+    /** 立即验证证据；通常由 onTestFinished 自动执行。 */
     verify(): void;
 }
+/** registerGameplayContract 所需的最小 Vitest 测试上下文。 */
 interface GameplayTestContext {
+    /** 当前 Vitest task 及其可序列化 metadata。 */
     task: {
-        meta: Record<string, unknown>;
+        meta: {
+            gameplayContract?: GameplayContractMetadata;
+        };
     };
+    /** 注册在测试及 afterEach 结束后执行的回调。 */
     onTestFinished(callback: () => void | Promise<void>): void;
+    /** 注册仅在当前测试失败时执行的回调。 */
     onTestFailed?: (callback: () => void) => void;
 }
+/** gameplayTest 测试函数接收的契约参数。 */
+interface GameplayTestArguments<TScene extends Phaser.Scene> {
+    /** Vitest 原生测试上下文。 */
+    context: TestContext;
+    /** 已自动注册到当前 task 的玩法契约句柄。 */
+    contract: GameplayContractHandle<TScene>;
+}
 /**
  * 将一个 gameplay contract 绑定到当前 Vitest 测试。
  *
- * 证据校验在 `onTestFinished` 中执行，晚于 `afterEach`，因此即使测试使用
- * 通用 cleanup 销毁 host，也仍可读取 host 的 renderer-independent evidence。
- * contract 元数据只包含可序列化值，供 reporter 在 worker 之外汇总。
+ * 证据校验在 `onTestFinished` 中执行，晚于 `afterEach`，因此通用 cleanup
+ * 可以先销毁 host。写入 metadata 的内容全部可序列化，供主线程 reporter 汇总。
  */
 declare function registerGameplayContract<TScene extends Phaser.Scene>(context: GameplayTestContext, options: GameplayContractOptions): GameplayContractHandle<TScene>;
+/**
+ * 定义一个可被全局 reporter 在执行前发现的玩法测试。
+ *
+ * 该方法在测试收集阶段写入静态 metadata，并在执行阶段自动注册同一个 contract。
+ */
+declare function gameplayTest<TScene extends Phaser.Scene>(name: string, options: GameplayTestOptions, run: (arguments_: GameplayTestArguments<TScene>) => void | Promise<void>): void;
+declare module "vitest" {
+    interface TaskMeta {
+        /** 供玩法审计 reporter 读取的可序列化契约数据。 */
+        gameplayContract?: GameplayContractMetadata;
+    }
+}
 
 declare function assertSceneRuntimeHealth(scene: Phaser.Scene): void;
 declare function assertSceneInteractiveHealth(scene: Phaser.Scene): void;
 
-/** Returns non-whitespace UTF-16 code units that are absent from a Bitmap Font. */
+/** 返回 Bitmap Font 中缺失的非空白 UTF-16 code unit。 */
 declare function collectMissingBitmapGlyphs(text: string, chars: Record<number, unknown>): string[];
-/** Throws an actionable error suitable for CI and coding-agent feedback. */
+/** 在文字状态损坏时抛出适合 CI 和编码智能体处理的错误。 */
 declare function assertSceneTextHealth(scene: Phaser.Scene): void;
 
-export { type GameplayContractHandle, type GameplayContractOptions, type GameplayTestContext, type HeadlessCanvasBounds, type HeadlessGameHost, type HeadlessGameOptions, type HeadlessGameplayEvidence, type HeadlessGameplayEvidenceRequirements, type HeadlessInputDriver, type HeadlessInputPoint, type HeadlessMouseInput, assertSceneInteractiveHealth, assertSceneRuntimeHealth, assertSceneTextHealth, collectMissingBitmapGlyphs, createHeadlessGame, registerGameplayContract };
+export { type GameplayContractHandle, GameplayContractMetadata, type GameplayContractOptions, type GameplayTestArguments, type GameplayTestContext, type GameplayTestOptions, HeadlessGameHost, HeadlessGameplayEvidenceRequirements, assertSceneInteractiveHealth, assertSceneRuntimeHealth, assertSceneTextHealth, collectMissingBitmapGlyphs, gameplayTest, registerGameplayContract };