miaoda-game-devkit 0.2.6 → 0.2.8

package/dist/{gameplay-audit-XBGq_jIV.d.mts → gameplay-audit-CusQfLYQ.d.mts}

@@ -18,7 +18,9 @@ interface HeadlessGameHost<TScene extends Phaser.Scene> {
     /** 推进完整 Phaser 帧并等待异步 update 或生命周期完成。 */
     stepFramesAsync(count?: number): Promise<void>;
     /** 在限定帧数内推进游戏，直到条件成立。 */
-    stepUntil(condition: () => boolean, maxFrames?: number): number;
+    stepUntil(condition: () => boolean, maxFrames?: number | {
+        maxFrames?: number;
+    }): number;
     /** 精确推进指定次数的 Arcade Physics 单步。 */
     stepPhysics(steps?: number): void;
     /** 记录由测试定义的可序列化玩法检查点。 */

package/dist/{gameplay-audit-XBGq_jIV.d.ts → gameplay-audit-CusQfLYQ.d.ts}

@@ -18,7 +18,9 @@ interface HeadlessGameHost<TScene extends Phaser.Scene> {
     /** 推进完整 Phaser 帧并等待异步 update 或生命周期完成。 */
     stepFramesAsync(count?: number): Promise<void>;
     /** 在限定帧数内推进游戏，直到条件成立。 */
-    stepUntil(condition: () => boolean, maxFrames?: number): number;
+    stepUntil(condition: () => boolean, maxFrames?: number | {
+        maxFrames?: number;
+    }): number;
     /** 精确推进指定次数的 Arcade Physics 单步。 */
     stepPhysics(steps?: number): void;
     /** 记录由测试定义的可序列化玩法检查点。 */

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-XBGq_jIV.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-XBGq_jIV.mjs';
+import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-CusQfLYQ.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-CusQfLYQ.mjs';
 import * as Phaser from 'phaser';
 import { TestContext, TestOptions } from 'vitest';
 
@@ -23,6 +23,8 @@ interface GameplayTestOptions extends GameplayContractOptions {
 interface GameplayContractHandle<TScene extends Phaser.Scene> {
     /** 将当前 contract 绑定到实际创建的 HEADLESS host。 */
     attachHost(host: HeadlessGameHost<TScene>): void;
+    /** 记录一个由测试先断言、再声明的玩法检查点。 */
+    checkpoint(id: string): void;
     /** 立即验证证据；通常由 onTestFinished 自动执行。 */
     verify(): void;
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-XBGq_jIV.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-XBGq_jIV.js';
+import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-CusQfLYQ.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-CusQfLYQ.js';
 import * as Phaser from 'phaser';
 import { TestContext, TestOptions } from 'vitest';
 
@@ -23,6 +23,8 @@ interface GameplayTestOptions extends GameplayContractOptions {
 interface GameplayContractHandle<TScene extends Phaser.Scene> {
     /** 将当前 contract 绑定到实际创建的 HEADLESS host。 */
     attachHost(host: HeadlessGameHost<TScene>): void;
+    /** 记录一个由测试先断言、再声明的玩法检查点。 */
+    checkpoint(id: string): void;
     /** 立即验证证据；通常由 onTestFinished 自动执行。 */
     verify(): void;
 }

package/dist/index.js

@@ -1021,7 +1021,8 @@ async function createHeadlessGame(scene, options = {}) {
       stepFrames(count);
       await settleRuntime();
     },
-    stepUntil(condition, maxFrames = 120) {
+    stepUntil(condition, maxFramesOrOptions = 120) {
+      const maxFrames = typeof maxFramesOrOptions === "number" ? maxFramesOrOptions : maxFramesOrOptions.maxFrames ?? 120;
       assertStepCount(maxFrames, "stepUntil maxFrames");
       throwRuntimeError();
       for (let frame = 0; frame <= maxFrames; frame += 1) {
@@ -1193,6 +1194,14 @@ function registerGameplayContract(context, options) {
       }
       host = currentHost;
     },
+    checkpoint(id) {
+      if (!host) {
+        throw new Error(
+          `Gameplay contract "${options.id}" must attach a HEADLESS host before recording a checkpoint.`
+        );
+      }
+      host.checkpoint(id);
+    },
     verify
   };
 }

package/dist/index.mjs

@@ -979,7 +979,8 @@ async function createHeadlessGame(scene, options = {}) {
       stepFrames(count);
       await settleRuntime();
     },
-    stepUntil(condition, maxFrames = 120) {
+    stepUntil(condition, maxFramesOrOptions = 120) {
+      const maxFrames = typeof maxFramesOrOptions === "number" ? maxFramesOrOptions : maxFramesOrOptions.maxFrames ?? 120;
       assertStepCount(maxFrames, "stepUntil maxFrames");
       throwRuntimeError();
       for (let frame = 0; frame <= maxFrames; frame += 1) {
@@ -1151,6 +1152,14 @@ function registerGameplayContract(context, options) {
       }
       host = currentHost;
     },
+    checkpoint(id) {
+      if (!host) {
+        throw new Error(
+          `Gameplay contract "${options.id}" must attach a HEADLESS host before recording a checkpoint.`
+        );
+      }
+      host.checkpoint(id);
+    },
     verify
   };
 }

package/dist/lint/gameplay-audit.contract.mjs

@@ -308,7 +308,11 @@ function auditGameplayRun(options2, tests) {
     }
     issues.push(...getDefinitionIssues(expected, metadata));
     if (test.state !== "passed") {
-      issues.push(`contract "${expected.id}" \u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A ${test.state}\u3002`);
+      if (test.error) {
+        issues.push(`\u73A9\u6CD5\u6D4B\u8BD5 "${expected.id}" \u6D4B\u8BD5\u5931\u8D25\uFF1A${test.error}`);
+      } else {
+        issues.push(`\u73A9\u6CD5\u6D4B\u8BD5 "${expected.id}" \u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A ${test.state}\u3002`);
+      }
       continue;
     }
     if (!metadata.verified || !metadata.evidence) {
@@ -383,7 +387,8 @@ function formatGameplayIssues(issues) {
     destroy: "\u6E05\u7406\uFF1A\u5728 afterEach \u4E2D\u8C03\u7528 host.destroy()\uFF0C\u5E76\u4FDD\u6301\u9500\u6BC1\u5E42\u7B49\u3002",
     registry: "Scene \u6CE8\u518C\uFF1A\u786E\u8BA4\u6E38\u620F\u6E90\u7801\u6CE8\u518C\u4E86\u8BE5 Scene\uFF1B\u6D4B\u8BD5\u9700\u8981\u5207\u6362\u5230\u5B83\u65F6\uFF0C\u5728\u521B\u5EFA host \u65F6\u901A\u8FC7 additionalScenes \u63D0\u4F9B Scene \u7C7B\u3002",
     missing: "\u6253\u5F00\u4E0A\u8FF0\u6587\u4EF6\uFF0C\u7528 gameplayTest \u6DFB\u52A0\u8FD9\u4E9B\u73A9\u6CD5\u6D4B\u8BD5\uFF1Bid \u5FC5\u987B\u4E0E vitest.config.ts \u4E2D\u7684\u914D\u7F6E\u5B8C\u5168\u4E00\u81F4\uFF0C\u521B\u5EFA host \u540E\u8C03\u7528 contract.attachHost(host)\u3002",
-    test: "\u5148\u4FEE\u590D\u5BF9\u5E94\u6D4B\u8BD5\u4E0A\u65B9\u663E\u793A\u7684\u7B2C\u4E00\u6761\u539F\u59CB\u9519\u8BEF\uFF0C\u7136\u540E\u91CD\u65B0\u8FD0\u884C pnpm test\u3002"
+    test: "\u5148\u4FEE\u590D\u5BF9\u5E94\u6D4B\u8BD5\u4E0A\u65B9\u663E\u793A\u7684\u7B2C\u4E00\u6761\u539F\u59CB\u9519\u8BEF\uFF0C\u7136\u540E\u91CD\u65B0\u8FD0\u884C pnpm test\u3002",
+    unhandled: "\u5F02\u6B65\u9519\u8BEF\uFF1A\u5148\u4FEE\u590D\u4E0A\u65B9\u663E\u793A\u7684\u7B2C\u4E00\u6761\u9519\u8BEF\uFF1B\u8F93\u5165\u3001\u5E27\u63A8\u8FDB\u548C\u751F\u547D\u5468\u671F\u64CD\u4F5C\u90FD\u8981\u5728\u6B63\u786E\u7684 host \u751F\u547D\u5468\u671F\u5185\u5E76\u4F7F\u7528 await\u3002"
   };
   const getCategory = (issue) => {
     if (issue.includes("\u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165")) return { category: "input", key: "input" };
@@ -408,6 +413,14 @@ function formatGameplayIssues(issues) {
       return { category: "registry", key: `registry:${scene}` };
     }
     if (issue.includes("\u7F3A\u5C11 gameplay contract")) return { category: "missing", key: "missing" };
+    if (issue.includes("\u6D4B\u8BD5\u5931\u8D25\uFF1A")) {
+      const message = issue.split("\u6D4B\u8BD5\u5931\u8D25\uFF1A")[1] ?? issue;
+      return { category: "test", key: `test:${message}` };
+    }
+    if (issue.includes("\u6D4B\u8BD5\u8FD0\u884C\u671F\u95F4\u53D1\u751F\u5F02\u6B65\u9519\u8BEF\uFF1A")) {
+      const message = issue.split("\u6D4B\u8BD5\u8FD0\u884C\u671F\u95F4\u53D1\u751F\u5F02\u6B65\u9519\u8BEF\uFF1A")[1] ?? issue;
+      return { category: "unhandled", key: `test:${message}` };
+    }
     if (issue.includes("\u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A")) return { category: "test", key: "test" };
     return { category: "other", key: `other:${issue}` };
   };
@@ -431,7 +444,7 @@ function formatGameplayIssues(issues) {
       continue;
     }
     const readable = compact.replaceAll(/(?:gameplay )?contract "([^"]+)"/g, '\u73A9\u6CD5\u6D4B\u8BD5 "$1"').replaceAll("evidence requirements", "\u8981\u6C42\u9A8C\u8BC1\u7684\u6E38\u620F\u884C\u4E3A").replaceAll("metadata", "\u6D4B\u8BD5\u914D\u7F6E").replaceAll("host registry", "\u6D4B\u8BD5\u8BB0\u5F55\u7684 Scene \u5217\u8868");
-    const id = compact.match(/contract "([^"]+)"/)?.[1];
+    const id = compact.match(/(?:contract|玩法测试) "([^"]+)"/)?.[1];
     const { category, key } = getCategory(compact);
     const group = groups.get(key);
     if (group) {
@@ -817,4 +830,15 @@ describe("gameplay audit", () => {
     expect(result.repairs).toHaveLength(1);
     expect(result.repairs[0]).toContain("vitest.config.ts");
   });
+  it("\u4FDD\u7559\u5E76\u5408\u5E76 Vitest \u8FD0\u884C\u65F6\u5F02\u5E38\u6D88\u606F", () => {
+    const result = formatGameplayIssues([
+      '\u73A9\u6CD5\u6D4B\u8BD5 "Map.transition" \u6D4B\u8BD5\u5931\u8D25\uFF1APhaser HEADLESS mouse input target cannot dispatch DOM events',
+      '\u73A9\u6CD5\u6D4B\u8BD5 "Editor.transition" \u6D4B\u8BD5\u5931\u8D25\uFF1APhaser HEADLESS mouse input target cannot dispatch DOM events',
+      "\u6D4B\u8BD5\u8FD0\u884C\u671F\u95F4\u53D1\u751F\u5F02\u6B65\u9519\u8BEF\uFF1APhaser HEADLESS mouse input target cannot dispatch DOM events"
+    ]);
+    expect(result.issues).toEqual([
+      '\u73A9\u6CD5\u6D4B\u8BD5 "Map.transition" \u6D4B\u8BD5\u5931\u8D25\uFF1APhaser HEADLESS mouse input target cannot dispatch DOM events\uFF08\u540C\u7C7B\u95EE\u9898\u8FD8\u51FA\u73B0\u5728\uFF1AEditor.transition\uFF09'
+    ]);
+    expect(result.repairs[0]).toContain("\u7B2C\u4E00\u6761\u539F\u59CB\u9519\u8BEF");
+  });
 });

package/dist/lint/gameplay-contract.contract.mjs

@@ -983,7 +983,8 @@ async function createHeadlessGame(scene, options = {}) {
       stepFrames(count);
       await settleRuntime();
     },
-    stepUntil(condition, maxFrames = 120) {
+    stepUntil(condition, maxFramesOrOptions = 120) {
+      const maxFrames = typeof maxFramesOrOptions === "number" ? maxFramesOrOptions : maxFramesOrOptions.maxFrames ?? 120;
       assertStepCount(maxFrames, "stepUntil maxFrames");
       throwRuntimeError();
       for (let frame = 0; frame <= maxFrames; frame += 1) {
@@ -1155,6 +1156,14 @@ function registerGameplayContract(context, options) {
       }
       host = currentHost;
     },
+    checkpoint(id) {
+      if (!host) {
+        throw new Error(
+          `Gameplay contract "${options.id}" must attach a HEADLESS host before recording a checkpoint.`
+        );
+      }
+      host.checkpoint(id);
+    },
     verify
   };
 }
@@ -1190,7 +1199,8 @@ describe("gameplay contract lifecycle integration", () => {
       id: "InputScene.hit",
       kind: "playthrough",
       requireInput: true,
-      requireFrameAdvance: true
+      requireFrameAdvance: true,
+      requireCheckpoint: "hit-recorded"
     });
     let host;
     try {
@@ -1199,12 +1209,14 @@ describe("gameplay contract lifecycle integration", () => {
       host.stepFrames();
       await host.input.mouse.click(40, 40);
       expect(host.scene.hits).toBe(1);
+      contract.checkpoint("hit-recorded");
       host.destroy();
       await callbacks[0]?.();
       expect(context.task.meta.gameplayContract).toMatchObject({
         id: "InputScene.hit",
         evidence: {
           clicks: 1,
+          checkpoints: ["hit-recorded"],
           frames: 1,
           mouseEvents: 3
         }

package/dist/lint/phaser-headless.contract.mjs

@@ -983,7 +983,8 @@ async function createHeadlessGame(scene, options = {}) {
       stepFrames(count);
       await settleRuntime();
     },
-    stepUntil(condition, maxFrames = 120) {
+    stepUntil(condition, maxFramesOrOptions = 120) {
+      const maxFrames = typeof maxFramesOrOptions === "number" ? maxFramesOrOptions : maxFramesOrOptions.maxFrames ?? 120;
       assertStepCount(maxFrames, "stepUntil maxFrames");
       throwRuntimeError();
       for (let frame = 0; frame <= maxFrames; frame += 1) {
@@ -1149,6 +1150,9 @@ describe("Phaser HEADLESS host", () => {
     expect(() => boundedHost.stepUntil(() => false, 1.5)).toThrow(
       "stepUntil maxFrames must be a non-negative safe integer"
     );
+    expect(() => boundedHost.stepUntil(() => false, { maxFrames: 0 })).toThrow(
+      "Condition was not met within 0 complete Phaser frames"
+    );
     expect(() => boundedHost.stepPhysics(-1)).toThrow(
       "stepPhysics steps must be a non-negative safe integer"
     );

package/dist/lint/vitest-config.contract.mjs

@@ -313,7 +313,11 @@ function auditGameplayRun(options, tests) {
     }
     issues.push(...getDefinitionIssues(expected, metadata));
     if (test.state !== "passed") {
-      issues.push(`contract "${expected.id}" \u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A ${test.state}\u3002`);
+      if (test.error) {
+        issues.push(`\u73A9\u6CD5\u6D4B\u8BD5 "${expected.id}" \u6D4B\u8BD5\u5931\u8D25\uFF1A${test.error}`);
+      } else {
+        issues.push(`\u73A9\u6CD5\u6D4B\u8BD5 "${expected.id}" \u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A ${test.state}\u3002`);
+      }
       continue;
     }
     if (!metadata.verified || !metadata.evidence) {
@@ -370,11 +374,13 @@ function isGameplayContractMetadata(value) {
 }
 function toAuditTest(test) {
   const metadata = test.meta().gameplayContract;
+  const firstError = test.result().errors?.[0];
   return {
     file: normalizePath(test.module.relativeModuleId),
     name: test.fullName,
     state: test.result().state,
-    metadata: isGameplayContractMetadata(metadata) ? metadata : void 0
+    metadata: isGameplayContractMetadata(metadata) ? metadata : void 0,
+    error: firstError?.message?.replaceAll(/\s+/g, " ").trim().slice(0, 360) || void 0
   };
 }
 function formatGameplayIssues(issues) {
@@ -405,7 +411,8 @@ function formatGameplayIssues(issues) {
     destroy: "\u6E05\u7406\uFF1A\u5728 afterEach \u4E2D\u8C03\u7528 host.destroy()\uFF0C\u5E76\u4FDD\u6301\u9500\u6BC1\u5E42\u7B49\u3002",
     registry: "Scene \u6CE8\u518C\uFF1A\u786E\u8BA4\u6E38\u620F\u6E90\u7801\u6CE8\u518C\u4E86\u8BE5 Scene\uFF1B\u6D4B\u8BD5\u9700\u8981\u5207\u6362\u5230\u5B83\u65F6\uFF0C\u5728\u521B\u5EFA host \u65F6\u901A\u8FC7 additionalScenes \u63D0\u4F9B Scene \u7C7B\u3002",
     missing: "\u6253\u5F00\u4E0A\u8FF0\u6587\u4EF6\uFF0C\u7528 gameplayTest \u6DFB\u52A0\u8FD9\u4E9B\u73A9\u6CD5\u6D4B\u8BD5\uFF1Bid \u5FC5\u987B\u4E0E vitest.config.ts \u4E2D\u7684\u914D\u7F6E\u5B8C\u5168\u4E00\u81F4\uFF0C\u521B\u5EFA host \u540E\u8C03\u7528 contract.attachHost(host)\u3002",
-    test: "\u5148\u4FEE\u590D\u5BF9\u5E94\u6D4B\u8BD5\u4E0A\u65B9\u663E\u793A\u7684\u7B2C\u4E00\u6761\u539F\u59CB\u9519\u8BEF\uFF0C\u7136\u540E\u91CD\u65B0\u8FD0\u884C pnpm test\u3002"
+    test: "\u5148\u4FEE\u590D\u5BF9\u5E94\u6D4B\u8BD5\u4E0A\u65B9\u663E\u793A\u7684\u7B2C\u4E00\u6761\u539F\u59CB\u9519\u8BEF\uFF0C\u7136\u540E\u91CD\u65B0\u8FD0\u884C pnpm test\u3002",
+    unhandled: "\u5F02\u6B65\u9519\u8BEF\uFF1A\u5148\u4FEE\u590D\u4E0A\u65B9\u663E\u793A\u7684\u7B2C\u4E00\u6761\u9519\u8BEF\uFF1B\u8F93\u5165\u3001\u5E27\u63A8\u8FDB\u548C\u751F\u547D\u5468\u671F\u64CD\u4F5C\u90FD\u8981\u5728\u6B63\u786E\u7684 host \u751F\u547D\u5468\u671F\u5185\u5E76\u4F7F\u7528 await\u3002"
   };
   const getCategory = (issue) => {
     if (issue.includes("\u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165")) return { category: "input", key: "input" };
@@ -430,6 +437,14 @@ function formatGameplayIssues(issues) {
       return { category: "registry", key: `registry:${scene}` };
     }
     if (issue.includes("\u7F3A\u5C11 gameplay contract")) return { category: "missing", key: "missing" };
+    if (issue.includes("\u6D4B\u8BD5\u5931\u8D25\uFF1A")) {
+      const message = issue.split("\u6D4B\u8BD5\u5931\u8D25\uFF1A")[1] ?? issue;
+      return { category: "test", key: `test:${message}` };
+    }
+    if (issue.includes("\u6D4B\u8BD5\u8FD0\u884C\u671F\u95F4\u53D1\u751F\u5F02\u6B65\u9519\u8BEF\uFF1A")) {
+      const message = issue.split("\u6D4B\u8BD5\u8FD0\u884C\u671F\u95F4\u53D1\u751F\u5F02\u6B65\u9519\u8BEF\uFF1A")[1] ?? issue;
+      return { category: "unhandled", key: `test:${message}` };
+    }
     if (issue.includes("\u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A")) return { category: "test", key: "test" };
     return { category: "other", key: `other:${issue}` };
   };
@@ -453,7 +468,7 @@ function formatGameplayIssues(issues) {
       continue;
     }
     const readable = compact.replaceAll(/(?:gameplay )?contract "([^"]+)"/g, '\u73A9\u6CD5\u6D4B\u8BD5 "$1"').replaceAll("evidence requirements", "\u8981\u6C42\u9A8C\u8BC1\u7684\u6E38\u620F\u884C\u4E3A").replaceAll("metadata", "\u6D4B\u8BD5\u914D\u7F6E").replaceAll("host registry", "\u6D4B\u8BD5\u8BB0\u5F55\u7684 Scene \u5217\u8868");
-    const id = compact.match(/contract "([^"]+)"/)?.[1];
+    const id = compact.match(/(?:contract|玩法测试) "([^"]+)"/)?.[1];
     const { category, key } = getCategory(compact);
     const group = groups.get(key);
     if (group) {
@@ -530,7 +545,7 @@ var GameplayAuditReporter = class {
     for (const issue of result.issues) this.reportPreflightIssue(issue);
   }
   /** 在测试运行结束后汇总全部 contract、Ledger 和 Scene registry，并决定命令退出码。 */
-  onTestRunEnd(testModules, _unhandledErrors = [], reason = "passed") {
+  onTestRunEnd(testModules, unhandledErrors = [], reason = "passed") {
     const collectionFailed = reason === "failed" && testModules.some(
       (testModule) => testModule.state() === "failed" && [...testModule.children.allTests()].length === 0
     );
@@ -545,9 +560,11 @@ var GameplayAuditReporter = class {
       (testModule) => [...testModule.children.allTests()].map(toAuditTest)
     );
     const result = auditGameplayRun(this.options, tests);
+    const runtimeIssues = unhandledErrors.map((error) => error.message?.replaceAll(/\s+/g, " ").trim()).filter(Boolean).map((message) => `\u6D4B\u8BD5\u8FD0\u884C\u671F\u95F4\u53D1\u751F\u5F02\u6B65\u9519\u8BEF\uFF1A${message}`);
     const combinedIssues = [
       ...this.preflightIssues,
-      ...result.issues
+      ...result.issues,
+      ...runtimeIssues
     ];
     if (combinedIssues.length > 0) {
       printIssues("FINAL", [...new Set(combinedIssues)]);

package/dist/vitest-config.d.mts

@@ -1,5 +1,5 @@
 import { ViteUserConfig } from 'vitest/config';
-import { c as GameplayAuditOptions } from './gameplay-audit-XBGq_jIV.mjs';
+import { c as GameplayAuditOptions } from './gameplay-audit-CusQfLYQ.mjs';
 import 'phaser';
 
 interface GameVitestConfigOptions {

package/dist/vitest-config.d.ts

@@ -1,5 +1,5 @@
 import { ViteUserConfig } from 'vitest/config';
-import { c as GameplayAuditOptions } from './gameplay-audit-XBGq_jIV.js';
+import { c as GameplayAuditOptions } from './gameplay-audit-CusQfLYQ.js';
 import 'phaser';
 
 interface GameVitestConfigOptions {

package/dist/vitest-config.js

@@ -333,7 +333,11 @@ function auditGameplayRun(options, tests) {
     }
     issues.push(...getDefinitionIssues(expected, metadata));
     if (test.state !== "passed") {
-      issues.push(`contract "${expected.id}" \u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A ${test.state}\u3002`);
+      if (test.error) {
+        issues.push(`\u73A9\u6CD5\u6D4B\u8BD5 "${expected.id}" \u6D4B\u8BD5\u5931\u8D25\uFF1A${test.error}`);
+      } else {
+        issues.push(`\u73A9\u6CD5\u6D4B\u8BD5 "${expected.id}" \u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A ${test.state}\u3002`);
+      }
       continue;
     }
     if (!metadata.verified || !metadata.evidence) {
@@ -390,11 +394,13 @@ function isGameplayContractMetadata(value) {
 }
 function toAuditTest(test) {
   const metadata = test.meta().gameplayContract;
+  const firstError = test.result().errors?.[0];
   return {
     file: normalizePath(test.module.relativeModuleId),
     name: test.fullName,
     state: test.result().state,
-    metadata: isGameplayContractMetadata(metadata) ? metadata : void 0
+    metadata: isGameplayContractMetadata(metadata) ? metadata : void 0,
+    error: firstError?.message?.replaceAll(/\s+/g, " ").trim().slice(0, 360) || void 0
   };
 }
 function formatGameplayIssues(issues) {
@@ -425,7 +431,8 @@ function formatGameplayIssues(issues) {
     destroy: "\u6E05\u7406\uFF1A\u5728 afterEach \u4E2D\u8C03\u7528 host.destroy()\uFF0C\u5E76\u4FDD\u6301\u9500\u6BC1\u5E42\u7B49\u3002",
     registry: "Scene \u6CE8\u518C\uFF1A\u786E\u8BA4\u6E38\u620F\u6E90\u7801\u6CE8\u518C\u4E86\u8BE5 Scene\uFF1B\u6D4B\u8BD5\u9700\u8981\u5207\u6362\u5230\u5B83\u65F6\uFF0C\u5728\u521B\u5EFA host \u65F6\u901A\u8FC7 additionalScenes \u63D0\u4F9B Scene \u7C7B\u3002",
     missing: "\u6253\u5F00\u4E0A\u8FF0\u6587\u4EF6\uFF0C\u7528 gameplayTest \u6DFB\u52A0\u8FD9\u4E9B\u73A9\u6CD5\u6D4B\u8BD5\uFF1Bid \u5FC5\u987B\u4E0E vitest.config.ts \u4E2D\u7684\u914D\u7F6E\u5B8C\u5168\u4E00\u81F4\uFF0C\u521B\u5EFA host \u540E\u8C03\u7528 contract.attachHost(host)\u3002",
-    test: "\u5148\u4FEE\u590D\u5BF9\u5E94\u6D4B\u8BD5\u4E0A\u65B9\u663E\u793A\u7684\u7B2C\u4E00\u6761\u539F\u59CB\u9519\u8BEF\uFF0C\u7136\u540E\u91CD\u65B0\u8FD0\u884C pnpm test\u3002"
+    test: "\u5148\u4FEE\u590D\u5BF9\u5E94\u6D4B\u8BD5\u4E0A\u65B9\u663E\u793A\u7684\u7B2C\u4E00\u6761\u539F\u59CB\u9519\u8BEF\uFF0C\u7136\u540E\u91CD\u65B0\u8FD0\u884C pnpm test\u3002",
+    unhandled: "\u5F02\u6B65\u9519\u8BEF\uFF1A\u5148\u4FEE\u590D\u4E0A\u65B9\u663E\u793A\u7684\u7B2C\u4E00\u6761\u9519\u8BEF\uFF1B\u8F93\u5165\u3001\u5E27\u63A8\u8FDB\u548C\u751F\u547D\u5468\u671F\u64CD\u4F5C\u90FD\u8981\u5728\u6B63\u786E\u7684 host \u751F\u547D\u5468\u671F\u5185\u5E76\u4F7F\u7528 await\u3002"
   };
   const getCategory = (issue) => {
     if (issue.includes("\u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165")) return { category: "input", key: "input" };
@@ -450,6 +457,14 @@ function formatGameplayIssues(issues) {
       return { category: "registry", key: `registry:${scene}` };
     }
     if (issue.includes("\u7F3A\u5C11 gameplay contract")) return { category: "missing", key: "missing" };
+    if (issue.includes("\u6D4B\u8BD5\u5931\u8D25\uFF1A")) {
+      const message = issue.split("\u6D4B\u8BD5\u5931\u8D25\uFF1A")[1] ?? issue;
+      return { category: "test", key: `test:${message}` };
+    }
+    if (issue.includes("\u6D4B\u8BD5\u8FD0\u884C\u671F\u95F4\u53D1\u751F\u5F02\u6B65\u9519\u8BEF\uFF1A")) {
+      const message = issue.split("\u6D4B\u8BD5\u8FD0\u884C\u671F\u95F4\u53D1\u751F\u5F02\u6B65\u9519\u8BEF\uFF1A")[1] ?? issue;
+      return { category: "unhandled", key: `test:${message}` };
+    }
     if (issue.includes("\u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A")) return { category: "test", key: "test" };
     return { category: "other", key: `other:${issue}` };
   };
@@ -473,7 +488,7 @@ function formatGameplayIssues(issues) {
       continue;
     }
     const readable = compact.replaceAll(/(?:gameplay )?contract "([^"]+)"/g, '\u73A9\u6CD5\u6D4B\u8BD5 "$1"').replaceAll("evidence requirements", "\u8981\u6C42\u9A8C\u8BC1\u7684\u6E38\u620F\u884C\u4E3A").replaceAll("metadata", "\u6D4B\u8BD5\u914D\u7F6E").replaceAll("host registry", "\u6D4B\u8BD5\u8BB0\u5F55\u7684 Scene \u5217\u8868");
-    const id = compact.match(/contract "([^"]+)"/)?.[1];
+    const id = compact.match(/(?:contract|玩法测试) "([^"]+)"/)?.[1];
     const { category, key } = getCategory(compact);
     const group = groups.get(key);
     if (group) {
@@ -550,7 +565,7 @@ var GameplayAuditReporter = class {
     for (const issue of result.issues) this.reportPreflightIssue(issue);
   }
   /** 在测试运行结束后汇总全部 contract、Ledger 和 Scene registry，并决定命令退出码。 */
-  onTestRunEnd(testModules, _unhandledErrors = [], reason = "passed") {
+  onTestRunEnd(testModules, unhandledErrors = [], reason = "passed") {
     const collectionFailed = reason === "failed" && testModules.some(
       (testModule) => testModule.state() === "failed" && [...testModule.children.allTests()].length === 0
     );
@@ -565,9 +580,11 @@ var GameplayAuditReporter = class {
       (testModule) => [...testModule.children.allTests()].map(toAuditTest)
     );
     const result = auditGameplayRun(this.options, tests);
+    const runtimeIssues = unhandledErrors.map((error) => error.message?.replaceAll(/\s+/g, " ").trim()).filter(Boolean).map((message) => `\u6D4B\u8BD5\u8FD0\u884C\u671F\u95F4\u53D1\u751F\u5F02\u6B65\u9519\u8BEF\uFF1A${message}`);
     const combinedIssues = [
       ...this.preflightIssues,
-      ...result.issues
+      ...result.issues,
+      ...runtimeIssues
     ];
     if (combinedIssues.length > 0) {
       printIssues("FINAL", [...new Set(combinedIssues)]);

package/dist/vitest-config.mjs

@@ -309,7 +309,11 @@ function auditGameplayRun(options, tests) {
     }
     issues.push(...getDefinitionIssues(expected, metadata));
     if (test.state !== "passed") {
-      issues.push(`contract "${expected.id}" \u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A ${test.state}\u3002`);
+      if (test.error) {
+        issues.push(`\u73A9\u6CD5\u6D4B\u8BD5 "${expected.id}" \u6D4B\u8BD5\u5931\u8D25\uFF1A${test.error}`);
+      } else {
+        issues.push(`\u73A9\u6CD5\u6D4B\u8BD5 "${expected.id}" \u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A ${test.state}\u3002`);
+      }
       continue;
     }
     if (!metadata.verified || !metadata.evidence) {
@@ -366,11 +370,13 @@ function isGameplayContractMetadata(value) {
 }
 function toAuditTest(test) {
   const metadata = test.meta().gameplayContract;
+  const firstError = test.result().errors?.[0];
   return {
     file: normalizePath(test.module.relativeModuleId),
     name: test.fullName,
     state: test.result().state,
-    metadata: isGameplayContractMetadata(metadata) ? metadata : void 0
+    metadata: isGameplayContractMetadata(metadata) ? metadata : void 0,
+    error: firstError?.message?.replaceAll(/\s+/g, " ").trim().slice(0, 360) || void 0
   };
 }
 function formatGameplayIssues(issues) {
@@ -401,7 +407,8 @@ function formatGameplayIssues(issues) {
     destroy: "\u6E05\u7406\uFF1A\u5728 afterEach \u4E2D\u8C03\u7528 host.destroy()\uFF0C\u5E76\u4FDD\u6301\u9500\u6BC1\u5E42\u7B49\u3002",
     registry: "Scene \u6CE8\u518C\uFF1A\u786E\u8BA4\u6E38\u620F\u6E90\u7801\u6CE8\u518C\u4E86\u8BE5 Scene\uFF1B\u6D4B\u8BD5\u9700\u8981\u5207\u6362\u5230\u5B83\u65F6\uFF0C\u5728\u521B\u5EFA host \u65F6\u901A\u8FC7 additionalScenes \u63D0\u4F9B Scene \u7C7B\u3002",
     missing: "\u6253\u5F00\u4E0A\u8FF0\u6587\u4EF6\uFF0C\u7528 gameplayTest \u6DFB\u52A0\u8FD9\u4E9B\u73A9\u6CD5\u6D4B\u8BD5\uFF1Bid \u5FC5\u987B\u4E0E vitest.config.ts \u4E2D\u7684\u914D\u7F6E\u5B8C\u5168\u4E00\u81F4\uFF0C\u521B\u5EFA host \u540E\u8C03\u7528 contract.attachHost(host)\u3002",
-    test: "\u5148\u4FEE\u590D\u5BF9\u5E94\u6D4B\u8BD5\u4E0A\u65B9\u663E\u793A\u7684\u7B2C\u4E00\u6761\u539F\u59CB\u9519\u8BEF\uFF0C\u7136\u540E\u91CD\u65B0\u8FD0\u884C pnpm test\u3002"
+    test: "\u5148\u4FEE\u590D\u5BF9\u5E94\u6D4B\u8BD5\u4E0A\u65B9\u663E\u793A\u7684\u7B2C\u4E00\u6761\u539F\u59CB\u9519\u8BEF\uFF0C\u7136\u540E\u91CD\u65B0\u8FD0\u884C pnpm test\u3002",
+    unhandled: "\u5F02\u6B65\u9519\u8BEF\uFF1A\u5148\u4FEE\u590D\u4E0A\u65B9\u663E\u793A\u7684\u7B2C\u4E00\u6761\u9519\u8BEF\uFF1B\u8F93\u5165\u3001\u5E27\u63A8\u8FDB\u548C\u751F\u547D\u5468\u671F\u64CD\u4F5C\u90FD\u8981\u5728\u6B63\u786E\u7684 host \u751F\u547D\u5468\u671F\u5185\u5E76\u4F7F\u7528 await\u3002"
   };
   const getCategory = (issue) => {
     if (issue.includes("\u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165")) return { category: "input", key: "input" };
@@ -426,6 +433,14 @@ function formatGameplayIssues(issues) {
       return { category: "registry", key: `registry:${scene}` };
     }
     if (issue.includes("\u7F3A\u5C11 gameplay contract")) return { category: "missing", key: "missing" };
+    if (issue.includes("\u6D4B\u8BD5\u5931\u8D25\uFF1A")) {
+      const message = issue.split("\u6D4B\u8BD5\u5931\u8D25\uFF1A")[1] ?? issue;
+      return { category: "test", key: `test:${message}` };
+    }
+    if (issue.includes("\u6D4B\u8BD5\u8FD0\u884C\u671F\u95F4\u53D1\u751F\u5F02\u6B65\u9519\u8BEF\uFF1A")) {
+      const message = issue.split("\u6D4B\u8BD5\u8FD0\u884C\u671F\u95F4\u53D1\u751F\u5F02\u6B65\u9519\u8BEF\uFF1A")[1] ?? issue;
+      return { category: "unhandled", key: `test:${message}` };
+    }
     if (issue.includes("\u7684\u6D4B\u8BD5\u72B6\u6001\u4E3A")) return { category: "test", key: "test" };
     return { category: "other", key: `other:${issue}` };
   };
@@ -449,7 +464,7 @@ function formatGameplayIssues(issues) {
       continue;
     }
     const readable = compact.replaceAll(/(?:gameplay )?contract "([^"]+)"/g, '\u73A9\u6CD5\u6D4B\u8BD5 "$1"').replaceAll("evidence requirements", "\u8981\u6C42\u9A8C\u8BC1\u7684\u6E38\u620F\u884C\u4E3A").replaceAll("metadata", "\u6D4B\u8BD5\u914D\u7F6E").replaceAll("host registry", "\u6D4B\u8BD5\u8BB0\u5F55\u7684 Scene \u5217\u8868");
-    const id = compact.match(/contract "([^"]+)"/)?.[1];
+    const id = compact.match(/(?:contract|玩法测试) "([^"]+)"/)?.[1];
     const { category, key } = getCategory(compact);
     const group = groups.get(key);
     if (group) {
@@ -526,7 +541,7 @@ var GameplayAuditReporter = class {
     for (const issue of result.issues) this.reportPreflightIssue(issue);
   }
   /** 在测试运行结束后汇总全部 contract、Ledger 和 Scene registry，并决定命令退出码。 */
-  onTestRunEnd(testModules, _unhandledErrors = [], reason = "passed") {
+  onTestRunEnd(testModules, unhandledErrors = [], reason = "passed") {
     const collectionFailed = reason === "failed" && testModules.some(
       (testModule) => testModule.state() === "failed" && [...testModule.children.allTests()].length === 0
     );
@@ -541,9 +556,11 @@ var GameplayAuditReporter = class {
       (testModule) => [...testModule.children.allTests()].map(toAuditTest)
     );
     const result = auditGameplayRun(this.options, tests);
+    const runtimeIssues = unhandledErrors.map((error) => error.message?.replaceAll(/\s+/g, " ").trim()).filter(Boolean).map((message) => `\u6D4B\u8BD5\u8FD0\u884C\u671F\u95F4\u53D1\u751F\u5F02\u6B65\u9519\u8BEF\uFF1A${message}`);
     const combinedIssues = [
       ...this.preflightIssues,
-      ...result.issues
+      ...result.issues,
+      ...runtimeIssues
     ];
     if (combinedIssues.length > 0) {
       printIssues("FINAL", [...new Set(combinedIssues)]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miaoda-game-devkit",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Shared lint and deterministic Phaser HEADLESS testing tools for Miaoda games",
   "license": "MIT",
   "main": "./dist/index.js",