miaoda-game-devkit 0.2.15 → 0.2.17

package/dist/react/testing.mjs

@@ -52,6 +52,185 @@ var ManualGameClock = class {
     return this.timers.size;
   }
 };
+
+// src/react/react-playthrough.ts
+import { render } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { expect, 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();
+  if (reason.length < 20) {
+    throw new Error(
+      "playthroughTest.skip reason must contain at least 20 characters."
+    );
+  }
+  return reason;
+}
+async function runBoundedUntil(condition, options = {}) {
+  const maxSteps = options.maxSteps ?? 120;
+  if (!Number.isSafeInteger(maxSteps) || maxSteps < 0 || maxSteps > 1e4) {
+    throw new RangeError(
+      "stepUntil maxSteps must be a safe integer between 0 and 10000."
+    );
+  }
+  for (let step = 0; step <= maxSteps; step += 1) {
+    if (condition()) return step;
+    if (step < maxSteps) {
+      await act(async () => {
+        await options.step?.(step + 1);
+      });
+    }
+  }
+  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. ${guidance}${suffix}`
+  );
+}
+
+// src/react/react-playthrough.ts
+var INPUT_EVENTS = [
+  "click",
+  "keydown",
+  "keyup",
+  "pointerdown",
+  "pointerup",
+  "touchstart",
+  "touchend"
+];
+function createMetadata(waiverReason) {
+  return {
+    version: 1,
+    waiverReason,
+    evidence: {
+      domInputEvents: 0,
+      boundedRuns: 0,
+      assertionsAfterOutcome: 0,
+      verified: false
+    }
+  };
+}
+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 () => {
+    const evidence = metadata.evidence;
+    let assertionsAtOutcome;
+    const recordInput = () => {
+      evidence.domInputEvents += 1;
+    };
+    for (const event of INPUT_EVENTS) {
+      document.addEventListener(event, recordInput, true);
+    }
+    try {
+      const view = render(element);
+      if (view.container.childNodes.length === 0) {
+        throw new Error(
+          "playthroughTest must render the production game entry."
+        );
+      }
+      const user = userEvent.setup();
+      await run({
+        view,
+        user,
+        async stepUntil(condition, options = {}) {
+          const steps = await runBoundedUntil(condition, options);
+          if (evidence.domInputEvents === 0) {
+            throw new Error(
+              "stepUntil reached an outcome before any production DOM input."
+            );
+          }
+          evidence.boundedRuns += 1;
+          assertionsAtOutcome = expect.getState().assertionCalls;
+          return steps;
+        }
+      });
+      const assertionCalls = expect.getState().assertionCalls;
+      evidence.assertionsAfterOutcome = assertionsAtOutcome === void 0 ? 0 : assertionCalls - assertionsAtOutcome;
+      if (evidence.domInputEvents === 0) {
+        throw new Error(
+          "playthroughTest did not observe production DOM input."
+        );
+      }
+      if (evidence.boundedRuns === 0) {
+        throw new Error("playthroughTest must complete one bounded stepUntil.");
+      }
+      if (evidence.assertionsAfterOutcome === 0) {
+        throw new Error(
+          "Assert an authoritative game outcome after stepUntil returns."
+        );
+      }
+      evidence.verified = true;
+    } finally {
+      for (const event of INPUT_EVENTS) {
+        document.removeEventListener(event, recordInput, true);
+      }
+    }
+  });
+}
+var playthroughTest = Object.assign(
+  (element, run) => definePlaythrough(element, run),
+  {
+    skip: (reason, element, run) => definePlaythrough(element, run, reason)
+  }
+);
+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;
+  });
+  const waivers = declared.filter(
+    ({ state, metadata }) => state === "skipped" && (metadata?.waiverReason?.trim().length ?? 0) >= 20
+  );
+  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"
+    );
+  } else {
+    for (const candidate of declared) {
+      const isValid = valid.includes(candidate);
+      const isWaived = waivers.includes(candidate);
+      if (isValid || isWaived) continue;
+      if (candidate.state === "skipped") {
+        issues.push(
+          `\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u88AB\u8DF3\u8FC7\uFF0C\u4F46\u6CA1\u6709\u81F3\u5C11 20 \u4E2A\u5B57\u7B26\u7684\u660E\u786E\u7406\u7531\u3002`
+        );
+      } 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`
+        );
+      }
+    }
+  }
+  if (issues.length > 0) return { passed: false, waived: false, issues };
+  if (valid.length > 0) return { passed: true, waived: false, issues: [] };
+  if (waivers.length > 0) return { passed: true, waived: true, issues: [] };
+  return { passed: false, waived: false, issues };
+}
 export {
-  ManualGameClock
+  ManualGameClock,
+  auditReactPlaythroughRun,
+  playthroughTest
 };

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
@@ -23,9 +33,344 @@ __export(react_vitest_config_exports, {
   defineReactGameVitestConfig: () => defineReactGameVitestConfig
 });
 module.exports = __toCommonJS(react_vitest_config_exports);
+var import_node_fs2 = require("fs");
+var import_node_path2 = require("path");
+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_config = require("vitest/config");
+
+// 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();
+  if (reason.length < 20) {
+    throw new Error(
+      "playthroughTest.skip reason must contain at least 20 characters."
+    );
+  }
+  return reason;
+}
+async function runBoundedUntil(condition, options = {}) {
+  const maxSteps = options.maxSteps ?? 120;
+  if (!Number.isSafeInteger(maxSteps) || maxSteps < 0 || maxSteps > 1e4) {
+    throw new RangeError(
+      "stepUntil maxSteps must be a safe integer between 0 and 10000."
+    );
+  }
+  for (let step = 0; step <= maxSteps; step += 1) {
+    if (condition()) return step;
+    if (step < maxSteps) {
+      await (0, import_react.act)(async () => {
+        await options.step?.(step + 1);
+      });
+    }
+  }
+  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. ${guidance}${suffix}`
+  );
+}
+
+// src/react/react-playthrough.ts
+var INPUT_EVENTS = [
+  "click",
+  "keydown",
+  "keyup",
+  "pointerdown",
+  "pointerup",
+  "touchstart",
+  "touchend"
+];
+function createMetadata(waiverReason) {
+  return {
+    version: 1,
+    waiverReason,
+    evidence: {
+      domInputEvents: 0,
+      boundedRuns: 0,
+      assertionsAfterOutcome: 0,
+      verified: false
+    }
+  };
+}
+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 () => {
+    const evidence = metadata.evidence;
+    let assertionsAtOutcome;
+    const recordInput = () => {
+      evidence.domInputEvents += 1;
+    };
+    for (const event of INPUT_EVENTS) {
+      document.addEventListener(event, recordInput, true);
+    }
+    try {
+      const view = (0, import_react2.render)(element);
+      if (view.container.childNodes.length === 0) {
+        throw new Error(
+          "playthroughTest must render the production game entry."
+        );
+      }
+      const user = import_user_event.default.setup();
+      await run({
+        view,
+        user,
+        async stepUntil(condition, options = {}) {
+          const steps = await runBoundedUntil(condition, options);
+          if (evidence.domInputEvents === 0) {
+            throw new Error(
+              "stepUntil reached an outcome before any production DOM input."
+            );
+          }
+          evidence.boundedRuns += 1;
+          assertionsAtOutcome = import_vitest.expect.getState().assertionCalls;
+          return steps;
+        }
+      });
+      const assertionCalls = import_vitest.expect.getState().assertionCalls;
+      evidence.assertionsAfterOutcome = assertionsAtOutcome === void 0 ? 0 : assertionCalls - assertionsAtOutcome;
+      if (evidence.domInputEvents === 0) {
+        throw new Error(
+          "playthroughTest did not observe production DOM input."
+        );
+      }
+      if (evidence.boundedRuns === 0) {
+        throw new Error("playthroughTest must complete one bounded stepUntil.");
+      }
+      if (evidence.assertionsAfterOutcome === 0) {
+        throw new Error(
+          "Assert an authoritative game outcome after stepUntil returns."
+        );
+      }
+      evidence.verified = true;
+    } finally {
+      for (const event of INPUT_EVENTS) {
+        document.removeEventListener(event, recordInput, true);
+      }
+    }
+  });
+}
+var playthroughTest = Object.assign(
+  (element, run) => definePlaythrough(element, run),
+  {
+    skip: (reason, element, run) => definePlaythrough(element, run, reason)
+  }
+);
+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;
+  });
+  const waivers = declared.filter(
+    ({ state, metadata }) => state === "skipped" && (metadata?.waiverReason?.trim().length ?? 0) >= 20
+  );
+  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"
+    );
+  } else {
+    for (const candidate of declared) {
+      const isValid = valid.includes(candidate);
+      const isWaived = waivers.includes(candidate);
+      if (isValid || isWaived) continue;
+      if (candidate.state === "skipped") {
+        issues.push(
+          `\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u88AB\u8DF3\u8FC7\uFF0C\u4F46\u6CA1\u6709\u81F3\u5C11 20 \u4E2A\u5B57\u7B26\u7684\u660E\u786E\u7406\u7531\u3002`
+        );
+      } 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`
+        );
+      }
+    }
+  }
+  if (issues.length > 0) return { passed: false, waived: false, issues };
+  if (valid.length > 0) return { passed: true, waived: false, issues: [] };
+  if (waivers.length > 0) return { passed: true, waived: true, issues: [] };
+  return { passed: false, waived: false, issues };
+}
+
+// src/react/react-playthrough-reporter.ts
+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);
+}
+function toAuditInput(test2) {
+  const metadata = test2.meta().reactPlaythrough;
+  return {
+    name: test2.fullName,
+    state: test2.result().state,
+    metadata: isMetadata(metadata) ? metadata : void 0
+  };
+}
+function firstLine(value) {
+  if (typeof value !== "string") return void 0;
+  return value.split("\n").map((line) => line.trim()).find(Boolean);
+}
+function toModuleResult(module2, projectRoot) {
+  const tests = [...module2.children.allTests()];
+  const errors = [
+    ...module2.errors().map((error) => firstLine(error.message)),
+    ...tests.flatMap(
+      (test2) => (test2.result().errors ?? []).map((error) => firstLine(error.message))
+    )
+  ].filter((message) => Boolean(message));
+  return {
+    file: (0, import_node_path.relative)(projectRoot, module2.moduleId).replaceAll("\\", "/"),
+    state: module2.state(),
+    errors,
+    tests: tests.map(toAuditInput)
+  };
+}
+function assessReactPlaythroughReport(input) {
+  const base = { file: input.expectedFile };
+  if (!input.expectedFileScheduled) {
+    if (input.expectedFileExists) {
+      return {
+        ...base,
+        status: "NOT_CHECKED",
+        next: `\u672C\u6B21\u662F\u805A\u7126\u8FD0\u884C\uFF0C\u672A\u68C0\u67E5\u6700\u4F4E\u53EF\u73A9\u6D41\u7A0B\uFF1B\u63D0\u4EA4\u524D\u8FD0\u884C pnpm test\uFF0C\u786E\u4FDD ${input.expectedFile} \u901A\u8FC7\u3002`,
+        failsRun: false
+      };
+    }
+    return {
+      ...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",
+      failsRun: true
+    };
+  }
+  const productionModule = input.modules.find(
+    (module2) => module2.file === input.expectedFile
+  );
+  const executedProductionFlow = productionModule?.tests.some(
+    (test2) => test2.state !== "skipped" && test2.state !== "pending"
+  );
+  if (input.focusedSelection && !executedProductionFlow) {
+    return {
+      ...base,
+      status: "NOT_CHECKED",
+      next: `\u672C\u6B21\u540D\u79F0\u6216\u884C\u53F7\u8FC7\u6EE4\u6CA1\u6709\u6267\u884C\u6700\u4F4E\u53EF\u73A9\u6D41\u7A0B\uFF1B\u63D0\u4EA4\u524D\u8FD0\u884C pnpm test\uFF0C\u786E\u4FDD ${input.expectedFile} \u901A\u8FC7\u3002`,
+      failsRun: false
+    };
+  }
+  if (!productionModule || productionModule.tests.length === 0) {
+    return {
+      ...base,
+      status: "NOT_RUN",
+      cause: productionModule?.errors[0] ?? input.unhandledErrors?.[0] ?? "\u751F\u4EA7\u53EF\u73A9\u6027\u6D4B\u8BD5\u672A\u5B8C\u6210\u6536\u96C6\u6216\u6267\u884C\u3002",
+      next: "\u5148\u4FEE\u590D Vitest \u4E0A\u65B9\u9996\u4E2A\u8BED\u6CD5\u3001\u5BFC\u5165\u6216\u6536\u96C6\u9519\u8BEF\uFF0C\u518D\u8FD0\u884C pnpm test\uFF1B\u4E0D\u8981\u7528 skip \u63A9\u76D6\u52A0\u8F7D\u5931\u8D25\u3002",
+      failsRun: true
+    };
+  }
+  const tests = input.modules.flatMap((module2) => module2.tests);
+  const audit = auditReactPlaythroughRun(tests);
+  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);
+    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" : "\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
+    };
+  }
+  if (audit.waived) {
+    return {
+      ...base,
+      status: "WAIVED",
+      waiverReasons: tests.map((test2) => test2.metadata?.waiverReason).filter((reason) => Boolean(reason)),
+      failsRun: false
+    };
+  }
+  return { ...base, status: "PASS", failsRun: false };
+}
+function formatReactPlaythroughReport(report) {
+  const lines = [`REACT_PLAYTHROUGH: ${report.status}`, `FILE: ${report.file}`];
+  if (report.cause) lines.push(`CAUSE: ${report.cause}`);
+  if (report.waiverReasons?.length) {
+    lines.push(`REASON: ${report.waiverReasons.join("\uFF1B")}`);
+  }
+  if (report.next) lines.push(`NEXT: ${report.next}`);
+  return `
+${lines.join("\n")}`;
+}
+var ReactPlaythroughReporter = class {
+  /** 绑定模板根目录，以稳定识别生产可玩性测试而不依赖测试名称。 */
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    this.expectedModuleId = (0, import_node_path.resolve)(projectRoot, this.expectedFile);
+  }
+  projectRoot;
+  expectedFile = PRODUCTION_PLAYTHROUGH_FILE;
+  expectedModuleId;
+  expectedFileScheduled = false;
+  focusedSelection = false;
+  /** 记录本轮是否实际选择了生产流程文件，用于区分聚焦运行与门禁失败。 */
+  onTestRunStart(specifications) {
+    this.expectedFileScheduled = specifications.some(
+      (specification) => (0, import_node_path.resolve)(specification.moduleId) === this.expectedModuleId
+    );
+    this.focusedSelection = specifications.some(
+      (specification) => Boolean(specification.project.globalConfig.testNamePattern) || Boolean(specification.testNamePattern) || Boolean(specification.testLines?.length)
+    );
+  }
+  /** 测试运行结束后执行项目级主流程门禁，并写入最终退出码。 */
+  onTestRunEnd(testModules, unhandledErrors) {
+    const report = assessReactPlaythroughReport({
+      expectedFile: this.expectedFile,
+      expectedFileExists: (0, import_node_fs.existsSync)(this.expectedModuleId),
+      expectedFileScheduled: this.expectedFileScheduled,
+      focusedSelection: this.focusedSelection,
+      modules: testModules.map(
+        (module2) => toModuleResult(module2, this.projectRoot)
+      ),
+      unhandledErrors: unhandledErrors.map((error) => firstLine(error.message)).filter((message) => Boolean(message))
+    });
+    const output = formatReactPlaythroughReport(report);
+    if (report.failsRun) {
+      console.error(output);
+      process.exitCode = 1;
+    } else if (report.status === "WAIVED" || report.status === "NOT_CHECKED") {
+      console.warn(output);
+    } else {
+      console.log(output);
+    }
+  }
+};
 
 // src/testing/vitest-node-args.ts
 function getJSDOMWorkerExecArgv() {
@@ -35,16 +380,16 @@ function getJSDOMWorkerExecArgv() {
 
 // src/react-vitest-config.ts
 function resolvePhaser3BrowserEntry(projectRoot) {
-  const manifestPath = (0, import_node_path.resolve)(projectRoot, "node_modules/phaser/package.json");
-  if (!(0, import_node_fs.existsSync)(manifestPath)) return void 0;
+  const manifestPath = (0, import_node_path2.resolve)(projectRoot, "node_modules/phaser/package.json");
+  if (!(0, import_node_fs2.existsSync)(manifestPath)) return void 0;
   try {
-    const manifest = JSON.parse((0, import_node_fs.readFileSync)(manifestPath, "utf8"));
+    const manifest = JSON.parse((0, import_node_fs2.readFileSync)(manifestPath, "utf8"));
     if (!manifest.version?.startsWith("3.")) return void 0;
-    const browserEntry = (0, import_node_path.resolve)(
-      (0, import_node_path.dirname)(manifestPath),
+    const browserEntry = (0, import_node_path2.resolve)(
+      (0, import_node_path2.dirname)(manifestPath),
       manifest.browser ?? "dist/phaser.js"
     );
-    return (0, import_node_fs.existsSync)(browserEntry) ? browserEntry : void 0;
+    return (0, import_node_fs2.existsSync)(browserEntry) ? browserEntry : void 0;
   } catch {
     return void 0;
   }
@@ -56,7 +401,7 @@ function defineReactGameVitestConfig(options) {
       alias: {
         ...phaser3BrowserEntry ? { phaser: phaser3BrowserEntry } : {},
         ...options.aliases,
-        "@": (0, import_node_path.resolve)(options.projectRoot, "src")
+        "@": (0, import_node_path2.resolve)(options.projectRoot, "src")
       }
     },
     test: {
@@ -79,7 +424,8 @@ function defineReactGameVitestConfig(options) {
       sequence: {
         setupFiles: "list"
       },
-      reporters: ["minimal"],
+      // minimal 保留业务失败；附加 reporter 负责项目级最低可玩性门禁。
+      reporters: ["minimal", new ReactPlaythroughReporter(options.projectRoot)],
       restoreMocks: true,
       clearMocks: true,
       testTimeout: options.testTimeout,