miaoda-game-devkit 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,111 +1,75 @@
+import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-CYqLL8gY.js';
+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.js';
 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 };