miaoda-game-devkit 0.2.21 → 0.3.0

package/README.md

@@ -154,8 +154,8 @@ DOM 到 Phaser 的输入、命中测试和游戏状态变化，不验证 Canvas/
 给出直接修复步骤；测试文件无法加载或配置要求的测试尚未建立时，不再继续报告 Scene
 注册等派生问题。先处理第一类错误，再重新运行 `pnpm test`。
 
-共享 Vitest 配置使用 `minimal` reporter 和 `text-summary` coverage reporter，保留失败
-定位、Scene 覆盖摘要和最终机器标识，同时避免输出完整测试列表和逐文件噪声。
+Phaser Vitest 配置使用 `minimal` reporter；React Vitest 配置使用无 ANSI 的精简 reporter。
+两者都保留失败定位、coverage 摘要和最终机器标识，同时避免输出完整 DOM 快照、测试列表和逐文件噪声。
 
 ## 发布顺序
 

package/dist/react/index.d.mts

@@ -10,4 +10,22 @@ interface DisposableGameController {
  */
 declare function useOwnedGameController<TController extends DisposableGameController>(createController: () => TController): TController;
 
-export { type DisposableGameController, useOwnedGameController };
+/** 同时提供订阅与权威快照读取的游戏 Controller，是最小可渲染运行时。 */
+interface SubscribableGameController<TState> extends DisposableGameController {
+    subscribe(listener: () => void): () => void;
+    snapshot(): TState;
+}
+/**
+ * 一次调用接管游戏 Controller 的创建、销毁与状态订阅：
+ * useOwnedGameController 的 ownership，加上 useSyncExternalStore 的渲染桥。
+ *
+ * 附带一道开发期检查：状态内容变了、但 snapshot() 返回的还是原来那个
+ * 对象时，React 会认为"什么都没变"而不刷新界面——游戏悄悄卡死，没有
+ * 任何报错。检测到这种情况就立刻抛错，并直接告诉你怎么修。
+ */
+declare function useGameController<TController extends SubscribableGameController<unknown>>(createController: () => TController): {
+    game: TController;
+    state: ReturnType<TController["snapshot"]>;
+};
+
+export { type DisposableGameController, type SubscribableGameController, useGameController, useOwnedGameController };

package/dist/react/index.d.ts

@@ -10,4 +10,22 @@ interface DisposableGameController {
  */
 declare function useOwnedGameController<TController extends DisposableGameController>(createController: () => TController): TController;
 
-export { type DisposableGameController, useOwnedGameController };
+/** 同时提供订阅与权威快照读取的游戏 Controller，是最小可渲染运行时。 */
+interface SubscribableGameController<TState> extends DisposableGameController {
+    subscribe(listener: () => void): () => void;
+    snapshot(): TState;
+}
+/**
+ * 一次调用接管游戏 Controller 的创建、销毁与状态订阅：
+ * useOwnedGameController 的 ownership，加上 useSyncExternalStore 的渲染桥。
+ *
+ * 附带一道开发期检查：状态内容变了、但 snapshot() 返回的还是原来那个
+ * 对象时，React 会认为"什么都没变"而不刷新界面——游戏悄悄卡死，没有
+ * 任何报错。检测到这种情况就立刻抛错，并直接告诉你怎么修。
+ */
+declare function useGameController<TController extends SubscribableGameController<unknown>>(createController: () => TController): {
+    game: TController;
+    state: ReturnType<TController["snapshot"]>;
+};
+
+export { type DisposableGameController, type SubscribableGameController, useGameController, useOwnedGameController };

package/dist/react/index.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var react_exports = {};
 __export(react_exports, {
   browserGameClock: () => browserGameClock,
+  useGameController: () => useGameController,
   useOwnedGameController: () => useOwnedGameController
 });
 module.exports = __toCommonJS(react_exports);
@@ -50,8 +51,57 @@ function useOwnedGameController(createController) {
   }, [controller]);
   return controller;
 }
+
+// src/react/use-game-controller.ts
+var import_react2 = require("react");
+function useGameController(createController) {
+  const game = useOwnedGameController(createController);
+  useSnapshotIntegrityCheck(game);
+  const state = (0, import_react2.useSyncExternalStore)(
+    game.subscribe,
+    game.snapshot,
+    game.snapshot
+  );
+  return { game, state };
+}
+function useSnapshotIntegrityCheck(game) {
+  const reported = (0, import_react2.useRef)(false);
+  (0, import_react2.useEffect)(() => {
+    if (process.env.NODE_ENV === "production") return void 0;
+    let previous = game.snapshot();
+    let previousJson;
+    try {
+      previousJson = JSON.stringify(previous);
+    } catch {
+      previousJson = void 0;
+    }
+    return game.subscribe(() => {
+      if (reported.current) return;
+      const next = game.snapshot();
+      if (!Object.is(previous, next)) {
+        previous = next;
+        previousJson = void 0;
+        return;
+      }
+      let nextJson;
+      try {
+        nextJson = JSON.stringify(next);
+      } catch {
+        return;
+      }
+      if (previousJson !== void 0 && nextJson !== previousJson) {
+        reported.current = true;
+        throw new Error(
+          "Game state changed while snapshot() returned the same reference \u2014 React compares snapshots by reference and skips the re-render, so the UI freezes. \u539F\u56E0\uFF1AReact \u9760\u6BD4\u8F83\u5F15\u7528\u5224\u65AD\u72B6\u6001\u53D8\u6CA1\u53D8\uFF0C\u5F15\u7528\u76F8\u540C\u5C31\u5F53\u4F5C\u6CA1\u53D8\u5316\u3002\u4FEE\u590D\uFF1A\u6BCF\u6B21 notify \u524D\u6362\u4E00\u4E2A\u65B0\u5BF9\u8C61\uFF0C\u4F8B\u5982\u5728 controller \u91CC cachedSnapshot = { ...state }\uFF1B\u4E0D\u8981\u628A\u88AB\u539F\u5730\u4FEE\u6539\u7684\u5185\u90E8\u5BF9\u8C61\u76F4\u63A5\u7ED9 React\u3002"
+        );
+      }
+      previousJson = nextJson;
+    });
+  }, [game]);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   browserGameClock,
+  useGameController,
   useOwnedGameController
 });

package/dist/react/index.mjs

@@ -23,7 +23,56 @@ function useOwnedGameController(createController) {
   }, [controller]);
   return controller;
 }
+
+// src/react/use-game-controller.ts
+import { useEffect as useEffect2, useRef as useRef2, useSyncExternalStore } from "react";
+function useGameController(createController) {
+  const game = useOwnedGameController(createController);
+  useSnapshotIntegrityCheck(game);
+  const state = useSyncExternalStore(
+    game.subscribe,
+    game.snapshot,
+    game.snapshot
+  );
+  return { game, state };
+}
+function useSnapshotIntegrityCheck(game) {
+  const reported = useRef2(false);
+  useEffect2(() => {
+    if (process.env.NODE_ENV === "production") return void 0;
+    let previous = game.snapshot();
+    let previousJson;
+    try {
+      previousJson = JSON.stringify(previous);
+    } catch {
+      previousJson = void 0;
+    }
+    return game.subscribe(() => {
+      if (reported.current) return;
+      const next = game.snapshot();
+      if (!Object.is(previous, next)) {
+        previous = next;
+        previousJson = void 0;
+        return;
+      }
+      let nextJson;
+      try {
+        nextJson = JSON.stringify(next);
+      } catch {
+        return;
+      }
+      if (previousJson !== void 0 && nextJson !== previousJson) {
+        reported.current = true;
+        throw new Error(
+          "Game state changed while snapshot() returned the same reference \u2014 React compares snapshots by reference and skips the re-render, so the UI freezes. \u539F\u56E0\uFF1AReact \u9760\u6BD4\u8F83\u5F15\u7528\u5224\u65AD\u72B6\u6001\u53D8\u6CA1\u53D8\uFF0C\u5F15\u7528\u76F8\u540C\u5C31\u5F53\u4F5C\u6CA1\u53D8\u5316\u3002\u4FEE\u590D\uFF1A\u6BCF\u6B21 notify \u524D\u6362\u4E00\u4E2A\u65B0\u5BF9\u8C61\uFF0C\u4F8B\u5982\u5728 controller \u91CC cachedSnapshot = { ...state }\uFF1B\u4E0D\u8981\u628A\u88AB\u539F\u5730\u4FEE\u6539\u7684\u5185\u90E8\u5BF9\u8C61\u76F4\u63A5\u7ED9 React\u3002"
+        );
+      }
+      previousJson = nextJson;
+    });
+  }, [game]);
+}
 export {
   browserGameClock,
+  useGameController,
   useOwnedGameController
 };

package/dist/react/testing.d.mts

@@ -33,6 +33,16 @@ interface StepUntilOptions {
      * The value is sampled only when the bound is exhausted.
      */
     diagnostics?: () => unknown;
+    /**
+     * 默认有一道检查：如果等待的结果"不用玩就已经成立"（第 0 步即成立，
+     * 且页面文本从进入游戏起一个字都没变），说明这个结果跟游戏过程无关，
+     * 判为失败——它能抓住输入没接上、界面卡死、断言了静态标题这类假通过。
+     *
+     * 例外：Canvas 游戏的结果画在画布上，页面文本本来就不会变。这类游戏
+     * 观察的是 Telemetry 等页面外的权威状态，此时置 true 跳过该检查。
+     * 结果通过 DOM 呈现的游戏不要传。
+     */
+    allowStaticDom?: boolean;
 }
 
 /** 单条 React 主流程测试留下的可序列化运行期证据。 */

package/dist/react/testing.d.ts

@@ -33,6 +33,16 @@ interface StepUntilOptions {
      * The value is sampled only when the bound is exhausted.
      */
     diagnostics?: () => unknown;
+    /**
+     * 默认有一道检查：如果等待的结果"不用玩就已经成立"（第 0 步即成立，
+     * 且页面文本从进入游戏起一个字都没变），说明这个结果跟游戏过程无关，
+     * 判为失败——它能抓住输入没接上、界面卡死、断言了静态标题这类假通过。
+     *
+     * 例外：Canvas 游戏的结果画在画布上，页面文本本来就不会变。这类游戏
+     * 观察的是 Telemetry 等页面外的权威状态，此时置 true 跳过该检查。
+     * 结果通过 DOM 呈现的游戏不要传。
+     */
+    allowStaticDom?: boolean;
 }
 
 /** 单条 React 主流程测试留下的可序列化运行期证据。 */

package/dist/react/testing.js

@@ -192,6 +192,7 @@ function definePlaythrough(element, run, waiverReason) {
     const evidence = metadata.evidence;
     let assertionsAtOutcome;
     let enteredRecorded = false;
+    let domTextAtEntered;
     const recordInput = () => {
       evidence.domInputEvents += 1;
     };
@@ -244,6 +245,7 @@ function definePlaythrough(element, run, waiverReason) {
               );
             }
             enteredRecorded = true;
+            domTextAtEntered = document.body.textContent ?? "";
             evidence.checkpoints.push(kind);
             return;
           }
@@ -271,6 +273,11 @@ function definePlaythrough(element, run, waiverReason) {
               'stepUntil must follow performInput("primary", ...). A menu/help click is not gameplay evidence.'
             );
           }
+          if (steps === 0 && options.allowStaticDom !== true && domTextAtEntered !== void 0 && (document.body.textContent ?? "") === domTextAtEntered) {
+            throw new Error(
+              'stepUntil outcome was already true at step 0 and the DOM has not changed since checkpoint("entered"), so the flow cannot prove that gameplay changed anything. \u610F\u601D\uFF1A\u6E38\u620F\u4E00\u6B65\u90FD\u6CA1\u73A9\uFF0C\u7B49\u5F85\u7684"\u7ED3\u679C"\u5C31\u5DF2\u7ECF\u6210\u7ACB\uFF0C\u9875\u9762\u4E5F\u4E00\u4E2A\u5B57\u6CA1\u53D8\u2014\u2014\u8FD9\u4E2A\u7ED3\u679C\u8BC1\u660E\u4E0D\u4E86\u4EFB\u4F55\u4E8B\u3002\u5E38\u89C1\u539F\u56E0\uFF1A\u2460 \u8F93\u5165\u6CA1\u6709\u63A5\u5230\u6E38\u620F\u4E0A\uFF1B\u2461 \u754C\u9762\u5361\u6B7B\uFF08\u72B6\u6001\u6539\u4E86\u4F46 snapshot \u5F15\u7528\u6CA1\u6362\uFF0CReact \u6CA1\u6709\u5237\u65B0\uFF09\uFF1B\u2462 \u65AD\u8A00\u4E86\u5F00\u5C40\u524D\u5C31\u5B58\u5728\u7684\u9759\u6001\u6587\u672C\u3002\u4FEE\u590D\uFF1A\u7B49\u5F85\u5E76\u65AD\u8A00\u53EA\u6709\u73A9\u8D77\u6765\u4E4B\u540E\u624D\u4F1A\u51FA\u73B0\u7684\u4E1C\u897F\uFF08\u5F00\u59CB\u906E\u7F69\u6D88\u5931\u3001\u6BD4\u5206\u53D8\u5316\u3001\u7ED3\u7B97\u753B\u9762\u51FA\u73B0\uFF09\u3002\u4F8B\u5916\uFF1A\u7ED3\u679C\u753B\u5728 Canvas \u4E0A\u3001\u7ECF Telemetry \u7B49\u9875\u9762\u5916\u72B6\u6001\u89C2\u5BDF\u7684\u6E38\u620F\uFF0C\u663E\u5F0F\u4F20 { allowStaticDom: true }\u3002'
+            );
+          }
           evidence.boundedRuns += 1;
           assertionsAtOutcome = expect.getState().assertionCalls;
           return steps;

package/dist/react/testing.mjs

@@ -154,6 +154,7 @@ function definePlaythrough(element, run, waiverReason) {
     const evidence = metadata.evidence;
     let assertionsAtOutcome;
     let enteredRecorded = false;
+    let domTextAtEntered;
     const recordInput = () => {
       evidence.domInputEvents += 1;
     };
@@ -206,6 +207,7 @@ function definePlaythrough(element, run, waiverReason) {
               );
             }
             enteredRecorded = true;
+            domTextAtEntered = document.body.textContent ?? "";
             evidence.checkpoints.push(kind);
             return;
           }
@@ -233,6 +235,11 @@ function definePlaythrough(element, run, waiverReason) {
               'stepUntil must follow performInput("primary", ...). A menu/help click is not gameplay evidence.'
             );
           }
+          if (steps === 0 && options.allowStaticDom !== true && domTextAtEntered !== void 0 && (document.body.textContent ?? "") === domTextAtEntered) {
+            throw new Error(
+              'stepUntil outcome was already true at step 0 and the DOM has not changed since checkpoint("entered"), so the flow cannot prove that gameplay changed anything. \u610F\u601D\uFF1A\u6E38\u620F\u4E00\u6B65\u90FD\u6CA1\u73A9\uFF0C\u7B49\u5F85\u7684"\u7ED3\u679C"\u5C31\u5DF2\u7ECF\u6210\u7ACB\uFF0C\u9875\u9762\u4E5F\u4E00\u4E2A\u5B57\u6CA1\u53D8\u2014\u2014\u8FD9\u4E2A\u7ED3\u679C\u8BC1\u660E\u4E0D\u4E86\u4EFB\u4F55\u4E8B\u3002\u5E38\u89C1\u539F\u56E0\uFF1A\u2460 \u8F93\u5165\u6CA1\u6709\u63A5\u5230\u6E38\u620F\u4E0A\uFF1B\u2461 \u754C\u9762\u5361\u6B7B\uFF08\u72B6\u6001\u6539\u4E86\u4F46 snapshot \u5F15\u7528\u6CA1\u6362\uFF0CReact \u6CA1\u6709\u5237\u65B0\uFF09\uFF1B\u2462 \u65AD\u8A00\u4E86\u5F00\u5C40\u524D\u5C31\u5B58\u5728\u7684\u9759\u6001\u6587\u672C\u3002\u4FEE\u590D\uFF1A\u7B49\u5F85\u5E76\u65AD\u8A00\u53EA\u6709\u73A9\u8D77\u6765\u4E4B\u540E\u624D\u4F1A\u51FA\u73B0\u7684\u4E1C\u897F\uFF08\u5F00\u59CB\u906E\u7F69\u6D88\u5931\u3001\u6BD4\u5206\u53D8\u5316\u3001\u7ED3\u7B97\u753B\u9762\u51FA\u73B0\uFF09\u3002\u4F8B\u5916\uFF1A\u7ED3\u679C\u753B\u5728 Canvas \u4E0A\u3001\u7ECF Telemetry \u7B49\u9875\u9762\u5916\u72B6\u6001\u89C2\u5BDF\u7684\u6E38\u620F\uFF0C\u663E\u5F0F\u4F20 { allowStaticDom: true }\u3002'
+            );
+          }
           evidence.boundedRuns += 1;
           assertionsAtOutcome = expect.getState().assertionCalls;
           return steps;

package/dist/react/vitest-config.js

@@ -40,6 +40,7 @@ var import_config = require("vitest/config");
 // src/react/react-playthrough-reporter.ts
 var import_node_fs = require("fs");
 var import_node_path = require("path");
+var import_node_util = require("util");
 
 // src/react/react-playthrough.ts
 var import_react2 = require("@testing-library/react");
@@ -142,6 +143,7 @@ function definePlaythrough(element, run, waiverReason) {
     const evidence = metadata.evidence;
     let assertionsAtOutcome;
     let enteredRecorded = false;
+    let domTextAtEntered;
     const recordInput = () => {
       evidence.domInputEvents += 1;
     };
@@ -194,6 +196,7 @@ function definePlaythrough(element, run, waiverReason) {
               );
             }
             enteredRecorded = true;
+            domTextAtEntered = document.body.textContent ?? "";
             evidence.checkpoints.push(kind);
             return;
           }
@@ -221,6 +224,11 @@ function definePlaythrough(element, run, waiverReason) {
               'stepUntil must follow performInput("primary", ...). A menu/help click is not gameplay evidence.'
             );
           }
+          if (steps === 0 && options.allowStaticDom !== true && domTextAtEntered !== void 0 && (document.body.textContent ?? "") === domTextAtEntered) {
+            throw new Error(
+              'stepUntil outcome was already true at step 0 and the DOM has not changed since checkpoint("entered"), so the flow cannot prove that gameplay changed anything. \u610F\u601D\uFF1A\u6E38\u620F\u4E00\u6B65\u90FD\u6CA1\u73A9\uFF0C\u7B49\u5F85\u7684"\u7ED3\u679C"\u5C31\u5DF2\u7ECF\u6210\u7ACB\uFF0C\u9875\u9762\u4E5F\u4E00\u4E2A\u5B57\u6CA1\u53D8\u2014\u2014\u8FD9\u4E2A\u7ED3\u679C\u8BC1\u660E\u4E0D\u4E86\u4EFB\u4F55\u4E8B\u3002\u5E38\u89C1\u539F\u56E0\uFF1A\u2460 \u8F93\u5165\u6CA1\u6709\u63A5\u5230\u6E38\u620F\u4E0A\uFF1B\u2461 \u754C\u9762\u5361\u6B7B\uFF08\u72B6\u6001\u6539\u4E86\u4F46 snapshot \u5F15\u7528\u6CA1\u6362\uFF0CReact \u6CA1\u6709\u5237\u65B0\uFF09\uFF1B\u2462 \u65AD\u8A00\u4E86\u5F00\u5C40\u524D\u5C31\u5B58\u5728\u7684\u9759\u6001\u6587\u672C\u3002\u4FEE\u590D\uFF1A\u7B49\u5F85\u5E76\u65AD\u8A00\u53EA\u6709\u73A9\u8D77\u6765\u4E4B\u540E\u624D\u4F1A\u51FA\u73B0\u7684\u4E1C\u897F\uFF08\u5F00\u59CB\u906E\u7F69\u6D88\u5931\u3001\u6BD4\u5206\u53D8\u5316\u3001\u7ED3\u7B97\u753B\u9762\u51FA\u73B0\uFF09\u3002\u4F8B\u5916\uFF1A\u7ED3\u679C\u753B\u5728 Canvas \u4E0A\u3001\u7ECF Telemetry \u7B49\u9875\u9762\u5916\u72B6\u6001\u89C2\u5BDF\u7684\u6E38\u620F\uFF0C\u663E\u5F0F\u4F20 { allowStaticDom: true }\u3002'
+            );
+          }
           evidence.boundedRuns += 1;
           assertionsAtOutcome = expect.getState().assertionCalls;
           return steps;
@@ -323,7 +331,18 @@ function toAuditInput(test2) {
 }
 function firstLine(value) {
   if (typeof value !== "string") return void 0;
-  return value.split("\n").map((line) => line.trim()).find(Boolean);
+  return (0, import_node_util.stripVTControlCharacters)(value).split("\n").map((line) => line.trim()).find(Boolean);
+}
+function failureHint(value) {
+  const names = [...value.matchAll(/button\s*\n\s*Name "([^"]+)"/g)].map(
+    (match) => match[1]
+  );
+  if (names.length === 0) return void 0;
+  return `Available button names: ${names.map((name) => JSON.stringify(name)).join(", ")}`;
+}
+function errorLocation(value) {
+  const match = value.match(/(?:^|\n)\s*at\s+(.*?\.(?:test|spec)\.[^\n]+:\d+:\d+)/);
+  return match?.[1];
 }
 function toModuleResult(module2, projectRoot) {
   const tests = [...module2.children.allTests()];
@@ -333,13 +352,48 @@ function toModuleResult(module2, projectRoot) {
       (test2) => (test2.result().errors ?? []).map((error) => firstLine(error.message))
     )
   ].filter((message) => Boolean(message));
+  const failures = tests.filter((test2) => test2.result().state === "failed").map((test2) => {
+    const raw = test2.result().errors?.[0]?.message ?? module2.errors()[0]?.message ?? "Unknown failure";
+    return {
+      test: test2.fullName,
+      cause: firstLine(raw) ?? "Unknown failure",
+      location: test2.location ? `${(0, import_node_path.relative)(projectRoot, module2.moduleId).replaceAll("\\", "/")}:${test2.location.line}:${test2.location.column}` : errorLocation(raw),
+      hint: failureHint(raw)
+    };
+  });
+  if (failures.length === 0 && tests.length === 0 && module2.errors().length > 0) {
+    const raw = module2.errors()[0]?.message ?? "Module failed to load";
+    failures.push({
+      test: "<collection>",
+      cause: firstLine(raw) ?? "Module failed to load",
+      location: errorLocation(raw),
+      hint: failureHint(raw)
+    });
+  }
   return {
     file: (0, import_node_path.relative)(projectRoot, module2.moduleId).replaceAll("\\", "/"),
     state: module2.state(),
     errors,
-    tests: tests.map(toAuditInput)
+    tests: tests.map(toAuditInput),
+    failures
   };
 }
+function formatFailureSummary(modules) {
+  const failures = modules.flatMap(
+    (module2) => (module2.failures ?? []).map((failure) => ({ ...failure, file: module2.file }))
+  );
+  if (failures.length === 0) return ["TEST_RESULT: PASS"];
+  const lines = [`FAILED_TESTS: ${failures.length}`];
+  for (const [index, failure] of failures.entries()) {
+    lines.push(`FAILURE_${index + 1}: ${failure.file}`);
+    lines.push(`TEST: ${failure.test}`);
+    lines.push(`CAUSE: ${failure.cause}`);
+    if (failure.location) lines.push(`AT: ${failure.location}`);
+    if (failure.hint) lines.push(`HINT: ${failure.hint}`);
+  }
+  lines.push("TEST_RESULT: FAIL");
+  return lines;
+}
 function assessReactPlaythroughReport(input) {
   const base = { file: input.expectedFile };
   if (!input.expectedFileScheduled) {
@@ -388,12 +442,14 @@ function assessReactPlaythroughReport(input) {
     const cause = productionModule.errors[0] ?? input.unhandledErrors?.[0] ?? audit.issues[0] ?? "\u751F\u4EA7\u53EF\u73A9\u6D41\u7A0B\u6CA1\u6709\u7559\u4E0B\u5B8C\u6574\u8BC1\u636E\u3002";
     const timedOut = /outcome was not reached within \d+ steps/i.test(cause);
     const missingStep = /No step callback was provided/i.test(cause);
+    const staticOutcome = /already true at step 0 and the DOM has not changed/i.test(cause);
+    const staleSnapshot = /snapshot\(\) returned the same reference/i.test(cause);
     const missingStructuredEvidence = /performInput|checkpoint/.test(cause);
     return {
       ...base,
       status: "FAILED",
       cause,
-      next: missingStep ? "\u8BE5\u6D41\u7A0B\u662F\u65F6\u95F4\u6216\u5E27\u9A71\u52A8\u7684\uFF0C\u4F46 stepUntil \u6CA1\u6709\u63A8\u8FDB\u6E38\u620F\u65F6\u95F4\uFF1B\u4E3A\u751F\u4EA7\u6E38\u620F\u6CE8\u5165 devkit \u7684 GameClock\uFF0C\u5E76\u4F20\u5165 step: () => clock.stepFrame()\u3002\u4E0D\u8981\u7528\u771F\u5B9E setTimeout\u3002" : timedOut ? "\u771F\u5B9E\u8F93\u5165\u5DF2\u6267\u884C\uFF0C\u4F46\u73A9\u6CD5\u6CA1\u6709\u5728\u4E0A\u9650\u5185\u4EA7\u751F\u7ED3\u679C\uFF1B\u68C0\u67E5\u751F\u4EA7\u63A7\u5236\u662F\u5426\u6536\u5230\u8F93\u5165\uFF0C\u518D\u67E5\u770B\u8D85\u65F6\u9519\u8BEF\u4E2D\u7684 Last diagnostics \u5224\u65AD\u662F\u6E38\u620F\u5FAA\u73AF\u3001\u89C4\u5219\u72B6\u6001\u8FD8\u662F UI \u540C\u6B65\u672A\u63A8\u8FDB\u3002" : missingStructuredEvidence ? '\u6309\u987A\u5E8F\u8865\u9F50\u81F3\u5C11\u4E24\u6B21\u7B7E\u5230\uFF1AperformInput("entry") \u540E\u8C03\u7528 checkpoint("entered")\uFF1B\u518D\u7528 performInput("primary") \u6267\u884C\u6838\u5FC3\u64CD\u4F5C\uFF0CstepUntil \u7B49\u5F85\u7ED3\u679C\uFF0C\u7528\u56DE\u8C03\u63D0\u4F9B\u7684 expect \u65AD\u8A00\u540E\u8C03\u7528 checkpoint("progress") \u6216 checkpoint("terminal")\u3002' : "\u4ECE\u751F\u4EA7\u5165\u53E3\u6267\u884C\u771F\u5B9E DOM \u8F93\u5165\uFF0C\u7528 stepUntil \u6709\u754C\u63A8\u8FDB\u5230\u73A9\u5BB6\u53EF\u89C1\u7ED3\u679C\u6216\u6E38\u620F\u6743\u5A01\u72B6\u6001\uFF0C\u5E76\u5728\u5176\u540E\u65AD\u8A00\uFF1B\u4E0D\u8981\u76F4\u8FBE\u5185\u90E8\u5173\u5361\u6216\u4FEE\u6539\u73A9\u6CD5\u72B6\u6001\u3002",
+      next: staleSnapshot ? "\u6E38\u620F\u539F\u5730\u4FEE\u6539\u72B6\u6001\u540E\u6CA1\u6709\u53D1\u5E03\u65B0\u7684\u5FEB\u7167\u5F15\u7528\uFF0CReact \u56E0 Object.is \u6BD4\u8F83\u76F8\u540C\u800C\u8DF3\u8FC7\u91CD\u6E32\u3002\u5728 controller \u7684 notify \u8DEF\u5F84\u4E0A\u53D1\u5E03\u65B0\u9876\u5C42\u5BF9\u8C61\uFF08cachedSnapshot = { ...state }\uFF09\uFF0C\u4E0D\u8981\u628A\u53EF\u53D8\u7684\u5185\u90E8\u5BF9\u8C61\u76F4\u63A5\u4F5C\u4E3A\u5FEB\u7167\u66B4\u9732\u3002" : staticOutcome ? "\u7ED3\u679C\u5728\u63A8\u8FDB\u524D\u5DF2\u6210\u7ACB\u4E14 DOM \u81EA entered \u4EE5\u6765\u65E0\u53D8\u5316\uFF1A\u8F93\u5165\u53EF\u80FD\u672A\u63A5\u5230\u751F\u4EA7\u63A7\u5236\uFF0CUI \u53EF\u80FD\u51BB\u7ED3\uFF0C\u4E5F\u53EF\u80FD\u65AD\u8A00\u4E86\u6E38\u620F\u5F00\u59CB\u524D\u5C31\u5B58\u5728\u7684\u9759\u6001\u6587\u672C\u3002\u6539\u4E3A\u7B49\u5F85\u5E76\u65AD\u8A00\u53EA\u6709\u73A9\u6CD5\u63A8\u8FDB\u540E\u624D\u51FA\u73B0\u7684\u72B6\u6001\uFF08\u5F00\u59CB\u906E\u7F69\u6D88\u5931\u3001\u6BD4\u5206\u53D8\u5316\u3001\u7ED3\u7B97\u51FA\u73B0\uFF09\uFF1B\u7ECF Canvas/Telemetry \u7B49 DOM \u5916\u6743\u5A01\u72B6\u6001\u89C2\u5BDF\u7684\u6D41\u7A0B\u4F20 { allowStaticDom: true }\u3002" : missingStep ? "\u8BE5\u6D41\u7A0B\u662F\u65F6\u95F4\u6216\u5E27\u9A71\u52A8\u7684\uFF0C\u4F46 stepUntil \u6CA1\u6709\u63A8\u8FDB\u6E38\u620F\u65F6\u95F4\uFF1B\u4E3A\u751F\u4EA7\u6E38\u620F\u6CE8\u5165 devkit \u7684 GameClock\uFF0C\u5E76\u4F20\u5165 step: () => clock.stepFrame()\u3002\u4E0D\u8981\u7528\u771F\u5B9E setTimeout\u3002" : timedOut ? "\u771F\u5B9E\u8F93\u5165\u5DF2\u6267\u884C\uFF0C\u4F46\u73A9\u6CD5\u6CA1\u6709\u5728\u4E0A\u9650\u5185\u4EA7\u751F\u7ED3\u679C\uFF1B\u68C0\u67E5\u751F\u4EA7\u63A7\u5236\u662F\u5426\u6536\u5230\u8F93\u5165\uFF0C\u518D\u67E5\u770B\u8D85\u65F6\u9519\u8BEF\u4E2D\u7684 Last diagnostics \u5224\u65AD\u662F\u6E38\u620F\u5FAA\u73AF\u3001\u89C4\u5219\u72B6\u6001\u8FD8\u662F UI \u540C\u6B65\u672A\u63A8\u8FDB\u3002" : missingStructuredEvidence ? '\u6309\u987A\u5E8F\u8865\u9F50\u81F3\u5C11\u4E24\u6B21\u7B7E\u5230\uFF1AperformInput("entry") \u540E\u8C03\u7528 checkpoint("entered")\uFF1B\u518D\u7528 performInput("primary") \u6267\u884C\u6838\u5FC3\u64CD\u4F5C\uFF0CstepUntil \u7B49\u5F85\u7ED3\u679C\uFF0C\u7528\u56DE\u8C03\u63D0\u4F9B\u7684 expect \u65AD\u8A00\u540E\u8C03\u7528 checkpoint("progress") \u6216 checkpoint("terminal")\u3002' : "\u4ECE\u751F\u4EA7\u5165\u53E3\u6267\u884C\u771F\u5B9E DOM \u8F93\u5165\uFF0C\u7528 stepUntil \u6709\u754C\u63A8\u8FDB\u5230\u73A9\u5BB6\u53EF\u89C1\u7ED3\u679C\u6216\u6E38\u620F\u6743\u5A01\u72B6\u6001\uFF0C\u5E76\u5728\u5176\u540E\u65AD\u8A00\uFF1B\u4E0D\u8981\u76F4\u8FBE\u5185\u90E8\u5173\u5361\u6216\u4FEE\u6539\u73A9\u6CD5\u72B6\u6001\u3002",
       failsRun: true
     };
   }
@@ -458,6 +514,14 @@ var ReactPlaythroughReporter = class {
     } else {
       console.log(output);
     }
+    const summary = formatFailureSummary(
+      testModules.map((module2) => toModuleResult(module2, this.projectRoot))
+    );
+    if (report.failsRun && summary[0] === "TEST_RESULT: PASS") {
+      summary[0] = "TEST_RESULT: FAIL";
+    }
+    console.log(`
+${summary.join("\n")}`);
   }
 };
 
@@ -506,6 +570,7 @@ function defineReactGameVitestConfig(options) {
       environmentOptions: {
         jsdom: { url: "http://localhost/", pretendToBeVisual: true }
       },
+      includeTaskLocation: true,
       setupFiles: [
         "miaoda-game-devkit/react/vitest-setup",
         ...options.additionalSetupFiles ?? []
@@ -513,8 +578,8 @@ function defineReactGameVitestConfig(options) {
       sequence: {
         setupFiles: "list"
       },
-      // minimal 保留业务失败；附加 reporter 负责项目级最低可玩性门禁。
-      reporters: ["minimal", new ReactPlaythroughReporter(options.projectRoot)],
+      // 单一 reporter 输出无 ANSI 的紧凑失败摘要和项目级可玩性门禁。
+      reporters: [new ReactPlaythroughReporter(options.projectRoot)],
       restoreMocks: true,
       clearMocks: true,
       testTimeout: options.testTimeout,

package/dist/react/vitest-config.mjs

@@ -6,6 +6,7 @@ import { defineConfig } from "vitest/config";
 // src/react/react-playthrough-reporter.ts
 import { existsSync } from "fs";
 import { relative, resolve } from "path";
+import { stripVTControlCharacters } from "util";
 
 // src/react/react-playthrough.ts
 import { render } from "@testing-library/react";
@@ -108,6 +109,7 @@ function definePlaythrough(element, run, waiverReason) {
     const evidence = metadata.evidence;
     let assertionsAtOutcome;
     let enteredRecorded = false;
+    let domTextAtEntered;
     const recordInput = () => {
       evidence.domInputEvents += 1;
     };
@@ -160,6 +162,7 @@ function definePlaythrough(element, run, waiverReason) {
               );
             }
             enteredRecorded = true;
+            domTextAtEntered = document.body.textContent ?? "";
             evidence.checkpoints.push(kind);
             return;
           }
@@ -187,6 +190,11 @@ function definePlaythrough(element, run, waiverReason) {
               'stepUntil must follow performInput("primary", ...). A menu/help click is not gameplay evidence.'
             );
           }
+          if (steps === 0 && options.allowStaticDom !== true && domTextAtEntered !== void 0 && (document.body.textContent ?? "") === domTextAtEntered) {
+            throw new Error(
+              'stepUntil outcome was already true at step 0 and the DOM has not changed since checkpoint("entered"), so the flow cannot prove that gameplay changed anything. \u610F\u601D\uFF1A\u6E38\u620F\u4E00\u6B65\u90FD\u6CA1\u73A9\uFF0C\u7B49\u5F85\u7684"\u7ED3\u679C"\u5C31\u5DF2\u7ECF\u6210\u7ACB\uFF0C\u9875\u9762\u4E5F\u4E00\u4E2A\u5B57\u6CA1\u53D8\u2014\u2014\u8FD9\u4E2A\u7ED3\u679C\u8BC1\u660E\u4E0D\u4E86\u4EFB\u4F55\u4E8B\u3002\u5E38\u89C1\u539F\u56E0\uFF1A\u2460 \u8F93\u5165\u6CA1\u6709\u63A5\u5230\u6E38\u620F\u4E0A\uFF1B\u2461 \u754C\u9762\u5361\u6B7B\uFF08\u72B6\u6001\u6539\u4E86\u4F46 snapshot \u5F15\u7528\u6CA1\u6362\uFF0CReact \u6CA1\u6709\u5237\u65B0\uFF09\uFF1B\u2462 \u65AD\u8A00\u4E86\u5F00\u5C40\u524D\u5C31\u5B58\u5728\u7684\u9759\u6001\u6587\u672C\u3002\u4FEE\u590D\uFF1A\u7B49\u5F85\u5E76\u65AD\u8A00\u53EA\u6709\u73A9\u8D77\u6765\u4E4B\u540E\u624D\u4F1A\u51FA\u73B0\u7684\u4E1C\u897F\uFF08\u5F00\u59CB\u906E\u7F69\u6D88\u5931\u3001\u6BD4\u5206\u53D8\u5316\u3001\u7ED3\u7B97\u753B\u9762\u51FA\u73B0\uFF09\u3002\u4F8B\u5916\uFF1A\u7ED3\u679C\u753B\u5728 Canvas \u4E0A\u3001\u7ECF Telemetry \u7B49\u9875\u9762\u5916\u72B6\u6001\u89C2\u5BDF\u7684\u6E38\u620F\uFF0C\u663E\u5F0F\u4F20 { allowStaticDom: true }\u3002'
+            );
+          }
           evidence.boundedRuns += 1;
           assertionsAtOutcome = expect.getState().assertionCalls;
           return steps;
@@ -289,7 +297,18 @@ function toAuditInput(test2) {
 }
 function firstLine(value) {
   if (typeof value !== "string") return void 0;
-  return value.split("\n").map((line) => line.trim()).find(Boolean);
+  return stripVTControlCharacters(value).split("\n").map((line) => line.trim()).find(Boolean);
+}
+function failureHint(value) {
+  const names = [...value.matchAll(/button\s*\n\s*Name "([^"]+)"/g)].map(
+    (match) => match[1]
+  );
+  if (names.length === 0) return void 0;
+  return `Available button names: ${names.map((name) => JSON.stringify(name)).join(", ")}`;
+}
+function errorLocation(value) {
+  const match = value.match(/(?:^|\n)\s*at\s+(.*?\.(?:test|spec)\.[^\n]+:\d+:\d+)/);
+  return match?.[1];
 }
 function toModuleResult(module, projectRoot) {
   const tests = [...module.children.allTests()];
@@ -299,13 +318,48 @@ function toModuleResult(module, projectRoot) {
       (test2) => (test2.result().errors ?? []).map((error) => firstLine(error.message))
     )
   ].filter((message) => Boolean(message));
+  const failures = tests.filter((test2) => test2.result().state === "failed").map((test2) => {
+    const raw = test2.result().errors?.[0]?.message ?? module.errors()[0]?.message ?? "Unknown failure";
+    return {
+      test: test2.fullName,
+      cause: firstLine(raw) ?? "Unknown failure",
+      location: test2.location ? `${relative(projectRoot, module.moduleId).replaceAll("\\", "/")}:${test2.location.line}:${test2.location.column}` : errorLocation(raw),
+      hint: failureHint(raw)
+    };
+  });
+  if (failures.length === 0 && tests.length === 0 && module.errors().length > 0) {
+    const raw = module.errors()[0]?.message ?? "Module failed to load";
+    failures.push({
+      test: "<collection>",
+      cause: firstLine(raw) ?? "Module failed to load",
+      location: errorLocation(raw),
+      hint: failureHint(raw)
+    });
+  }
   return {
     file: relative(projectRoot, module.moduleId).replaceAll("\\", "/"),
     state: module.state(),
     errors,
-    tests: tests.map(toAuditInput)
+    tests: tests.map(toAuditInput),
+    failures
   };
 }
+function formatFailureSummary(modules) {
+  const failures = modules.flatMap(
+    (module) => (module.failures ?? []).map((failure) => ({ ...failure, file: module.file }))
+  );
+  if (failures.length === 0) return ["TEST_RESULT: PASS"];
+  const lines = [`FAILED_TESTS: ${failures.length}`];
+  for (const [index, failure] of failures.entries()) {
+    lines.push(`FAILURE_${index + 1}: ${failure.file}`);
+    lines.push(`TEST: ${failure.test}`);
+    lines.push(`CAUSE: ${failure.cause}`);
+    if (failure.location) lines.push(`AT: ${failure.location}`);
+    if (failure.hint) lines.push(`HINT: ${failure.hint}`);
+  }
+  lines.push("TEST_RESULT: FAIL");
+  return lines;
+}
 function assessReactPlaythroughReport(input) {
   const base = { file: input.expectedFile };
   if (!input.expectedFileScheduled) {
@@ -354,12 +408,14 @@ function assessReactPlaythroughReport(input) {
     const cause = productionModule.errors[0] ?? input.unhandledErrors?.[0] ?? audit.issues[0] ?? "\u751F\u4EA7\u53EF\u73A9\u6D41\u7A0B\u6CA1\u6709\u7559\u4E0B\u5B8C\u6574\u8BC1\u636E\u3002";
     const timedOut = /outcome was not reached within \d+ steps/i.test(cause);
     const missingStep = /No step callback was provided/i.test(cause);
+    const staticOutcome = /already true at step 0 and the DOM has not changed/i.test(cause);
+    const staleSnapshot = /snapshot\(\) returned the same reference/i.test(cause);
     const missingStructuredEvidence = /performInput|checkpoint/.test(cause);
     return {
       ...base,
       status: "FAILED",
       cause,
-      next: missingStep ? "\u8BE5\u6D41\u7A0B\u662F\u65F6\u95F4\u6216\u5E27\u9A71\u52A8\u7684\uFF0C\u4F46 stepUntil \u6CA1\u6709\u63A8\u8FDB\u6E38\u620F\u65F6\u95F4\uFF1B\u4E3A\u751F\u4EA7\u6E38\u620F\u6CE8\u5165 devkit \u7684 GameClock\uFF0C\u5E76\u4F20\u5165 step: () => clock.stepFrame()\u3002\u4E0D\u8981\u7528\u771F\u5B9E setTimeout\u3002" : timedOut ? "\u771F\u5B9E\u8F93\u5165\u5DF2\u6267\u884C\uFF0C\u4F46\u73A9\u6CD5\u6CA1\u6709\u5728\u4E0A\u9650\u5185\u4EA7\u751F\u7ED3\u679C\uFF1B\u68C0\u67E5\u751F\u4EA7\u63A7\u5236\u662F\u5426\u6536\u5230\u8F93\u5165\uFF0C\u518D\u67E5\u770B\u8D85\u65F6\u9519\u8BEF\u4E2D\u7684 Last diagnostics \u5224\u65AD\u662F\u6E38\u620F\u5FAA\u73AF\u3001\u89C4\u5219\u72B6\u6001\u8FD8\u662F UI \u540C\u6B65\u672A\u63A8\u8FDB\u3002" : missingStructuredEvidence ? '\u6309\u987A\u5E8F\u8865\u9F50\u81F3\u5C11\u4E24\u6B21\u7B7E\u5230\uFF1AperformInput("entry") \u540E\u8C03\u7528 checkpoint("entered")\uFF1B\u518D\u7528 performInput("primary") \u6267\u884C\u6838\u5FC3\u64CD\u4F5C\uFF0CstepUntil \u7B49\u5F85\u7ED3\u679C\uFF0C\u7528\u56DE\u8C03\u63D0\u4F9B\u7684 expect \u65AD\u8A00\u540E\u8C03\u7528 checkpoint("progress") \u6216 checkpoint("terminal")\u3002' : "\u4ECE\u751F\u4EA7\u5165\u53E3\u6267\u884C\u771F\u5B9E DOM \u8F93\u5165\uFF0C\u7528 stepUntil \u6709\u754C\u63A8\u8FDB\u5230\u73A9\u5BB6\u53EF\u89C1\u7ED3\u679C\u6216\u6E38\u620F\u6743\u5A01\u72B6\u6001\uFF0C\u5E76\u5728\u5176\u540E\u65AD\u8A00\uFF1B\u4E0D\u8981\u76F4\u8FBE\u5185\u90E8\u5173\u5361\u6216\u4FEE\u6539\u73A9\u6CD5\u72B6\u6001\u3002",
+      next: staleSnapshot ? "\u6E38\u620F\u539F\u5730\u4FEE\u6539\u72B6\u6001\u540E\u6CA1\u6709\u53D1\u5E03\u65B0\u7684\u5FEB\u7167\u5F15\u7528\uFF0CReact \u56E0 Object.is \u6BD4\u8F83\u76F8\u540C\u800C\u8DF3\u8FC7\u91CD\u6E32\u3002\u5728 controller \u7684 notify \u8DEF\u5F84\u4E0A\u53D1\u5E03\u65B0\u9876\u5C42\u5BF9\u8C61\uFF08cachedSnapshot = { ...state }\uFF09\uFF0C\u4E0D\u8981\u628A\u53EF\u53D8\u7684\u5185\u90E8\u5BF9\u8C61\u76F4\u63A5\u4F5C\u4E3A\u5FEB\u7167\u66B4\u9732\u3002" : staticOutcome ? "\u7ED3\u679C\u5728\u63A8\u8FDB\u524D\u5DF2\u6210\u7ACB\u4E14 DOM \u81EA entered \u4EE5\u6765\u65E0\u53D8\u5316\uFF1A\u8F93\u5165\u53EF\u80FD\u672A\u63A5\u5230\u751F\u4EA7\u63A7\u5236\uFF0CUI \u53EF\u80FD\u51BB\u7ED3\uFF0C\u4E5F\u53EF\u80FD\u65AD\u8A00\u4E86\u6E38\u620F\u5F00\u59CB\u524D\u5C31\u5B58\u5728\u7684\u9759\u6001\u6587\u672C\u3002\u6539\u4E3A\u7B49\u5F85\u5E76\u65AD\u8A00\u53EA\u6709\u73A9\u6CD5\u63A8\u8FDB\u540E\u624D\u51FA\u73B0\u7684\u72B6\u6001\uFF08\u5F00\u59CB\u906E\u7F69\u6D88\u5931\u3001\u6BD4\u5206\u53D8\u5316\u3001\u7ED3\u7B97\u51FA\u73B0\uFF09\uFF1B\u7ECF Canvas/Telemetry \u7B49 DOM \u5916\u6743\u5A01\u72B6\u6001\u89C2\u5BDF\u7684\u6D41\u7A0B\u4F20 { allowStaticDom: true }\u3002" : missingStep ? "\u8BE5\u6D41\u7A0B\u662F\u65F6\u95F4\u6216\u5E27\u9A71\u52A8\u7684\uFF0C\u4F46 stepUntil \u6CA1\u6709\u63A8\u8FDB\u6E38\u620F\u65F6\u95F4\uFF1B\u4E3A\u751F\u4EA7\u6E38\u620F\u6CE8\u5165 devkit \u7684 GameClock\uFF0C\u5E76\u4F20\u5165 step: () => clock.stepFrame()\u3002\u4E0D\u8981\u7528\u771F\u5B9E setTimeout\u3002" : timedOut ? "\u771F\u5B9E\u8F93\u5165\u5DF2\u6267\u884C\uFF0C\u4F46\u73A9\u6CD5\u6CA1\u6709\u5728\u4E0A\u9650\u5185\u4EA7\u751F\u7ED3\u679C\uFF1B\u68C0\u67E5\u751F\u4EA7\u63A7\u5236\u662F\u5426\u6536\u5230\u8F93\u5165\uFF0C\u518D\u67E5\u770B\u8D85\u65F6\u9519\u8BEF\u4E2D\u7684 Last diagnostics \u5224\u65AD\u662F\u6E38\u620F\u5FAA\u73AF\u3001\u89C4\u5219\u72B6\u6001\u8FD8\u662F UI \u540C\u6B65\u672A\u63A8\u8FDB\u3002" : missingStructuredEvidence ? '\u6309\u987A\u5E8F\u8865\u9F50\u81F3\u5C11\u4E24\u6B21\u7B7E\u5230\uFF1AperformInput("entry") \u540E\u8C03\u7528 checkpoint("entered")\uFF1B\u518D\u7528 performInput("primary") \u6267\u884C\u6838\u5FC3\u64CD\u4F5C\uFF0CstepUntil \u7B49\u5F85\u7ED3\u679C\uFF0C\u7528\u56DE\u8C03\u63D0\u4F9B\u7684 expect \u65AD\u8A00\u540E\u8C03\u7528 checkpoint("progress") \u6216 checkpoint("terminal")\u3002' : "\u4ECE\u751F\u4EA7\u5165\u53E3\u6267\u884C\u771F\u5B9E DOM \u8F93\u5165\uFF0C\u7528 stepUntil \u6709\u754C\u63A8\u8FDB\u5230\u73A9\u5BB6\u53EF\u89C1\u7ED3\u679C\u6216\u6E38\u620F\u6743\u5A01\u72B6\u6001\uFF0C\u5E76\u5728\u5176\u540E\u65AD\u8A00\uFF1B\u4E0D\u8981\u76F4\u8FBE\u5185\u90E8\u5173\u5361\u6216\u4FEE\u6539\u73A9\u6CD5\u72B6\u6001\u3002",
       failsRun: true
     };
   }
@@ -424,6 +480,14 @@ var ReactPlaythroughReporter = class {
     } else {
       console.log(output);
     }
+    const summary = formatFailureSummary(
+      testModules.map((module) => toModuleResult(module, this.projectRoot))
+    );
+    if (report.failsRun && summary[0] === "TEST_RESULT: PASS") {
+      summary[0] = "TEST_RESULT: FAIL";
+    }
+    console.log(`
+${summary.join("\n")}`);
   }
 };
 
@@ -472,6 +536,7 @@ function defineReactGameVitestConfig(options) {
       environmentOptions: {
         jsdom: { url: "http://localhost/", pretendToBeVisual: true }
       },
+      includeTaskLocation: true,
       setupFiles: [
         "miaoda-game-devkit/react/vitest-setup",
         ...options.additionalSetupFiles ?? []
@@ -479,8 +544,8 @@ function defineReactGameVitestConfig(options) {
       sequence: {
         setupFiles: "list"
       },
-      // minimal 保留业务失败；附加 reporter 负责项目级最低可玩性门禁。
-      reporters: ["minimal", new ReactPlaythroughReporter(options.projectRoot)],
+      // 单一 reporter 输出无 ANSI 的紧凑失败摘要和项目级可玩性门禁。
+      reporters: [new ReactPlaythroughReporter(options.projectRoot)],
       restoreMocks: true,
       clearMocks: true,
       testTimeout: options.testTimeout,

package/package.json

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