miaoda-game-devkit 0.6.5 → 0.7.0

package/dist/react/vitest-config.mjs

@@ -5,246 +5,7 @@ import { defineConfig } from "vitest/config";
 
 // src/react/react-playthrough-reporter.ts
 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. 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 {
-    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";
+import { resolve as resolve2 } from "path";
 
 // src/react/react-error-diagnostics.ts
 var MAX_DIAGNOSTIC_LENGTH = 1e3;
@@ -272,47 +33,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 value.trim() ? [{ code: fallbackCode, message: truncate(value) }] : [];
+    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: 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;
@@ -343,6 +202,15 @@ function codedError(code, message) {
   return error;
 }
 
+// src/react/react-playthrough-results.ts
+import { relative } from "path";
+import { stripVTControlCharacters } from "util";
+
+// 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-playthrough-core.ts
 import { act } from "@testing-library/react";
 function throwIfAborted(signal) {
@@ -393,10 +261,10 @@ 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 guidance = options.step ? "The step callback ran, but the authoritative outcome did not change." : "No step callback was provided, and the condition did not become true after the stage action. This does not identify a clock problem; inspect the condition, production input wiring, and observed state boundary.";
   const suffix = diagnostics ? ` Last diagnostics: ${diagnostics}` : "";
   throw codedError(
-    options.step ? "PLAYTHROUGH_BOUND_EXHAUSTED" : "PLAYTHROUGH_CLOCK_NOT_ADVANCED",
+    options.step ? "PLAYTHROUGH_BOUND_EXHAUSTED" : "PLAYTHROUGH_OUTCOME_NOT_REACHED",
     `Playthrough outcome was not reached within ${maxSteps} steps. ${guidance}${suffix}`
   );
 }
@@ -824,28 +692,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;
@@ -863,17 +710,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 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((module) => {
-    const file = relative2(projectRoot, module.moduleId).replaceAll("\\", "/");
+    const file = relative(projectRoot, module.moduleId).replaceAll("\\", "/");
     if (file.split("/").includes("examples")) return [];
     const tests = [...module.children.allTests()];
     const pending = tests.filter((test2) => {
@@ -892,36 +744,6 @@ function findPendingProductTests(modules, projectRoot) {
     }));
   });
 }
-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) {
@@ -934,8 +756,17 @@ function selectReactFailure(values, errorRecordCount = values.length) {
   }
   const primary = entries[0];
   const rawCause = primary.message;
-  const cause = firstLine(rawCause) ?? rawCause;
-  return { code: primary.code, cause, rawCause, related: entries.slice(1) };
+  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(
@@ -950,6 +781,11 @@ function errorLocation(value) {
   );
   return match?.[1];
 }
+function truncateReporterLine(value, limit) {
+  const compact = 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;
@@ -963,25 +799,20 @@ function failureTrace(test2) {
   const trace = annotationTrace ?? (isMetadata(metadata) ? metadata.trace : void 0);
   return trace ? truncateReporterLine(trace, 720) : void 0;
 }
-function truncateReporterLine(value, limit) {
-  const compact = stripVTControlCharacters(value).replace(/\s+/g, " ").trim();
-  if (compact.length <= limit) return compact;
-  return `${compact.slice(0, Math.max(0, limit - 1))}\u2026`;
-}
-function toModuleResult(module, projectRoot) {
+function toReactPlaythroughModuleResult(module, projectRoot) {
   const tests = [...module.children.allTests()];
   const moduleFailure = selectReactFailure(
     module.errors(),
     module.errors().length
   );
   const moduleErrors = extractFailureEntries(module.errors()).map(
-    (entry) => firstLine(entry.message) ?? entry.message
+    (entry) => firstFailureLine(entry.message) ?? entry.message
   );
   const errors = [
     ...moduleErrors,
     ...tests.flatMap(
       (test2) => extractFailureEntries(test2.result().errors ?? []).map(
-        (entry) => firstLine(entry.message) ?? entry.message
+        (entry) => firstFailureLine(entry.message) ?? entry.message
       )
     )
   ];
@@ -998,8 +829,13 @@ function toModuleResult(module, projectRoot) {
       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 ? `${relative2(projectRoot, module.moduleId).replaceAll("\\", "/")}:${test2.location.line}:${test2.location.column}` : errorLocation(selected.rawCause),
+      location: test2.location ? `${relative(projectRoot, module.moduleId).replaceAll("\\", "/")}:${test2.location.line}:${test2.location.column}` : errorLocation(selected.rawCause),
       hint: failureHint(selected.rawCause),
       trace: failureTrace(test2)
     };
@@ -1009,13 +845,18 @@ function toModuleResult(module, projectRoot) {
       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: relative2(projectRoot, module.moduleId).replaceAll("\\", "/"),
+    file: relative(projectRoot, module.moduleId).replaceAll("\\", "/"),
     state: module.state(),
     errors,
     primaryError: moduleErrors[0] ?? failures[0]?.cause,
@@ -1025,6 +866,47 @@ function toModuleResult(module, projectRoot) {
     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 = [
+    "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 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(
     (module) => (module.failures ?? []).map((failure) => ({
@@ -1039,11 +921,20 @@ function formatReactFailureSummary(modules) {
     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}: ${firstLine(related.message) ?? related.message}`
+        `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}`);
@@ -1052,6 +943,282 @@ function formatReactFailureSummary(modules) {
   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 module of modules) {
+    if (module.state in files && module.state !== "total") {
+      files[module.state] += 1;
+    }
+    for (const test2 of module.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
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { dirname, join, relative as relative2, resolve, sep } from "path";
+import { parseSync } from "oxc-parser";
+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 = relative2(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 parseSource(file, source) {
+  return parseSync(file, source, { sourceType: "module" });
+}
+function staticImports(file, source) {
+  return parseSource(file, source).module.staticImports;
+}
+function collectDynamicImportSpecifiers(value, modules) {
+  if (Array.isArray(value)) {
+    for (const item of value) collectDynamicImportSpecifiers(item, modules);
+    return;
+  }
+  if (!isRecord(value)) return;
+  if (value.type === "ImportExpression" && isRecord(value.source) && value.source.type === "Literal" && typeof value.source.value === "string") {
+    modules.push(value.source.value);
+  }
+  for (const child of Object.values(value)) {
+    collectDynamicImportSpecifiers(child, modules);
+  }
+}
+function importedModuleSpecifiers(file, source) {
+  const parsed = parseSource(file, source);
+  const modules = parsed.module.staticImports.map(
+    ({ moduleRequest }) => moduleRequest.value
+  );
+  collectDynamicImportSpecifiers(parsed.program, modules);
+  return modules;
+}
+function productionFileImportsExample(file, projectRoot) {
+  const exampleRoot = join(projectRoot, "src/game/example");
+  return importedModuleSpecifiers(file, 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(file, source) {
+  return importedModuleSpecifiers(file, source).some(
+    (moduleName) => moduleName.startsWith(EXAMPLE_IMPORT_PREFIX)
+  );
+}
+function namedImports(file, source, moduleName) {
+  const names = /* @__PURE__ */ new Set();
+  for (const declaration of staticImports(file, source)) {
+    if (declaration.moduleRequest.value !== moduleName) continue;
+    for (const entry of declaration.entries) {
+      if (entry.importName.kind === "Name" && entry.importName.name) {
+        names.add(entry.importName.name);
+      }
+    }
+  }
+  return names;
+}
+function containsAny(values, expected) {
+  return [...values].some((value) => expected.has(value));
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function containsObserveProperty(value) {
+  if (Array.isArray(value)) return value.some(containsObserveProperty);
+  if (!isRecord(value)) return false;
+  if (value.type === "Property" && isRecord(value.key)) {
+    if (value.key.type === "Identifier" && value.key.name === "observe") return true;
+    if (value.key.type === "Literal" && value.key.value === "observe") return true;
+  }
+  return Object.values(value).some(containsObserveProperty);
+}
+function declaresObserve(file, source) {
+  return containsObserveProperty(parseSource(file, source).program);
+}
+function auditReactAuthoritativePlaythrough(projectRoot) {
+  const clockFiles = [];
+  const controllerFiles = [];
+  const productionFiles = sourceFiles(projectRoot);
+  for (const file of productionFiles) {
+    const imports = namedImports(
+      file,
+      readFileSync(file, "utf8"),
+      REACT_RUNTIME_ENTRY
+    );
+    const projectPath = relative2(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(file, readFileSync(file, "utf8"))
+  ).map((file) => relative2(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(
+    testPath,
+    testSource,
+    REACT_TESTING_ENTRY
+  );
+  const hasObserve = declaresObserve(testPath, 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 {
+    ok: issues.length === 0,
+    issues,
+    clockFiles,
+    controllerFiles,
+    productionEntryExists,
+    productionUsesExample,
+    staleExampleTestFiles
+  };
+}
+
+// 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] };
+  }
+  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) {
     case "GAME_SNAPSHOT_REFERENCE_REUSED":
@@ -1066,8 +1233,16 @@ function repairGuidance(code) {
       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_OUTCOME_NOT_REACHED":
+      return "The stage action completed, but its until condition never became true. Inspect TRACE and Last diagnostics, then confirm that the production DOM input reaches the rendered App, until describes the result caused by this stage, and observe reads the matching authoritative state when used. Add a deterministic step only if the gameplay is actually driven by time or frames; do not add a no-op step or weaken the intended outcome.";
     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":
@@ -1153,31 +1328,9 @@ 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) {
@@ -1204,16 +1357,17 @@ var ReactPlaythroughReporter = class {
       testModules,
       this.projectRoot
     );
+    const moduleResults = testModules.map(
+      (module) => toReactPlaythroughModuleResult(module, this.projectRoot)
+    );
     const report = assessReactPlaythroughReport({
       expectedFile: this.expectedFile,
       expectedFileExists: existsSync2(this.expectedModuleId),
       expectedFileScheduled: this.expectedFileScheduled,
       focusedSelection: this.focusedSelection,
-      modules: testModules.map(
-        (module) => toModuleResult(module, 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);
@@ -1231,14 +1385,14 @@ var ReactPlaythroughReporter = class {
       console.error(pendingOutput);
       process.exitCode = 1;
     }
-    const summary = formatReactFailureSummary(
-      testModules.map((module) => toModuleResult(module, 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")}`
+    );
   }
 };
 
@@ -1298,8 +1452,11 @@ function defineReactGameVitestConfig(options) {
       sequence: {
         setupFiles: "list"
       },
-      // 单一 reporter 输出无 ANSI 的紧凑失败摘要和项目级可玩性门禁。
-      reporters: [new ReactPlaythroughReporter(options.projectRoot)],
+      ...options.enablePlaythroughReporter ? {
+        // The structured reporter remains available to existing Devkit consumers,
+        // but is no longer a default requirement for generated React games.
+        reporters: [new ReactPlaythroughReporter(options.projectRoot)]
+      } : {},
       restoreMocks: true,
       clearMocks: true,
       testTimeout: options.testTimeout,