miaoda-game-devkit 0.2.21 → 0.4.0

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";
@@ -68,20 +69,50 @@ var INPUT_EVENTS = [
   "touchend"
 ];
 var MIN_CHECKPOINTS = 2;
+var MAX_FORMATTED_OBSERVATION_LENGTH = 500;
+function formatObservation(fingerprint) {
+  if (fingerprint.length <= MAX_FORMATTED_OBSERVATION_LENGTH) return fingerprint;
+  return `${fingerprint.slice(0, MAX_FORMATTED_OBSERVATION_LENGTH)}\u2026 (${fingerprint.length} chars)`;
+}
+function sampleObservation(observe, stage) {
+  let value;
+  try {
+    value = observe();
+  } catch (error) {
+    throw new Error(`observe() threw at ${stage}: ${String(error)}`);
+  }
+  try {
+    const fingerprint = JSON.stringify(value);
+    if (fingerprint === void 0) throw new Error("unsupported value");
+    return { fingerprint, formatted: formatObservation(fingerprint) };
+  } catch {
+    throw new Error(
+      `observe() must return JSON-serializable read-only state; sampling failed at ${stage}.`
+    );
+  }
+}
+function formatObservationTimeline(entered, afterPrimary, outcome) {
+  return [
+    `entered=${entered.formatted}`,
+    `after-primary=${afterPrimary?.formatted ?? "<not sampled>"}`,
+    `outcome=${outcome.formatted}`
+  ].join(", ");
+}
 function describeMissingEvidence(evidence) {
-  if (!evidence || evidence.entryInputs === 0) return "entry \u8F93\u5165";
-  if (evidence.primaryInputs === 0) return "primary \u8F93\u5165";
+  if (!evidence || evidence.entryInputs === 0) return "an entry input";
+  if (evidence.primaryInputs === 0) return "a primary gameplay input";
   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.boundedRuns === 0) return "a bounded stepUntil call";
+  if (evidence.assertionsAfterOutcome === 0)
+    return "an outcome assertion after stepUntil";
   if (evidence.checkpoints.length < MIN_CHECKPOINTS)
-    return `\u81F3\u5C11 ${MIN_CHECKPOINTS} \u4E2A checkpoint`;
+    return `at least ${MIN_CHECKPOINTS} checkpoints`;
   if (!evidence.checkpoints.some(
     (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
   )) {
     return "progress/terminal checkpoint";
   }
-  return "\u5B8C\u6574\u7684 playthrough \u6821\u9A8C\u6807\u8BB0";
+  return "a complete playthrough verification marker";
 }
 function createMetadata(waiverReason) {
   return {
@@ -98,7 +129,7 @@ function createMetadata(waiverReason) {
     }
   };
 }
-function definePlaythrough(element, run, waiverReason) {
+function definePlaythrough(element, run, playthroughOptions, waiverReason) {
   const reason = normalizePlaythroughWaiverReason(waiverReason);
   const metadata = createMetadata(reason);
   test("production game completes a bounded playthrough", {
@@ -108,6 +139,9 @@ function definePlaythrough(element, run, waiverReason) {
     const evidence = metadata.evidence;
     let assertionsAtOutcome;
     let enteredRecorded = false;
+    let domTextAtEntered;
+    let enteredObservation;
+    let afterPrimaryObservation;
     const recordInput = () => {
       evidence.domInputEvents += 1;
     };
@@ -145,7 +179,15 @@ function definePlaythrough(element, run, waiverReason) {
             );
           }
           if (kind === "entry") evidence.entryInputs += 1;
-          else evidence.primaryInputs += 1;
+          else {
+            evidence.primaryInputs += 1;
+            if (playthroughOptions?.observe) {
+              afterPrimaryObservation = sampleObservation(
+                playthroughOptions.observe,
+                "after-primary"
+              );
+            }
+          }
         },
         checkpoint(kind) {
           if (kind === "entered") {
@@ -160,6 +202,14 @@ function definePlaythrough(element, run, waiverReason) {
               );
             }
             enteredRecorded = true;
+            if (playthroughOptions?.observe) {
+              enteredObservation = sampleObservation(
+                playthroughOptions.observe,
+                "entered"
+              );
+            } else {
+              domTextAtEntered = document.body.textContent ?? "";
+            }
             evidence.checkpoints.push(kind);
             return;
           }
@@ -180,13 +230,37 @@ function definePlaythrough(element, run, waiverReason) {
           }
           evidence.checkpoints.push(kind);
         },
-        async stepUntil(condition, options = {}) {
-          const steps = await runBoundedUntil(condition, options);
+        async stepUntil(condition, stepOptions = {}) {
+          const boundedOptions = stepOptions.diagnostics || !playthroughOptions?.observe ? stepOptions : {
+            ...stepOptions,
+            diagnostics: playthroughOptions.observe
+          };
+          const steps = await runBoundedUntil(condition, boundedOptions);
           if (evidence.primaryInputs === 0) {
             throw new Error(
               'stepUntil must follow performInput("primary", ...). A menu/help click is not gameplay evidence.'
             );
           }
+          if (playthroughOptions?.observe) {
+            if (!enteredObservation) {
+              throw new Error(
+                'observe requires checkpoint("entered") before primary gameplay input.'
+              );
+            }
+            const outcomeObservation = sampleObservation(
+              playthroughOptions.observe,
+              "outcome"
+            );
+            if (outcomeObservation.fingerprint === enteredObservation.fingerprint) {
+              throw new Error(
+                `The authoritative observation did not change from checkpoint("entered") to the outcome. Timeline: ${formatObservationTimeline(enteredObservation, afterPrimaryObservation, outcomeObservation)}`
+              );
+            }
+          } else if (steps === 0 && domTextAtEntered !== void 0 && (document.body.textContent ?? "") === domTextAtEntered) {
+            throw new Error(
+              'stepUntil found the outcome at step 0, and the DOM has not changed since checkpoint("entered"). The flow therefore provides no evidence that the primary gameplay input produced a result. For Canvas or Controller state outside the DOM, declare one playthrough observe callback.'
+            );
+          }
           evidence.boundedRuns += 1;
           assertionsAtOutcome = expect.getState().assertionCalls;
           return steps;
@@ -228,9 +302,16 @@ function definePlaythrough(element, run, waiverReason) {
   });
 }
 var playthroughTest = Object.assign(
-  (element, run) => definePlaythrough(element, run),
+  (element, optionsOrRun, maybeRun) => {
+    if (typeof optionsOrRun === "function") {
+      definePlaythrough(element, optionsOrRun);
+      return;
+    }
+    if (!maybeRun) throw new TypeError("playthroughTest requires a run callback.");
+    definePlaythrough(element, maybeRun, optionsOrRun);
+  },
   {
-    skip: (reason, element, run) => definePlaythrough(element, run, reason)
+    skip: (reason, element, run) => definePlaythrough(element, run, void 0, reason)
   }
 );
 function auditReactPlaythroughRun(tests) {
@@ -247,7 +328,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\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'
+      'No production gameplay verification was declared. Use playthroughTest to render <App />, then run performInput("entry"), checkpoint("entered"), performInput("primary"), and a bounded stepUntil. Assert the authoritative outcome with the expect provided by playthroughTest, then record checkpoint("progress") or checkpoint("terminal").'
     );
   } else {
     for (const candidate of declared) {
@@ -256,13 +337,17 @@ function auditReactPlaythroughRun(tests) {
       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`
+          `Playthrough ${JSON.stringify(candidate.name)} was skipped without an explicit reason of at least 20 characters.`
         );
       } else if (candidate.state !== "passed") {
-        issues.push(`\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u7684\u72B6\u6001\u4E3A ${candidate.state}\u3002`);
+        issues.push(
+          `Playthrough ${JSON.stringify(candidate.name)} finished with state ${candidate.state}.`
+        );
       } else {
         const missing = describeMissingEvidence(candidate.metadata?.evidence);
-        issues.push(`\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u7F3A\u5C11${missing}\u3002`);
+        issues.push(
+          `Playthrough ${JSON.stringify(candidate.name)} is missing ${missing}.`
+        );
       }
     }
   }
@@ -289,7 +374,18 @@ function toAuditInput(test2) {
 }
 function firstLine(value) {
   if (typeof value !== "string") return void 0;
-  return value.split("\n").map((line) => line.trim()).find(Boolean);
+  return stripVTControlCharacters(value).split("\n").map((line) => line.trim()).find(Boolean);
+}
+function failureHint(value) {
+  const names = [...value.matchAll(/button\s*\n\s*Name "([^"]+)"/g)].map(
+    (match) => match[1]
+  );
+  if (names.length === 0) return void 0;
+  return `Available button names: ${names.map((name) => JSON.stringify(name)).join(", ")}`;
+}
+function errorLocation(value) {
+  const match = value.match(/(?:^|\n)\s*at\s+(.*?\.(?:test|spec)\.[^\n]+:\d+:\d+)/);
+  return match?.[1];
 }
 function toModuleResult(module, projectRoot) {
   const tests = [...module.children.allTests()];
@@ -299,13 +395,71 @@ 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 repairGuidance(cause) {
+  if (/snapshot\(\) returned the same reference/i.test(cause)) {
+    return "The game mutated state without publishing a new snapshot reference, so React skipped the render after an Object.is comparison. Publish a new top-level object before notifying subscribers, for example cachedSnapshot = { ...state }, and never expose a mutable internal object as the snapshot.";
+  }
+  if (/(?:already true|found the outcome) at step 0.*DOM has not changed/i.test(
+    cause
+  )) {
+    return 'Make the stepUntil condition false at checkpoint("entered"). Verify that the primary input reaches the production control, then wait for a post-input outcome such as a changed score, a removed entry overlay, a completed turn, or a result screen. For Canvas or Controller state outside the DOM, declare observe once on playthroughTest and return the read-only production Telemetry snapshot.';
+  }
+  if (/authoritative observation did not change/i.test(cause)) {
+    return "The flow reached its condition while observe still returned the same authoritative state. Make observe read the same production Controller that React renders, verify the primary input changes that Controller, and wait for a post-input result. Inspect the Timeline values to locate the disconnected stage.";
+  }
+  if (/No step callback was provided/i.test(cause)) {
+    return "This flow is driven by time or frames, but stepUntil did not advance the game clock. Inject the devkit GameClock into the production game and pass step: () => clock.stepFrame(). Do not replace deterministic advancement with a real setTimeout.";
+  }
+  if (/outcome was not reached within \d+ steps/i.test(cause)) {
+    return "The real input was dispatched, but gameplay did not reach the outcome within the bound. Confirm that the production control received the input, then inspect Last diagnostics to determine whether the game loop, rule state, or UI synchronization failed to advance.";
+  }
+  if (/performInput|checkpoint/.test(cause)) {
+    return 'Complete the evidence sequence in order: performInput("entry"), checkpoint("entered"), performInput("primary"), bounded stepUntil, an authoritative result assertion using the provided expect, then checkpoint("progress") or checkpoint("terminal").';
+  }
+  return "Start from the production entry, dispatch real DOM input, and use stepUntil to reach a bounded player-visible or authoritative game outcome before asserting it. Do not jump to an internal level or mutate gameplay state.";
+}
 function assessReactPlaythroughReport(input) {
   const base = { file: input.expectedFile };
   if (!input.expectedFileScheduled) {
@@ -313,15 +467,15 @@ function assessReactPlaythroughReport(input) {
       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`,
+        next: `This focused run did not execute the minimum production playthrough. Run pnpm test before submitting and make sure ${input.expectedFile} passes.`,
         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 /> \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',
+      cause: "The required production playthrough test file does not exist.",
+      next: 'Create the file and render <App />. Drive a legal entry with performInput("entry"), record checkpoint("entered"), perform a core game action with performInput("primary"), and use a bounded stepUntil. Assert the authoritative result with the provided expect, then record checkpoint("progress") or checkpoint("terminal").',
       failsRun: true
     };
   }
@@ -335,7 +489,7 @@ function assessReactPlaythroughReport(input) {
     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`,
+      next: `The name or line filter did not execute the minimum production playthrough. Run pnpm test before submitting and make sure ${input.expectedFile} passes.`,
       failsRun: false
     };
   }
@@ -343,23 +497,20 @@ function assessReactPlaythroughReport(input) {
     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",
+      cause: productionModule?.errors[0] ?? input.unhandledErrors?.[0] ?? "The production playthrough could not be collected or executed.",
+      next: "Fix the first Vitest syntax, import, environment, or collection error shown above, then run pnpm test again. Do not use skip to hide a load failure.",
       failsRun: true
     };
   }
   const tests = input.modules.flatMap((module) => module.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);
-    const missingStructuredEvidence = /performInput|checkpoint/.test(cause);
+    const cause = productionModule.errors[0] ?? input.unhandledErrors?.[0] ?? audit.issues[0] ?? "The production playthrough did not leave complete gameplay evidence.";
     return {
       ...base,
       status: "FAILED",
       cause,
-      next: missingStep ? "\u8BE5\u6D41\u7A0B\u662F\u65F6\u95F4\u6216\u5E27\u9A71\u52A8\u7684\uFF0C\u4F46 stepUntil \u6CA1\u6709\u63A8\u8FDB\u6E38\u620F\u65F6\u95F4\uFF1B\u4E3A\u751F\u4EA7\u6E38\u620F\u6CE8\u5165 devkit \u7684 GameClock\uFF0C\u5E76\u4F20\u5165 step: () => clock.stepFrame()\u3002\u4E0D\u8981\u7528\u771F\u5B9E setTimeout\u3002" : timedOut ? "\u771F\u5B9E\u8F93\u5165\u5DF2\u6267\u884C\uFF0C\u4F46\u73A9\u6CD5\u6CA1\u6709\u5728\u4E0A\u9650\u5185\u4EA7\u751F\u7ED3\u679C\uFF1B\u68C0\u67E5\u751F\u4EA7\u63A7\u5236\u662F\u5426\u6536\u5230\u8F93\u5165\uFF0C\u518D\u67E5\u770B\u8D85\u65F6\u9519\u8BEF\u4E2D\u7684 Last diagnostics \u5224\u65AD\u662F\u6E38\u620F\u5FAA\u73AF\u3001\u89C4\u5219\u72B6\u6001\u8FD8\u662F UI \u540C\u6B65\u672A\u63A8\u8FDB\u3002" : missingStructuredEvidence ? '\u6309\u987A\u5E8F\u8865\u9F50\u81F3\u5C11\u4E24\u6B21\u7B7E\u5230\uFF1AperformInput("entry") \u540E\u8C03\u7528 checkpoint("entered")\uFF1B\u518D\u7528 performInput("primary") \u6267\u884C\u6838\u5FC3\u64CD\u4F5C\uFF0CstepUntil \u7B49\u5F85\u7ED3\u679C\uFF0C\u7528\u56DE\u8C03\u63D0\u4F9B\u7684 expect \u65AD\u8A00\u540E\u8C03\u7528 checkpoint("progress") \u6216 checkpoint("terminal")\u3002' : "\u4ECE\u751F\u4EA7\u5165\u53E3\u6267\u884C\u771F\u5B9E DOM \u8F93\u5165\uFF0C\u7528 stepUntil \u6709\u754C\u63A8\u8FDB\u5230\u73A9\u5BB6\u53EF\u89C1\u7ED3\u679C\u6216\u6E38\u620F\u6743\u5A01\u72B6\u6001\uFF0C\u5E76\u5728\u5176\u540E\u65AD\u8A00\uFF1B\u4E0D\u8981\u76F4\u8FBE\u5185\u90E8\u5173\u5361\u6216\u4FEE\u6539\u73A9\u6CD5\u72B6\u6001\u3002",
+      next: repairGuidance(cause),
       failsRun: true
     };
   }
@@ -377,7 +528,7 @@ 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")}`);
+    lines.push(`REASON: ${report.waiverReasons.join("; ")}`);
   }
   if (report.next) lines.push(`NEXT: ${report.next}`);
   return `
@@ -424,6 +575,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")}`);
   }
 };
 
@@ -452,6 +611,9 @@ function resolvePhaser3BrowserEntry(projectRoot) {
 function defineReactGameVitestConfig(options) {
   const phaser3BrowserEntry = resolvePhaser3BrowserEntry(options.projectRoot);
   return defineConfig({
+    // Keep discovery and dependency resolution anchored to the generated app even
+    // when an external runner invokes Vitest from a parent workspace directory.
+    root: options.projectRoot,
     resolve: {
       alias: {
         ...phaser3BrowserEntry ? { phaser: phaser3BrowserEntry } : {},
@@ -472,6 +634,7 @@ function defineReactGameVitestConfig(options) {
       environmentOptions: {
         jsdom: { url: "http://localhost/", pretendToBeVisual: true }
       },
+      includeTaskLocation: true,
       setupFiles: [
         "miaoda-game-devkit/react/vitest-setup",
         ...options.additionalSetupFiles ?? []
@@ -479,8 +642,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/rules/react-test-boundary-plugin.js

@@ -0,0 +1,97 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/rules/react-test-boundary-plugin.ts
+var react_test_boundary_plugin_exports = {};
+__export(react_test_boundary_plugin_exports, {
+  default: () => react_test_boundary_plugin_default
+});
+module.exports = __toCommonJS(react_test_boundary_plugin_exports);
+var PRODUCTION_PLAYTHROUGH = "/tests/production-playthrough.test.tsx";
+function normalizedFilename(filename) {
+  return filename.replaceAll("\\", "/");
+}
+function importedName(specifier) {
+  const imported = specifier.imported;
+  return imported.type === "Identifier" ? imported.name : String(imported.value);
+}
+function internalGameImports(node) {
+  if (typeof node.source.value !== "string") return [];
+  if (!node.source.value.startsWith("@/game/")) return [];
+  if (node.importKind === "type") return [];
+  return node.specifiers.flatMap((specifier) => {
+    const importKind = specifier.importKind;
+    return importKind === "type" ? [] : [specifier.local.name];
+  });
+}
+var rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Protect production React game and playthrough boundaries"
+    },
+    messages: {
+      boundExpect: "Use the expect provided by playthroughTest. An imported Vitest expect may belong to a different module instance and cannot provide reliable assertion evidence.",
+      providedUser: "Use the user provided by playthroughTest; do not import or create another userEvent instance in the production playthrough.",
+      productionTestingImport: "Production source must not import miaoda-game-devkit/react/testing. Inject test clocks and observers through the production App factory boundary.",
+      productionEntry: "Render <App /> from the production playthrough. Import Controller and Telemetry helpers when needed, but do not render an internal game component directly."
+    },
+    schema: []
+  },
+  create(context) {
+    const filename = normalizedFilename(context.filename);
+    const isProductionPlaythrough = filename.endsWith(PRODUCTION_PLAYTHROUGH);
+    const isProductionSource = filename.includes("/src/");
+    const internalGameBindings = /* @__PURE__ */ new Set();
+    return {
+      ImportDeclaration(node) {
+        const source = node.source.value;
+        if (typeof source !== "string") return;
+        if (isProductionSource && source === "miaoda-game-devkit/react/testing") {
+          context.report({ node: node.source, messageId: "productionTestingImport" });
+        }
+        if (!isProductionPlaythrough) return;
+        if (source === "vitest" && node.specifiers.some(
+          (specifier) => specifier.type === "ImportSpecifier" && importedName(specifier) === "expect"
+        )) {
+          context.report({ node: node.source, messageId: "boundExpect" });
+        }
+        if (source === "@testing-library/user-event") {
+          context.report({ node: node.source, messageId: "providedUser" });
+        }
+        for (const name of internalGameImports(node)) {
+          internalGameBindings.add(name);
+        }
+      },
+      JSXOpeningElement(node) {
+        if (!isProductionPlaythrough) return;
+        const opening = node;
+        if (opening.name?.type === "JSXIdentifier" && opening.name.name && internalGameBindings.has(opening.name.name)) {
+          context.report({ node, messageId: "productionEntry" });
+        }
+      }
+    };
+  }
+};
+var plugin = {
+  meta: { name: "react-game-boundaries" },
+  rules: { "no-test-bypass": rule }
+};
+var react_test_boundary_plugin_default = plugin;
+module.exports = module.exports.default;

package/oxlint-config.json

@@ -5,10 +5,12 @@
   },
   "jsPlugins": [
     "./dist/rules/check-image-import-plugin.js",
-    "./dist/rules/check-style-import-plugin.js"
+    "./dist/rules/check-style-import-plugin.js",
+    "./dist/rules/react-test-boundary-plugin.js"
   ],
   "rules": {
     "check-image-exists/no-missing-image": "error",
-    "check-style-exists/no-missing-style": "error"
+    "check-style-exists/no-missing-style": "error",
+    "react-game-boundaries/no-test-bypass": "error"
   }
 }

package/package.json

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