miaoda-game-devkit 0.6.4 → 0.6.6

package/dist/react/vitest-config.js

@@ -34,251 +34,12 @@ __export(react_vitest_config_exports, {
 });
 module.exports = __toCommonJS(react_vitest_config_exports);
 var import_node_fs3 = require("fs");
-var import_node_path3 = require("path");
+var import_node_path4 = require("path");
 var import_config = require("vitest/config");
 
 // src/react/react-playthrough-reporter.ts
 var import_node_fs2 = require("fs");
-var import_node_path2 = require("path");
-var import_node_util = require("util");
-
-// src/cli/react-authoritative-playthrough.ts
-var import_node_fs = require("fs");
-var import_node_path = require("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 = (0, import_node_path.join)(root, "tests")) {
-  if (!(0, import_node_fs.existsSync)(directory)) return [];
-  const files = [];
-  for (const entry of (0, import_node_fs.readdirSync)(directory, { withFileTypes: true })) {
-    const path = (0, import_node_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 = (0, import_node_path.join)(root, "src")) {
-  if (!(0, import_node_fs.existsSync)(directory)) return [];
-  const files = [];
-  for (const entry of (0, import_node_fs.readdirSync)(directory, { withFileTypes: true })) {
-    const path = (0, import_node_path.join)(directory, entry.name);
-    const projectPath = (0, import_node_path.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 = (0, import_node_path.join)(projectRoot, "src/game/example");
-  return importedModuleSpecifiers((0, import_node_fs.readFileSync)(file, "utf8")).some(
-    (moduleName) => {
-      if (moduleName.startsWith(EXAMPLE_IMPORT_PREFIX)) return true;
-      if (!moduleName.startsWith(".")) return false;
-      const target = (0, import_node_path.resolve)((0, import_node_path.dirname)(file), moduleName);
-      return target === exampleRoot || target.startsWith(`${exampleRoot}${import_node_path.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(
-      (0, import_node_fs.readFileSync)(file, "utf8"),
-      REACT_RUNTIME_ENTRY
-    );
-    const projectPath = (0, import_node_path.relative)(projectRoot, file).replaceAll("\\", "/");
-    if (containsAny(imports, CLOCK_IMPORTS)) clockFiles.push(projectPath);
-    if (containsAny(imports, CONTROLLER_IMPORTS))
-      controllerFiles.push(projectPath);
-  }
-  const appPath = (0, import_node_path.join)(projectRoot, PRODUCTION_APP);
-  const productionEntryExists = (0, import_node_fs.existsSync)(appPath);
-  const productionUsesExample = productionFiles.some(
-    (file) => productionFileImportsExample(file, projectRoot)
-  );
-  const staleExampleTestFiles = productionUsesExample ? [] : runnableTestFiles(projectRoot).filter((file) => importsExampleAlias((0, import_node_fs.readFileSync)(file, "utf8"))).map((file) => (0, import_node_path.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 = (0, import_node_path.join)(projectRoot, PRODUCTION_PLAYTHROUGH);
-  const testSource = (0, import_node_fs.existsSync)(testPath) ? (0, import_node_fs.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
-var import_react2 = require("@testing-library/react");
-var import_user_event = __toESM(require("@testing-library/user-event"));
-var import_vitest = require("vitest");
+var import_node_path3 = require("path");
 
 // src/react/react-error-diagnostics.ts
 var MAX_DIAGNOSTIC_LENGTH = 1e3;
@@ -306,47 +67,145 @@ function safeJson(value) {
     return void 0;
   }
 }
-function collectEntries(value, fallbackCode, seen) {
+function diagnosticValue(value) {
+  if (value === void 0) return void 0;
+  if (typeof value === "string") {
+    return truncate(value.replace(/\s+/g, " ").trim());
+  }
+  if (value === null || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  if (typeof value === "symbol") return value.toString();
+  if (typeof value === "function") {
+    return `Function<${value.name || "anonymous"}>`;
+  }
+  const json = safeJson(value);
+  return truncate(json ?? String(value));
+}
+function normalizeFile(value) {
+  return value.replaceAll("\\", "/").replace(/^file:\/\//, "");
+}
+function failureLayer(file) {
+  const normalized = normalizeFile(file);
+  if (normalized.includes("/miaoda-game-devkit/") || normalized.includes("/packages/game-devkit/")) {
+    return "harness";
+  }
+  if (normalized.includes("/node_modules/")) return "dependency";
+  if (/(?:^|\/)tests?\//.test(normalized) || /\.(?:test|spec)\.[cm]?[jt]sx?$/.test(normalized)) {
+    return "test";
+  }
+  if (/(?:^|\/)src\//.test(normalized)) return "product";
+  return "unknown";
+}
+function parsedOrigin(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const frame = value;
+  if (typeof frame.file !== "string" || typeof frame.line !== "number" || typeof frame.column !== "number") {
+    return void 0;
+  }
+  return {
+    file: normalizeFile(frame.file),
+    line: frame.line,
+    column: frame.column
+  };
+}
+function stackOrigins(record) {
+  if (Array.isArray(record.stacks)) {
+    const parsed = record.stacks.map(parsedOrigin).filter((origin) => Boolean(origin));
+    if (parsed.length > 0) return parsed;
+  }
+  if (typeof record.stack !== "string") return [];
+  const origins = [];
+  const pattern = /(?:at\s+.*?\()?((?:file:\/\/)?[^()\s]+):(\d+):(\d+)\)?/g;
+  for (const match of record.stack.matchAll(pattern)) {
+    origins.push({
+      file: normalizeFile(match[1]),
+      line: Number(match[2]),
+      column: Number(match[3])
+    });
+  }
+  return origins;
+}
+function selectOrigin(record) {
+  const origins = stackOrigins(record);
+  return origins.find((origin) => {
+    const layer = failureLayer(origin.file);
+    return layer === "product" || layer === "test";
+  }) ?? origins.find((origin) => failureLayer(origin.file) !== "dependency");
+}
+function fallbackCode(record, origin, defaultCode) {
+  if (typeof record.code === "string" && record.code.trim()) {
+    return record.code.trim();
+  }
+  if (record.name === "AssertionError" && record.actual !== void 0 && record.expected !== void 0) {
+    return "EXPECTATION_MISMATCH";
+  }
+  if (record.name === "TypeError" && origin) {
+    const layer = failureLayer(origin.file);
+    if (layer === "product") return "PRODUCT_RUNTIME_TYPE_ERROR";
+    if (layer === "test") return "TEST_API_MISMATCH";
+  }
+  return defaultCode;
+}
+function structuredEntry(record, message, defaultCode) {
+  const origin = selectOrigin(record);
+  return {
+    code: fallbackCode(record, origin, defaultCode),
+    message: truncate(message),
+    errorName: typeof record.name === "string" && record.name.trim() ? record.name.trim() : void 0,
+    actual: diagnosticValue(record.actual),
+    expected: diagnosticValue(record.expected),
+    origin,
+    layer: origin ? failureLayer(origin.file) : void 0
+  };
+}
+function collectEntries(value, fallbackCode2, seen) {
   if (typeof value === "string") {
-    return value.trim() ? [{ code: fallbackCode, message: truncate(value) }] : [];
+    return value.trim() ? [{ code: fallbackCode2, 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) }];
+    return [{ code: fallbackCode2, message: String(value) }];
   }
   if (typeof value === "function") {
     return [
-      { code: fallbackCode, message: `Function<${value.name || "anonymous"}>` }
+      { code: fallbackCode2, 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));
+    return value.flatMap((item) => collectEntries(item, fallbackCode2, 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) });
+    entries.push(structuredEntry(record, record.message, fallbackCode2));
   }
   if (record.cause !== void 0) {
-    entries.push(...collectEntries(record.cause, fallbackCode, seen));
+    entries.push(...collectEntries(record.cause, fallbackCode2, seen));
   }
   if (Array.isArray(record.errors)) {
-    entries.push(...collectEntries(record.errors, fallbackCode, seen));
+    entries.push(...collectEntries(record.errors, fallbackCode2, seen));
   }
   if (entries.length > 0) return entries;
   if (typeof record.stack === "string" && record.stack.trim()) {
-    return [{ code, message: truncate(record.stack) }];
+    return [structuredEntry(record, record.stack, fallbackCode2)];
   }
   const json = safeJson(value);
-  return json && json !== "{}" ? [{ code, message: truncate(json) }] : [];
+  return json && json !== "{}" ? [structuredEntry(record, json, fallbackCode2)] : [];
 }
-function extractFailureEntries(value, fallbackCode = "TEST_FAILURE") {
-  const entries = collectEntries(value, fallbackCode, /* @__PURE__ */ new WeakSet());
+function extractFailureEntries(value, fallbackCode2 = "TEST_FAILURE") {
+  const entries = collectEntries(value, fallbackCode2, /* @__PURE__ */ new WeakSet());
   const keys = /* @__PURE__ */ new Set();
   return entries.filter((entry) => {
-    const key = `${entry.code}\0${entry.message}`;
+    const key = [
+      entry.code,
+      entry.message,
+      entry.errorName,
+      entry.actual,
+      entry.expected,
+      entry.origin ? `${entry.origin.file}:${entry.origin.line}:${entry.origin.column}` : void 0
+    ].join("\0");
     if (keys.has(key)) return false;
     keys.add(key);
     return true;
@@ -377,6 +236,15 @@ function codedError(code, message) {
   return error;
 }
 
+// src/react/react-playthrough-results.ts
+var import_node_path = require("path");
+var import_node_util = require("util");
+
+// src/react/react-playthrough.ts
+var import_react2 = require("@testing-library/react");
+var import_user_event = __toESM(require("@testing-library/user-event"));
+var import_vitest = require("vitest");
+
 // src/react/react-playthrough-core.ts
 var import_react = require("@testing-library/react");
 function throwIfAborted(signal) {
@@ -858,28 +726,7 @@ function auditReactPlaythroughRun(tests) {
   return { passed: false, waived: false, issues };
 }
 
-// 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" };
-}
+// src/react/react-playthrough-results.ts
 function isMetadata(value) {
   if (!value || typeof value !== "object") return false;
   const metadata = value;
@@ -897,17 +744,22 @@ function isMetadata(value) {
     (stage) => Boolean(stage) && typeof stage === "object" && typeof stage.name === "string" && typeof stage.kind === "string" && typeof stage.domInputEvents === "number" && typeof stage.advancedSteps === "number" && typeof stage.assertions === "number" && typeof stage.stateChanged === "boolean" && typeof stage.before === "string" && typeof stage.after === "string"
   );
 }
+function firstFailureLine(value) {
+  if (typeof value !== "string") return void 0;
+  return (0, import_node_util.stripVTControlCharacters)(value).split("\n").map((line) => line.trim()).find(Boolean);
+}
 function toAuditInput(test2) {
   const metadata = test2.meta().reactPlaythrough;
   return {
     name: test2.fullName,
     state: test2.result().state,
+    mode: test2.options.mode,
     metadata: isMetadata(metadata) ? metadata : void 0
   };
 }
 function findPendingProductTests(modules, projectRoot) {
   return modules.flatMap((module2) => {
-    const file = (0, import_node_path2.relative)(projectRoot, module2.moduleId).replaceAll("\\", "/");
+    const file = (0, import_node_path.relative)(projectRoot, module2.moduleId).replaceAll("\\", "/");
     if (file.split("/").includes("examples")) return [];
     const tests = [...module2.children.allTests()];
     const pending = tests.filter((test2) => {
@@ -926,6 +778,131 @@ function findPendingProductTests(modules, projectRoot) {
     }));
   });
 }
+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;
+  return {
+    code: primary.code,
+    cause: firstFailureLine(rawCause) ?? rawCause,
+    rawCause,
+    errorName: primary.errorName,
+    actual: primary.actual,
+    expected: primary.expected,
+    origin: primary.origin,
+    layer: primary.layer,
+    related: entries.slice(1)
+  };
+}
+function failureHint(value) {
+  const names = [...value.matchAll(/button\s*\n\s*Name "([^"]+)"/g)].map(
+    (match) => match[1]
+  );
+  if (names.length === 0) return void 0;
+  return `Available button names: ${names.map((name) => JSON.stringify(name)).join(", ")}`;
+}
+function errorLocation(value) {
+  const match = value.match(
+    /(?:^|\n)\s*at\s+(.*?\.(?:test|spec)\.[^\n]+:\d+:\d+)/
+  );
+  return match?.[1];
+}
+function 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 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 toReactPlaythroughModuleResult(module2, projectRoot) {
+  const tests = [...module2.children.allTests()];
+  const moduleFailure = selectReactFailure(
+    module2.errors(),
+    module2.errors().length
+  );
+  const moduleErrors = extractFailureEntries(module2.errors()).map(
+    (entry) => firstFailureLine(entry.message) ?? entry.message
+  );
+  const errors = [
+    ...moduleErrors,
+    ...tests.flatMap(
+      (test2) => extractFailureEntries(test2.result().errors ?? []).map(
+        (entry) => firstFailureLine(entry.message) ?? entry.message
+      )
+    )
+  ];
+  const failures = tests.filter((test2) => test2.result().state === "failed").map((test2) => {
+    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, ...module2.errors()],
+      testErrors.length + module2.errors().length
+    );
+    return {
+      test: test2.fullName,
+      causeCode: selected.code,
+      cause: selected.cause,
+      errorName: selected.errorName,
+      actual: selected.actual,
+      expected: selected.expected,
+      origin: selected.origin,
+      layer: selected.layer,
+      related: selected.related,
+      location: test2.location ? `${(0, import_node_path.relative)(projectRoot, module2.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 && module2.errors().length > 0) {
+    failures.push({
+      test: "<collection>",
+      causeCode: moduleFailure.code,
+      cause: moduleFailure.cause,
+      errorName: moduleFailure.errorName,
+      actual: moduleFailure.actual,
+      expected: moduleFailure.expected,
+      origin: moduleFailure.origin,
+      layer: moduleFailure.layer,
+      related: moduleFailure.related,
+      location: errorLocation(moduleFailure.rawCause),
+      hint: failureHint(moduleFailure.rawCause)
+    });
+  }
+  return {
+    file: (0, import_node_path.relative)(projectRoot, module2.moduleId).replaceAll("\\", "/"),
+    state: module2.state(),
+    errors,
+    primaryError: moduleErrors[0] ?? failures[0]?.cause,
+    primaryCauseCode: failures[0]?.causeCode,
+    relatedErrors: failures[0]?.related,
+    tests: tests.map(toAuditInput),
+    failures
+  };
+}
+
+// src/react/react-playthrough-report-format.ts
+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 formatPendingProductTestReport(pending) {
   if (pending.length === 0) return void 0;
   const lines = [
@@ -942,149 +919,383 @@ function formatPendingProductTestReport(pending) {
       );
       reportedIncompleteFiles.add(item.file);
     }
-    lines.push(`FILE: ${item.file}`);
-    lines.push(`TEST: ${item.test}`);
-    lines.push(`MODE: ${item.mode}`);
+    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 formatOrigin(origin) {
+  return `${origin.file}:${origin.line}:${origin.column}`;
+}
+function appendFailureDetails(lines, failure) {
+  if (failure.errorName) lines.push(`ERROR_NAME: ${failure.errorName}`);
+  if (failure.layer) lines.push(`CAUSE_LAYER: ${failure.layer}`);
+  if (failure.origin) lines.push(`ORIGIN: ${formatOrigin(failure.origin)}`);
+  if (failure.expected !== void 0) {
+    lines.push(`EXPECTED: ${failure.expected}`);
+  }
+  if (failure.actual !== void 0) lines.push(`ACTUAL: ${failure.actual}`);
+}
+function formatReactFailureSummary(modules) {
+  const failures = modules.flatMap(
+    (module2) => (module2.failures ?? []).map((failure) => ({
+      ...failure,
+      file: module2.file
+    }))
+  );
+  if (failures.length === 0) return ["TEST_RESULT: PASS"];
+  const lines = [`FAILED_TESTS: ${failures.length}`];
+  for (const [index, failure] of failures.entries()) {
+    lines.push(`FAILURE_${index + 1}: ${failure.file}`);
+    lines.push(`TEST: ${failure.test}`);
+    lines.push(`CAUSE_CODE: ${failure.causeCode ?? "TEST_FAILURE"}`);
+    lines.push(`CAUSE: ${failure.cause}`);
+    appendFailureDetails(lines, failure);
+    for (const [relatedIndex, related] of (failure.related ?? []).entries()) {
+      lines.push(`RELATED_${relatedIndex + 1}_CODE: ${related.code}`);
+      lines.push(
+        `RELATED_${relatedIndex + 1}: ${firstFailureLine(related.message) ?? related.message}`
+      );
+      if (related.layer) {
+        lines.push(`RELATED_${relatedIndex + 1}_LAYER: ${related.layer}`);
+      }
+      if (related.origin) {
+        lines.push(
+          `RELATED_${relatedIndex + 1}_ORIGIN: ${formatOrigin(related.origin)}`
+        );
+      }
+    }
+    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 formatReactTestCountSummary(modules) {
+  const files = {
+    total: modules.length,
+    passed: 0,
+    failed: 0,
+    skipped: 0,
+    pending: 0,
+    queued: 0
+  };
+  const tests = {
+    total: 0,
+    passed: 0,
+    failed: 0,
+    skipped: 0,
+    todo: 0,
+    pending: 0
+  };
+  let declaredPlaythroughs = 0;
+  let verifiedPlaythroughs = 0;
+  let waivedPlaythroughs = 0;
+  for (const module2 of modules) {
+    if (module2.state in files && module2.state !== "total") {
+      files[module2.state] += 1;
+    }
+    for (const test2 of module2.tests) {
+      tests.total += 1;
+      if (test2.mode === "todo") tests.todo += 1;
+      else tests[test2.state] += 1;
+      if (test2.metadata) {
+        declaredPlaythroughs += 1;
+        if (test2.metadata.evidence.verified) verifiedPlaythroughs += 1;
+        if (test2.metadata.waiverReason) waivedPlaythroughs += 1;
+      }
+    }
+  }
+  return [
+    `TEST_FILES: total=${files.total} passed=${files.passed} failed=${files.failed} skipped=${files.skipped} pending=${files.pending} queued=${files.queued}`,
+    `TESTS: total=${tests.total} passed=${tests.passed} failed=${tests.failed} skipped=${tests.skipped} todo=${tests.todo} pending=${tests.pending}`,
+    `PLAYTHROUGHS: declared=${declaredPlaythroughs} verified=${verifiedPlaythroughs} waived=${waivedPlaythroughs}`
+  ];
+}
+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}: ${firstFailureLine(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")}`;
+}
+
+// src/cli/react-authoritative-playthrough.ts
+var import_node_fs = require("fs");
+var import_node_path2 = require("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 = (0, import_node_path2.join)(root, "tests")) {
+  if (!(0, import_node_fs.existsSync)(directory)) return [];
+  const files = [];
+  for (const entry of (0, import_node_fs.readdirSync)(directory, { withFileTypes: true })) {
+    const path = (0, import_node_path2.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 = (0, import_node_path2.join)(root, "src")) {
+  if (!(0, import_node_fs.existsSync)(directory)) return [];
+  const files = [];
+  for (const entry of (0, import_node_fs.readdirSync)(directory, { withFileTypes: true })) {
+    const path = (0, import_node_path2.join)(directory, entry.name);
+    const projectPath = (0, import_node_path2.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";
+    }
   }
-  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 (0, import_node_util.stripVTControlCharacters)(value).split("\n").map((line) => line.trim()).find(Boolean);
+  return positions;
 }
-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: []
-    };
+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]);
   }
-  const primary = entries[0];
-  const rawCause = primary.message;
-  const cause = firstLine(rawCause) ?? rawCause;
-  return { code: primary.code, cause, rawCause, related: entries.slice(1) };
+  return modules;
 }
-function failureHint(value) {
-  const names = [...value.matchAll(/button\s*\n\s*Name "([^"]+)"/g)].map(
-    (match) => match[1]
+function productionFileImportsExample(file, projectRoot) {
+  const exampleRoot = (0, import_node_path2.join)(projectRoot, "src/game/example");
+  return importedModuleSpecifiers((0, import_node_fs.readFileSync)(file, "utf8")).some(
+    (moduleName) => {
+      if (moduleName.startsWith(EXAMPLE_IMPORT_PREFIX)) return true;
+      if (!moduleName.startsWith(".")) return false;
+      const target = (0, import_node_path2.resolve)((0, import_node_path2.dirname)(file), moduleName);
+      return target === exampleRoot || target.startsWith(`${exampleRoot}${import_node_path2.sep}`);
+    }
   );
-  if (names.length === 0) return void 0;
-  return `Available button names: ${names.map((name) => JSON.stringify(name)).join(", ")}`;
 }
-function errorLocation(value) {
-  const match = value.match(
-    /(?:^|\n)\s*at\s+(.*?\.(?:test|spec)\.[^\n]+:\d+:\d+)/
+function importsExampleAlias(source) {
+  return importedModuleSpecifiers(source).some(
+    (moduleName) => moduleName.startsWith(EXAMPLE_IMPORT_PREFIX)
   );
-  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;
+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);
     }
   }
-  const metadata = test2.meta().reactPlaythrough;
-  const trace = annotationTrace ?? (isMetadata(metadata) ? metadata.trace : void 0);
-  return trace ? truncateReporterLine(trace, 720) : void 0;
+  return names;
 }
-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 containsAny(values, expected) {
+  return [...values].some((value) => expected.has(value));
 }
-function toModuleResult(module2, projectRoot) {
-  const tests = [...module2.children.allTests()];
-  const moduleFailure = selectReactFailure(
-    module2.errors(),
-    module2.errors().length
-  );
-  const moduleErrors = extractFailureEntries(module2.errors()).map(
-    (entry) => firstLine(entry.message) ?? entry.message
+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(
+      (0, import_node_fs.readFileSync)(file, "utf8"),
+      REACT_RUNTIME_ENTRY
+    );
+    const projectPath = (0, import_node_path2.relative)(projectRoot, file).replaceAll("\\", "/");
+    if (containsAny(imports, CLOCK_IMPORTS)) clockFiles.push(projectPath);
+    if (containsAny(imports, CONTROLLER_IMPORTS))
+      controllerFiles.push(projectPath);
+  }
+  const appPath = (0, import_node_path2.join)(projectRoot, PRODUCTION_APP);
+  const productionEntryExists = (0, import_node_fs.existsSync)(appPath);
+  const productionUsesExample = productionFiles.some(
+    (file) => productionFileImportsExample(file, projectRoot)
   );
-  const errors = [
-    ...moduleErrors,
-    ...tests.flatMap(
-      (test2) => extractFailureEntries(test2.result().errors ?? []).map(
-        (entry) => firstLine(entry.message) ?? entry.message
-      )
-    )
-  ];
-  const failures = tests.filter((test2) => test2.result().state === "failed").map((test2) => {
-    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, ...module2.errors()],
-      testErrors.length + module2.errors().length
+  const staleExampleTestFiles = productionUsesExample ? [] : runnableTestFiles(projectRoot).filter((file) => importsExampleAlias((0, import_node_fs.readFileSync)(file, "utf8"))).map((file) => (0, import_node_path2.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 {
-      test: test2.fullName,
-      causeCode: selected.code,
-      cause: selected.cause,
-      related: selected.related,
-      location: test2.location ? `${(0, import_node_path2.relative)(projectRoot, module2.moduleId).replaceAll("\\", "/")}:${test2.location.line}:${test2.location.column}` : errorLocation(selected.rawCause),
-      hint: failureHint(selected.rawCause),
-      trace: failureTrace(test2)
+      ok: issues.length === 0,
+      issues,
+      clockFiles,
+      controllerFiles,
+      productionEntryExists,
+      productionUsesExample,
+      staleExampleTestFiles
     };
-  });
-  if (failures.length === 0 && tests.length === 0 && module2.errors().length > 0) {
-    failures.push({
-      test: "<collection>",
-      causeCode: moduleFailure.code,
-      cause: moduleFailure.cause,
-      related: moduleFailure.related,
-      location: errorLocation(moduleFailure.rawCause),
-      hint: failureHint(moduleFailure.rawCause)
-    });
+  }
+  const testPath = (0, import_node_path2.join)(projectRoot, PRODUCTION_PLAYTHROUGH);
+  const testSource = (0, import_node_fs.existsSync)(testPath) ? (0, import_node_fs.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. Pass { observe: () => telemetry.read.session() } to playthroughTest, using Telemetry backed by the same production Controller rendered by <App />; 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(", ")}. Add this import to the test: import { ManualGameClock } from "miaoda-game-devkit/react/testing"; Then create one, inject it through the production <App /> factory, and advance it with step: () => clock.stepFrame().`
+    );
   }
   return {
-    file: (0, import_node_path2.relative)(projectRoot, module2.moduleId).replaceAll("\\", "/"),
-    state: module2.state(),
-    errors,
-    primaryError: moduleErrors[0] ?? failures[0]?.cause,
-    primaryCauseCode: failures[0]?.causeCode,
-    relatedErrors: failures[0]?.related,
-    tests: tests.map(toAuditInput),
-    failures
+    ok: issues.length === 0,
+    issues,
+    clockFiles,
+    controllerFiles,
+    productionEntryExists,
+    productionUsesExample,
+    staleExampleTestFiles
   };
 }
-function formatReactFailureSummary(modules) {
-  const failures = modules.flatMap(
-    (module2) => (module2.failures ?? []).map((failure) => ({
-      ...failure,
-      file: module2.file
-    }))
-  );
-  if (failures.length === 0) return ["TEST_RESULT: PASS"];
-  const lines = [`FAILED_TESTS: ${failures.length}`];
-  for (const [index, failure] of failures.entries()) {
-    lines.push(`FAILURE_${index + 1}: ${failure.file}`);
-    lines.push(`TEST: ${failure.test}`);
-    lines.push(`CAUSE_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}`);
+
+// src/react/react-playthrough-policy.ts
+function assessProductTestAlignment(projectRoot) {
+  const audit = auditReactAuthoritativePlaythrough(projectRoot);
+  if (audit.staleExampleTestFiles.length > 0) {
+    return { status: "FAILED", cause: audit.issues[0] };
   }
-  lines.push("TEST_RESULT: FAIL");
-  return lines;
+  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 repairGuidance(code) {
   switch (code) {
@@ -1102,6 +1313,12 @@ function repairGuidance(code) {
       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 "EXPECTATION_MISMATCH":
+      return "The test assertion observed a different value than it expected. Compare EXPECTED and ACTUAL with the game-owned state type and inspect ORIGIN before editing. Fix production only when the observed value violates the product contract; otherwise correct the test expectation without weakening the intended outcome.";
+    case "PRODUCT_RUNTIME_TYPE_ERROR":
+      return "A TypeError originated in production source. Open ORIGIN, validate the referenced dependency or state before mutation, and fix the owning initialization or lifecycle boundary. Do not bypass the crashing path in the test.";
+    case "TEST_API_MISMATCH":
+      return "A TypeError originated in test code. Open ORIGIN and align the call with the installed public API or the game-owned typed Session. Do not add a production shim solely for an invented test helper.";
     case "INVALID_STAGE_ORDER":
     case "INCOMPLETE_PLAYTHROUGH_EVIDENCE":
     case "INVALID_STAGE_NAME":
@@ -1187,36 +1404,14 @@ function assessReactPlaythroughReport(input) {
   }
   return { ...base, status: "PASS", failsRun: false };
 }
-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("; ")}`);
-  }
-  if (report.next) lines.push(`NEXT: ${report.next}`);
-  if (report.status === "FAILED") {
-    lines.push(`REPAIR_CONSTRAINT: ${REPAIR_CONSTRAINT}`);
-  }
-  return `
-${lines.join("\n")}`;
-}
+
+// src/react/react-playthrough-reporter.ts
+var PRODUCTION_PLAYTHROUGH_FILE = "tests/production-playthrough.test.tsx";
 var ReactPlaythroughReporter = class {
   /** 绑定模板根目录，以稳定识别生产可玩性测试而不依赖测试名称。 */
   constructor(projectRoot) {
     this.projectRoot = projectRoot;
-    this.expectedModuleId = (0, import_node_path2.resolve)(projectRoot, this.expectedFile);
+    this.expectedModuleId = (0, import_node_path3.resolve)(projectRoot, this.expectedFile);
   }
   projectRoot;
   expectedFile = PRODUCTION_PLAYTHROUGH_FILE;
@@ -1226,7 +1421,7 @@ var ReactPlaythroughReporter = class {
   /** 记录本轮是否实际选择了生产流程文件，用于区分聚焦运行与门禁失败。 */
   onTestRunStart(specifications) {
     this.expectedFileScheduled = specifications.some(
-      (specification) => (0, import_node_path2.resolve)(specification.moduleId) === this.expectedModuleId
+      (specification) => (0, import_node_path3.resolve)(specification.moduleId) === this.expectedModuleId
     );
     this.focusedSelection = specifications.some(
       (specification) => Boolean(specification.project.globalConfig.testNamePattern) || Boolean(specification.testNamePattern) || Boolean(specification.testLines?.length)
@@ -1238,16 +1433,17 @@ var ReactPlaythroughReporter = class {
       testModules,
       this.projectRoot
     );
+    const moduleResults = testModules.map(
+      (module2) => toReactPlaythroughModuleResult(module2, this.projectRoot)
+    );
     const report = assessReactPlaythroughReport({
       expectedFile: this.expectedFile,
       expectedFileExists: (0, import_node_fs2.existsSync)(this.expectedModuleId),
       expectedFileScheduled: this.expectedFileScheduled,
       focusedSelection: this.focusedSelection,
-      modules: testModules.map(
-        (module2) => toModuleResult(module2, this.projectRoot)
-      ),
+      modules: moduleResults,
       unhandledErrors: extractFailureEntries(unhandledErrors).map(
-        (entry) => firstLine(entry.message) ?? entry.message
+        (entry) => firstFailureLine(entry.message) ?? entry.message
       )
     });
     const alignment = assessProductTestAlignment(this.projectRoot);
@@ -1265,14 +1461,14 @@ var ReactPlaythroughReporter = class {
       console.error(pendingOutput);
       process.exitCode = 1;
     }
-    const summary = formatReactFailureSummary(
-      testModules.map((module2) => toModuleResult(module2, this.projectRoot))
-    );
+    const summary = formatReactFailureSummary(moduleResults);
     if ((report.failsRun || alignment.status === "FAILED" || pendingProductTests.length > 0) && summary[0] === "TEST_RESULT: PASS") {
       summary[0] = "TEST_RESULT: FAIL";
     }
-    console.log(`
-${summary.join("\n")}`);
+    console.log(
+      `
+${[...formatReactTestCountSummary(moduleResults), ...summary].join("\n")}`
+    );
   }
 };
 
@@ -1284,13 +1480,13 @@ function getJSDOMWorkerExecArgv() {
 
 // src/react-vitest-config.ts
 function resolvePhaser3BrowserEntry(projectRoot) {
-  const manifestPath = (0, import_node_path3.resolve)(projectRoot, "node_modules/phaser/package.json");
+  const manifestPath = (0, import_node_path4.resolve)(projectRoot, "node_modules/phaser/package.json");
   if (!(0, import_node_fs3.existsSync)(manifestPath)) return void 0;
   try {
     const manifest = JSON.parse((0, import_node_fs3.readFileSync)(manifestPath, "utf8"));
     if (!manifest.version?.startsWith("3.")) return void 0;
-    const browserEntry = (0, import_node_path3.resolve)(
-      (0, import_node_path3.dirname)(manifestPath),
+    const browserEntry = (0, import_node_path4.resolve)(
+      (0, import_node_path4.dirname)(manifestPath),
       manifest.browser ?? "dist/phaser.js"
     );
     return (0, import_node_fs3.existsSync)(browserEntry) ? browserEntry : void 0;
@@ -1308,7 +1504,7 @@ function defineReactGameVitestConfig(options) {
       alias: {
         ...phaser3BrowserEntry ? { phaser: phaser3BrowserEntry } : {},
         ...options.aliases,
-        "@": (0, import_node_path3.resolve)(options.projectRoot, "src")
+        "@": (0, import_node_path4.resolve)(options.projectRoot, "src")
       }
     },
     test: {