miaoda-game-devkit 0.2.16 → 0.2.19

package/dist/react/testing.d.mts

@@ -1,6 +1,8 @@
 import { G as GameClock, a as GameFrameCallback } from '../game-clock-suUidZdT.mjs';
 import { RenderResult } from '@testing-library/react';
+import { UserEvent } from '@testing-library/user-event';
 import { ReactNode } from 'react';
+import { ExpectStatic } from 'vitest';
 
 /** 测试用确定性时钟；应用测试推进它，不直接伪造游戏状态。 */
 declare class ManualGameClock implements GameClock {
@@ -26,36 +28,68 @@ interface StepUntilOptions {
     maxSteps?: number;
     /** 每轮推进一单位游戏自有时间或工作；即时回合制结果可以省略。 */
     step?: (step: number) => void | Promise<void>;
+    /**
+     * Optional read-only state used to make bounded failures actionable.
+     * The value is sampled only when the bound is exhausted.
+     */
+    diagnostics?: () => unknown;
 }
 
 /** 单条 React 主流程测试留下的可序列化运行期证据。 */
 interface ReactPlaythroughEvidence {
     /** 捕获阶段观察到的键盘、指针或触摸类 DOM 输入总数。 */
     domInputEvents: number;
+    /** 由 performInput 明确标记的入口输入次数。 */
+    entryInputs: number;
+    /** 由 performInput 明确标记的核心玩法输入次数。 */
+    primaryInputs: number;
     /** 在步数上限内成功满足条件的 stepUntil 次数。 */
     boundedRuns: number;
     /** 最后一次 stepUntil 成功后新增的 Vitest 断言数。 */
     assertionsAfterOutcome: number;
+    /** 已验证相对 entered snapshot 发生变化的进展或终局 checkpoint 次数。 */
+    changedOutcomeCheckpoints: number;
+    /** 已记录的 checkpoint 类型，供 reporter 给出精确提示。 */
+    checkpoints: ReactPlaythroughCheckpointKind[];
     /** helper 是否已经完成全部证据校验。 */
     verified: boolean;
 }
 /** 通过 Vitest task metadata 从 worker 传递给主线程 reporter 的数据。 */
 interface ReactPlaythroughMetadata {
     /** metadata 结构版本，用于拒绝无法识别的旧数据。 */
-    version: 1;
+    version: 2;
     /** 静态、非交互项目跳过主流程验证时必须提供的理由。 */
     waiverReason?: string;
     /** 测试执行期间持续更新的客观证据。 */
     evidence: ReactPlaythroughEvidence;
 }
 
+/** 玩家输入在最低可玩流程中的语义阶段。 */
+type ReactPlaythroughInputKind = "entry" | "primary";
+/** 可审计状态证据；entered 是基线，progress/terminal 是有效结果。 */
+type ReactPlaythroughCheckpointKind = "entered" | "progress" | "terminal";
 /** 主流程回调唯一需要学习的测试工具。 */
 interface ReactPlaythroughArguments {
     /** Testing Library 对生产游戏入口的渲染结果。 */
     view: RenderResult;
+    /** 已由 playthroughTest 创建的真实 DOM 用户输入驱动。 */
+    user: UserEvent;
+    /** Vitest 绑定到当前 test 的断言 API；结果断言必须使用这个实例。 */
+    expect: ExpectStatic;
+    /**
+     * 包裹一段真实 DOM 输入并声明用途。
+     * entry 用于进入合法游戏状态，primary 用于移动、挥拍、拖拽、落子等核心操作。
+     */
+    performInput(kind: ReactPlaythroughInputKind, input: () => void | Promise<void>): Promise<void>;
+    /**
+     * 记录只读状态证据。先在 entry 后记录 entered，再在 primary 和 stepUntil
+     * 后记录 progress 或 terminal；Canvas 游戏应传 Telemetry snapshot。
+     */
+    checkpoint(kind: ReactPlaythroughCheckpointKind, snapshot: unknown): void;
     /**
      * 在硬性步数上限内等待权威结果。
      * 返回后必须再断言该结果，进入中间 active/running 状态不算完成。
+     * 即时结果不需要 step；时间、帧或自定义 scheduler 流程必须传入确定性 step。
      */
     stepUntil(condition: () => boolean, options?: StepUntilOptions): Promise<number>;
 }
@@ -102,4 +136,4 @@ declare module "vitest" {
     }
 }
 
-export { ManualGameClock, type ReactPlaythroughArguments, type ReactPlaythroughAuditInput, type ReactPlaythroughAuditResult, type ReactPlaythroughEvidence, type ReactPlaythroughMetadata, type ReactPlaythroughTest, type StepUntilOptions, auditReactPlaythroughRun, playthroughTest };
+export { ManualGameClock, type ReactPlaythroughArguments, type ReactPlaythroughAuditInput, type ReactPlaythroughAuditResult, type ReactPlaythroughCheckpointKind, type ReactPlaythroughEvidence, type ReactPlaythroughInputKind, type ReactPlaythroughMetadata, type ReactPlaythroughTest, type StepUntilOptions, auditReactPlaythroughRun, playthroughTest };

package/dist/react/testing.d.ts

@@ -1,6 +1,8 @@
 import { G as GameClock, a as GameFrameCallback } from '../game-clock-suUidZdT.js';
 import { RenderResult } from '@testing-library/react';
+import { UserEvent } from '@testing-library/user-event';
 import { ReactNode } from 'react';
+import { ExpectStatic } from 'vitest';
 
 /** 测试用确定性时钟；应用测试推进它，不直接伪造游戏状态。 */
 declare class ManualGameClock implements GameClock {
@@ -26,36 +28,68 @@ interface StepUntilOptions {
     maxSteps?: number;
     /** 每轮推进一单位游戏自有时间或工作；即时回合制结果可以省略。 */
     step?: (step: number) => void | Promise<void>;
+    /**
+     * Optional read-only state used to make bounded failures actionable.
+     * The value is sampled only when the bound is exhausted.
+     */
+    diagnostics?: () => unknown;
 }
 
 /** 单条 React 主流程测试留下的可序列化运行期证据。 */
 interface ReactPlaythroughEvidence {
     /** 捕获阶段观察到的键盘、指针或触摸类 DOM 输入总数。 */
     domInputEvents: number;
+    /** 由 performInput 明确标记的入口输入次数。 */
+    entryInputs: number;
+    /** 由 performInput 明确标记的核心玩法输入次数。 */
+    primaryInputs: number;
     /** 在步数上限内成功满足条件的 stepUntil 次数。 */
     boundedRuns: number;
     /** 最后一次 stepUntil 成功后新增的 Vitest 断言数。 */
     assertionsAfterOutcome: number;
+    /** 已验证相对 entered snapshot 发生变化的进展或终局 checkpoint 次数。 */
+    changedOutcomeCheckpoints: number;
+    /** 已记录的 checkpoint 类型，供 reporter 给出精确提示。 */
+    checkpoints: ReactPlaythroughCheckpointKind[];
     /** helper 是否已经完成全部证据校验。 */
     verified: boolean;
 }
 /** 通过 Vitest task metadata 从 worker 传递给主线程 reporter 的数据。 */
 interface ReactPlaythroughMetadata {
     /** metadata 结构版本，用于拒绝无法识别的旧数据。 */
-    version: 1;
+    version: 2;
     /** 静态、非交互项目跳过主流程验证时必须提供的理由。 */
     waiverReason?: string;
     /** 测试执行期间持续更新的客观证据。 */
     evidence: ReactPlaythroughEvidence;
 }
 
+/** 玩家输入在最低可玩流程中的语义阶段。 */
+type ReactPlaythroughInputKind = "entry" | "primary";
+/** 可审计状态证据；entered 是基线，progress/terminal 是有效结果。 */
+type ReactPlaythroughCheckpointKind = "entered" | "progress" | "terminal";
 /** 主流程回调唯一需要学习的测试工具。 */
 interface ReactPlaythroughArguments {
     /** Testing Library 对生产游戏入口的渲染结果。 */
     view: RenderResult;
+    /** 已由 playthroughTest 创建的真实 DOM 用户输入驱动。 */
+    user: UserEvent;
+    /** Vitest 绑定到当前 test 的断言 API；结果断言必须使用这个实例。 */
+    expect: ExpectStatic;
+    /**
+     * 包裹一段真实 DOM 输入并声明用途。
+     * entry 用于进入合法游戏状态，primary 用于移动、挥拍、拖拽、落子等核心操作。
+     */
+    performInput(kind: ReactPlaythroughInputKind, input: () => void | Promise<void>): Promise<void>;
+    /**
+     * 记录只读状态证据。先在 entry 后记录 entered，再在 primary 和 stepUntil
+     * 后记录 progress 或 terminal；Canvas 游戏应传 Telemetry snapshot。
+     */
+    checkpoint(kind: ReactPlaythroughCheckpointKind, snapshot: unknown): void;
     /**
      * 在硬性步数上限内等待权威结果。
      * 返回后必须再断言该结果，进入中间 active/running 状态不算完成。
+     * 即时结果不需要 step；时间、帧或自定义 scheduler 流程必须传入确定性 step。
      */
     stepUntil(condition: () => boolean, options?: StepUntilOptions): Promise<number>;
 }
@@ -102,4 +136,4 @@ declare module "vitest" {
     }
 }
 
-export { ManualGameClock, type ReactPlaythroughArguments, type ReactPlaythroughAuditInput, type ReactPlaythroughAuditResult, type ReactPlaythroughEvidence, type ReactPlaythroughMetadata, type ReactPlaythroughTest, type StepUntilOptions, auditReactPlaythroughRun, playthroughTest };
+export { ManualGameClock, type ReactPlaythroughArguments, type ReactPlaythroughAuditInput, type ReactPlaythroughAuditResult, type ReactPlaythroughCheckpointKind, type ReactPlaythroughEvidence, type ReactPlaythroughInputKind, type ReactPlaythroughMetadata, type ReactPlaythroughTest, type StepUntilOptions, auditReactPlaythroughRun, playthroughTest };

package/dist/react/testing.js

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/react/testing.ts
@@ -83,10 +93,21 @@ var ManualGameClock = class {
 
 // src/react/react-playthrough.ts
 var import_react2 = require("@testing-library/react");
+var import_user_event = __toESM(require("@testing-library/user-event"));
 var import_vitest = require("vitest");
 
 // src/react/react-playthrough-core.ts
 var import_react = require("@testing-library/react");
+function formatDiagnostics(read) {
+  if (!read) return void 0;
+  try {
+    const value = read();
+    if (typeof value === "string") return value;
+    return JSON.stringify(value);
+  } catch (error) {
+    return `diagnostics() threw: ${String(error)}`;
+  }
+}
 function normalizePlaythroughWaiverReason(waiverReason) {
   if (waiverReason === void 0) return void 0;
   const reason = waiverReason.trim();
@@ -112,8 +133,11 @@ async function runBoundedUntil(condition, options = {}) {
       });
     }
   }
+  const diagnostics = formatDiagnostics(options.diagnostics);
+  const guidance = options.step ? "The step callback ran, but the authoritative outcome did not change." : "No step callback was provided, so time-driven gameplay was not advanced. Inject a ManualGameClock for this test and pass step: () => clock.stepFrame().";
+  const suffix = diagnostics ? ` Last diagnostics: ${diagnostics}` : "";
   throw new Error(
-    `Playthrough outcome was not reached within ${maxSteps} steps.`
+    `Playthrough outcome was not reached within ${maxSteps} steps. ${guidance}${suffix}`
   );
 }
 
@@ -127,27 +151,54 @@ var INPUT_EVENTS = [
   "touchstart",
   "touchend"
 ];
+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";
+  }
+  return "\u5B8C\u6574\u7684 playthrough \u6821\u9A8C\u6807\u8BB0";
+}
 function createMetadata(waiverReason) {
   return {
-    version: 1,
+    version: 2,
     waiverReason,
     evidence: {
       domInputEvents: 0,
+      entryInputs: 0,
+      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);
   (0, import_vitest.test)("production game completes a bounded playthrough", {
     skip: Boolean(reason),
     meta: { reactPlaythrough: metadata }
-  }, async () => {
+  }, async ({ expect }) => {
     const evidence = metadata.evidence;
     let assertionsAtOutcome;
+    let enteredSnapshot;
     const recordInput = () => {
       evidence.domInputEvents += 1;
     };
@@ -161,25 +212,94 @@ function definePlaythrough(element, run, waiverReason) {
           "playthroughTest must render the production game entry."
         );
       }
+      const user = import_user_event.default.setup();
       await run({
         view,
+        user,
+        expect,
+        async performInput(kind, input) {
+          if (kind === "entry" && enteredSnapshot !== void 0) {
+            throw new Error(
+              'performInput("entry") must run before checkpoint("entered"). Group multiple setup actions in the same callback.'
+            );
+          }
+          if (kind === "primary" && enteredSnapshot === void 0) {
+            throw new Error(
+              'Before performInput("primary"), run an entry input and checkpoint("entered", snapshot).'
+            );
+          }
+          const inputsBefore = evidence.domInputEvents;
+          await input();
+          if (evidence.domInputEvents === inputsBefore) {
+            throw new Error(
+              `performInput("${kind}") did not dispatch a supported production DOM input. Use the provided user or dispatch a real keyboard, pointer, or touch event to the production target.`
+            );
+          }
+          if (kind === "entry") evidence.entryInputs += 1;
+          else evidence.primaryInputs += 1;
+        },
+        checkpoint(kind, snapshot) {
+          const fingerprint = snapshotFingerprint(snapshot);
+          if (kind === "entered") {
+            if (enteredSnapshot !== void 0) {
+              throw new Error(
+                'checkpoint("entered") may only be recorded once, before the primary input.'
+              );
+            }
+            if (evidence.entryInputs === 0) {
+              throw new Error(
+                'checkpoint("entered") must follow performInput("entry", ...).'
+              );
+            }
+            enteredSnapshot = fingerprint;
+            evidence.checkpoints.push(kind);
+            return;
+          }
+          if (evidence.primaryInputs === 0) {
+            throw new Error(
+              `checkpoint("${kind}") must follow performInput("primary", ...).`
+            );
+          }
+          if (evidence.boundedRuns === 0) {
+            throw new Error(
+              `checkpoint("${kind}") must be recorded after stepUntil returns.`
+            );
+          }
+          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).`
+            );
+          }
+          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 = {}) {
           const steps = await runBoundedUntil(condition, options);
-          if (evidence.domInputEvents === 0) {
+          if (evidence.primaryInputs === 0) {
             throw new Error(
-              "stepUntil reached an outcome before any production DOM input."
+              'stepUntil must follow performInput("primary", ...). A menu/help click is not gameplay evidence.'
             );
           }
           evidence.boundedRuns += 1;
-          assertionsAtOutcome = import_vitest.expect.getState().assertionCalls;
+          assertionsAtOutcome = expect.getState().assertionCalls;
           return steps;
         }
       });
-      const assertionCalls = import_vitest.expect.getState().assertionCalls;
+      const assertionCalls = expect.getState().assertionCalls;
       evidence.assertionsAfterOutcome = assertionsAtOutcome === void 0 ? 0 : assertionCalls - assertionsAtOutcome;
-      if (evidence.domInputEvents === 0) {
+      if (evidence.entryInputs === 0) {
         throw new Error(
-          "playthroughTest did not observe production DOM input."
+          'playthroughTest must perform an entry input with performInput("entry", ...).'
+        );
+      }
+      if (evidence.primaryInputs === 0) {
+        throw new Error(
+          'playthroughTest must perform a core game action with performInput("primary", ...).'
         );
       }
       if (evidence.boundedRuns === 0) {
@@ -187,7 +307,12 @@ function definePlaythrough(element, run, waiverReason) {
       }
       if (evidence.assertionsAfterOutcome === 0) {
         throw new Error(
-          "Assert an authoritative game outcome after stepUntil returns."
+          "Use the expect provided by playthroughTest to assert an authoritative game outcome after stepUntil returns."
+        );
+      }
+      if (evidence.changedOutcomeCheckpoints === 0) {
+        throw new Error(
+          'After asserting the result, record checkpoint("progress", snapshot) or checkpoint("terminal", snapshot). The snapshot must differ from checkpoint("entered").'
         );
       }
       evidence.verified = true;
@@ -208,7 +333,9 @@ 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.boundedRuns > 0 && evidence.assertionsAfterOutcome > 0;
+    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(
+      (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
+    );
   });
   const waivers = declared.filter(
     ({ state, metadata }) => state === "skipped" && (metadata?.waiverReason?.trim().length ?? 0) >= 20
@@ -216,7 +343,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\u901A\u8FC7\u771F\u5B9E DOM \u8F93\u5165\u5B8C\u6210\u4E00\u4E2A\u6709\u6B65\u6570\u4E0A\u9650\u7684\u5173\u952E\u6D41\u7A0B\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\u7ED3\u679C\uFF0C\u5E76\u8BB0\u5F55 progress/terminal checkpoint\u3002'
     );
   } else {
     for (const candidate of declared) {
@@ -230,9 +357,8 @@ function auditReactPlaythroughRun(tests) {
       } else if (candidate.state !== "passed") {
         issues.push(`\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u7684\u72B6\u6001\u4E3A ${candidate.state}\u3002`);
       } else {
-        issues.push(
-          `\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u6CA1\u6709\u7559\u4E0B\u5B8C\u6574\u7684\u8F93\u5165\u3001\u6709\u9650\u63A8\u8FDB\u548C\u7ED3\u679C\u65AD\u8A00\u8BC1\u636E\u3002`
-        );
+        const missing = describeMissingEvidence(candidate.metadata?.evidence);
+        issues.push(`\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u7F3A\u5C11${missing}\u3002`);
       }
     }
   }

package/dist/react/testing.mjs

@@ -55,10 +55,21 @@ var ManualGameClock = class {
 
 // src/react/react-playthrough.ts
 import { render } from "@testing-library/react";
-import { expect, test } from "vitest";
+import userEvent from "@testing-library/user-event";
+import { test } from "vitest";
 
 // src/react/react-playthrough-core.ts
 import { act } from "@testing-library/react";
+function formatDiagnostics(read) {
+  if (!read) return void 0;
+  try {
+    const value = read();
+    if (typeof value === "string") return value;
+    return JSON.stringify(value);
+  } catch (error) {
+    return `diagnostics() threw: ${String(error)}`;
+  }
+}
 function normalizePlaythroughWaiverReason(waiverReason) {
   if (waiverReason === void 0) return void 0;
   const reason = waiverReason.trim();
@@ -84,8 +95,11 @@ async function runBoundedUntil(condition, options = {}) {
       });
     }
   }
+  const diagnostics = formatDiagnostics(options.diagnostics);
+  const guidance = options.step ? "The step callback ran, but the authoritative outcome did not change." : "No step callback was provided, so time-driven gameplay was not advanced. Inject a ManualGameClock for this test and pass step: () => clock.stepFrame().";
+  const suffix = diagnostics ? ` Last diagnostics: ${diagnostics}` : "";
   throw new Error(
-    `Playthrough outcome was not reached within ${maxSteps} steps.`
+    `Playthrough outcome was not reached within ${maxSteps} steps. ${guidance}${suffix}`
   );
 }
 
@@ -99,27 +113,54 @@ var INPUT_EVENTS = [
   "touchstart",
   "touchend"
 ];
+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";
+  }
+  return "\u5B8C\u6574\u7684 playthrough \u6821\u9A8C\u6807\u8BB0";
+}
 function createMetadata(waiverReason) {
   return {
-    version: 1,
+    version: 2,
     waiverReason,
     evidence: {
       domInputEvents: 0,
+      entryInputs: 0,
+      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);
   test("production game completes a bounded playthrough", {
     skip: Boolean(reason),
     meta: { reactPlaythrough: metadata }
-  }, async () => {
+  }, async ({ expect }) => {
     const evidence = metadata.evidence;
     let assertionsAtOutcome;
+    let enteredSnapshot;
     const recordInput = () => {
       evidence.domInputEvents += 1;
     };
@@ -133,13 +174,77 @@ function definePlaythrough(element, run, waiverReason) {
           "playthroughTest must render the production game entry."
         );
       }
+      const user = userEvent.setup();
       await run({
         view,
+        user,
+        expect,
+        async performInput(kind, input) {
+          if (kind === "entry" && enteredSnapshot !== void 0) {
+            throw new Error(
+              'performInput("entry") must run before checkpoint("entered"). Group multiple setup actions in the same callback.'
+            );
+          }
+          if (kind === "primary" && enteredSnapshot === void 0) {
+            throw new Error(
+              'Before performInput("primary"), run an entry input and checkpoint("entered", snapshot).'
+            );
+          }
+          const inputsBefore = evidence.domInputEvents;
+          await input();
+          if (evidence.domInputEvents === inputsBefore) {
+            throw new Error(
+              `performInput("${kind}") did not dispatch a supported production DOM input. Use the provided user or dispatch a real keyboard, pointer, or touch event to the production target.`
+            );
+          }
+          if (kind === "entry") evidence.entryInputs += 1;
+          else evidence.primaryInputs += 1;
+        },
+        checkpoint(kind, snapshot) {
+          const fingerprint = snapshotFingerprint(snapshot);
+          if (kind === "entered") {
+            if (enteredSnapshot !== void 0) {
+              throw new Error(
+                'checkpoint("entered") may only be recorded once, before the primary input.'
+              );
+            }
+            if (evidence.entryInputs === 0) {
+              throw new Error(
+                'checkpoint("entered") must follow performInput("entry", ...).'
+              );
+            }
+            enteredSnapshot = fingerprint;
+            evidence.checkpoints.push(kind);
+            return;
+          }
+          if (evidence.primaryInputs === 0) {
+            throw new Error(
+              `checkpoint("${kind}") must follow performInput("primary", ...).`
+            );
+          }
+          if (evidence.boundedRuns === 0) {
+            throw new Error(
+              `checkpoint("${kind}") must be recorded after stepUntil returns.`
+            );
+          }
+          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).`
+            );
+          }
+          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 = {}) {
           const steps = await runBoundedUntil(condition, options);
-          if (evidence.domInputEvents === 0) {
+          if (evidence.primaryInputs === 0) {
             throw new Error(
-              "stepUntil reached an outcome before any production DOM input."
+              'stepUntil must follow performInput("primary", ...). A menu/help click is not gameplay evidence.'
             );
           }
           evidence.boundedRuns += 1;
@@ -149,9 +254,14 @@ function definePlaythrough(element, run, waiverReason) {
       });
       const assertionCalls = expect.getState().assertionCalls;
       evidence.assertionsAfterOutcome = assertionsAtOutcome === void 0 ? 0 : assertionCalls - assertionsAtOutcome;
-      if (evidence.domInputEvents === 0) {
+      if (evidence.entryInputs === 0) {
         throw new Error(
-          "playthroughTest did not observe production DOM input."
+          'playthroughTest must perform an entry input with performInput("entry", ...).'
+        );
+      }
+      if (evidence.primaryInputs === 0) {
+        throw new Error(
+          'playthroughTest must perform a core game action with performInput("primary", ...).'
         );
       }
       if (evidence.boundedRuns === 0) {
@@ -159,7 +269,12 @@ function definePlaythrough(element, run, waiverReason) {
       }
       if (evidence.assertionsAfterOutcome === 0) {
         throw new Error(
-          "Assert an authoritative game outcome after stepUntil returns."
+          "Use the expect provided by playthroughTest to assert an authoritative game outcome after stepUntil returns."
+        );
+      }
+      if (evidence.changedOutcomeCheckpoints === 0) {
+        throw new Error(
+          'After asserting the result, record checkpoint("progress", snapshot) or checkpoint("terminal", snapshot). The snapshot must differ from checkpoint("entered").'
         );
       }
       evidence.verified = true;
@@ -180,7 +295,9 @@ 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.boundedRuns > 0 && evidence.assertionsAfterOutcome > 0;
+    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(
+      (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
+    );
   });
   const waivers = declared.filter(
     ({ state, metadata }) => state === "skipped" && (metadata?.waiverReason?.trim().length ?? 0) >= 20
@@ -188,7 +305,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\u901A\u8FC7\u771F\u5B9E DOM \u8F93\u5165\u5B8C\u6210\u4E00\u4E2A\u6709\u6B65\u6570\u4E0A\u9650\u7684\u5173\u952E\u6D41\u7A0B\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\u7ED3\u679C\uFF0C\u5E76\u8BB0\u5F55 progress/terminal checkpoint\u3002'
     );
   } else {
     for (const candidate of declared) {
@@ -202,9 +319,8 @@ function auditReactPlaythroughRun(tests) {
       } else if (candidate.state !== "passed") {
         issues.push(`\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u7684\u72B6\u6001\u4E3A ${candidate.state}\u3002`);
       } else {
-        issues.push(
-          `\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u6CA1\u6709\u7559\u4E0B\u5B8C\u6574\u7684\u8F93\u5165\u3001\u6709\u9650\u63A8\u8FDB\u548C\u7ED3\u679C\u65AD\u8A00\u8BC1\u636E\u3002`
-        );
+        const missing = describeMissingEvidence(candidate.metadata?.evidence);
+        issues.push(`\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u7F3A\u5C11${missing}\u3002`);
       }
     }
   }