miaoda-game-devkit 0.2.20 → 0.3.0

package/README.md

@@ -8,13 +8,14 @@
   Vitest 配置和自动收集运行错误的 Testing Library setup，分别从 `miaoda-game-devkit/react`、
   `miaoda-game-devkit/react/testing` 和 `miaoda-game-devkit/react/vitest-config` 导入；
 - React 的 `playthroughTest` 与项目级 reporter 自动验证独立的 entry/primary DOM
-  输入、有界推进、结果断言及前后权威 snapshot 变化；聚焦运行只提示未检查，
+  输入、有界推进、结果断言及至少两次有序 checkpoint 签到；聚焦运行只提示未检查，
   完整运行缺少有效流程时失败；
 
 `playthroughTest` 的主流程回调从参数接收 `user`、`performInput`、`checkpoint`、
-`stepUntil` 和绑定当前测试的 `expect`。按 entry 输入、entered snapshot、primary 输入、
-有界等待、使用回调提供的 `expect` 断言结果、
-progress/terminal snapshot 的顺序记录最低证据。大型游戏仍只保留一条最短关键流程；
+`stepUntil` 和绑定当前测试的 `expect`。按 entry 输入、`checkpoint("entered")`、primary 输入、
+有界等待、使用回调提供的 `expect` 断言权威结果、
+`checkpoint("progress")` 或 `checkpoint("terminal")` 的顺序记录最低证据。每条流程至少需要
+这两次 checkpoint；checkpoint 只负责签到，不携带或验证状态。大型游戏仍只保留一条最短关键流程；
 分支、关卡规则和恢复清理由专门测试覆盖。不要再次调用 `userEvent.setup()`。
 时间、帧或自定义 scheduler 流程必须显式传入确定性 `step`；精确物理时间、暂停恢复
 或调度清理测试可使用 `ManualGameClock`。
@@ -153,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 主流程测试留下的可序列化运行期证据。 */
@@ -47,8 +57,6 @@ interface ReactPlaythroughEvidence {
     boundedRuns: number;
     /** 最后一次 stepUntil 成功后新增的 Vitest 断言数。 */
     assertionsAfterOutcome: number;
-    /** 已验证相对 entered snapshot 发生变化的进展或终局 checkpoint 次数。 */
-    changedOutcomeCheckpoints: number;
     /** 已记录的 checkpoint 类型，供 reporter 给出精确提示。 */
     checkpoints: ReactPlaythroughCheckpointKind[];
     /** helper 是否已经完成全部证据校验。 */
@@ -57,7 +65,7 @@ interface ReactPlaythroughEvidence {
 /** 通过 Vitest task metadata 从 worker 传递给主线程 reporter 的数据。 */
 interface ReactPlaythroughMetadata {
     /** metadata 结构版本，用于拒绝无法识别的旧数据。 */
-    version: 2;
+    version: 3;
     /** 静态、非交互项目跳过主流程验证时必须提供的理由。 */
     waiverReason?: string;
     /** 测试执行期间持续更新的客观证据。 */
@@ -66,7 +74,7 @@ interface ReactPlaythroughMetadata {
 
 /** 玩家输入在最低可玩流程中的语义阶段。 */
 type ReactPlaythroughInputKind = "entry" | "primary";
-/** 可审计状态证据；entered 是基线，progress/terminal 是有效结果。 */
+/** 可审计流程签到；entered 是入口，progress/terminal 是有效结果。 */
 type ReactPlaythroughCheckpointKind = "entered" | "progress" | "terminal";
 /** 主流程回调唯一需要学习的测试工具。 */
 interface ReactPlaythroughArguments {
@@ -82,10 +90,10 @@ interface ReactPlaythroughArguments {
      */
     performInput(kind: ReactPlaythroughInputKind, input: () => void | Promise<void>): Promise<void>;
     /**
-     * 记录只读状态证据。先在 entry 后记录 entered，再在 primary 和 stepUntil
-     * 后记录 progress 或 terminal；Canvas 游戏应传 Telemetry snapshot。
+     * 记录流程签到。先在 entry 后记录 entered，再在 primary、stepUntil 和
+     * 结果断言后记录 progress 或 terminal。
      */
-    checkpoint(kind: ReactPlaythroughCheckpointKind, snapshot: unknown): void;
+    checkpoint(kind: ReactPlaythroughCheckpointKind): void;
     /**
      * 在硬性步数上限内等待权威结果。
      * 返回后必须再断言该结果，进入中间 active/running 状态不算完成。

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 主流程测试留下的可序列化运行期证据。 */
@@ -47,8 +57,6 @@ interface ReactPlaythroughEvidence {
     boundedRuns: number;
     /** 最后一次 stepUntil 成功后新增的 Vitest 断言数。 */
     assertionsAfterOutcome: number;
-    /** 已验证相对 entered snapshot 发生变化的进展或终局 checkpoint 次数。 */
-    changedOutcomeCheckpoints: number;
     /** 已记录的 checkpoint 类型，供 reporter 给出精确提示。 */
     checkpoints: ReactPlaythroughCheckpointKind[];
     /** helper 是否已经完成全部证据校验。 */
@@ -57,7 +65,7 @@ interface ReactPlaythroughEvidence {
 /** 通过 Vitest task metadata 从 worker 传递给主线程 reporter 的数据。 */
 interface ReactPlaythroughMetadata {
     /** metadata 结构版本，用于拒绝无法识别的旧数据。 */
-    version: 2;
+    version: 3;
     /** 静态、非交互项目跳过主流程验证时必须提供的理由。 */
     waiverReason?: string;
     /** 测试执行期间持续更新的客观证据。 */
@@ -66,7 +74,7 @@ interface ReactPlaythroughMetadata {
 
 /** 玩家输入在最低可玩流程中的语义阶段。 */
 type ReactPlaythroughInputKind = "entry" | "primary";
-/** 可审计状态证据；entered 是基线，progress/terminal 是有效结果。 */
+/** 可审计流程签到；entered 是入口，progress/terminal 是有效结果。 */
 type ReactPlaythroughCheckpointKind = "entered" | "progress" | "terminal";
 /** 主流程回调唯一需要学习的测试工具。 */
 interface ReactPlaythroughArguments {
@@ -82,10 +90,10 @@ interface ReactPlaythroughArguments {
      */
     performInput(kind: ReactPlaythroughInputKind, input: () => void | Promise<void>): Promise<void>;
     /**
-     * 记录只读状态证据。先在 entry 后记录 entered，再在 primary 和 stepUntil
-     * 后记录 progress 或 terminal；Canvas 游戏应传 Telemetry snapshot。
+     * 记录流程签到。先在 entry 后记录 entered，再在 primary、stepUntil 和
+     * 结果断言后记录 progress 或 terminal。
      */
-    checkpoint(kind: ReactPlaythroughCheckpointKind, snapshot: unknown): void;
+    checkpoint(kind: ReactPlaythroughCheckpointKind): void;
     /**
      * 在硬性步数上限内等待权威结果。
      * 返回后必须再断言该结果，进入中间 active/running 状态不算完成。

package/dist/react/testing.js

@@ -151,20 +151,25 @@ var INPUT_EVENTS = [
   "touchstart",
   "touchend"
 ];
+var MIN_CHECKPOINTS = 2;
 function describeMissingEvidence(evidence) {
   if (!evidence || evidence.entryInputs === 0) return "entry \u8F93\u5165";
   if (evidence.primaryInputs === 0) return "primary \u8F93\u5165";
   if (!evidence.checkpoints.includes("entered")) return "entered checkpoint";
   if (evidence.boundedRuns === 0) return "\u6709\u754C stepUntil";
   if (evidence.assertionsAfterOutcome === 0) return "stepUntil \u540E\u7684\u7ED3\u679C\u65AD\u8A00";
-  if (evidence.changedOutcomeCheckpoints === 0) {
-    return "\u53D1\u751F\u72B6\u6001\u53D8\u5316\u7684 progress/terminal checkpoint";
+  if (evidence.checkpoints.length < MIN_CHECKPOINTS)
+    return `\u81F3\u5C11 ${MIN_CHECKPOINTS} \u4E2A checkpoint`;
+  if (!evidence.checkpoints.some(
+    (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
+  )) {
+    return "progress/terminal checkpoint";
   }
   return "\u5B8C\u6574\u7684 playthrough \u6821\u9A8C\u6807\u8BB0";
 }
 function createMetadata(waiverReason) {
   return {
-    version: 2,
+    version: 3,
     waiverReason,
     evidence: {
       domInputEvents: 0,
@@ -172,23 +177,11 @@ function createMetadata(waiverReason) {
       primaryInputs: 0,
       boundedRuns: 0,
       assertionsAfterOutcome: 0,
-      changedOutcomeCheckpoints: 0,
       checkpoints: [],
       verified: false
     }
   };
 }
-function snapshotFingerprint(snapshot) {
-  try {
-    const serialized = JSON.stringify(snapshot);
-    if (serialized === void 0) throw new Error("unsupported value");
-    return serialized;
-  } catch {
-    throw new Error(
-      "checkpoint snapshot must be JSON-serializable. Pass a read-only Telemetry snapshot or a small visible-state object."
-    );
-  }
-}
 function definePlaythrough(element, run, waiverReason) {
   const reason = normalizePlaythroughWaiverReason(waiverReason);
   const metadata = createMetadata(reason);
@@ -198,7 +191,8 @@ function definePlaythrough(element, run, waiverReason) {
   }, async ({ expect }) => {
     const evidence = metadata.evidence;
     let assertionsAtOutcome;
-    let enteredSnapshot;
+    let enteredRecorded = false;
+    let domTextAtEntered;
     const recordInput = () => {
       evidence.domInputEvents += 1;
     };
@@ -218,14 +212,14 @@ function definePlaythrough(element, run, waiverReason) {
         user,
         expect,
         async performInput(kind, input) {
-          if (kind === "entry" && enteredSnapshot !== void 0) {
+          if (kind === "entry" && enteredRecorded) {
             throw new Error(
               'performInput("entry") must run before checkpoint("entered"). Group multiple setup actions in the same callback.'
             );
           }
-          if (kind === "primary" && enteredSnapshot === void 0) {
+          if (kind === "primary" && !enteredRecorded) {
             throw new Error(
-              'Before performInput("primary"), run an entry input and checkpoint("entered", snapshot).'
+              'Before performInput("primary"), run an entry input and checkpoint("entered").'
             );
           }
           const inputsBefore = evidence.domInputEvents;
@@ -238,10 +232,9 @@ function definePlaythrough(element, run, waiverReason) {
           if (kind === "entry") evidence.entryInputs += 1;
           else evidence.primaryInputs += 1;
         },
-        checkpoint(kind, snapshot) {
-          const fingerprint = snapshotFingerprint(snapshot);
+        checkpoint(kind) {
           if (kind === "entered") {
-            if (enteredSnapshot !== void 0) {
+            if (enteredRecorded) {
               throw new Error(
                 'checkpoint("entered") may only be recorded once, before the primary input.'
               );
@@ -251,7 +244,8 @@ function definePlaythrough(element, run, waiverReason) {
                 'checkpoint("entered") must follow performInput("entry", ...).'
               );
             }
-            enteredSnapshot = fingerprint;
+            enteredRecorded = true;
+            domTextAtEntered = document.body.textContent ?? "";
             evidence.checkpoints.push(kind);
             return;
           }
@@ -267,15 +261,9 @@ function definePlaythrough(element, run, waiverReason) {
           }
           if (assertionsAtOutcome === void 0 || expect.getState().assertionCalls <= assertionsAtOutcome) {
             throw new Error(
-              `Use the expect provided by playthroughTest to assert the authoritative result after stepUntil, then record checkpoint("${kind}", snapshot).`
+              `Use the expect provided by playthroughTest to assert the authoritative result after stepUntil, then record checkpoint("${kind}").`
             );
           }
-          if (fingerprint === enteredSnapshot) {
-            throw new Error(
-              `checkpoint("${kind}") matches the entered snapshot. Assert a production state change caused by the primary input.`
-            );
-          }
-          evidence.changedOutcomeCheckpoints += 1;
           evidence.checkpoints.push(kind);
         },
         async stepUntil(condition, options = {}) {
@@ -285,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;
@@ -310,9 +303,11 @@ function definePlaythrough(element, run, waiverReason) {
           "Use the expect provided by playthroughTest to assert an authoritative game outcome after stepUntil returns."
         );
       }
-      if (evidence.changedOutcomeCheckpoints === 0) {
+      if (evidence.checkpoints.length < MIN_CHECKPOINTS || !evidence.checkpoints.some(
+        (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
+      )) {
         throw new Error(
-          'After asserting the result, record checkpoint("progress", snapshot) or checkpoint("terminal", snapshot). The snapshot must differ from checkpoint("entered").'
+          `playthroughTest requires at least ${MIN_CHECKPOINTS} checkpoints: checkpoint("entered") and, after asserting the result, checkpoint("progress") or checkpoint("terminal").`
         );
       }
       evidence.verified = true;
@@ -333,7 +328,7 @@ function auditReactPlaythroughRun(tests) {
   const declared = tests.filter((candidate) => candidate.metadata);
   const valid = declared.filter(({ state, metadata }) => {
     const evidence = metadata?.evidence;
-    return state === "passed" && evidence?.verified === true && evidence.domInputEvents > 0 && evidence.entryInputs > 0 && evidence.primaryInputs > 0 && evidence.boundedRuns > 0 && evidence.assertionsAfterOutcome > 0 && evidence.changedOutcomeCheckpoints > 0 && evidence.checkpoints.includes("entered") && evidence.checkpoints.some(
+    return state === "passed" && evidence?.verified === true && evidence.domInputEvents > 0 && evidence.entryInputs > 0 && evidence.primaryInputs > 0 && evidence.boundedRuns > 0 && evidence.assertionsAfterOutcome > 0 && evidence.checkpoints.length >= MIN_CHECKPOINTS && evidence.checkpoints.includes("entered") && evidence.checkpoints.some(
       (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
     );
   });
@@ -343,7 +338,7 @@ function auditReactPlaythroughRun(tests) {
   const issues = [];
   if (declared.length === 0) {
     issues.push(
-      '\u7F3A\u5C11\u751F\u4EA7\u6E38\u620F\u53EF\u73A9\u6027\u9A8C\u8BC1\uFF1A\u4F7F\u7528 playthroughTest \u6E32\u67D3 <App />\uFF0C\u4F9D\u6B21\u6267\u884C performInput("entry")\u3001checkpoint("entered")\u3001performInput("primary")\u3001stepUntil\u3001\u7528 playthroughTest \u63D0\u4F9B\u7684 expect \u65AD\u8A00\u7ED3\u679C\uFF0C\u5E76\u8BB0\u5F55 progress/terminal checkpoint\u3002'
+      '\u7F3A\u5C11\u751F\u4EA7\u6E38\u620F\u53EF\u73A9\u6027\u9A8C\u8BC1\uFF1A\u4F7F\u7528 playthroughTest \u6E32\u67D3 <App />\uFF0C\u4F9D\u6B21\u6267\u884C performInput("entry")\u3001checkpoint("entered")\u3001performInput("primary")\u3001stepUntil\u3001\u7528 playthroughTest \u63D0\u4F9B\u7684 expect \u65AD\u8A00\u6743\u5A01\u7ED3\u679C\uFF0C\u5E76\u8BB0\u5F55 checkpoint("progress") \u6216 checkpoint("terminal")\uFF1B\u81F3\u5C11\u5B8C\u6210\u8FD9\u4E24\u6B21 checkpoint \u7B7E\u5230\u3002'
     );
   } else {
     for (const candidate of declared) {

package/dist/react/testing.mjs

@@ -113,20 +113,25 @@ var INPUT_EVENTS = [
   "touchstart",
   "touchend"
 ];
+var MIN_CHECKPOINTS = 2;
 function describeMissingEvidence(evidence) {
   if (!evidence || evidence.entryInputs === 0) return "entry \u8F93\u5165";
   if (evidence.primaryInputs === 0) return "primary \u8F93\u5165";
   if (!evidence.checkpoints.includes("entered")) return "entered checkpoint";
   if (evidence.boundedRuns === 0) return "\u6709\u754C stepUntil";
   if (evidence.assertionsAfterOutcome === 0) return "stepUntil \u540E\u7684\u7ED3\u679C\u65AD\u8A00";
-  if (evidence.changedOutcomeCheckpoints === 0) {
-    return "\u53D1\u751F\u72B6\u6001\u53D8\u5316\u7684 progress/terminal checkpoint";
+  if (evidence.checkpoints.length < MIN_CHECKPOINTS)
+    return `\u81F3\u5C11 ${MIN_CHECKPOINTS} \u4E2A checkpoint`;
+  if (!evidence.checkpoints.some(
+    (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
+  )) {
+    return "progress/terminal checkpoint";
   }
   return "\u5B8C\u6574\u7684 playthrough \u6821\u9A8C\u6807\u8BB0";
 }
 function createMetadata(waiverReason) {
   return {
-    version: 2,
+    version: 3,
     waiverReason,
     evidence: {
       domInputEvents: 0,
@@ -134,23 +139,11 @@ function createMetadata(waiverReason) {
       primaryInputs: 0,
       boundedRuns: 0,
       assertionsAfterOutcome: 0,
-      changedOutcomeCheckpoints: 0,
       checkpoints: [],
       verified: false
     }
   };
 }
-function snapshotFingerprint(snapshot) {
-  try {
-    const serialized = JSON.stringify(snapshot);
-    if (serialized === void 0) throw new Error("unsupported value");
-    return serialized;
-  } catch {
-    throw new Error(
-      "checkpoint snapshot must be JSON-serializable. Pass a read-only Telemetry snapshot or a small visible-state object."
-    );
-  }
-}
 function definePlaythrough(element, run, waiverReason) {
   const reason = normalizePlaythroughWaiverReason(waiverReason);
   const metadata = createMetadata(reason);
@@ -160,7 +153,8 @@ function definePlaythrough(element, run, waiverReason) {
   }, async ({ expect }) => {
     const evidence = metadata.evidence;
     let assertionsAtOutcome;
-    let enteredSnapshot;
+    let enteredRecorded = false;
+    let domTextAtEntered;
     const recordInput = () => {
       evidence.domInputEvents += 1;
     };
@@ -180,14 +174,14 @@ function definePlaythrough(element, run, waiverReason) {
         user,
         expect,
         async performInput(kind, input) {
-          if (kind === "entry" && enteredSnapshot !== void 0) {
+          if (kind === "entry" && enteredRecorded) {
             throw new Error(
               'performInput("entry") must run before checkpoint("entered"). Group multiple setup actions in the same callback.'
             );
           }
-          if (kind === "primary" && enteredSnapshot === void 0) {
+          if (kind === "primary" && !enteredRecorded) {
             throw new Error(
-              'Before performInput("primary"), run an entry input and checkpoint("entered", snapshot).'
+              'Before performInput("primary"), run an entry input and checkpoint("entered").'
             );
           }
           const inputsBefore = evidence.domInputEvents;
@@ -200,10 +194,9 @@ function definePlaythrough(element, run, waiverReason) {
           if (kind === "entry") evidence.entryInputs += 1;
           else evidence.primaryInputs += 1;
         },
-        checkpoint(kind, snapshot) {
-          const fingerprint = snapshotFingerprint(snapshot);
+        checkpoint(kind) {
           if (kind === "entered") {
-            if (enteredSnapshot !== void 0) {
+            if (enteredRecorded) {
               throw new Error(
                 'checkpoint("entered") may only be recorded once, before the primary input.'
               );
@@ -213,7 +206,8 @@ function definePlaythrough(element, run, waiverReason) {
                 'checkpoint("entered") must follow performInput("entry", ...).'
               );
             }
-            enteredSnapshot = fingerprint;
+            enteredRecorded = true;
+            domTextAtEntered = document.body.textContent ?? "";
             evidence.checkpoints.push(kind);
             return;
           }
@@ -229,15 +223,9 @@ function definePlaythrough(element, run, waiverReason) {
           }
           if (assertionsAtOutcome === void 0 || expect.getState().assertionCalls <= assertionsAtOutcome) {
             throw new Error(
-              `Use the expect provided by playthroughTest to assert the authoritative result after stepUntil, then record checkpoint("${kind}", snapshot).`
+              `Use the expect provided by playthroughTest to assert the authoritative result after stepUntil, then record checkpoint("${kind}").`
             );
           }
-          if (fingerprint === enteredSnapshot) {
-            throw new Error(
-              `checkpoint("${kind}") matches the entered snapshot. Assert a production state change caused by the primary input.`
-            );
-          }
-          evidence.changedOutcomeCheckpoints += 1;
           evidence.checkpoints.push(kind);
         },
         async stepUntil(condition, options = {}) {
@@ -247,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;
@@ -272,9 +265,11 @@ function definePlaythrough(element, run, waiverReason) {
           "Use the expect provided by playthroughTest to assert an authoritative game outcome after stepUntil returns."
         );
       }
-      if (evidence.changedOutcomeCheckpoints === 0) {
+      if (evidence.checkpoints.length < MIN_CHECKPOINTS || !evidence.checkpoints.some(
+        (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
+      )) {
         throw new Error(
-          'After asserting the result, record checkpoint("progress", snapshot) or checkpoint("terminal", snapshot). The snapshot must differ from checkpoint("entered").'
+          `playthroughTest requires at least ${MIN_CHECKPOINTS} checkpoints: checkpoint("entered") and, after asserting the result, checkpoint("progress") or checkpoint("terminal").`
         );
       }
       evidence.verified = true;
@@ -295,7 +290,7 @@ function auditReactPlaythroughRun(tests) {
   const declared = tests.filter((candidate) => candidate.metadata);
   const valid = declared.filter(({ state, metadata }) => {
     const evidence = metadata?.evidence;
-    return state === "passed" && evidence?.verified === true && evidence.domInputEvents > 0 && evidence.entryInputs > 0 && evidence.primaryInputs > 0 && evidence.boundedRuns > 0 && evidence.assertionsAfterOutcome > 0 && evidence.changedOutcomeCheckpoints > 0 && evidence.checkpoints.includes("entered") && evidence.checkpoints.some(
+    return state === "passed" && evidence?.verified === true && evidence.domInputEvents > 0 && evidence.entryInputs > 0 && evidence.primaryInputs > 0 && evidence.boundedRuns > 0 && evidence.assertionsAfterOutcome > 0 && evidence.checkpoints.length >= MIN_CHECKPOINTS && evidence.checkpoints.includes("entered") && evidence.checkpoints.some(
       (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
     );
   });
@@ -305,7 +300,7 @@ function auditReactPlaythroughRun(tests) {
   const issues = [];
   if (declared.length === 0) {
     issues.push(
-      '\u7F3A\u5C11\u751F\u4EA7\u6E38\u620F\u53EF\u73A9\u6027\u9A8C\u8BC1\uFF1A\u4F7F\u7528 playthroughTest \u6E32\u67D3 <App />\uFF0C\u4F9D\u6B21\u6267\u884C performInput("entry")\u3001checkpoint("entered")\u3001performInput("primary")\u3001stepUntil\u3001\u7528 playthroughTest \u63D0\u4F9B\u7684 expect \u65AD\u8A00\u7ED3\u679C\uFF0C\u5E76\u8BB0\u5F55 progress/terminal checkpoint\u3002'
+      '\u7F3A\u5C11\u751F\u4EA7\u6E38\u620F\u53EF\u73A9\u6027\u9A8C\u8BC1\uFF1A\u4F7F\u7528 playthroughTest \u6E32\u67D3 <App />\uFF0C\u4F9D\u6B21\u6267\u884C performInput("entry")\u3001checkpoint("entered")\u3001performInput("primary")\u3001stepUntil\u3001\u7528 playthroughTest \u63D0\u4F9B\u7684 expect \u65AD\u8A00\u6743\u5A01\u7ED3\u679C\uFF0C\u5E76\u8BB0\u5F55 checkpoint("progress") \u6216 checkpoint("terminal")\uFF1B\u81F3\u5C11\u5B8C\u6210\u8FD9\u4E24\u6B21 checkpoint \u7B7E\u5230\u3002'
     );
   } else {
     for (const candidate of declared) {

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");
@@ -101,20 +102,25 @@ var INPUT_EVENTS = [
   "touchstart",
   "touchend"
 ];
+var MIN_CHECKPOINTS = 2;
 function describeMissingEvidence(evidence) {
   if (!evidence || evidence.entryInputs === 0) return "entry \u8F93\u5165";
   if (evidence.primaryInputs === 0) return "primary \u8F93\u5165";
   if (!evidence.checkpoints.includes("entered")) return "entered checkpoint";
   if (evidence.boundedRuns === 0) return "\u6709\u754C stepUntil";
   if (evidence.assertionsAfterOutcome === 0) return "stepUntil \u540E\u7684\u7ED3\u679C\u65AD\u8A00";
-  if (evidence.changedOutcomeCheckpoints === 0) {
-    return "\u53D1\u751F\u72B6\u6001\u53D8\u5316\u7684 progress/terminal checkpoint";
+  if (evidence.checkpoints.length < MIN_CHECKPOINTS)
+    return `\u81F3\u5C11 ${MIN_CHECKPOINTS} \u4E2A checkpoint`;
+  if (!evidence.checkpoints.some(
+    (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
+  )) {
+    return "progress/terminal checkpoint";
   }
   return "\u5B8C\u6574\u7684 playthrough \u6821\u9A8C\u6807\u8BB0";
 }
 function createMetadata(waiverReason) {
   return {
-    version: 2,
+    version: 3,
     waiverReason,
     evidence: {
       domInputEvents: 0,
@@ -122,23 +128,11 @@ function createMetadata(waiverReason) {
       primaryInputs: 0,
       boundedRuns: 0,
       assertionsAfterOutcome: 0,
-      changedOutcomeCheckpoints: 0,
       checkpoints: [],
       verified: false
     }
   };
 }
-function snapshotFingerprint(snapshot) {
-  try {
-    const serialized = JSON.stringify(snapshot);
-    if (serialized === void 0) throw new Error("unsupported value");
-    return serialized;
-  } catch {
-    throw new Error(
-      "checkpoint snapshot must be JSON-serializable. Pass a read-only Telemetry snapshot or a small visible-state object."
-    );
-  }
-}
 function definePlaythrough(element, run, waiverReason) {
   const reason = normalizePlaythroughWaiverReason(waiverReason);
   const metadata = createMetadata(reason);
@@ -148,7 +142,8 @@ function definePlaythrough(element, run, waiverReason) {
   }, async ({ expect }) => {
     const evidence = metadata.evidence;
     let assertionsAtOutcome;
-    let enteredSnapshot;
+    let enteredRecorded = false;
+    let domTextAtEntered;
     const recordInput = () => {
       evidence.domInputEvents += 1;
     };
@@ -168,14 +163,14 @@ function definePlaythrough(element, run, waiverReason) {
         user,
         expect,
         async performInput(kind, input) {
-          if (kind === "entry" && enteredSnapshot !== void 0) {
+          if (kind === "entry" && enteredRecorded) {
             throw new Error(
               'performInput("entry") must run before checkpoint("entered"). Group multiple setup actions in the same callback.'
             );
           }
-          if (kind === "primary" && enteredSnapshot === void 0) {
+          if (kind === "primary" && !enteredRecorded) {
             throw new Error(
-              'Before performInput("primary"), run an entry input and checkpoint("entered", snapshot).'
+              'Before performInput("primary"), run an entry input and checkpoint("entered").'
             );
           }
           const inputsBefore = evidence.domInputEvents;
@@ -188,10 +183,9 @@ function definePlaythrough(element, run, waiverReason) {
           if (kind === "entry") evidence.entryInputs += 1;
           else evidence.primaryInputs += 1;
         },
-        checkpoint(kind, snapshot) {
-          const fingerprint = snapshotFingerprint(snapshot);
+        checkpoint(kind) {
           if (kind === "entered") {
-            if (enteredSnapshot !== void 0) {
+            if (enteredRecorded) {
               throw new Error(
                 'checkpoint("entered") may only be recorded once, before the primary input.'
               );
@@ -201,7 +195,8 @@ function definePlaythrough(element, run, waiverReason) {
                 'checkpoint("entered") must follow performInput("entry", ...).'
               );
             }
-            enteredSnapshot = fingerprint;
+            enteredRecorded = true;
+            domTextAtEntered = document.body.textContent ?? "";
             evidence.checkpoints.push(kind);
             return;
           }
@@ -217,15 +212,9 @@ function definePlaythrough(element, run, waiverReason) {
           }
           if (assertionsAtOutcome === void 0 || expect.getState().assertionCalls <= assertionsAtOutcome) {
             throw new Error(
-              `Use the expect provided by playthroughTest to assert the authoritative result after stepUntil, then record checkpoint("${kind}", snapshot).`
+              `Use the expect provided by playthroughTest to assert the authoritative result after stepUntil, then record checkpoint("${kind}").`
             );
           }
-          if (fingerprint === enteredSnapshot) {
-            throw new Error(
-              `checkpoint("${kind}") matches the entered snapshot. Assert a production state change caused by the primary input.`
-            );
-          }
-          evidence.changedOutcomeCheckpoints += 1;
           evidence.checkpoints.push(kind);
         },
         async stepUntil(condition, options = {}) {
@@ -235,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;
@@ -260,9 +254,11 @@ function definePlaythrough(element, run, waiverReason) {
           "Use the expect provided by playthroughTest to assert an authoritative game outcome after stepUntil returns."
         );
       }
-      if (evidence.changedOutcomeCheckpoints === 0) {
+      if (evidence.checkpoints.length < MIN_CHECKPOINTS || !evidence.checkpoints.some(
+        (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
+      )) {
         throw new Error(
-          'After asserting the result, record checkpoint("progress", snapshot) or checkpoint("terminal", snapshot). The snapshot must differ from checkpoint("entered").'
+          `playthroughTest requires at least ${MIN_CHECKPOINTS} checkpoints: checkpoint("entered") and, after asserting the result, checkpoint("progress") or checkpoint("terminal").`
         );
       }
       evidence.verified = true;
@@ -283,7 +279,7 @@ function auditReactPlaythroughRun(tests) {
   const declared = tests.filter((candidate) => candidate.metadata);
   const valid = declared.filter(({ state, metadata }) => {
     const evidence = metadata?.evidence;
-    return state === "passed" && evidence?.verified === true && evidence.domInputEvents > 0 && evidence.entryInputs > 0 && evidence.primaryInputs > 0 && evidence.boundedRuns > 0 && evidence.assertionsAfterOutcome > 0 && evidence.changedOutcomeCheckpoints > 0 && evidence.checkpoints.includes("entered") && evidence.checkpoints.some(
+    return state === "passed" && evidence?.verified === true && evidence.domInputEvents > 0 && evidence.entryInputs > 0 && evidence.primaryInputs > 0 && evidence.boundedRuns > 0 && evidence.assertionsAfterOutcome > 0 && evidence.checkpoints.length >= MIN_CHECKPOINTS && evidence.checkpoints.includes("entered") && evidence.checkpoints.some(
       (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
     );
   });
@@ -293,7 +289,7 @@ function auditReactPlaythroughRun(tests) {
   const issues = [];
   if (declared.length === 0) {
     issues.push(
-      '\u7F3A\u5C11\u751F\u4EA7\u6E38\u620F\u53EF\u73A9\u6027\u9A8C\u8BC1\uFF1A\u4F7F\u7528 playthroughTest \u6E32\u67D3 <App />\uFF0C\u4F9D\u6B21\u6267\u884C performInput("entry")\u3001checkpoint("entered")\u3001performInput("primary")\u3001stepUntil\u3001\u7528 playthroughTest \u63D0\u4F9B\u7684 expect \u65AD\u8A00\u7ED3\u679C\uFF0C\u5E76\u8BB0\u5F55 progress/terminal checkpoint\u3002'
+      '\u7F3A\u5C11\u751F\u4EA7\u6E38\u620F\u53EF\u73A9\u6027\u9A8C\u8BC1\uFF1A\u4F7F\u7528 playthroughTest \u6E32\u67D3 <App />\uFF0C\u4F9D\u6B21\u6267\u884C performInput("entry")\u3001checkpoint("entered")\u3001performInput("primary")\u3001stepUntil\u3001\u7528 playthroughTest \u63D0\u4F9B\u7684 expect \u65AD\u8A00\u6743\u5A01\u7ED3\u679C\uFF0C\u5E76\u8BB0\u5F55 checkpoint("progress") \u6216 checkpoint("terminal")\uFF1B\u81F3\u5C11\u5B8C\u6210\u8FD9\u4E24\u6B21 checkpoint \u7B7E\u5230\u3002'
     );
   } else {
     for (const candidate of declared) {
@@ -323,7 +319,7 @@ var PRODUCTION_PLAYTHROUGH_FILE = "tests/production-playthrough.test.tsx";
 function isMetadata(value) {
   if (!value || typeof value !== "object") return false;
   const metadata = value;
-  return metadata.version === 2 && Boolean(metadata.evidence);
+  return metadata.version === 3 && Boolean(metadata.evidence);
 }
 function toAuditInput(test2) {
   const metadata = test2.meta().reactPlaythrough;
@@ -335,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()];
@@ -345,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) {
@@ -367,7 +409,7 @@ function assessReactPlaythroughReport(input) {
       ...base,
       status: "FAILED",
       cause: "\u751F\u4EA7\u53EF\u73A9\u6027\u6D4B\u8BD5\u6587\u4EF6\u4E0D\u5B58\u5728\u3002",
-      next: '\u521B\u5EFA\u8BE5\u6587\u4EF6\uFF1A\u4ECE <App /> \u901A\u8FC7\u771F\u5B9E DOM \u8F93\u5165\u4F9D\u6B21\u6267\u884C performInput("entry")\u3001checkpoint("entered")\u3001performInput("primary")\u3001stepUntil\u3001\u7528 playthroughTest \u63D0\u4F9B\u7684 expect \u65AD\u8A00\u7ED3\u679C\uFF0C\u5E76\u8BB0\u5F55 progress/terminal checkpoint\u3002Canvas \u7528\u771F\u5B9E DOM \u4E8B\u4EF6\u8F93\u5165\u5E76\u8BFB\u53D6 Telemetry snapshot\u3002',
+      next: '\u521B\u5EFA\u8BE5\u6587\u4EF6\uFF1A\u4ECE <App /> \u901A\u8FC7\u771F\u5B9E DOM \u8F93\u5165\u4F9D\u6B21\u6267\u884C performInput("entry")\u3001checkpoint("entered")\u3001performInput("primary")\u3001stepUntil\u3001\u7528 playthroughTest \u63D0\u4F9B\u7684 expect \u65AD\u8A00\u6743\u5A01\u7ED3\u679C\uFF0C\u5E76\u8BB0\u5F55 checkpoint("progress") \u6216 checkpoint("terminal")\u3002\u6BCF\u6761\u4E3B\u6D41\u7A0B\u81F3\u5C11\u9700\u8981\u8FD9\u4E24\u6B21 checkpoint \u7B7E\u5230\u3002',
       failsRun: true
     };
   }
@@ -400,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\uFF1AperformInput("entry") \u540E\u8BB0\u5F55 entered snapshot\uFF1B\u518D\u7528 performInput("primary") \u6267\u884C\u6838\u5FC3\u64CD\u4F5C\uFF0CstepUntil \u7B49\u5F85\u53D8\u5316\uFF0C\u65AD\u8A00\u540E\u8BB0\u5F55 progress \u6216 terminal snapshot\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\u771F\u5B9E\u72B6\u6001\u7684\u53EA\u8BFB snapshot\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
     };
   }
@@ -470,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")}`);
   }
 };
 
@@ -518,6 +570,7 @@ function defineReactGameVitestConfig(options) {
       environmentOptions: {
         jsdom: { url: "http://localhost/", pretendToBeVisual: true }
       },
+      includeTaskLocation: true,
       setupFiles: [
         "miaoda-game-devkit/react/vitest-setup",
         ...options.additionalSetupFiles ?? []
@@ -525,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";
@@ -67,20 +68,25 @@ var INPUT_EVENTS = [
   "touchstart",
   "touchend"
 ];
+var MIN_CHECKPOINTS = 2;
 function describeMissingEvidence(evidence) {
   if (!evidence || evidence.entryInputs === 0) return "entry \u8F93\u5165";
   if (evidence.primaryInputs === 0) return "primary \u8F93\u5165";
   if (!evidence.checkpoints.includes("entered")) return "entered checkpoint";
   if (evidence.boundedRuns === 0) return "\u6709\u754C stepUntil";
   if (evidence.assertionsAfterOutcome === 0) return "stepUntil \u540E\u7684\u7ED3\u679C\u65AD\u8A00";
-  if (evidence.changedOutcomeCheckpoints === 0) {
-    return "\u53D1\u751F\u72B6\u6001\u53D8\u5316\u7684 progress/terminal checkpoint";
+  if (evidence.checkpoints.length < MIN_CHECKPOINTS)
+    return `\u81F3\u5C11 ${MIN_CHECKPOINTS} \u4E2A checkpoint`;
+  if (!evidence.checkpoints.some(
+    (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
+  )) {
+    return "progress/terminal checkpoint";
   }
   return "\u5B8C\u6574\u7684 playthrough \u6821\u9A8C\u6807\u8BB0";
 }
 function createMetadata(waiverReason) {
   return {
-    version: 2,
+    version: 3,
     waiverReason,
     evidence: {
       domInputEvents: 0,
@@ -88,23 +94,11 @@ function createMetadata(waiverReason) {
       primaryInputs: 0,
       boundedRuns: 0,
       assertionsAfterOutcome: 0,
-      changedOutcomeCheckpoints: 0,
       checkpoints: [],
       verified: false
     }
   };
 }
-function snapshotFingerprint(snapshot) {
-  try {
-    const serialized = JSON.stringify(snapshot);
-    if (serialized === void 0) throw new Error("unsupported value");
-    return serialized;
-  } catch {
-    throw new Error(
-      "checkpoint snapshot must be JSON-serializable. Pass a read-only Telemetry snapshot or a small visible-state object."
-    );
-  }
-}
 function definePlaythrough(element, run, waiverReason) {
   const reason = normalizePlaythroughWaiverReason(waiverReason);
   const metadata = createMetadata(reason);
@@ -114,7 +108,8 @@ function definePlaythrough(element, run, waiverReason) {
   }, async ({ expect }) => {
     const evidence = metadata.evidence;
     let assertionsAtOutcome;
-    let enteredSnapshot;
+    let enteredRecorded = false;
+    let domTextAtEntered;
     const recordInput = () => {
       evidence.domInputEvents += 1;
     };
@@ -134,14 +129,14 @@ function definePlaythrough(element, run, waiverReason) {
         user,
         expect,
         async performInput(kind, input) {
-          if (kind === "entry" && enteredSnapshot !== void 0) {
+          if (kind === "entry" && enteredRecorded) {
             throw new Error(
               'performInput("entry") must run before checkpoint("entered"). Group multiple setup actions in the same callback.'
             );
           }
-          if (kind === "primary" && enteredSnapshot === void 0) {
+          if (kind === "primary" && !enteredRecorded) {
             throw new Error(
-              'Before performInput("primary"), run an entry input and checkpoint("entered", snapshot).'
+              'Before performInput("primary"), run an entry input and checkpoint("entered").'
             );
           }
           const inputsBefore = evidence.domInputEvents;
@@ -154,10 +149,9 @@ function definePlaythrough(element, run, waiverReason) {
           if (kind === "entry") evidence.entryInputs += 1;
           else evidence.primaryInputs += 1;
         },
-        checkpoint(kind, snapshot) {
-          const fingerprint = snapshotFingerprint(snapshot);
+        checkpoint(kind) {
           if (kind === "entered") {
-            if (enteredSnapshot !== void 0) {
+            if (enteredRecorded) {
               throw new Error(
                 'checkpoint("entered") may only be recorded once, before the primary input.'
               );
@@ -167,7 +161,8 @@ function definePlaythrough(element, run, waiverReason) {
                 'checkpoint("entered") must follow performInput("entry", ...).'
               );
             }
-            enteredSnapshot = fingerprint;
+            enteredRecorded = true;
+            domTextAtEntered = document.body.textContent ?? "";
             evidence.checkpoints.push(kind);
             return;
           }
@@ -183,15 +178,9 @@ function definePlaythrough(element, run, waiverReason) {
           }
           if (assertionsAtOutcome === void 0 || expect.getState().assertionCalls <= assertionsAtOutcome) {
             throw new Error(
-              `Use the expect provided by playthroughTest to assert the authoritative result after stepUntil, then record checkpoint("${kind}", snapshot).`
+              `Use the expect provided by playthroughTest to assert the authoritative result after stepUntil, then record checkpoint("${kind}").`
             );
           }
-          if (fingerprint === enteredSnapshot) {
-            throw new Error(
-              `checkpoint("${kind}") matches the entered snapshot. Assert a production state change caused by the primary input.`
-            );
-          }
-          evidence.changedOutcomeCheckpoints += 1;
           evidence.checkpoints.push(kind);
         },
         async stepUntil(condition, options = {}) {
@@ -201,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;
@@ -226,9 +220,11 @@ function definePlaythrough(element, run, waiverReason) {
           "Use the expect provided by playthroughTest to assert an authoritative game outcome after stepUntil returns."
         );
       }
-      if (evidence.changedOutcomeCheckpoints === 0) {
+      if (evidence.checkpoints.length < MIN_CHECKPOINTS || !evidence.checkpoints.some(
+        (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
+      )) {
         throw new Error(
-          'After asserting the result, record checkpoint("progress", snapshot) or checkpoint("terminal", snapshot). The snapshot must differ from checkpoint("entered").'
+          `playthroughTest requires at least ${MIN_CHECKPOINTS} checkpoints: checkpoint("entered") and, after asserting the result, checkpoint("progress") or checkpoint("terminal").`
         );
       }
       evidence.verified = true;
@@ -249,7 +245,7 @@ function auditReactPlaythroughRun(tests) {
   const declared = tests.filter((candidate) => candidate.metadata);
   const valid = declared.filter(({ state, metadata }) => {
     const evidence = metadata?.evidence;
-    return state === "passed" && evidence?.verified === true && evidence.domInputEvents > 0 && evidence.entryInputs > 0 && evidence.primaryInputs > 0 && evidence.boundedRuns > 0 && evidence.assertionsAfterOutcome > 0 && evidence.changedOutcomeCheckpoints > 0 && evidence.checkpoints.includes("entered") && evidence.checkpoints.some(
+    return state === "passed" && evidence?.verified === true && evidence.domInputEvents > 0 && evidence.entryInputs > 0 && evidence.primaryInputs > 0 && evidence.boundedRuns > 0 && evidence.assertionsAfterOutcome > 0 && evidence.checkpoints.length >= MIN_CHECKPOINTS && evidence.checkpoints.includes("entered") && evidence.checkpoints.some(
       (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
     );
   });
@@ -259,7 +255,7 @@ function auditReactPlaythroughRun(tests) {
   const issues = [];
   if (declared.length === 0) {
     issues.push(
-      '\u7F3A\u5C11\u751F\u4EA7\u6E38\u620F\u53EF\u73A9\u6027\u9A8C\u8BC1\uFF1A\u4F7F\u7528 playthroughTest \u6E32\u67D3 <App />\uFF0C\u4F9D\u6B21\u6267\u884C performInput("entry")\u3001checkpoint("entered")\u3001performInput("primary")\u3001stepUntil\u3001\u7528 playthroughTest \u63D0\u4F9B\u7684 expect \u65AD\u8A00\u7ED3\u679C\uFF0C\u5E76\u8BB0\u5F55 progress/terminal checkpoint\u3002'
+      '\u7F3A\u5C11\u751F\u4EA7\u6E38\u620F\u53EF\u73A9\u6027\u9A8C\u8BC1\uFF1A\u4F7F\u7528 playthroughTest \u6E32\u67D3 <App />\uFF0C\u4F9D\u6B21\u6267\u884C performInput("entry")\u3001checkpoint("entered")\u3001performInput("primary")\u3001stepUntil\u3001\u7528 playthroughTest \u63D0\u4F9B\u7684 expect \u65AD\u8A00\u6743\u5A01\u7ED3\u679C\uFF0C\u5E76\u8BB0\u5F55 checkpoint("progress") \u6216 checkpoint("terminal")\uFF1B\u81F3\u5C11\u5B8C\u6210\u8FD9\u4E24\u6B21 checkpoint \u7B7E\u5230\u3002'
     );
   } else {
     for (const candidate of declared) {
@@ -289,7 +285,7 @@ var PRODUCTION_PLAYTHROUGH_FILE = "tests/production-playthrough.test.tsx";
 function isMetadata(value) {
   if (!value || typeof value !== "object") return false;
   const metadata = value;
-  return metadata.version === 2 && Boolean(metadata.evidence);
+  return metadata.version === 3 && Boolean(metadata.evidence);
 }
 function toAuditInput(test2) {
   const metadata = test2.meta().reactPlaythrough;
@@ -301,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()];
@@ -311,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) {
@@ -333,7 +375,7 @@ function assessReactPlaythroughReport(input) {
       ...base,
       status: "FAILED",
       cause: "\u751F\u4EA7\u53EF\u73A9\u6027\u6D4B\u8BD5\u6587\u4EF6\u4E0D\u5B58\u5728\u3002",
-      next: '\u521B\u5EFA\u8BE5\u6587\u4EF6\uFF1A\u4ECE <App /> \u901A\u8FC7\u771F\u5B9E DOM \u8F93\u5165\u4F9D\u6B21\u6267\u884C performInput("entry")\u3001checkpoint("entered")\u3001performInput("primary")\u3001stepUntil\u3001\u7528 playthroughTest \u63D0\u4F9B\u7684 expect \u65AD\u8A00\u7ED3\u679C\uFF0C\u5E76\u8BB0\u5F55 progress/terminal checkpoint\u3002Canvas \u7528\u771F\u5B9E DOM \u4E8B\u4EF6\u8F93\u5165\u5E76\u8BFB\u53D6 Telemetry snapshot\u3002',
+      next: '\u521B\u5EFA\u8BE5\u6587\u4EF6\uFF1A\u4ECE <App /> \u901A\u8FC7\u771F\u5B9E DOM \u8F93\u5165\u4F9D\u6B21\u6267\u884C performInput("entry")\u3001checkpoint("entered")\u3001performInput("primary")\u3001stepUntil\u3001\u7528 playthroughTest \u63D0\u4F9B\u7684 expect \u65AD\u8A00\u6743\u5A01\u7ED3\u679C\uFF0C\u5E76\u8BB0\u5F55 checkpoint("progress") \u6216 checkpoint("terminal")\u3002\u6BCF\u6761\u4E3B\u6D41\u7A0B\u81F3\u5C11\u9700\u8981\u8FD9\u4E24\u6B21 checkpoint \u7B7E\u5230\u3002',
       failsRun: true
     };
   }
@@ -366,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\uFF1AperformInput("entry") \u540E\u8BB0\u5F55 entered snapshot\uFF1B\u518D\u7528 performInput("primary") \u6267\u884C\u6838\u5FC3\u64CD\u4F5C\uFF0CstepUntil \u7B49\u5F85\u53D8\u5316\uFF0C\u65AD\u8A00\u540E\u8BB0\u5F55 progress \u6216 terminal snapshot\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\u771F\u5B9E\u72B6\u6001\u7684\u53EA\u8BFB snapshot\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
     };
   }
@@ -436,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")}`);
   }
 };
 
@@ -484,6 +536,7 @@ function defineReactGameVitestConfig(options) {
       environmentOptions: {
         jsdom: { url: "http://localhost/", pretendToBeVisual: true }
       },
+      includeTaskLocation: true,
       setupFiles: [
         "miaoda-game-devkit/react/vitest-setup",
         ...options.additionalSetupFiles ?? []
@@ -491,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.20",
+  "version": "0.3.0",
   "description": "Shared React and Phaser game lint plus deterministic testing tools for Miaoda games",
   "license": "MIT",
   "main": "./dist/index.js",