miaoda-game-devkit 0.2.16 → 0.2.19

package/dist/react/vitest-config.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-vitest-config.ts
@@ -33,10 +43,21 @@ var import_node_path = require("path");
 
 // 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();
@@ -62,8 +83,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}`
   );
 }
 
@@ -77,27 +101,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;
     };
@@ -111,25 +162,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) {
@@ -137,7 +257,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;
@@ -158,7 +283,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
@@ -166,7 +293,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) {
@@ -180,9 +307,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`);
       }
     }
   }
@@ -197,7 +323,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 === 1 && Boolean(metadata.evidence);
+  return metadata.version === 2 && Boolean(metadata.evidence);
 }
 function toAuditInput(test2) {
   const metadata = test2.meta().reactPlaythrough;
@@ -241,7 +367,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 /> \u89E6\u53D1\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\u518D\u65AD\u8A00\u7ED3\u679C\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',
       failsRun: true
     };
   }
@@ -273,11 +399,13 @@ function assessReactPlaythroughReport(input) {
   if (!audit.passed) {
     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 missingStructuredEvidence = /performInput|checkpoint/.test(cause);
     return {
       ...base,
       status: "FAILED",
       cause,
-      next: 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\u70B9\u51FB\u6216\u6309\u952E\u662F\u5426\u771F\u7684\u8C03\u7528\u6E38\u620F\u7684\u751F\u4EA7\u63A7\u5236\u65B9\u6CD5\uFF0C\u4EE5\u53CA\u6E38\u620F\u771F\u5B9E\u72B6\u6001\u662F\u5426\u5230\u8FBE\u5E76\u663E\u793A\u7ED3\u679C\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: 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",
       failsRun: true
     };
   }

package/dist/react/vitest-config.mjs

@@ -9,10 +9,21 @@ import { relative, resolve } from "path";
 
 // 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();
@@ -38,8 +49,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}`
   );
 }
 
@@ -53,27 +67,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;
     };
@@ -87,13 +128,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;
@@ -103,9 +208,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) {
@@ -113,7 +223,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;
@@ -134,7 +249,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
@@ -142,7 +259,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) {
@@ -156,9 +273,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`);
       }
     }
   }
@@ -173,7 +289,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 === 1 && Boolean(metadata.evidence);
+  return metadata.version === 2 && Boolean(metadata.evidence);
 }
 function toAuditInput(test2) {
   const metadata = test2.meta().reactPlaythrough;
@@ -217,7 +333,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 /> \u89E6\u53D1\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\u518D\u65AD\u8A00\u7ED3\u679C\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',
       failsRun: true
     };
   }
@@ -249,11 +365,13 @@ function assessReactPlaythroughReport(input) {
   if (!audit.passed) {
     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 missingStructuredEvidence = /performInput|checkpoint/.test(cause);
     return {
       ...base,
       status: "FAILED",
       cause,
-      next: 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\u70B9\u51FB\u6216\u6309\u952E\u662F\u5426\u771F\u7684\u8C03\u7528\u6E38\u620F\u7684\u751F\u4EA7\u63A7\u5236\u65B9\u6CD5\uFF0C\u4EE5\u53CA\u6E38\u620F\u771F\u5B9E\u72B6\u6001\u662F\u5426\u5230\u8FBE\u5E76\u663E\u793A\u7ED3\u679C\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: 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",
       failsRun: true
     };
   }

package/dist/vitest-config.d.mts

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

package/dist/vitest-config.d.ts

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

package/dist/vitest-config.js

@@ -275,14 +275,14 @@ function auditGameplayCollection(options, file, tests) {
 function getGameplayEvidenceIssues(id, requirements, evidence) {
   const issues = [];
   const inputEvents = evidence.mouseEvents + evidence.keyboardEvents + evidence.touchEvents;
-  if (requirements.requireInput && inputEvents === 0) {
-    issues.push(`contract "${id}" \u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165\u3002`);
+  if (requirements.requireInput && (inputEvents === 0 || evidence.consumedInputEvents === 0)) {
+    issues.push(`contract "${id}" \u672A\u8BB0\u5F55\u88AB Phaser InputPlugin \u6D88\u8D39\u7684 DOM \u8F93\u5165\u3002`);
   }
-  if (requirements.requireFrameAdvance && evidence.frames === 0) {
-    issues.push(`contract "${id}" \u672A\u63A8\u8FDB\u5B8C\u6574 Phaser \u5E27\u3002`);
+  if (requirements.requireFrameAdvance && (evidence.frames === 0 || evidence.observedFrames === 0)) {
+    issues.push(`contract "${id}" \u672A\u8BB0\u5F55\u7531\u6D3B\u52A8 Scene \u5B9E\u9645\u6267\u884C\u7684\u5B8C\u6574 Phaser \u5E27\u3002`);
   }
-  if (requirements.requirePhysicsStep && evidence.physicsSteps === 0) {
-    issues.push(`contract "${id}" \u672A\u63A8\u8FDB Arcade Physics\u3002`);
+  if (requirements.requirePhysicsStep && (evidence.physicsSteps === 0 || evidence.observedPhysicsSteps === 0)) {
+    issues.push(`contract "${id}" \u672A\u8BB0\u5F55 Arcade WORLD_STEP\u3002`);
   }
   for (const target of normalizeList(requirements.requireTransition)) {
     if (!evidence.transitions.some((transition) => transition.to === target)) {
@@ -455,9 +455,9 @@ function formatGameplayIssues(issues) {
     unhandled: "\u5F02\u6B65\u9519\u8BEF\uFF1A\u5148\u4FEE\u590D\u4E0A\u65B9\u663E\u793A\u7684\u7B2C\u4E00\u6761\u9519\u8BEF\uFF1B\u8F93\u5165\u3001\u5E27\u63A8\u8FDB\u548C\u751F\u547D\u5468\u671F\u64CD\u4F5C\u90FD\u8981\u5728\u6B63\u786E\u7684 host \u751F\u547D\u5468\u671F\u5185\u5E76\u4F7F\u7528 await\u3002"
   };
   const getCategory = (issue) => {
-    if (issue.includes("\u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165")) return { category: "input", key: "input" };
-    if (issue.includes("\u672A\u63A8\u8FDB\u5B8C\u6574 Phaser \u5E27")) return { category: "frames", key: "frames" };
-    if (issue.includes("\u672A\u63A8\u8FDB Arcade Physics")) return { category: "physics", key: "physics" };
+    if (issue.includes("\u672A\u8BB0\u5F55\u771F\u5B9E DOM \u8F93\u5165") || issue.includes("Phaser InputPlugin \u6D88\u8D39\u7684 DOM \u8F93\u5165")) return { category: "input", key: "input" };
+    if (issue.includes("\u672A\u63A8\u8FDB\u5B8C\u6574 Phaser \u5E27") || issue.includes("\u6D3B\u52A8 Scene \u5B9E\u9645\u6267\u884C\u7684\u5B8C\u6574 Phaser \u5E27")) return { category: "frames", key: "frames" };
+    if (issue.includes("\u672A\u63A8\u8FDB Arcade Physics") || issue.includes("\u672A\u8BB0\u5F55 Arcade WORLD_STEP")) return { category: "physics", key: "physics" };
     if (issue.includes("\u672A\u8BB0\u5F55\u5230 ") && issue.includes("Scene \u8F6C\u573A")) {
       const target = issue.match(/未记录到 (.+?) 的 Scene 转场/)?.[1] ?? "unknown";
       return { category: "transition", key: `transition:${target}` };