miaoda-game-devkit 0.6.3 → 0.6.5

package/dist/cli/phaser-lint.js

@@ -12,6 +12,8 @@ var import_node_path2 = require("path");
 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"]);
@@ -20,6 +22,19 @@ var CONTROLLER_IMPORTS = /* @__PURE__ */ new Set([
   "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);
@@ -109,6 +124,32 @@ function codePositions(source) {
   }
   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, projectRoot2) {
+  const exampleRoot = (0, import_node_path.join)(projectRoot2, "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);
@@ -141,15 +182,39 @@ function declaresObserve(source) {
 function auditReactAuthoritativePlaythrough(projectRoot2) {
   const clockFiles = [];
   const controllerFiles = [];
-  for (const file of sourceFiles(projectRoot2)) {
-    const imports = namedImports((0, import_node_fs.readFileSync)(file, "utf8"), REACT_RUNTIME_ENTRY);
+  const productionFiles = sourceFiles(projectRoot2);
+  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)(projectRoot2, file).replaceAll("\\", "/");
     if (containsAny(imports, CLOCK_IMPORTS)) clockFiles.push(projectPath);
-    if (containsAny(imports, CONTROLLER_IMPORTS)) controllerFiles.push(projectPath);
+    if (containsAny(imports, CONTROLLER_IMPORTS))
+      controllerFiles.push(projectPath);
   }
+  const appPath = (0, import_node_path.join)(projectRoot2, PRODUCTION_APP);
+  const productionEntryExists = (0, import_node_fs.existsSync)(appPath);
+  const productionUsesExample = productionFiles.some(
+    (file) => productionFileImportsExample(file, projectRoot2)
+  );
+  const staleExampleTestFiles = productionUsesExample ? [] : runnableTestFiles(projectRoot2).filter((file) => importsExampleAlias((0, import_node_fs.readFileSync)(file, "utf8"))).map((file) => (0, import_node_path.relative)(projectRoot2, 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: true, issues, clockFiles, controllerFiles };
+    return {
+      ok: issues.length === 0,
+      issues,
+      clockFiles,
+      controllerFiles,
+      productionEntryExists,
+      productionUsesExample,
+      staleExampleTestFiles
+    };
   }
   const testPath = (0, import_node_path.join)(projectRoot2, PRODUCTION_PLAYTHROUGH);
   const testSource = (0, import_node_fs.existsSync)(testPath) ? (0, import_node_fs.readFileSync)(testPath, "utf8") : "";
@@ -157,15 +222,23 @@ function auditReactAuthoritativePlaythrough(projectRoot2) {
   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.`
+      `${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(", ")}. Inject it through the production <App /> factory and advance it with a non-empty deterministic step.`
+      `${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 };
+  return {
+    ok: issues.length === 0,
+    issues,
+    clockFiles,
+    controllerFiles,
+    productionEntryExists,
+    productionUsesExample,
+    staleExampleTestFiles
+  };
 }
 
 // src/cli/lint.ts

package/dist/cli/react-lint.js

@@ -12,6 +12,8 @@ var import_node_path2 = require("path");
 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"]);
@@ -20,6 +22,19 @@ var CONTROLLER_IMPORTS = /* @__PURE__ */ new Set([
   "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);
@@ -109,6 +124,32 @@ function codePositions(source) {
   }
   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, projectRoot2) {
+  const exampleRoot = (0, import_node_path.join)(projectRoot2, "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);
@@ -141,15 +182,39 @@ function declaresObserve(source) {
 function auditReactAuthoritativePlaythrough(projectRoot2) {
   const clockFiles = [];
   const controllerFiles = [];
-  for (const file of sourceFiles(projectRoot2)) {
-    const imports = namedImports((0, import_node_fs.readFileSync)(file, "utf8"), REACT_RUNTIME_ENTRY);
+  const productionFiles = sourceFiles(projectRoot2);
+  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)(projectRoot2, file).replaceAll("\\", "/");
     if (containsAny(imports, CLOCK_IMPORTS)) clockFiles.push(projectPath);
-    if (containsAny(imports, CONTROLLER_IMPORTS)) controllerFiles.push(projectPath);
+    if (containsAny(imports, CONTROLLER_IMPORTS))
+      controllerFiles.push(projectPath);
   }
+  const appPath = (0, import_node_path.join)(projectRoot2, PRODUCTION_APP);
+  const productionEntryExists = (0, import_node_fs.existsSync)(appPath);
+  const productionUsesExample = productionFiles.some(
+    (file) => productionFileImportsExample(file, projectRoot2)
+  );
+  const staleExampleTestFiles = productionUsesExample ? [] : runnableTestFiles(projectRoot2).filter((file) => importsExampleAlias((0, import_node_fs.readFileSync)(file, "utf8"))).map((file) => (0, import_node_path.relative)(projectRoot2, 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: true, issues, clockFiles, controllerFiles };
+    return {
+      ok: issues.length === 0,
+      issues,
+      clockFiles,
+      controllerFiles,
+      productionEntryExists,
+      productionUsesExample,
+      staleExampleTestFiles
+    };
   }
   const testPath = (0, import_node_path.join)(projectRoot2, PRODUCTION_PLAYTHROUGH);
   const testSource = (0, import_node_fs.existsSync)(testPath) ? (0, import_node_fs.readFileSync)(testPath, "utf8") : "";
@@ -157,15 +222,23 @@ function auditReactAuthoritativePlaythrough(projectRoot2) {
   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.`
+      `${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(", ")}. Inject it through the production <App /> factory and advance it with a non-empty deterministic step.`
+      `${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 };
+  return {
+    ok: issues.length === 0,
+    issues,
+    clockFiles,
+    controllerFiles,
+    productionEntryExists,
+    productionUsesExample,
+    staleExampleTestFiles
+  };
 }
 
 // src/cli/lint.ts

package/dist/react/vitest-config.js

@@ -33,14 +33,247 @@ __export(react_vitest_config_exports, {
   defineReactGameVitestConfig: () => defineReactGameVitestConfig
 });
 module.exports = __toCommonJS(react_vitest_config_exports);
-var import_node_fs2 = require("fs");
-var import_node_path2 = require("path");
+var import_node_fs3 = require("fs");
+var import_node_path3 = 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 import_node_util = require("util");
+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. 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
 var import_react2 = require("@testing-library/react");
@@ -628,6 +861,25 @@ function auditReactPlaythroughRun(tests) {
 // src/react/react-playthrough-reporter.ts
 var PRODUCTION_PLAYTHROUGH_FILE = "tests/production-playthrough.test.tsx";
 var REPAIR_CONSTRAINT = "Preserve the intended gameplay outcome. Fix the production mechanic, deterministic driver, or authoritative observation that prevents it. Do not make the test pass by weakening or deleting assertions, replacing the outcome with back/menu/exit navigation, observing arbitrary UI text only to change a fingerprint, using a no-op step, or treating an intermediate active/in-flight/running phase as meaningful progress.";
+function assessProductTestAlignment(projectRoot) {
+  const audit = auditReactAuthoritativePlaythrough(projectRoot);
+  if (audit.staleExampleTestFiles.length > 0) {
+    return { status: "FAILED", cause: audit.issues[0] };
+  }
+  if (!audit.productionEntryExists) {
+    return {
+      status: "NOT_VERIFIED",
+      cause: "The production src/App.tsx entry does not exist, so product-test alignment could not be verified."
+    };
+  }
+  if (audit.productionUsesExample) {
+    return {
+      status: "NOT_VERIFIED",
+      cause: "The production App still uses the replaceable src/game/example teaching game, so replacement-game test alignment is not applicable yet."
+    };
+  }
+  return { status: "PASS" };
+}
 function isMetadata(value) {
   if (!value || typeof value !== "object") return false;
   const metadata = value;
@@ -655,7 +907,7 @@ function toAuditInput(test2) {
 }
 function findPendingProductTests(modules, projectRoot) {
   return modules.flatMap((module2) => {
-    const file = (0, import_node_path.relative)(projectRoot, module2.moduleId).replaceAll("\\", "/");
+    const file = (0, import_node_path2.relative)(projectRoot, module2.moduleId).replaceAll("\\", "/");
     if (file.split("/").includes("examples")) return [];
     const tests = [...module2.children.allTests()];
     const pending = tests.filter((test2) => {
@@ -752,7 +1004,10 @@ function truncateReporterLine(value, limit) {
 }
 function toModuleResult(module2, projectRoot) {
   const tests = [...module2.children.allTests()];
-  const moduleFailure = selectReactFailure(module2.errors(), module2.errors().length);
+  const moduleFailure = selectReactFailure(
+    module2.errors(),
+    module2.errors().length
+  );
   const moduleErrors = extractFailureEntries(module2.errors()).map(
     (entry) => firstLine(entry.message) ?? entry.message
   );
@@ -778,7 +1033,7 @@ function toModuleResult(module2, projectRoot) {
       causeCode: selected.code,
       cause: selected.cause,
       related: selected.related,
-      location: test2.location ? `${(0, import_node_path.relative)(projectRoot, module2.moduleId).replaceAll("\\", "/")}:${test2.location.line}:${test2.location.column}` : errorLocation(selected.rawCause),
+      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)
     };
@@ -794,7 +1049,7 @@ function toModuleResult(module2, projectRoot) {
     });
   }
   return {
-    file: (0, import_node_path.relative)(projectRoot, module2.moduleId).replaceAll("\\", "/"),
+    file: (0, import_node_path2.relative)(projectRoot, module2.moduleId).replaceAll("\\", "/"),
     state: module2.state(),
     errors,
     primaryError: moduleErrors[0] ?? failures[0]?.cause,
@@ -932,8 +1187,13 @@ function assessReactPlaythroughReport(input) {
   }
   return { ...base, status: "PASS", failsRun: false };
 }
-function formatReactPlaythroughReport(report) {
-  const lines = [`REACT_PLAYTHROUGH: ${report.status}`, `FILE: ${report.file}`];
+function formatReactPlaythroughReport(report, alignment) {
+  const lines = [
+    `REACT_PLAYTHROUGH_STRUCTURE: ${report.status}`,
+    `PRODUCT_TEST_ALIGNMENT: ${alignment?.status ?? "NOT_VERIFIED"}`,
+    `FILE: ${report.file}`
+  ];
+  if (alignment?.cause) lines.push(`ALIGNMENT_CAUSE: ${alignment.cause}`);
   if (report.causeCode) lines.push(`CAUSE_CODE: ${report.causeCode}`);
   if (report.cause) lines.push(`CAUSE: ${report.cause}`);
   for (const [index, related] of (report.related ?? []).entries()) {
@@ -956,7 +1216,7 @@ var ReactPlaythroughReporter = class {
   /** 绑定模板根目录，以稳定识别生产可玩性测试而不依赖测试名称。 */
   constructor(projectRoot) {
     this.projectRoot = projectRoot;
-    this.expectedModuleId = (0, import_node_path.resolve)(projectRoot, this.expectedFile);
+    this.expectedModuleId = (0, import_node_path2.resolve)(projectRoot, this.expectedFile);
   }
   projectRoot;
   expectedFile = PRODUCTION_PLAYTHROUGH_FILE;
@@ -966,7 +1226,7 @@ var ReactPlaythroughReporter = class {
   /** 记录本轮是否实际选择了生产流程文件，用于区分聚焦运行与门禁失败。 */
   onTestRunStart(specifications) {
     this.expectedFileScheduled = specifications.some(
-      (specification) => (0, import_node_path.resolve)(specification.moduleId) === this.expectedModuleId
+      (specification) => (0, import_node_path2.resolve)(specification.moduleId) === this.expectedModuleId
     );
     this.focusedSelection = specifications.some(
       (specification) => Boolean(specification.project.globalConfig.testNamePattern) || Boolean(specification.testNamePattern) || Boolean(specification.testLines?.length)
@@ -980,7 +1240,7 @@ var ReactPlaythroughReporter = class {
     );
     const report = assessReactPlaythroughReport({
       expectedFile: this.expectedFile,
-      expectedFileExists: (0, import_node_fs.existsSync)(this.expectedModuleId),
+      expectedFileExists: (0, import_node_fs2.existsSync)(this.expectedModuleId),
       expectedFileScheduled: this.expectedFileScheduled,
       focusedSelection: this.focusedSelection,
       modules: testModules.map(
@@ -990,8 +1250,9 @@ var ReactPlaythroughReporter = class {
         (entry) => firstLine(entry.message) ?? entry.message
       )
     });
-    const output = formatReactPlaythroughReport(report);
-    if (report.failsRun) {
+    const alignment = assessProductTestAlignment(this.projectRoot);
+    const output = formatReactPlaythroughReport(report, alignment);
+    if (report.failsRun || alignment.status === "FAILED") {
       console.error(output);
       process.exitCode = 1;
     } else if (report.status === "WAIVED" || report.status === "NOT_CHECKED") {
@@ -1007,7 +1268,7 @@ var ReactPlaythroughReporter = class {
     const summary = formatReactFailureSummary(
       testModules.map((module2) => toModuleResult(module2, this.projectRoot))
     );
-    if ((report.failsRun || pendingProductTests.length > 0) && summary[0] === "TEST_RESULT: PASS") {
+    if ((report.failsRun || alignment.status === "FAILED" || pendingProductTests.length > 0) && summary[0] === "TEST_RESULT: PASS") {
       summary[0] = "TEST_RESULT: FAIL";
     }
     console.log(`
@@ -1023,16 +1284,16 @@ function getJSDOMWorkerExecArgv() {
 
 // src/react-vitest-config.ts
 function resolvePhaser3BrowserEntry(projectRoot) {
-  const manifestPath = (0, import_node_path2.resolve)(projectRoot, "node_modules/phaser/package.json");
-  if (!(0, import_node_fs2.existsSync)(manifestPath)) return void 0;
+  const manifestPath = (0, import_node_path3.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_fs2.readFileSync)(manifestPath, "utf8"));
+    const manifest = JSON.parse((0, import_node_fs3.readFileSync)(manifestPath, "utf8"));
     if (!manifest.version?.startsWith("3.")) return void 0;
-    const browserEntry = (0, import_node_path2.resolve)(
-      (0, import_node_path2.dirname)(manifestPath),
+    const browserEntry = (0, import_node_path3.resolve)(
+      (0, import_node_path3.dirname)(manifestPath),
       manifest.browser ?? "dist/phaser.js"
     );
-    return (0, import_node_fs2.existsSync)(browserEntry) ? browserEntry : void 0;
+    return (0, import_node_fs3.existsSync)(browserEntry) ? browserEntry : void 0;
   } catch {
     return void 0;
   }
@@ -1047,7 +1308,7 @@ function defineReactGameVitestConfig(options) {
       alias: {
         ...phaser3BrowserEntry ? { phaser: phaser3BrowserEntry } : {},
         ...options.aliases,
-        "@": (0, import_node_path2.resolve)(options.projectRoot, "src")
+        "@": (0, import_node_path3.resolve)(options.projectRoot, "src")
       }
     },
     test: {

package/dist/react/vitest-config.mjs

@@ -1,13 +1,246 @@
 // src/react-vitest-config.ts
-import { existsSync as existsSync2, readFileSync } from "fs";
-import { dirname, resolve as resolve2 } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import { dirname as dirname2, resolve as resolve3 } from "path";
 import { defineConfig } from "vitest/config";
 
 // src/react/react-playthrough-reporter.ts
-import { existsSync } from "fs";
-import { relative, resolve } from "path";
+import { existsSync as existsSync2 } from "fs";
+import { relative as relative2, resolve as resolve2 } from "path";
 import { stripVTControlCharacters } from "util";
 
+// src/cli/react-authoritative-playthrough.ts
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { dirname, join, relative, resolve, sep } from "path";
+var PRODUCTION_PLAYTHROUGH = "tests/production-playthrough.test.tsx";
+var PRODUCTION_APP = "src/App.tsx";
+var EXAMPLE_IMPORT_PREFIX = "@/game/example/";
+var REACT_RUNTIME_ENTRY = "miaoda-game-devkit/react";
+var REACT_TESTING_ENTRY = "miaoda-game-devkit/react/testing";
+var CLOCK_IMPORTS = /* @__PURE__ */ new Set(["browserGameClock"]);
+var CONTROLLER_IMPORTS = /* @__PURE__ */ new Set([
+  "useGameController",
+  "useOwnedGameController"
+]);
+var SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([".js", ".jsx", ".ts", ".tsx"]);
+function runnableTestFiles(root, directory = join(root, "tests")) {
+  if (!existsSync(directory)) return [];
+  const files = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...runnableTestFiles(root, path));
+    } else if (entry.isFile() && /\.test\.[cm]?[jt]sx?$/.test(entry.name)) {
+      files.push(path);
+    }
+  }
+  return files;
+}
+function extension(path) {
+  const index = path.lastIndexOf(".");
+  return index < 0 ? "" : path.slice(index);
+}
+function sourceFiles(root, directory = join(root, "src")) {
+  if (!existsSync(directory)) return [];
+  const files = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const path = join(directory, entry.name);
+    const projectPath = relative(root, path).replaceAll("\\", "/");
+    if (entry.isDirectory()) {
+      if (projectPath === "src/game/example") continue;
+      files.push(...sourceFiles(root, path));
+    } else if (entry.isFile() && SOURCE_EXTENSIONS.has(extension(entry.name))) {
+      files.push(path);
+    }
+  }
+  return files;
+}
+function withoutComments(source) {
+  let output = "";
+  let state = "code";
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index];
+    const next = source[index + 1];
+    if (state === "line") {
+      if (char === "\n") {
+        state = "code";
+        output += char;
+      } else {
+        output += " ";
+      }
+      continue;
+    }
+    if (state === "block") {
+      if (char === "*" && next === "/") {
+        output += "  ";
+        index += 1;
+        state = "code";
+      } else {
+        output += char === "\n" ? "\n" : " ";
+      }
+      continue;
+    }
+    if (state === "code" && char === "/" && next === "/") {
+      output += "  ";
+      index += 1;
+      state = "line";
+      continue;
+    }
+    if (state === "code" && char === "/" && next === "*") {
+      output += "  ";
+      index += 1;
+      state = "block";
+      continue;
+    }
+    if (state === "code" && char === "'") state = "single";
+    else if (state === "code" && char === '"') state = "double";
+    else if (state === "code" && char === "`") state = "template";
+    else if (state === "single" && char === "'" && source[index - 1] !== "\\") {
+      state = "code";
+    } else if (state === "double" && char === '"' && source[index - 1] !== "\\") {
+      state = "code";
+    } else if (state === "template" && char === "`" && source[index - 1] !== "\\") {
+      state = "code";
+    }
+    output += char;
+  }
+  return output;
+}
+function codePositions(source) {
+  const positions = Array.from({ length: source.length }, () => false);
+  let state = "code";
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index];
+    if (state === "code") positions[index] = true;
+    if (state === "code" && char === "'") state = "single";
+    else if (state === "code" && char === '"') state = "double";
+    else if (state === "code" && char === "`") state = "template";
+    else if (state === "single" && char === "'" && source[index - 1] !== "\\") {
+      state = "code";
+    } else if (state === "double" && char === '"' && source[index - 1] !== "\\") {
+      state = "code";
+    } else if (state === "template" && char === "`" && source[index - 1] !== "\\") {
+      state = "code";
+    }
+  }
+  return positions;
+}
+function importedModuleSpecifiers(source) {
+  const clean = withoutComments(source);
+  const positions = codePositions(clean);
+  const modules = [];
+  const pattern = /\b(?:from\s+|import\s*(?:\(\s*)?)["']([^"']+)["']\s*\)?/g;
+  for (const match of clean.matchAll(pattern)) {
+    if (positions[match.index]) modules.push(match[1]);
+  }
+  return modules;
+}
+function productionFileImportsExample(file, projectRoot) {
+  const exampleRoot = join(projectRoot, "src/game/example");
+  return importedModuleSpecifiers(readFileSync(file, "utf8")).some(
+    (moduleName) => {
+      if (moduleName.startsWith(EXAMPLE_IMPORT_PREFIX)) return true;
+      if (!moduleName.startsWith(".")) return false;
+      const target = resolve(dirname(file), moduleName);
+      return target === exampleRoot || target.startsWith(`${exampleRoot}${sep}`);
+    }
+  );
+}
+function importsExampleAlias(source) {
+  return importedModuleSpecifiers(source).some(
+    (moduleName) => moduleName.startsWith(EXAMPLE_IMPORT_PREFIX)
+  );
+}
+function namedImports(source, moduleName) {
+  const names = /* @__PURE__ */ new Set();
+  const clean = withoutComments(source);
+  const positions = codePositions(clean);
+  const escapedModule = moduleName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(
+    `^\\s*import\\s+(?:type\\s+)?\\{([\\s\\S]*?)\\}\\s+from\\s+["']${escapedModule}["']`,
+    "gm"
+  );
+  for (const match of clean.matchAll(pattern)) {
+    if (!positions[match.index]) continue;
+    for (const specifier of match[1].split(",")) {
+      const imported = specifier.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0].trim();
+      if (imported) names.add(imported);
+    }
+  }
+  return names;
+}
+function containsAny(values, expected) {
+  return [...values].some((value) => expected.has(value));
+}
+function declaresObserve(source) {
+  const clean = withoutComments(source);
+  const positions = codePositions(clean);
+  for (const match of clean.matchAll(/\bobserve\s*:/g)) {
+    if (positions[match.index]) return true;
+  }
+  return false;
+}
+function auditReactAuthoritativePlaythrough(projectRoot) {
+  const clockFiles = [];
+  const controllerFiles = [];
+  const productionFiles = sourceFiles(projectRoot);
+  for (const file of productionFiles) {
+    const imports = namedImports(
+      readFileSync(file, "utf8"),
+      REACT_RUNTIME_ENTRY
+    );
+    const projectPath = relative(projectRoot, file).replaceAll("\\", "/");
+    if (containsAny(imports, CLOCK_IMPORTS)) clockFiles.push(projectPath);
+    if (containsAny(imports, CONTROLLER_IMPORTS))
+      controllerFiles.push(projectPath);
+  }
+  const appPath = join(projectRoot, PRODUCTION_APP);
+  const productionEntryExists = existsSync(appPath);
+  const productionUsesExample = productionFiles.some(
+    (file) => productionFileImportsExample(file, projectRoot)
+  );
+  const staleExampleTestFiles = productionUsesExample ? [] : runnableTestFiles(projectRoot).filter((file) => importsExampleAlias(readFileSync(file, "utf8"))).map((file) => relative(projectRoot, file).replaceAll("\\", "/"));
+  const issues = [];
+  if (staleExampleTestFiles.length > 0) {
+    issues.push(
+      `Production ${PRODUCTION_APP} no longer imports ${EXAMPLE_IMPORT_PREFIX}*, but runnable product tests still do: ${staleExampleTestFiles.join(", ")}. Replace those CollectGame tests with tests for the production game or delete genuinely inapplicable slots. Teaching examples under tests/examples/**/*.example.* remain allowed.`
+    );
+  }
+  if (clockFiles.length === 0 && controllerFiles.length === 0) {
+    return {
+      ok: issues.length === 0,
+      issues,
+      clockFiles,
+      controllerFiles,
+      productionEntryExists,
+      productionUsesExample,
+      staleExampleTestFiles
+    };
+  }
+  const testPath = join(projectRoot, PRODUCTION_PLAYTHROUGH);
+  const testSource = existsSync(testPath) ? readFileSync(testPath, "utf8") : "";
+  const testingImports = namedImports(testSource, REACT_TESTING_ENTRY);
+  const hasObserve = declaresObserve(testSource);
+  if (!hasObserve) {
+    issues.push(
+      `${PRODUCTION_PLAYTHROUGH} must declare observe because production uses the devkit clock or Controller ownership hook. 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";
@@ -594,6 +827,25 @@ function auditReactPlaythroughRun(tests) {
 // src/react/react-playthrough-reporter.ts
 var PRODUCTION_PLAYTHROUGH_FILE = "tests/production-playthrough.test.tsx";
 var REPAIR_CONSTRAINT = "Preserve the intended gameplay outcome. Fix the production mechanic, deterministic driver, or authoritative observation that prevents it. Do not make the test pass by weakening or deleting assertions, replacing the outcome with back/menu/exit navigation, observing arbitrary UI text only to change a fingerprint, using a no-op step, or treating an intermediate active/in-flight/running phase as meaningful progress.";
+function assessProductTestAlignment(projectRoot) {
+  const audit = auditReactAuthoritativePlaythrough(projectRoot);
+  if (audit.staleExampleTestFiles.length > 0) {
+    return { status: "FAILED", cause: audit.issues[0] };
+  }
+  if (!audit.productionEntryExists) {
+    return {
+      status: "NOT_VERIFIED",
+      cause: "The production src/App.tsx entry does not exist, so product-test alignment could not be verified."
+    };
+  }
+  if (audit.productionUsesExample) {
+    return {
+      status: "NOT_VERIFIED",
+      cause: "The production App still uses the replaceable src/game/example teaching game, so replacement-game test alignment is not applicable yet."
+    };
+  }
+  return { status: "PASS" };
+}
 function isMetadata(value) {
   if (!value || typeof value !== "object") return false;
   const metadata = value;
@@ -621,7 +873,7 @@ function toAuditInput(test2) {
 }
 function findPendingProductTests(modules, projectRoot) {
   return modules.flatMap((module) => {
-    const file = relative(projectRoot, module.moduleId).replaceAll("\\", "/");
+    const file = relative2(projectRoot, module.moduleId).replaceAll("\\", "/");
     if (file.split("/").includes("examples")) return [];
     const tests = [...module.children.allTests()];
     const pending = tests.filter((test2) => {
@@ -718,7 +970,10 @@ function truncateReporterLine(value, limit) {
 }
 function toModuleResult(module, projectRoot) {
   const tests = [...module.children.allTests()];
-  const moduleFailure = selectReactFailure(module.errors(), module.errors().length);
+  const moduleFailure = selectReactFailure(
+    module.errors(),
+    module.errors().length
+  );
   const moduleErrors = extractFailureEntries(module.errors()).map(
     (entry) => firstLine(entry.message) ?? entry.message
   );
@@ -744,7 +999,7 @@ function toModuleResult(module, projectRoot) {
       causeCode: selected.code,
       cause: selected.cause,
       related: selected.related,
-      location: test2.location ? `${relative(projectRoot, module.moduleId).replaceAll("\\", "/")}:${test2.location.line}:${test2.location.column}` : errorLocation(selected.rawCause),
+      location: test2.location ? `${relative2(projectRoot, module.moduleId).replaceAll("\\", "/")}:${test2.location.line}:${test2.location.column}` : errorLocation(selected.rawCause),
       hint: failureHint(selected.rawCause),
       trace: failureTrace(test2)
     };
@@ -760,7 +1015,7 @@ function toModuleResult(module, projectRoot) {
     });
   }
   return {
-    file: relative(projectRoot, module.moduleId).replaceAll("\\", "/"),
+    file: relative2(projectRoot, module.moduleId).replaceAll("\\", "/"),
     state: module.state(),
     errors,
     primaryError: moduleErrors[0] ?? failures[0]?.cause,
@@ -898,8 +1153,13 @@ function assessReactPlaythroughReport(input) {
   }
   return { ...base, status: "PASS", failsRun: false };
 }
-function formatReactPlaythroughReport(report) {
-  const lines = [`REACT_PLAYTHROUGH: ${report.status}`, `FILE: ${report.file}`];
+function formatReactPlaythroughReport(report, alignment) {
+  const lines = [
+    `REACT_PLAYTHROUGH_STRUCTURE: ${report.status}`,
+    `PRODUCT_TEST_ALIGNMENT: ${alignment?.status ?? "NOT_VERIFIED"}`,
+    `FILE: ${report.file}`
+  ];
+  if (alignment?.cause) lines.push(`ALIGNMENT_CAUSE: ${alignment.cause}`);
   if (report.causeCode) lines.push(`CAUSE_CODE: ${report.causeCode}`);
   if (report.cause) lines.push(`CAUSE: ${report.cause}`);
   for (const [index, related] of (report.related ?? []).entries()) {
@@ -922,7 +1182,7 @@ var ReactPlaythroughReporter = class {
   /** 绑定模板根目录，以稳定识别生产可玩性测试而不依赖测试名称。 */
   constructor(projectRoot) {
     this.projectRoot = projectRoot;
-    this.expectedModuleId = resolve(projectRoot, this.expectedFile);
+    this.expectedModuleId = resolve2(projectRoot, this.expectedFile);
   }
   projectRoot;
   expectedFile = PRODUCTION_PLAYTHROUGH_FILE;
@@ -932,7 +1192,7 @@ var ReactPlaythroughReporter = class {
   /** 记录本轮是否实际选择了生产流程文件，用于区分聚焦运行与门禁失败。 */
   onTestRunStart(specifications) {
     this.expectedFileScheduled = specifications.some(
-      (specification) => resolve(specification.moduleId) === this.expectedModuleId
+      (specification) => resolve2(specification.moduleId) === this.expectedModuleId
     );
     this.focusedSelection = specifications.some(
       (specification) => Boolean(specification.project.globalConfig.testNamePattern) || Boolean(specification.testNamePattern) || Boolean(specification.testLines?.length)
@@ -946,7 +1206,7 @@ var ReactPlaythroughReporter = class {
     );
     const report = assessReactPlaythroughReport({
       expectedFile: this.expectedFile,
-      expectedFileExists: existsSync(this.expectedModuleId),
+      expectedFileExists: existsSync2(this.expectedModuleId),
       expectedFileScheduled: this.expectedFileScheduled,
       focusedSelection: this.focusedSelection,
       modules: testModules.map(
@@ -956,8 +1216,9 @@ var ReactPlaythroughReporter = class {
         (entry) => firstLine(entry.message) ?? entry.message
       )
     });
-    const output = formatReactPlaythroughReport(report);
-    if (report.failsRun) {
+    const alignment = assessProductTestAlignment(this.projectRoot);
+    const output = formatReactPlaythroughReport(report, alignment);
+    if (report.failsRun || alignment.status === "FAILED") {
       console.error(output);
       process.exitCode = 1;
     } else if (report.status === "WAIVED" || report.status === "NOT_CHECKED") {
@@ -973,7 +1234,7 @@ var ReactPlaythroughReporter = class {
     const summary = formatReactFailureSummary(
       testModules.map((module) => toModuleResult(module, this.projectRoot))
     );
-    if ((report.failsRun || pendingProductTests.length > 0) && summary[0] === "TEST_RESULT: PASS") {
+    if ((report.failsRun || alignment.status === "FAILED" || pendingProductTests.length > 0) && summary[0] === "TEST_RESULT: PASS") {
       summary[0] = "TEST_RESULT: FAIL";
     }
     console.log(`
@@ -989,16 +1250,16 @@ function getJSDOMWorkerExecArgv() {
 
 // src/react-vitest-config.ts
 function resolvePhaser3BrowserEntry(projectRoot) {
-  const manifestPath = resolve2(projectRoot, "node_modules/phaser/package.json");
-  if (!existsSync2(manifestPath)) return void 0;
+  const manifestPath = resolve3(projectRoot, "node_modules/phaser/package.json");
+  if (!existsSync3(manifestPath)) return void 0;
   try {
-    const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    const manifest = JSON.parse(readFileSync2(manifestPath, "utf8"));
     if (!manifest.version?.startsWith("3.")) return void 0;
-    const browserEntry = resolve2(
-      dirname(manifestPath),
+    const browserEntry = resolve3(
+      dirname2(manifestPath),
       manifest.browser ?? "dist/phaser.js"
     );
-    return existsSync2(browserEntry) ? browserEntry : void 0;
+    return existsSync3(browserEntry) ? browserEntry : void 0;
   } catch {
     return void 0;
   }
@@ -1013,7 +1274,7 @@ function defineReactGameVitestConfig(options) {
       alias: {
         ...phaser3BrowserEntry ? { phaser: phaser3BrowserEntry } : {},
         ...options.aliases,
-        "@": resolve2(options.projectRoot, "src")
+        "@": resolve3(options.projectRoot, "src")
       }
     },
     test: {

package/dist/rules/react-test-boundary-plugin.js

@@ -57,7 +57,7 @@ var rule = {
       providedUser: "Use the user provided by playthroughTest; do not import or create another userEvent instance in the production playthrough.",
       productionTestingImport: "Production source must not import miaoda-game-devkit/react/testing. Inject test clocks and observers through the production App factory boundary.",
       productionEntry: "Render <App /> from the production playthrough. Import Controller and Telemetry helpers when needed, but do not render an internal game component directly.",
-      emptyStep: "A deterministic step must advance production-owned time, frames, or queued work. An empty step is not gameplay evidence. Inject ManualGameClock through <App /> and call clock.stepFrame(...)."
+      emptyStep: 'A deterministic step must advance production-owned time, frames, or queued work. An empty step is not gameplay evidence. Add import { ManualGameClock } from "miaoda-game-devkit/react/testing"; inject it through the production <App /> factory, and use step: () => clock.stepFrame().'
     },
     schema: []
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miaoda-game-devkit",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Shared React and Phaser game lint plus deterministic testing tools for Miaoda games",
   "license": "MIT",
   "main": "./dist/index.js",