miaoda-game-devkit 0.6.2 → 0.6.4

package/dist/react/vitest-config.mjs

@@ -1,26 +1,357 @@
 // src/react-vitest-config.ts
-import { existsSync as existsSync2, readFileSync } from "fs";
-import { dirname, resolve as resolve2 } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import { dirname as dirname2, resolve as resolve3 } from "path";
 import { defineConfig } from "vitest/config";
 
 // src/react/react-playthrough-reporter.ts
-import { existsSync } from "fs";
-import { relative, resolve } from "path";
+import { existsSync as existsSync2 } from "fs";
+import { relative as relative2, resolve as resolve2 } from "path";
 import { stripVTControlCharacters } from "util";
 
+// src/cli/react-authoritative-playthrough.ts
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { dirname, join, relative, resolve, sep } from "path";
+var PRODUCTION_PLAYTHROUGH = "tests/production-playthrough.test.tsx";
+var PRODUCTION_APP = "src/App.tsx";
+var EXAMPLE_IMPORT_PREFIX = "@/game/example/";
+var REACT_RUNTIME_ENTRY = "miaoda-game-devkit/react";
+var REACT_TESTING_ENTRY = "miaoda-game-devkit/react/testing";
+var CLOCK_IMPORTS = /* @__PURE__ */ new Set(["browserGameClock"]);
+var CONTROLLER_IMPORTS = /* @__PURE__ */ new Set([
+  "useGameController",
+  "useOwnedGameController"
+]);
+var SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([".js", ".jsx", ".ts", ".tsx"]);
+function runnableTestFiles(root, directory = join(root, "tests")) {
+  if (!existsSync(directory)) return [];
+  const files = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...runnableTestFiles(root, path));
+    } else if (entry.isFile() && /\.test\.[cm]?[jt]sx?$/.test(entry.name)) {
+      files.push(path);
+    }
+  }
+  return files;
+}
+function extension(path) {
+  const index = path.lastIndexOf(".");
+  return index < 0 ? "" : path.slice(index);
+}
+function sourceFiles(root, directory = join(root, "src")) {
+  if (!existsSync(directory)) return [];
+  const files = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    const projectPath = relative(root, path).replaceAll("\\", "/");
+    if (entry.isDirectory()) {
+      if (projectPath === "src/game/example") continue;
+      files.push(...sourceFiles(root, path));
+    } else if (entry.isFile() && SOURCE_EXTENSIONS.has(extension(entry.name))) {
+      files.push(path);
+    }
+  }
+  return files;
+}
+function withoutComments(source) {
+  let output = "";
+  let state = "code";
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index];
+    const next = source[index + 1];
+    if (state === "line") {
+      if (char === "\n") {
+        state = "code";
+        output += char;
+      } else {
+        output += " ";
+      }
+      continue;
+    }
+    if (state === "block") {
+      if (char === "*" && next === "/") {
+        output += "  ";
+        index += 1;
+        state = "code";
+      } else {
+        output += char === "\n" ? "\n" : " ";
+      }
+      continue;
+    }
+    if (state === "code" && char === "/" && next === "/") {
+      output += "  ";
+      index += 1;
+      state = "line";
+      continue;
+    }
+    if (state === "code" && char === "/" && next === "*") {
+      output += "  ";
+      index += 1;
+      state = "block";
+      continue;
+    }
+    if (state === "code" && char === "'") state = "single";
+    else if (state === "code" && char === '"') state = "double";
+    else if (state === "code" && char === "`") state = "template";
+    else if (state === "single" && char === "'" && source[index - 1] !== "\\") {
+      state = "code";
+    } else if (state === "double" && char === '"' && source[index - 1] !== "\\") {
+      state = "code";
+    } else if (state === "template" && char === "`" && source[index - 1] !== "\\") {
+      state = "code";
+    }
+    output += char;
+  }
+  return output;
+}
+function codePositions(source) {
+  const positions = Array.from({ length: source.length }, () => false);
+  let state = "code";
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index];
+    if (state === "code") positions[index] = true;
+    if (state === "code" && char === "'") state = "single";
+    else if (state === "code" && char === '"') state = "double";
+    else if (state === "code" && char === "`") state = "template";
+    else if (state === "single" && char === "'" && source[index - 1] !== "\\") {
+      state = "code";
+    } else if (state === "double" && char === '"' && source[index - 1] !== "\\") {
+      state = "code";
+    } else if (state === "template" && char === "`" && source[index - 1] !== "\\") {
+      state = "code";
+    }
+  }
+  return positions;
+}
+function importedModuleSpecifiers(source) {
+  const clean = withoutComments(source);
+  const positions = codePositions(clean);
+  const modules = [];
+  const pattern = /\b(?:from\s+|import\s*(?:\(\s*)?)["']([^"']+)["']\s*\)?/g;
+  for (const match of clean.matchAll(pattern)) {
+    if (positions[match.index]) modules.push(match[1]);
+  }
+  return modules;
+}
+function productionFileImportsExample(file, projectRoot) {
+  const exampleRoot = join(projectRoot, "src/game/example");
+  return importedModuleSpecifiers(readFileSync(file, "utf8")).some(
+    (moduleName) => {
+      if (moduleName.startsWith(EXAMPLE_IMPORT_PREFIX)) return true;
+      if (!moduleName.startsWith(".")) return false;
+      const target = resolve(dirname(file), moduleName);
+      return target === exampleRoot || target.startsWith(`${exampleRoot}${sep}`);
+    }
+  );
+}
+function importsExampleAlias(source) {
+  return importedModuleSpecifiers(source).some(
+    (moduleName) => moduleName.startsWith(EXAMPLE_IMPORT_PREFIX)
+  );
+}
+function namedImports(source, moduleName) {
+  const names = /* @__PURE__ */ new Set();
+  const clean = withoutComments(source);
+  const positions = codePositions(clean);
+  const escapedModule = moduleName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(
+    `^\\s*import\\s+(?:type\\s+)?\\{([\\s\\S]*?)\\}\\s+from\\s+["']${escapedModule}["']`,
+    "gm"
+  );
+  for (const match of clean.matchAll(pattern)) {
+    if (!positions[match.index]) continue;
+    for (const specifier of match[1].split(",")) {
+      const imported = specifier.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0].trim();
+      if (imported) names.add(imported);
+    }
+  }
+  return names;
+}
+function containsAny(values, expected) {
+  return [...values].some((value) => expected.has(value));
+}
+function declaresObserve(source) {
+  const clean = withoutComments(source);
+  const positions = codePositions(clean);
+  for (const match of clean.matchAll(/\bobserve\s*:/g)) {
+    if (positions[match.index]) return true;
+  }
+  return false;
+}
+function auditReactAuthoritativePlaythrough(projectRoot) {
+  const clockFiles = [];
+  const controllerFiles = [];
+  const productionFiles = sourceFiles(projectRoot);
+  for (const file of productionFiles) {
+    const imports = namedImports(
+      readFileSync(file, "utf8"),
+      REACT_RUNTIME_ENTRY
+    );
+    const projectPath = relative(projectRoot, file).replaceAll("\\", "/");
+    if (containsAny(imports, CLOCK_IMPORTS)) clockFiles.push(projectPath);
+    if (containsAny(imports, CONTROLLER_IMPORTS))
+      controllerFiles.push(projectPath);
+  }
+  const appPath = join(projectRoot, PRODUCTION_APP);
+  const productionEntryExists = existsSync(appPath);
+  const productionUsesExample = productionFiles.some(
+    (file) => productionFileImportsExample(file, projectRoot)
+  );
+  const staleExampleTestFiles = productionUsesExample ? [] : runnableTestFiles(projectRoot).filter((file) => importsExampleAlias(readFileSync(file, "utf8"))).map((file) => relative(projectRoot, file).replaceAll("\\", "/"));
+  const issues = [];
+  if (staleExampleTestFiles.length > 0) {
+    issues.push(
+      `Production ${PRODUCTION_APP} no longer imports ${EXAMPLE_IMPORT_PREFIX}*, but runnable product tests still do: ${staleExampleTestFiles.join(", ")}. Replace those CollectGame tests with tests for the production game or delete genuinely inapplicable slots. Teaching examples under tests/examples/**/*.example.* remain allowed.`
+    );
+  }
+  if (clockFiles.length === 0 && controllerFiles.length === 0) {
+    return {
+      ok: issues.length === 0,
+      issues,
+      clockFiles,
+      controllerFiles,
+      productionEntryExists,
+      productionUsesExample,
+      staleExampleTestFiles
+    };
+  }
+  const testPath = join(projectRoot, PRODUCTION_PLAYTHROUGH);
+  const testSource = existsSync(testPath) ? readFileSync(testPath, "utf8") : "";
+  const testingImports = namedImports(testSource, REACT_TESTING_ENTRY);
+  const hasObserve = declaresObserve(testSource);
+  if (!hasObserve) {
+    issues.push(
+      `${PRODUCTION_PLAYTHROUGH} must declare observe because production uses the devkit clock or Controller ownership hook. Observe the same production Controller rendered by <App /> through Telemetry; DOM labels are not an authoritative gameplay boundary.`
+    );
+  }
+  if (clockFiles.length > 0 && !testingImports.has("ManualGameClock")) {
+    issues.push(
+      `${PRODUCTION_PLAYTHROUGH} must import ManualGameClock because production owns gameplay time in ${clockFiles.join(", ")}. Inject it through the production <App /> factory and advance it with a non-empty deterministic step.`
+    );
+  }
+  return {
+    ok: issues.length === 0,
+    issues,
+    clockFiles,
+    controllerFiles,
+    productionEntryExists,
+    productionUsesExample,
+    staleExampleTestFiles
+  };
+}
+
 // src/react/react-playthrough.ts
 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 +367,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 +377,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 +395,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}`
   );
 }
@@ -115,14 +449,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}.`
     );
   }
@@ -135,7 +473,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)})`;
@@ -171,6 +509,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;
@@ -201,8 +540,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);
@@ -212,7 +555,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."
           );
         }
@@ -241,17 +585,22 @@ 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".`
             );
           }
@@ -259,12 +608,14 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
           activeStage = { name: normalizedName, kind, before };
           stepTrace = { bound: stage.maxSteps ?? 120 };
           if (stage.step && !playthroughOptions?.observe) {
-            throw new Error(
+            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.`
             );
           }
@@ -278,12 +629,14 @@ 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 new Error(
+              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.`
               );
             }
@@ -302,7 +655,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.`
             );
           }
@@ -310,14 +664,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.`
             );
           }
@@ -339,27 +695,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;
@@ -368,19 +724,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.`
           );
         }
@@ -388,6 +747,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 {
@@ -467,10 +827,36 @@ 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 assessProductTestAlignment(projectRoot) {
+  const audit = auditReactAuthoritativePlaythrough(projectRoot);
+  if (audit.staleExampleTestFiles.length > 0) {
+    return { status: "FAILED", cause: audit.issues[0] };
+  }
+  if (!audit.productionEntryExists) {
+    return {
+      status: "NOT_VERIFIED",
+      cause: "The production src/App.tsx entry does not exist, so product-test alignment could not be verified."
+    };
+  }
+  if (audit.productionUsesExample) {
+    return {
+      status: "NOT_VERIFIED",
+      cause: "The production App still uses the replaceable src/game/example teaching game, so replacement-game test alignment is not applicable yet."
+    };
+  }
+  return { status: "PASS" };
+}
 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(
@@ -485,10 +871,72 @@ function toAuditInput(test2) {
     metadata: isMetadata(metadata) ? metadata : void 0
   };
 }
+function findPendingProductTests(modules, projectRoot) {
+  return modules.flatMap((module) => {
+    const file = relative2(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]
@@ -522,37 +970,57 @@ 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 ? `${relative2(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 {
-    file: relative(projectRoot, module.moduleId).replaceAll("\\", "/"),
+    file: relative2(projectRoot, module.moduleId).replaceAll("\\", "/"),
     state: module.state(),
     errors,
     primaryError: moduleErrors[0] ?? failures[0]?.cause,
+    primaryCauseCode: failures[0]?.causeCode,
+    relatedErrors: failures[0]?.related,
     tests: tests.map(toAuditInput),
     failures
   };
@@ -569,7 +1037,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}`);
@@ -577,32 +1052,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 (/deterministic step advancement without an authoritative observe callback/i.test(cause)) {
-    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.";
-  }
-  if (/production input to Canvas without an authoritative observe callback/i.test(cause)) {
-    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.";
-  }
-  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. Preserve the intended gameplay result and observe that result directly. Canvas or Controller games should make observe read the same production Controller that React renders. Do not substitute arbitrary labels, button visibility, navigation, or another weaker state change merely to produce a different fingerprint.";
-  }
-  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.";
+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 (/outcome was not reached within \d+ steps/i.test(cause)) {
-    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.";
-  }
-  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 };
@@ -618,6 +1097,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
@@ -641,6 +1121,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
@@ -653,8 +1134,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
     };
   }
@@ -668,9 +1153,21 @@ function assessReactPlaythroughReport(input) {
   }
   return { ...base, status: "PASS", failsRun: false };
 }
-function formatReactPlaythroughReport(report) {
-  const lines = [`REACT_PLAYTHROUGH: ${report.status}`, `FILE: ${report.file}`];
+function formatReactPlaythroughReport(report, alignment) {
+  const lines = [
+    `REACT_PLAYTHROUGH_STRUCTURE: ${report.status}`,
+    `PRODUCT_TEST_ALIGNMENT: ${alignment?.status ?? "NOT_VERIFIED"}`,
+    `FILE: ${report.file}`
+  ];
+  if (alignment?.cause) lines.push(`ALIGNMENT_CAUSE: ${alignment.cause}`);
+  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("; ")}`);
   }
@@ -685,7 +1182,7 @@ var ReactPlaythroughReporter = class {
   /** 绑定模板根目录，以稳定识别生产可玩性测试而不依赖测试名称。 */
   constructor(projectRoot) {
     this.projectRoot = projectRoot;
-    this.expectedModuleId = resolve(projectRoot, this.expectedFile);
+    this.expectedModuleId = resolve2(projectRoot, this.expectedFile);
   }
   projectRoot;
   expectedFile = PRODUCTION_PLAYTHROUGH_FILE;
@@ -695,7 +1192,7 @@ var ReactPlaythroughReporter = class {
   /** 记录本轮是否实际选择了生产流程文件，用于区分聚焦运行与门禁失败。 */
   onTestRunStart(specifications) {
     this.expectedFileScheduled = specifications.some(
-      (specification) => resolve(specification.moduleId) === this.expectedModuleId
+      (specification) => resolve2(specification.moduleId) === this.expectedModuleId
     );
     this.focusedSelection = specifications.some(
       (specification) => Boolean(specification.project.globalConfig.testNamePattern) || Boolean(specification.testNamePattern) || Boolean(specification.testLines?.length)
@@ -703,18 +1200,25 @@ var ReactPlaythroughReporter = class {
   }
   /** 测试运行结束后执行项目级主流程门禁，并写入最终退出码。 */
   onTestRunEnd(testModules, unhandledErrors) {
+    const pendingProductTests = findPendingProductTests(
+      testModules,
+      this.projectRoot
+    );
     const report = assessReactPlaythroughReport({
       expectedFile: this.expectedFile,
-      expectedFileExists: existsSync(this.expectedModuleId),
+      expectedFileExists: existsSync2(this.expectedModuleId),
       expectedFileScheduled: this.expectedFileScheduled,
       focusedSelection: this.focusedSelection,
       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) {
+    const alignment = assessProductTestAlignment(this.projectRoot);
+    const output = formatReactPlaythroughReport(report, alignment);
+    if (report.failsRun || alignment.status === "FAILED") {
       console.error(output);
       process.exitCode = 1;
     } else if (report.status === "WAIVED" || report.status === "NOT_CHECKED") {
@@ -722,10 +1226,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 || alignment.status === "FAILED" || pendingProductTests.length > 0) && summary[0] === "TEST_RESULT: PASS") {
       summary[0] = "TEST_RESULT: FAIL";
     }
     console.log(`
@@ -741,16 +1250,16 @@ function getJSDOMWorkerExecArgv() {
 
 // src/react-vitest-config.ts
 function resolvePhaser3BrowserEntry(projectRoot) {
-  const manifestPath = resolve2(projectRoot, "node_modules/phaser/package.json");
-  if (!existsSync2(manifestPath)) return void 0;
+  const manifestPath = resolve3(projectRoot, "node_modules/phaser/package.json");
+  if (!existsSync3(manifestPath)) return void 0;
   try {
-    const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    const manifest = JSON.parse(readFileSync2(manifestPath, "utf8"));
     if (!manifest.version?.startsWith("3.")) return void 0;
-    const browserEntry = resolve2(
-      dirname(manifestPath),
+    const browserEntry = resolve3(
+      dirname2(manifestPath),
       manifest.browser ?? "dist/phaser.js"
     );
-    return existsSync2(browserEntry) ? browserEntry : void 0;
+    return existsSync3(browserEntry) ? browserEntry : void 0;
   } catch {
     return void 0;
   }
@@ -765,7 +1274,7 @@ function defineReactGameVitestConfig(options) {
       alias: {
         ...phaser3BrowserEntry ? { phaser: phaser3BrowserEntry } : {},
         ...options.aliases,
-        "@": resolve2(options.projectRoot, "src")
+        "@": resolve3(options.projectRoot, "src")
       }
     },
     test: {