miaoda-game-devkit 0.6.1 → 0.6.3

package/dist/react/vitest-config.mjs

@@ -13,14 +13,112 @@ import { render } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { test } from "vitest";
 
+// src/react/react-error-diagnostics.ts
+var MAX_DIAGNOSTIC_LENGTH = 1e3;
+function truncate(value) {
+  const trimmed = value.trim();
+  if (trimmed.length <= MAX_DIAGNOSTIC_LENGTH) return trimmed;
+  return `${trimmed.slice(0, MAX_DIAGNOSTIC_LENGTH - 1)}\u2026`;
+}
+function safeJson(value) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  try {
+    return JSON.stringify(value, (_key, nested) => {
+      if (typeof nested === "bigint") return `${nested}n`;
+      if (typeof nested === "function") {
+        return `Function<${nested.name || "anonymous"}>`;
+      }
+      if (typeof nested === "symbol") return nested.toString();
+      if (nested && typeof nested === "object") {
+        if (seen.has(nested)) return "[Circular]";
+        seen.add(nested);
+      }
+      return nested;
+    });
+  } catch {
+    return void 0;
+  }
+}
+function collectEntries(value, fallbackCode, seen) {
+  if (typeof value === "string") {
+    return value.trim() ? [{ code: fallbackCode, message: truncate(value) }] : [];
+  }
+  if (value === null || value === void 0 || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint" || typeof value === "symbol") {
+    return [{ code: fallbackCode, message: String(value) }];
+  }
+  if (typeof value === "function") {
+    return [
+      { code: fallbackCode, message: `Function<${value.name || "anonymous"}>` }
+    ];
+  }
+  if (seen.has(value)) return [];
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => collectEntries(item, fallbackCode, seen));
+  }
+  const record = value;
+  const code = typeof record.code === "string" && record.code.trim() ? record.code.trim() : fallbackCode;
+  const entries = [];
+  if (typeof record.message === "string" && record.message.trim()) {
+    entries.push({ code, message: truncate(record.message) });
+  }
+  if (record.cause !== void 0) {
+    entries.push(...collectEntries(record.cause, fallbackCode, seen));
+  }
+  if (Array.isArray(record.errors)) {
+    entries.push(...collectEntries(record.errors, fallbackCode, seen));
+  }
+  if (entries.length > 0) return entries;
+  if (typeof record.stack === "string" && record.stack.trim()) {
+    return [{ code, message: truncate(record.stack) }];
+  }
+  const json = safeJson(value);
+  return json && json !== "{}" ? [{ code, message: truncate(json) }] : [];
+}
+function extractFailureEntries(value, fallbackCode = "TEST_FAILURE") {
+  const entries = collectEntries(value, fallbackCode, /* @__PURE__ */ new WeakSet());
+  const keys = /* @__PURE__ */ new Set();
+  return entries.filter((entry) => {
+    const key = `${entry.code}\0${entry.message}`;
+    if (keys.has(key)) return false;
+    keys.add(key);
+    return true;
+  });
+}
+function createFailureDiagnostic(source, value) {
+  return { source, entries: extractFailureEntries(value) };
+}
+function appendCurrentAttemptFailures(current, runnerValue) {
+  const runner = createFailureDiagnostic("test-runtime", runnerValue);
+  if (!current || current.entries.length === 0) return runner;
+  const primary = current.entries[0];
+  const currentStart = runner.entries.findIndex(
+    (entry) => entry.code === primary.code && entry.message === primary.message
+  );
+  if (currentStart < 0) return current;
+  return {
+    source: current.source,
+    entries: extractFailureEntries([
+      ...current.entries,
+      ...runner.entries.slice(currentStart + 1)
+    ])
+  };
+}
+function codedError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
 // src/react/react-playthrough-core.ts
 import { act } from "@testing-library/react";
 function throwIfAborted(signal) {
   if (!signal?.aborted) return;
   if (signal.reason instanceof Error) throw signal.reason;
-  throw new Error("Playthrough advancement was cancelled.", {
-    cause: signal.reason
-  });
+  throw codedError(
+    "PLAYTHROUGH_CANCELLED",
+    `Playthrough advancement was cancelled. Cause: ${String(signal.reason)}`
+  );
 }
 function formatDiagnostics(read) {
   if (!read) return void 0;
@@ -36,7 +134,8 @@ function normalizePlaythroughWaiverReason(waiverReason) {
   if (waiverReason === void 0) return void 0;
   const reason = waiverReason.trim();
   if (reason.length < 20) {
-    throw new Error(
+    throw codedError(
+      "INVALID_PLAYTHROUGH_WAIVER",
       "playthroughTest.skip reason must contain at least 20 characters."
     );
   }
@@ -45,7 +144,8 @@ function normalizePlaythroughWaiverReason(waiverReason) {
 async function runBoundedUntil(condition, options = {}) {
   const maxSteps = options.maxSteps ?? 120;
   if (!Number.isSafeInteger(maxSteps) || maxSteps < 0 || maxSteps > 1e4) {
-    throw new RangeError(
+    throw codedError(
+      "INVALID_STEP_BOUND",
       "stepUntil maxSteps must be a safe integer between 0 and 10000."
     );
   }
@@ -62,7 +162,8 @@ 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(
+  throw codedError(
+    options.step ? "PLAYTHROUGH_BOUND_EXHAUSTED" : "PLAYTHROUGH_CLOCK_NOT_ADVANCED",
     `Playthrough outcome was not reached within ${maxSteps} steps. ${guidance}${suffix}`
   );
 }
@@ -81,6 +182,11 @@ var MIN_STAGES = 5;
 var MIN_MILESTONES = 3;
 var MAX_TRACE_VALUE_LENGTH = 140;
 var MAX_TRACE_LENGTH = 720;
+function eventTargetsCanvas(event) {
+  const path = typeof event.composedPath === "function" ? event.composedPath() : [];
+  if (path.some((target) => target instanceof HTMLCanvasElement)) return true;
+  return event.target instanceof HTMLCanvasElement;
+}
 var REACT_PLAYTHROUGH_TRACE_ANNOTATION = "miaoda:react-playthrough-trace";
 function truncateTraceValue(value, limit) {
   const compact = value.replace(/\s+/g, " ").trim();
@@ -110,14 +216,18 @@ function sampleObservedState(observe, stage) {
   try {
     value = observe();
   } catch (error) {
-    throw new Error(`observe() threw at ${stage}: ${String(error)}`);
+    throw codedError(
+      "OBSERVE_FAILED",
+      `observe() threw at ${stage}: ${String(error)}`
+    );
   }
   try {
     const fingerprint = JSON.stringify(value);
     if (fingerprint === void 0) throw new Error("unsupported value");
     return { fingerprint, formatted: formatState(fingerprint) };
   } catch {
-    throw new Error(
+    throw codedError(
+      "OBSERVE_NOT_SERIALIZABLE",
       `observe() must return JSON-serializable read-only state; sampling failed at ${stage}.`
     );
   }
@@ -130,7 +240,7 @@ function createEvidence() {
   return { domInputEvents: 0, stages: [], verified: false };
 }
 function createMetadata(waiverReason) {
-  return { version: 4, waiverReason, evidence: createEvidence() };
+  return { version: 5, waiverReason, evidence: createEvidence() };
 }
 function stageLabel(kind, name) {
   return kind === "entered" ? "entered" : `${kind}(${JSON.stringify(name)})`;
@@ -166,6 +276,7 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
     async ({ annotate, expect, onTestFailed, signal }) => {
       metadata.evidence = createEvidence();
       metadata.trace = void 0;
+      metadata.failure = void 0;
       const evidence = metadata.evidence;
       let entered = false;
       let finished = false;
@@ -174,9 +285,12 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
       let stepTrace;
       let failureTraceFactory;
       let acceptingStageInput = false;
+      let activeStageTargetedCanvas = false;
       let inputCaptureAttached = false;
-      const recordInput = () => {
-        if (acceptingStageInput) evidence.domInputEvents += 1;
+      const recordInput = (event) => {
+        if (!acceptingStageInput) return;
+        evidence.domInputEvents += 1;
+        activeStageTargetedCanvas ||= eventTargetsCanvas(event);
       };
       const stopInputCapture = () => {
         acceptingStageInput = false;
@@ -193,8 +307,12 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
           return "stages=none";
         }
       };
-      onTestFailed(() => {
+      onTestFailed(({ task }) => {
         metadata.trace ??= captureFailureTrace();
+        metadata.failure = appendCurrentAttemptFailures(
+          metadata.failure,
+          task.result?.errors ?? []
+        );
       });
       for (const event of INPUT_EVENTS) {
         document.addEventListener(event, recordInput, true);
@@ -204,7 +322,8 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
       try {
         const view = render(element);
         if (view.container.childNodes.length === 0) {
-          throw new Error(
+          throw codedError(
+            "PRODUCTION_ENTRY_NOT_RENDERED",
             "playthroughTest must render the production game entry."
           );
         }
@@ -233,29 +352,42 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
         const executeStage = async (name, kind, stage) => {
           const normalizedName = name.trim();
           if (normalizedName.length === 0) {
-            throw new Error("playthrough stage names must be non-empty strings.");
+            throw codedError(
+              "INVALID_STAGE_NAME",
+              "playthrough stage names must be non-empty strings."
+            );
           }
           if (evidence.stages.some(
             (completed) => completed.name === normalizedName
           )) {
-            throw new Error(
+            throw codedError(
+              "DUPLICATE_STAGE_NAME",
               `playthrough stage ${JSON.stringify(normalizedName)} may only be recorded once.`
             );
           }
           if (kind === "milestone" && ["entered", "progress", "terminal"].includes(normalizedName)) {
-            throw new Error(
+            throw codedError(
+              "RESERVED_STAGE_NAME",
               `milestone name ${JSON.stringify(normalizedName)} is reserved; use a game-domain name such as "first-point" or "boss-entered".`
             );
           }
           const before = lastSample ?? sampleState(`before ${normalizedName}`);
           activeStage = { name: normalizedName, kind, before };
           stepTrace = { bound: stage.maxSteps ?? 120 };
+          if (stage.step && !playthroughOptions?.observe) {
+            throw codedError(
+              "AUTHORITATIVE_OBSERVE_REQUIRED_FOR_STEP",
+              `${stageLabel(kind, normalizedName)} uses deterministic step advancement without an authoritative observe callback. Time- or frame-driven stages must observe the same production Controller that <App /> renders through Telemetry; DOM labels alone are not deterministic gameplay state.`
+            );
+          }
           if (stage.until()) {
-            throw new Error(
+            throw codedError(
+              "STAGE_OUTCOME_ALREADY_REACHED",
               `${stageLabel(kind, normalizedName)} until condition must be false before its driver runs. Wait for a result caused by this stage, not state left by an earlier stage.`
             );
           }
           const inputsBefore = evidence.domInputEvents;
+          activeStageTargetedCanvas = false;
           if (stage.act) {
             acceptingStageInput = true;
             try {
@@ -264,10 +396,17 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
               acceptingStageInput = false;
             }
             if (evidence.domInputEvents === inputsBefore) {
-              throw new Error(
+              throw codedError(
+                "PRODUCTION_INPUT_NOT_DISPATCHED",
                 `${stageLabel(kind, normalizedName)} act did not dispatch a supported production DOM input. Use the provided user to click, type, press, point, or touch the production target; do not call Controller commands directly.`
               );
             }
+            if (activeStageTargetedCanvas && !playthroughOptions?.observe) {
+              throw codedError(
+                "AUTHORITATIVE_OBSERVE_REQUIRED_FOR_CANVAS",
+                `${stageLabel(kind, normalizedName)} dispatched production input to Canvas without an authoritative observe callback. Canvas pixels and control labels are not gameplay state; observe the same production Controller that <App /> renders through Telemetry.`
+              );
+            }
           }
           let advancedSteps = 0;
           const stepBound = stage.maxSteps ?? 120;
@@ -283,7 +422,8 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
           });
           stepTrace = { bound: stepBound, completed: steps };
           if (!stage.act && advancedSteps === 0) {
-            throw new Error(
+            throw codedError(
+              "AUTONOMOUS_STAGE_NOT_ADVANCED",
               `${stageLabel(kind, normalizedName)} did not execute its deterministic step. Autonomous stages must advance production time or frames at least once.`
             );
           }
@@ -291,14 +431,16 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
           await stage.assert({ expect, user, view });
           const assertions = expect.getState().assertionCalls - assertionsBefore;
           if (assertions === 0) {
-            throw new Error(
+            throw codedError(
+              "STAGE_ASSERTION_MISSING",
               `${stageLabel(kind, normalizedName)} assert must call the expect provided by playthroughTest at least once.`
             );
           }
           const after = sampleState(`after ${normalizedName}`);
           if (after.fingerprint === before.fingerprint) {
             const source = playthroughOptions?.observe ? "authoritative observe() state" : "production DOM";
-            throw new Error(
+            throw codedError(
+              "STAGE_STATE_UNCHANGED",
               `${stageLabel(kind, normalizedName)} did not change the ${source} from the previous stage. Each milestone must prove a new gameplay result.`
             );
           }
@@ -320,27 +462,27 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
           user,
           async enter(stage) {
             if (entered) {
-              throw new Error("enter may only be called once.");
+              throw codedError("INVALID_STAGE_ORDER", "enter may only be called once.");
             }
             if (evidence.stages.length > 0) {
-              throw new Error("enter must be the first playthrough stage.");
+              throw codedError("INVALID_STAGE_ORDER", "enter must be the first playthrough stage.");
             }
             await executeStage("entered", "entered", stage);
             entered = true;
           },
           async milestone(name, stage) {
             if (!entered) {
-              throw new Error("milestone must follow enter.");
+              throw codedError("INVALID_STAGE_ORDER", "milestone must follow enter.");
             }
             if (finished) {
-              throw new Error("milestone cannot run after finish.");
+              throw codedError("INVALID_STAGE_ORDER", "milestone cannot run after finish.");
             }
             await executeStage(name, "milestone", stage);
           },
           async finish(name, stage) {
-            if (!entered) throw new Error("finish must follow enter.");
+            if (!entered) throw codedError("INVALID_STAGE_ORDER", "finish must follow enter.");
             if (finished) {
-              throw new Error("finish may only be called once.");
+              throw codedError("INVALID_STAGE_ORDER", "finish may only be called once.");
             }
             await executeStage(name, stage.kind, stage);
             finished = true;
@@ -349,19 +491,22 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
         const milestones = evidence.stages.filter(
           (stage) => stage.kind === "milestone"
         );
-        if (!entered) throw new Error("playthroughTest must call enter once.");
+        if (!entered) throw codedError("INCOMPLETE_PLAYTHROUGH_EVIDENCE", "playthroughTest must call enter once.");
         if (milestones.length < MIN_MILESTONES) {
-          throw new Error(
+          throw codedError(
+            "INCOMPLETE_PLAYTHROUGH_EVIDENCE",
             `playthroughTest requires at least ${MIN_MILESTONES} named gameplay milestones between enter and finish; received ${milestones.length}.`
           );
         }
         if (!finished) {
-          throw new Error(
+          throw codedError(
+            "INCOMPLETE_PLAYTHROUGH_EVIDENCE",
             'playthroughTest must call finish with kind "progress" or "terminal".'
           );
         }
         if (evidence.stages.length < MIN_STAGES) {
-          throw new Error(
+          throw codedError(
+            "INCOMPLETE_PLAYTHROUGH_EVIDENCE",
             `playthroughTest requires at least ${MIN_STAGES} evidenced stages: enter, ${MIN_MILESTONES} named milestones, and finish.`
           );
         }
@@ -369,6 +514,7 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
       } catch (error) {
         const trace = captureFailureTrace();
         metadata.trace = trace;
+        metadata.failure = createFailureDiagnostic("playthrough", error);
         try {
           await annotate(trace, REACT_PLAYTHROUGH_TRACE_ANNOTATION);
         } catch {
@@ -447,10 +593,18 @@ function auditReactPlaythroughRun(tests) {
 
 // src/react/react-playthrough-reporter.ts
 var PRODUCTION_PLAYTHROUGH_FILE = "tests/production-playthrough.test.tsx";
+var REPAIR_CONSTRAINT = "Preserve the intended gameplay outcome. Fix the production mechanic, deterministic driver, or authoritative observation that prevents it. Do not make the test pass by weakening or deleting assertions, replacing the outcome with back/menu/exit navigation, observing arbitrary UI text only to change a fingerprint, using a no-op step, or treating an intermediate active/in-flight/running phase as meaningful progress.";
 function isMetadata(value) {
   if (!value || typeof value !== "object") return false;
   const metadata = value;
-  if (metadata.version !== 4) return false;
+  if (metadata.version !== 5) return false;
+  if (metadata.failure !== void 0) {
+    if (!metadata.failure || typeof metadata.failure !== "object" || typeof metadata.failure.source !== "string" || !Array.isArray(metadata.failure.entries) || !metadata.failure.entries.every(
+      (entry) => Boolean(entry) && typeof entry === "object" && typeof entry.code === "string" && typeof entry.message === "string"
+    )) {
+      return false;
+    }
+  }
   const evidence = metadata.evidence;
   if (!evidence || typeof evidence !== "object") return false;
   return typeof evidence.domInputEvents === "number" && Array.isArray(evidence.stages) && typeof evidence.verified === "boolean" && evidence.stages.every(
@@ -465,10 +619,72 @@ function toAuditInput(test2) {
     metadata: isMetadata(metadata) ? metadata : void 0
   };
 }
+function findPendingProductTests(modules, projectRoot) {
+  return modules.flatMap((module) => {
+    const file = relative(projectRoot, module.moduleId).replaceAll("\\", "/");
+    if (file.split("/").includes("examples")) return [];
+    const tests = [...module.children.allTests()];
+    const pending = tests.filter((test2) => {
+      const mode = test2.options.mode;
+      if (mode !== "todo" && mode !== "skip") return false;
+      const metadata = test2.meta().reactPlaythrough;
+      const approvedWaiver = mode === "skip" && isMetadata(metadata) && Boolean(metadata.waiverReason);
+      return !approvedWaiver;
+    });
+    const fileOnlyContainsPendingTests = tests.length > 0 && pending.length === tests.length;
+    return pending.map((test2) => ({
+      file,
+      test: test2.fullName,
+      mode: test2.options.mode,
+      fileOnlyContainsPendingTests
+    }));
+  });
+}
+function formatPendingProductTestReport(pending) {
+  if (pending.length === 0) return void 0;
+  const lines = [
+    "REACT_FOCUSED_TESTS: FAILED",
+    "CAUSE_CODE: TODO_OR_SKIP_TESTS",
+    "CAUSE: Product tests still contain explicit todo/skip cases."
+  ];
+  const reportedIncompleteFiles = /* @__PURE__ */ new Set();
+  for (const item of pending) {
+    if (item.fileOnlyContainsPendingTests && !reportedIncompleteFiles.has(item.file)) {
+      lines.push("FILE_CAUSE_CODE: PRODUCT_TEST_FILE_NOT_IMPLEMENTED");
+      lines.push(
+        `FILE_CAUSE: Every collected test in ${item.file} is marked todo/skip.`
+      );
+      reportedIncompleteFiles.add(item.file);
+    }
+    lines.push(`FILE: ${item.file}`);
+    lines.push(`TEST: ${item.test}`);
+    lines.push(`MODE: ${item.mode}`);
+  }
+  lines.push(
+    "NEXT: Implement each focused product test or delete a genuinely inapplicable slot. Do not replace todo with skip."
+  );
+  return `
+${lines.join("\n")}`;
+}
 function firstLine(value) {
   if (typeof value !== "string") return void 0;
   return stripVTControlCharacters(value).split("\n").map((line) => line.trim()).find(Boolean);
 }
+function selectReactFailure(values, errorRecordCount = values.length) {
+  const entries = extractFailureEntries(values);
+  if (entries.length === 0) {
+    return {
+      code: "MISSING_FAILURE_DETAILS",
+      cause: `Vitest marked this test as failed but returned no readable message in ${errorRecordCount} error record${errorRecordCount === 1 ? "" : "s"}.`,
+      rawCause: "",
+      related: []
+    };
+  }
+  const primary = entries[0];
+  const rawCause = primary.message;
+  const cause = firstLine(rawCause) ?? rawCause;
+  return { code: primary.code, cause, rawCause, related: entries.slice(1) };
+}
 function failureHint(value) {
   const names = [...value.matchAll(/button\s*\n\s*Name "([^"]+)"/g)].map(
     (match) => match[1]
@@ -502,30 +718,45 @@ function truncateReporterLine(value, limit) {
 }
 function toModuleResult(module, projectRoot) {
   const tests = [...module.children.allTests()];
-  const moduleErrors = module.errors().map((error) => firstLine(error.message)).filter((message) => Boolean(message));
+  const moduleFailure = selectReactFailure(module.errors(), module.errors().length);
+  const moduleErrors = extractFailureEntries(module.errors()).map(
+    (entry) => firstLine(entry.message) ?? entry.message
+  );
   const errors = [
     ...moduleErrors,
     ...tests.flatMap(
-      (test2) => (test2.result().errors ?? []).map((error) => firstLine(error.message))
+      (test2) => extractFailureEntries(test2.result().errors ?? []).map(
+        (entry) => firstLine(entry.message) ?? entry.message
+      )
     )
-  ].filter((message) => Boolean(message));
+  ];
   const failures = tests.filter((test2) => test2.result().state === "failed").map((test2) => {
-    const raw = test2.result().errors?.at(-1)?.message ?? module.errors()[0]?.message ?? "Unknown failure";
+    const metadata = test2.meta().reactPlaythrough;
+    const testErrors = test2.result().errors ?? [];
+    const metadataErrors = isMetadata(metadata) ? metadata.failure?.entries ?? [] : [];
+    const attemptErrors = metadataErrors.length > 0 ? metadataErrors : testErrors;
+    const selected = selectReactFailure(
+      [...attemptErrors, ...module.errors()],
+      testErrors.length + module.errors().length
+    );
     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),
+      causeCode: selected.code,
+      cause: selected.cause,
+      related: selected.related,
+      location: test2.location ? `${relative(projectRoot, module.moduleId).replaceAll("\\", "/")}:${test2.location.line}:${test2.location.column}` : errorLocation(selected.rawCause),
+      hint: failureHint(selected.rawCause),
       trace: failureTrace(test2)
     };
   });
   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)
+      causeCode: moduleFailure.code,
+      cause: moduleFailure.cause,
+      related: moduleFailure.related,
+      location: errorLocation(moduleFailure.rawCause),
+      hint: failureHint(moduleFailure.rawCause)
     });
   }
   return {
@@ -533,6 +764,8 @@ function toModuleResult(module, projectRoot) {
     state: module.state(),
     errors,
     primaryError: moduleErrors[0] ?? failures[0]?.cause,
+    primaryCauseCode: failures[0]?.causeCode,
+    relatedErrors: failures[0]?.related,
     tests: tests.map(toAuditInput),
     failures
   };
@@ -549,7 +782,14 @@ function formatReactFailureSummary(modules) {
   for (const [index, failure] of failures.entries()) {
     lines.push(`FAILURE_${index + 1}: ${failure.file}`);
     lines.push(`TEST: ${failure.test}`);
+    lines.push(`CAUSE_CODE: ${failure.causeCode ?? "TEST_FAILURE"}`);
     lines.push(`CAUSE: ${failure.cause}`);
+    for (const [relatedIndex, related] of (failure.related ?? []).entries()) {
+      lines.push(`RELATED_${relatedIndex + 1}_CODE: ${related.code}`);
+      lines.push(
+        `RELATED_${relatedIndex + 1}: ${firstLine(related.message) ?? related.message}`
+      );
+    }
     if (failure.trace) lines.push(`TRACE: ${failure.trace}`);
     if (failure.location) lines.push(`AT: ${failure.location}`);
     if (failure.hint) lines.push(`HINT: ${failure.hint}`);
@@ -557,26 +797,36 @@ function formatReactFailureSummary(modules) {
   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 (/until condition must be false before its driver runs/i.test(cause)) {
-    return "Make this stage's until condition describe a new result that does not exist before act or step runs. Do not reuse state completed by an earlier milestone.";
-  }
-  if (/did not change the (?:authoritative observe\(\) state|production DOM)/i.test(cause)) {
-    return "The stage ran and asserted, but its observable state matched the previous milestone. Wait for a genuinely new gameplay result. Canvas or Controller games should make observe read the same production Controller that React renders.";
-  }
-  if (/No step callback was provided/i.test(cause)) {
-    return "This stage is driven by time or frames, but it 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 stage driver ran, but gameplay did not reach the outcome within the bound. Confirm that its production input or deterministic step changed the intended rule state, then inspect Last diagnostics to locate the stalled stage.";
+function repairGuidance(code) {
+  switch (code) {
+    case "GAME_SNAPSHOT_REFERENCE_REUSED":
+      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.";
+    case "AUTHORITATIVE_OBSERVE_REQUIRED_FOR_STEP":
+      return "This stage advances production time or frames, so DOM text is not a sufficient state boundary. Keep the intended outcome, inject ManualGameClock through the production <App /> factory, and make observe read the same production Controller through Telemetry. Do not remove step or replace the outcome with an immediate UI transition.";
+    case "AUTHORITATIVE_OBSERVE_REQUIRED_FOR_CANVAS":
+      return "The player input reached the production Canvas, but JSDOM cannot verify its pixels. Keep the real Canvas input and make observe read the authoritative state from the same production Controller rendered by <App /> through Telemetry. Do not replace Canvas input with a test-only Controller command or button-label assertion.";
+    case "STAGE_OUTCOME_ALREADY_REACHED":
+      return "Make this stage's until condition describe a new result that does not exist before act or step runs. Do not reuse state completed by an earlier milestone.";
+    case "STAGE_STATE_UNCHANGED":
+      return "The stage ran and asserted, but its observable state matched the previous milestone. Preserve the intended gameplay result and observe the same production Controller rendered by <App />. Do not substitute arbitrary labels or a weaker state change.";
+    case "PLAYTHROUGH_BOUND_EXHAUSTED":
+      return "Keep the intended outcome unchanged. The stage driver ran, but gameplay did not reach it within the bound. Inspect TRACE and Last diagnostics, then confirm that each deterministic step advances the same production Controller rendered by <App />. If state remains unchanged, inject ManualGameClock through the production App factory and observe that Controller through Telemetry. Do not replace the outcome with navigation, an intermediate phase, a no-op step, or a weaker assertion.";
+    case "PLAYTHROUGH_CLOCK_NOT_ADVANCED":
+      return "This stage is driven by time or frames, but it 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.";
+    case "INVALID_STAGE_ORDER":
+    case "INCOMPLETE_PLAYTHROUGH_EVIDENCE":
+    case "INVALID_STAGE_NAME":
+    case "DUPLICATE_STAGE_NAME":
+    case "RESERVED_STAGE_NAME":
+    case "PRODUCTION_INPUT_NOT_DISPATCHED":
+    case "AUTONOMOUS_STAGE_NOT_ADVANCED":
+    case "STAGE_ASSERTION_MISSING":
+      return "Compose one enter stage, at least three named gameplay milestones, and one finish stage. Enter must drive real DOM input; each later stage must drive input or deterministic steps. Every stage waits for a bounded new result and asserts it with the provided expect.";
+    case "MISSING_FAILURE_DETAILS":
+      return "Vitest reported a failed task without a readable serialized error. Inspect the RELATED records and rerun the focused file with the verbose reporter if no details are present.";
+    default:
+      return "Fix the first reported CAUSE, then rerun the same test. RELATED entries preserve the remaining Vitest errors in their original order.";
   }
-  if (/enter|milestone|finish|stage| act | assert /.test(cause)) {
-    return "Compose one enter stage, at least three named gameplay milestones, and one finish stage. Enter must drive real DOM input; each later stage must drive input or deterministic steps. Every stage waits for a bounded new result and asserts it with the provided expect.";
-  }
-  return "Start from the production entry and describe the real game as enter, named milestones, and finish. Enter must act through production input; later stages may act or step. Every stage waits for and asserts a new player-visible or authoritative result. Do not jump to an internal level or mutate gameplay state.";
 }
 function assessReactPlaythroughReport(input) {
   const base = { file: input.expectedFile };
@@ -592,6 +842,7 @@ function assessReactPlaythroughReport(input) {
     return {
       ...base,
       status: "FAILED",
+      causeCode: "MISSING_PRODUCTION_PLAYTHROUGH",
       cause: "The required production playthrough test file does not exist.",
       next: "Create the file and render <App />. Compose one real-input enter stage, at least three named gameplay milestones, and one finish stage. Later stages may drive production input or deterministic advancement; every stage must reach and assert a bounded new result.",
       failsRun: true
@@ -615,6 +866,7 @@ function assessReactPlaythroughReport(input) {
     return {
       ...base,
       status: "NOT_RUN",
+      causeCode: productionModule?.primaryCauseCode ?? "TEST_NOT_RUN",
       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
@@ -627,8 +879,12 @@ function assessReactPlaythroughReport(input) {
     return {
       ...base,
       status: "FAILED",
+      causeCode: productionModule.primaryCauseCode ?? "INCOMPLETE_PLAYTHROUGH_EVIDENCE",
       cause,
-      next: repairGuidance(cause),
+      related: productionModule.relatedErrors,
+      next: repairGuidance(
+        productionModule.primaryCauseCode ?? "INCOMPLETE_PLAYTHROUGH_EVIDENCE"
+      ),
       failsRun: true
     };
   }
@@ -644,11 +900,21 @@ function assessReactPlaythroughReport(input) {
 }
 function formatReactPlaythroughReport(report) {
   const lines = [`REACT_PLAYTHROUGH: ${report.status}`, `FILE: ${report.file}`];
+  if (report.causeCode) lines.push(`CAUSE_CODE: ${report.causeCode}`);
   if (report.cause) lines.push(`CAUSE: ${report.cause}`);
+  for (const [index, related] of (report.related ?? []).entries()) {
+    lines.push(`RELATED_${index + 1}_CODE: ${related.code}`);
+    lines.push(
+      `RELATED_${index + 1}: ${firstLine(related.message) ?? related.message}`
+    );
+  }
   if (report.waiverReasons?.length) {
     lines.push(`REASON: ${report.waiverReasons.join("; ")}`);
   }
   if (report.next) lines.push(`NEXT: ${report.next}`);
+  if (report.status === "FAILED") {
+    lines.push(`REPAIR_CONSTRAINT: ${REPAIR_CONSTRAINT}`);
+  }
   return `
 ${lines.join("\n")}`;
 }
@@ -674,6 +940,10 @@ var ReactPlaythroughReporter = class {
   }
   /** 测试运行结束后执行项目级主流程门禁，并写入最终退出码。 */
   onTestRunEnd(testModules, unhandledErrors) {
+    const pendingProductTests = findPendingProductTests(
+      testModules,
+      this.projectRoot
+    );
     const report = assessReactPlaythroughReport({
       expectedFile: this.expectedFile,
       expectedFileExists: existsSync(this.expectedModuleId),
@@ -682,7 +952,9 @@ var ReactPlaythroughReporter = class {
       modules: testModules.map(
         (module) => toModuleResult(module, this.projectRoot)
       ),
-      unhandledErrors: unhandledErrors.map((error) => firstLine(error.message)).filter((message) => Boolean(message))
+      unhandledErrors: extractFailureEntries(unhandledErrors).map(
+        (entry) => firstLine(entry.message) ?? entry.message
+      )
     });
     const output = formatReactPlaythroughReport(report);
     if (report.failsRun) {
@@ -693,10 +965,15 @@ var ReactPlaythroughReporter = class {
     } else {
       console.log(output);
     }
+    const pendingOutput = formatPendingProductTestReport(pendingProductTests);
+    if (pendingOutput) {
+      console.error(pendingOutput);
+      process.exitCode = 1;
+    }
     const summary = formatReactFailureSummary(
       testModules.map((module) => toModuleResult(module, this.projectRoot))
     );
-    if (report.failsRun && summary[0] === "TEST_RESULT: PASS") {
+    if ((report.failsRun || pendingProductTests.length > 0) && summary[0] === "TEST_RESULT: PASS") {
       summary[0] = "TEST_RESULT: FAIL";
     }
     console.log(`