miaoda-game-devkit 0.3.0 → 0.5.0

package/dist/react/vitest-config.js

@@ -103,47 +103,123 @@ var INPUT_EVENTS = [
   "touchend"
 ];
 var MIN_CHECKPOINTS = 2;
+var REACT_PLAYTHROUGH_TRACE_ANNOTATION = "miaoda:react-playthrough-trace";
+var MAX_TRACE_VALUE_LENGTH = 180;
+var MAX_TRACE_LENGTH = 720;
+function truncateTraceValue(value, limit) {
+  const compact = value.replace(/\s+/g, " ").trim();
+  if (compact.length <= limit) return compact;
+  return `${compact.slice(0, Math.max(0, limit - 1))}\u2026`;
+}
+function formatReactPlaythroughFailureTrace(trace) {
+  const stages = [
+    ["entered", trace.entered],
+    ["after-primary", trace.afterPrimary],
+    ["last", trace.last]
+  ].filter((stage) => stage[1] !== void 0).map(
+    ([stage, value]) => `${stage}=${truncateTraceValue(value, MAX_TRACE_VALUE_LENGTH)}`
+  );
+  const details = [
+    trace.checkpoints.length > 0 ? `checkpoints=${trace.checkpoints.join(",")}` : "checkpoints=none",
+    trace.step ? `stepUntil=${trace.step.completed ?? "failed"}/${trace.step.bound}` : void 0
+  ].filter((detail) => Boolean(detail));
+  const formatted = `${stages.join(" -> ")}${stages.length ? "; " : ""}${details.join("; ")}`;
+  return truncateTraceValue(formatted, MAX_TRACE_LENGTH);
+}
+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) {
+function createEvidence() {
   return {
-    version: 3,
-    waiverReason,
-    evidence: {
-      domInputEvents: 0,
-      entryInputs: 0,
-      primaryInputs: 0,
-      boundedRuns: 0,
-      assertionsAfterOutcome: 0,
-      checkpoints: [],
-      verified: false
-    }
+    domInputEvents: 0,
+    entryInputs: 0,
+    primaryInputs: 0,
+    boundedRuns: 0,
+    assertionsAfterOutcome: 0,
+    checkpoints: [],
+    verified: false
   };
 }
-function definePlaythrough(element, run, waiverReason) {
+function createMetadata(waiverReason) {
+  return { version: 3, waiverReason, evidence: createEvidence() };
+}
+function definePlaythrough(element, run, playthroughOptions, 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 ({ expect }) => {
+  }, async ({ annotate, expect }) => {
+    metadata.evidence = createEvidence();
+    metadata.trace = void 0;
     const evidence = metadata.evidence;
     let assertionsAtOutcome;
     let enteredRecorded = false;
     let domTextAtEntered;
+    let enteredObservation;
+    let afterPrimaryObservation;
+    let enteredTrace;
+    let afterPrimaryTrace;
+    let outcomeTrace;
+    let stepTrace;
+    const sampleDomTrace = () => JSON.stringify((document.body.textContent ?? "").replace(/\s+/g, " ").trim());
+    const sampleLastTrace = () => {
+      if (!playthroughOptions?.observe) return sampleDomTrace();
+      try {
+        return sampleObservation(playthroughOptions.observe, "outcome").formatted;
+      } catch (error) {
+        return `<observe unavailable: ${String(error)}>`;
+      }
+    };
+    const createFailureTrace = () => formatReactPlaythroughFailureTrace({
+      entered: enteredTrace,
+      afterPrimary: afterPrimaryTrace,
+      last: outcomeTrace ?? sampleLastTrace(),
+      checkpoints: [...evidence.checkpoints],
+      step: stepTrace
+    });
     const recordInput = () => {
       evidence.domInputEvents += 1;
     };
@@ -181,7 +257,18 @@ 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"
+              );
+              afterPrimaryTrace = afterPrimaryObservation.formatted;
+            } else {
+              afterPrimaryTrace = sampleDomTrace();
+            }
+          }
         },
         checkpoint(kind) {
           if (kind === "entered") {
@@ -196,7 +283,16 @@ function definePlaythrough(element, run, waiverReason) {
               );
             }
             enteredRecorded = true;
-            domTextAtEntered = document.body.textContent ?? "";
+            if (playthroughOptions?.observe) {
+              enteredObservation = sampleObservation(
+                playthroughOptions.observe,
+                "entered"
+              );
+              enteredTrace = enteredObservation.formatted;
+            } else {
+              domTextAtEntered = document.body.textContent ?? "";
+              enteredTrace = sampleDomTrace();
+            }
             evidence.checkpoints.push(kind);
             return;
           }
@@ -217,17 +313,43 @@ function definePlaythrough(element, run, waiverReason) {
           }
           evidence.checkpoints.push(kind);
         },
-        async stepUntil(condition, options = {}) {
-          const steps = await runBoundedUntil(condition, options);
+        async stepUntil(condition, stepOptions = {}) {
+          const stepBound = stepOptions.maxSteps ?? 120;
+          stepTrace = { bound: stepBound };
+          const boundedOptions = stepOptions.diagnostics || !playthroughOptions?.observe ? stepOptions : {
+            ...stepOptions,
+            diagnostics: playthroughOptions.observe
+          };
+          const steps = await runBoundedUntil(condition, boundedOptions);
+          stepTrace = { bound: stepBound, completed: steps };
           if (evidence.primaryInputs === 0) {
             throw new Error(
               'stepUntil must follow performInput("primary", ...). A menu/help click is not gameplay evidence.'
             );
           }
-          if (steps === 0 && options.allowStaticDom !== true && domTextAtEntered !== void 0 && (document.body.textContent ?? "") === domTextAtEntered) {
-            throw new Error(
-              'stepUntil outcome was already true at step 0 and the DOM has not changed since checkpoint("entered"), so the flow cannot prove that gameplay changed anything. \u610F\u601D\uFF1A\u6E38\u620F\u4E00\u6B65\u90FD\u6CA1\u73A9\uFF0C\u7B49\u5F85\u7684"\u7ED3\u679C"\u5C31\u5DF2\u7ECF\u6210\u7ACB\uFF0C\u9875\u9762\u4E5F\u4E00\u4E2A\u5B57\u6CA1\u53D8\u2014\u2014\u8FD9\u4E2A\u7ED3\u679C\u8BC1\u660E\u4E0D\u4E86\u4EFB\u4F55\u4E8B\u3002\u5E38\u89C1\u539F\u56E0\uFF1A\u2460 \u8F93\u5165\u6CA1\u6709\u63A5\u5230\u6E38\u620F\u4E0A\uFF1B\u2461 \u754C\u9762\u5361\u6B7B\uFF08\u72B6\u6001\u6539\u4E86\u4F46 snapshot \u5F15\u7528\u6CA1\u6362\uFF0CReact \u6CA1\u6709\u5237\u65B0\uFF09\uFF1B\u2462 \u65AD\u8A00\u4E86\u5F00\u5C40\u524D\u5C31\u5B58\u5728\u7684\u9759\u6001\u6587\u672C\u3002\u4FEE\u590D\uFF1A\u7B49\u5F85\u5E76\u65AD\u8A00\u53EA\u6709\u73A9\u8D77\u6765\u4E4B\u540E\u624D\u4F1A\u51FA\u73B0\u7684\u4E1C\u897F\uFF08\u5F00\u59CB\u906E\u7F69\u6D88\u5931\u3001\u6BD4\u5206\u53D8\u5316\u3001\u7ED3\u7B97\u753B\u9762\u51FA\u73B0\uFF09\u3002\u4F8B\u5916\uFF1A\u7ED3\u679C\u753B\u5728 Canvas \u4E0A\u3001\u7ECF Telemetry \u7B49\u9875\u9762\u5916\u72B6\u6001\u89C2\u5BDF\u7684\u6E38\u620F\uFF0C\u663E\u5F0F\u4F20 { allowStaticDom: true }\u3002'
+          if (playthroughOptions?.observe) {
+            if (!enteredObservation) {
+              throw new Error(
+                'observe requires checkpoint("entered") before primary gameplay input.'
+              );
+            }
+            const outcomeObservation = sampleObservation(
+              playthroughOptions.observe,
+              "outcome"
             );
+            outcomeTrace = outcomeObservation.formatted;
+            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 {
+            outcomeTrace = sampleDomTrace();
+            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;
@@ -262,7 +384,15 @@ function definePlaythrough(element, run, waiverReason) {
         );
       }
       evidence.verified = true;
+    } catch (error) {
+      metadata.trace = createFailureTrace();
+      try {
+        await annotate(metadata.trace, REACT_PLAYTHROUGH_TRACE_ANNOTATION);
+      } catch {
+      }
+      throw error;
     } finally {
+      metadata.trace ??= createFailureTrace();
       for (const event of INPUT_EVENTS) {
         document.removeEventListener(event, recordInput, true);
       }
@@ -270,9 +400,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) {
@@ -289,7 +426,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) {
@@ -298,13 +435,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}.`
+        );
       }
     }
   }
@@ -344,21 +485,41 @@ function errorLocation(value) {
   const match = value.match(/(?:^|\n)\s*at\s+(.*?\.(?:test|spec)\.[^\n]+:\d+:\d+)/);
   return match?.[1];
 }
+function failureTrace(test2) {
+  const annotations = test2.annotations();
+  let annotationTrace;
+  for (let index = annotations.length - 1; index >= 0; index -= 1) {
+    if (annotations[index].type === REACT_PLAYTHROUGH_TRACE_ANNOTATION) {
+      annotationTrace = annotations[index].message;
+      break;
+    }
+  }
+  const metadata = test2.meta().reactPlaythrough;
+  const trace = annotationTrace ?? (isMetadata(metadata) ? metadata.trace : void 0);
+  return trace ? truncateReporterLine(trace, 720) : void 0;
+}
+function truncateReporterLine(value, limit) {
+  const compact = (0, import_node_util.stripVTControlCharacters)(value).replace(/\s+/g, " ").trim();
+  if (compact.length <= limit) return compact;
+  return `${compact.slice(0, Math.max(0, limit - 1))}\u2026`;
+}
 function toModuleResult(module2, projectRoot) {
   const tests = [...module2.children.allTests()];
+  const moduleErrors = module2.errors().map((error) => firstLine(error.message)).filter((message) => Boolean(message));
   const errors = [
-    ...module2.errors().map((error) => firstLine(error.message)),
+    ...moduleErrors,
     ...tests.flatMap(
       (test2) => (test2.result().errors ?? []).map((error) => firstLine(error.message))
     )
   ].filter((message) => Boolean(message));
   const failures = tests.filter((test2) => test2.result().state === "failed").map((test2) => {
-    const raw = test2.result().errors?.[0]?.message ?? module2.errors()[0]?.message ?? "Unknown failure";
+    const raw = test2.result().errors?.at(-1)?.message ?? module2.errors()[0]?.message ?? "Unknown failure";
     return {
       test: test2.fullName,
       cause: firstLine(raw) ?? "Unknown failure",
       location: test2.location ? `${(0, import_node_path.relative)(projectRoot, module2.moduleId).replaceAll("\\", "/")}:${test2.location.line}:${test2.location.column}` : errorLocation(raw),
-      hint: failureHint(raw)
+      hint: failureHint(raw),
+      trace: failureTrace(test2)
     };
   });
   if (failures.length === 0 && tests.length === 0 && module2.errors().length > 0) {
@@ -374,11 +535,12 @@ function toModuleResult(module2, projectRoot) {
     file: (0, import_node_path.relative)(projectRoot, module2.moduleId).replaceAll("\\", "/"),
     state: module2.state(),
     errors,
+    primaryError: moduleErrors[0] ?? failures[0]?.cause,
     tests: tests.map(toAuditInput),
     failures
   };
 }
-function formatFailureSummary(modules) {
+function formatReactFailureSummary(modules) {
   const failures = modules.flatMap(
     (module2) => (module2.failures ?? []).map((failure) => ({ ...failure, file: module2.file }))
   );
@@ -388,12 +550,36 @@ function formatFailureSummary(modules) {
     lines.push(`FAILURE_${index + 1}: ${failure.file}`);
     lines.push(`TEST: ${failure.test}`);
     lines.push(`CAUSE: ${failure.cause}`);
+    if (failure.trace) lines.push(`TRACE: ${failure.trace}`);
     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) {
@@ -401,15 +587,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
     };
   }
@@ -423,7 +609,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
     };
   }
@@ -431,25 +617,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((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);
-    const staticOutcome = /already true at step 0 and the DOM has not changed/i.test(cause);
-    const staleSnapshot = /snapshot\(\) returned the same reference/i.test(cause);
-    const missingStructuredEvidence = /performInput|checkpoint/.test(cause);
+    const cause = productionModule.primaryError ?? productionModule.errors[0] ?? input.unhandledErrors?.[0] ?? audit.issues[0] ?? "The production playthrough did not leave complete gameplay evidence.";
     return {
       ...base,
       status: "FAILED",
       cause,
-      next: staleSnapshot ? "\u6E38\u620F\u539F\u5730\u4FEE\u6539\u72B6\u6001\u540E\u6CA1\u6709\u53D1\u5E03\u65B0\u7684\u5FEB\u7167\u5F15\u7528\uFF0CReact \u56E0 Object.is \u6BD4\u8F83\u76F8\u540C\u800C\u8DF3\u8FC7\u91CD\u6E32\u3002\u5728 controller \u7684 notify \u8DEF\u5F84\u4E0A\u53D1\u5E03\u65B0\u9876\u5C42\u5BF9\u8C61\uFF08cachedSnapshot = { ...state }\uFF09\uFF0C\u4E0D\u8981\u628A\u53EF\u53D8\u7684\u5185\u90E8\u5BF9\u8C61\u76F4\u63A5\u4F5C\u4E3A\u5FEB\u7167\u66B4\u9732\u3002" : staticOutcome ? "\u7ED3\u679C\u5728\u63A8\u8FDB\u524D\u5DF2\u6210\u7ACB\u4E14 DOM \u81EA entered \u4EE5\u6765\u65E0\u53D8\u5316\uFF1A\u8F93\u5165\u53EF\u80FD\u672A\u63A5\u5230\u751F\u4EA7\u63A7\u5236\uFF0CUI \u53EF\u80FD\u51BB\u7ED3\uFF0C\u4E5F\u53EF\u80FD\u65AD\u8A00\u4E86\u6E38\u620F\u5F00\u59CB\u524D\u5C31\u5B58\u5728\u7684\u9759\u6001\u6587\u672C\u3002\u6539\u4E3A\u7B49\u5F85\u5E76\u65AD\u8A00\u53EA\u6709\u73A9\u6CD5\u63A8\u8FDB\u540E\u624D\u51FA\u73B0\u7684\u72B6\u6001\uFF08\u5F00\u59CB\u906E\u7F69\u6D88\u5931\u3001\u6BD4\u5206\u53D8\u5316\u3001\u7ED3\u7B97\u51FA\u73B0\uFF09\uFF1B\u7ECF Canvas/Telemetry \u7B49 DOM \u5916\u6743\u5A01\u72B6\u6001\u89C2\u5BDF\u7684\u6D41\u7A0B\u4F20 { allowStaticDom: true }\u3002" : missingStep ? "\u8BE5\u6D41\u7A0B\u662F\u65F6\u95F4\u6216\u5E27\u9A71\u52A8\u7684\uFF0C\u4F46 stepUntil \u6CA1\u6709\u63A8\u8FDB\u6E38\u620F\u65F6\u95F4\uFF1B\u4E3A\u751F\u4EA7\u6E38\u620F\u6CE8\u5165 devkit \u7684 GameClock\uFF0C\u5E76\u4F20\u5165 step: () => clock.stepFrame()\u3002\u4E0D\u8981\u7528\u771F\u5B9E setTimeout\u3002" : timedOut ? "\u771F\u5B9E\u8F93\u5165\u5DF2\u6267\u884C\uFF0C\u4F46\u73A9\u6CD5\u6CA1\u6709\u5728\u4E0A\u9650\u5185\u4EA7\u751F\u7ED3\u679C\uFF1B\u68C0\u67E5\u751F\u4EA7\u63A7\u5236\u662F\u5426\u6536\u5230\u8F93\u5165\uFF0C\u518D\u67E5\u770B\u8D85\u65F6\u9519\u8BEF\u4E2D\u7684 Last diagnostics \u5224\u65AD\u662F\u6E38\u620F\u5FAA\u73AF\u3001\u89C4\u5219\u72B6\u6001\u8FD8\u662F UI \u540C\u6B65\u672A\u63A8\u8FDB\u3002" : missingStructuredEvidence ? '\u6309\u987A\u5E8F\u8865\u9F50\u81F3\u5C11\u4E24\u6B21\u7B7E\u5230\uFF1AperformInput("entry") \u540E\u8C03\u7528 checkpoint("entered")\uFF1B\u518D\u7528 performInput("primary") \u6267\u884C\u6838\u5FC3\u64CD\u4F5C\uFF0CstepUntil \u7B49\u5F85\u7ED3\u679C\uFF0C\u7528\u56DE\u8C03\u63D0\u4F9B\u7684 expect \u65AD\u8A00\u540E\u8C03\u7528 checkpoint("progress") \u6216 checkpoint("terminal")\u3002' : "\u4ECE\u751F\u4EA7\u5165\u53E3\u6267\u884C\u771F\u5B9E DOM \u8F93\u5165\uFF0C\u7528 stepUntil \u6709\u754C\u63A8\u8FDB\u5230\u73A9\u5BB6\u53EF\u89C1\u7ED3\u679C\u6216\u6E38\u620F\u6743\u5A01\u72B6\u6001\uFF0C\u5E76\u5728\u5176\u540E\u65AD\u8A00\uFF1B\u4E0D\u8981\u76F4\u8FBE\u5185\u90E8\u5173\u5361\u6216\u4FEE\u6539\u73A9\u6CD5\u72B6\u6001\u3002",
+      next: repairGuidance(cause),
       failsRun: true
     };
   }
@@ -467,7 +648,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 `
@@ -514,7 +695,7 @@ var ReactPlaythroughReporter = class {
     } else {
       console.log(output);
     }
-    const summary = formatFailureSummary(
+    const summary = formatReactFailureSummary(
       testModules.map((module2) => toModuleResult(module2, this.projectRoot))
     );
     if (report.failsRun && summary[0] === "TEST_RESULT: PASS") {
@@ -550,6 +731,9 @@ function resolvePhaser3BrowserEntry(projectRoot) {
 function defineReactGameVitestConfig(options) {
   const phaser3BrowserEntry = resolvePhaser3BrowserEntry(options.projectRoot);
   return (0, import_config.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 } : {},