miaoda-game-devkit 0.6.6 → 0.7.0

package/dist/cli/phaser-lint.js

@@ -11,6 +11,7 @@ var import_node_path2 = require("path");
 // src/cli/react-authoritative-playthrough.ts
 var import_node_fs = require("fs");
 var import_node_path = require("path");
+var import_oxc_parser = require("oxc-parser");
 var PRODUCTION_PLAYTHROUGH = "tests/production-playthrough.test.tsx";
 var PRODUCTION_APP = "src/App.tsx";
 var EXAMPLE_IMPORT_PREFIX = "@/game/example/";
@@ -54,89 +55,36 @@ function sourceFiles(root, directory = (0, import_node_path.join)(root, "src"))
   }
   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 parseSource(file, source) {
+  return (0, import_oxc_parser.parseSync)(file, source, { sourceType: "module" });
 }
-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 staticImports(file, source) {
+  return parseSource(file, source).module.staticImports;
 }
-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]);
+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, projectRoot2) {
   const exampleRoot = (0, import_node_path.join)(projectRoot2, "src/game/example");
-  return importedModuleSpecifiers((0, import_node_fs.readFileSync)(file, "utf8")).some(
+  return importedModuleSpecifiers(file, (0, import_node_fs.readFileSync)(file, "utf8")).some(
     (moduleName) => {
       if (moduleName.startsWith(EXAMPLE_IMPORT_PREFIX)) return true;
       if (!moduleName.startsWith(".")) return false;
@@ -145,25 +93,19 @@ function productionFileImportsExample(file, projectRoot2) {
     }
   );
 }
-function importsExampleAlias(source) {
-  return importedModuleSpecifiers(source).some(
+function importsExampleAlias(file, source) {
+  return importedModuleSpecifiers(file, source).some(
     (moduleName) => moduleName.startsWith(EXAMPLE_IMPORT_PREFIX)
   );
 }
-function namedImports(source, moduleName) {
+function namedImports(file, 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);
+  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;
@@ -171,13 +113,20 @@ function namedImports(source, moduleName) {
 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;
+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 false;
+  return Object.values(value).some(containsObserveProperty);
+}
+function declaresObserve(file, source) {
+  return containsObserveProperty(parseSource(file, source).program);
 }
 function auditReactAuthoritativePlaythrough(projectRoot2) {
   const clockFiles = [];
@@ -185,6 +134,7 @@ function auditReactAuthoritativePlaythrough(projectRoot2) {
   const productionFiles = sourceFiles(projectRoot2);
   for (const file of productionFiles) {
     const imports = namedImports(
+      file,
       (0, import_node_fs.readFileSync)(file, "utf8"),
       REACT_RUNTIME_ENTRY
     );
@@ -198,7 +148,9 @@ function auditReactAuthoritativePlaythrough(projectRoot2) {
   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 staleExampleTestFiles = productionUsesExample ? [] : runnableTestFiles(projectRoot2).filter(
+    (file) => importsExampleAlias(file, (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(
@@ -218,8 +170,12 @@ function auditReactAuthoritativePlaythrough(projectRoot2) {
   }
   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") : "";
-  const testingImports = namedImports(testSource, REACT_TESTING_ENTRY);
-  const hasObserve = declaresObserve(testSource);
+  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.`
@@ -348,14 +304,15 @@ function checkVitestConfig(target) {
   }
   return { name, ok: true };
 }
-function checkReactAuthoritativePlaythrough() {
-  const name = "react-authoritative-playthrough";
+function checkReactProductTestAlignment() {
+  const name = "react-product-test-alignment";
   const audit = auditReactAuthoritativePlaythrough(projectRoot);
-  for (const issue of audit.issues) console.error(`[${name}] ${issue}`);
-  return { name, ok: audit.ok };
+  if (audit.staleExampleTestFiles.length === 0) return { name, ok: true };
+  console.error(`[${name}] ${audit.issues[0]}`);
+  return { name, ok: false };
 }
 async function runAllChecks(target) {
-  const targetChecks = target === "react" ? [checkVitestConfig("react"), checkReactAuthoritativePlaythrough()] : [checkPhaser4Dependency(), checkPhaserViteConfig(), checkVitestConfig("phaser")];
+  const targetChecks = target === "react" ? [checkVitestConfig("react"), checkReactProductTestAlignment()] : [checkPhaser4Dependency(), checkPhaserViteConfig(), checkVitestConfig("phaser")];
   const lintRoots = target === "react" && (0, import_node_fs2.existsSync)((0, import_node_path2.join)(projectRoot, "tests")) ? ["src", "tests"] : ["src"];
   const [tsgo, biome] = await Promise.all([
     run("tsgo", "@typescript/native-preview", "tsgo", ["-p", "tsconfig.json"]),

package/dist/cli/react-lint.js

@@ -11,6 +11,7 @@ var import_node_path2 = require("path");
 // src/cli/react-authoritative-playthrough.ts
 var import_node_fs = require("fs");
 var import_node_path = require("path");
+var import_oxc_parser = require("oxc-parser");
 var PRODUCTION_PLAYTHROUGH = "tests/production-playthrough.test.tsx";
 var PRODUCTION_APP = "src/App.tsx";
 var EXAMPLE_IMPORT_PREFIX = "@/game/example/";
@@ -54,89 +55,36 @@ function sourceFiles(root, directory = (0, import_node_path.join)(root, "src"))
   }
   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 parseSource(file, source) {
+  return (0, import_oxc_parser.parseSync)(file, source, { sourceType: "module" });
 }
-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 staticImports(file, source) {
+  return parseSource(file, source).module.staticImports;
 }
-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]);
+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, projectRoot2) {
   const exampleRoot = (0, import_node_path.join)(projectRoot2, "src/game/example");
-  return importedModuleSpecifiers((0, import_node_fs.readFileSync)(file, "utf8")).some(
+  return importedModuleSpecifiers(file, (0, import_node_fs.readFileSync)(file, "utf8")).some(
     (moduleName) => {
       if (moduleName.startsWith(EXAMPLE_IMPORT_PREFIX)) return true;
       if (!moduleName.startsWith(".")) return false;
@@ -145,25 +93,19 @@ function productionFileImportsExample(file, projectRoot2) {
     }
   );
 }
-function importsExampleAlias(source) {
-  return importedModuleSpecifiers(source).some(
+function importsExampleAlias(file, source) {
+  return importedModuleSpecifiers(file, source).some(
     (moduleName) => moduleName.startsWith(EXAMPLE_IMPORT_PREFIX)
   );
 }
-function namedImports(source, moduleName) {
+function namedImports(file, 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);
+  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;
@@ -171,13 +113,20 @@ function namedImports(source, moduleName) {
 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;
+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 false;
+  return Object.values(value).some(containsObserveProperty);
+}
+function declaresObserve(file, source) {
+  return containsObserveProperty(parseSource(file, source).program);
 }
 function auditReactAuthoritativePlaythrough(projectRoot2) {
   const clockFiles = [];
@@ -185,6 +134,7 @@ function auditReactAuthoritativePlaythrough(projectRoot2) {
   const productionFiles = sourceFiles(projectRoot2);
   for (const file of productionFiles) {
     const imports = namedImports(
+      file,
       (0, import_node_fs.readFileSync)(file, "utf8"),
       REACT_RUNTIME_ENTRY
     );
@@ -198,7 +148,9 @@ function auditReactAuthoritativePlaythrough(projectRoot2) {
   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 staleExampleTestFiles = productionUsesExample ? [] : runnableTestFiles(projectRoot2).filter(
+    (file) => importsExampleAlias(file, (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(
@@ -218,8 +170,12 @@ function auditReactAuthoritativePlaythrough(projectRoot2) {
   }
   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") : "";
-  const testingImports = namedImports(testSource, REACT_TESTING_ENTRY);
-  const hasObserve = declaresObserve(testSource);
+  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.`
@@ -348,14 +304,15 @@ function checkVitestConfig(target) {
   }
   return { name, ok: true };
 }
-function checkReactAuthoritativePlaythrough() {
-  const name = "react-authoritative-playthrough";
+function checkReactProductTestAlignment() {
+  const name = "react-product-test-alignment";
   const audit = auditReactAuthoritativePlaythrough(projectRoot);
-  for (const issue of audit.issues) console.error(`[${name}] ${issue}`);
-  return { name, ok: audit.ok };
+  if (audit.staleExampleTestFiles.length === 0) return { name, ok: true };
+  console.error(`[${name}] ${audit.issues[0]}`);
+  return { name, ok: false };
 }
 async function runAllChecks(target) {
-  const targetChecks = target === "react" ? [checkVitestConfig("react"), checkReactAuthoritativePlaythrough()] : [checkPhaser4Dependency(), checkPhaserViteConfig(), checkVitestConfig("phaser")];
+  const targetChecks = target === "react" ? [checkVitestConfig("react"), checkReactProductTestAlignment()] : [checkPhaser4Dependency(), checkPhaserViteConfig(), checkVitestConfig("phaser")];
   const lintRoots = target === "react" && (0, import_node_fs2.existsSync)((0, import_node_path2.join)(projectRoot, "tests")) ? ["src", "tests"] : ["src"];
   const [tsgo, biome] = await Promise.all([
     run("tsgo", "@typescript/native-preview", "tsgo", ["-p", "tsconfig.json"]),

package/dist/react/index.d.mts

@@ -18,6 +18,9 @@ interface SubscribableGameController<TState> extends DisposableGameController {
 /**
  * 一次调用接管游戏 Controller 的创建、销毁与状态订阅：
  * useOwnedGameController 的 ownership，加上 useSyncExternalStore 的渲染桥。
+ * `createController` 是零参数工厂；hook 不会向它传 clock、options 或 props。
+ * 需要注入依赖时在调用处闭包捕获，例如：
+ * `useGameController(() => gameFactory({ ...options, clock }))`。
  *
  * 附带一道开发期检查：状态内容变了、但 snapshot() 返回的还是原来那个
  * 对象时，React 会认为"什么都没变"而不刷新界面——游戏悄悄卡死，没有

package/dist/react/index.d.ts

@@ -18,6 +18,9 @@ interface SubscribableGameController<TState> extends DisposableGameController {
 /**
  * 一次调用接管游戏 Controller 的创建、销毁与状态订阅：
  * useOwnedGameController 的 ownership，加上 useSyncExternalStore 的渲染桥。
+ * `createController` 是零参数工厂；hook 不会向它传 clock、options 或 props。
+ * 需要注入依赖时在调用处闭包捕获，例如：
+ * `useGameController(() => gameFactory({ ...options, clock }))`。
  *
  * 附带一道开发期检查：状态内容变了、但 snapshot() 返回的还是原来那个
  * 对象时，React 会认为"什么都没变"而不刷新界面——游戏悄悄卡死，没有

package/dist/react/testing.d.mts

@@ -99,6 +99,10 @@ interface ReactPlaythroughAssertContext {
     user: UserEvent;
     view: RenderResult;
 }
+/**
+ * 每个阶段独立声明完成条件、断言和推进上限。确定性 `step` 属于具体阶段，
+ * 不存在 playthrough 顶层的共享 step；这样失败 TRACE 才能归属到准确区间。
+ */
 interface ReactPlaythroughStageShared {
     until: () => boolean;
     assert: (context: ReactPlaythroughAssertContext) => void | Promise<void>;
@@ -129,7 +133,13 @@ interface ReactPlaythroughArguments {
 }
 type ReactPlaythroughRun = (arguments_: ReactPlaythroughArguments) => void | Promise<void>;
 interface ReactPlaythroughTest {
+    /** 第一个参数是实际渲染的 ReactNode；简单游戏直接传 `<App />`。 */
     (element: ReactNode, run: ReactPlaythroughRun): void;
+    /**
+     * Controller/Canvas 游戏仍传生产 `<App gameFactory={factory} />`，通过
+     * options.observe 读取同一个 Controller。不要把 `(clock) => <App />`
+     * 之类的元素工厂传到这里；clock 应由 App 的 Controller factory 闭包注入。
+     */
     (element: ReactNode, options: ReactPlaythroughOptions, run: ReactPlaythroughRun): void;
     skip(reason: string, element: ReactNode): void;
 }

package/dist/react/testing.d.ts

@@ -99,6 +99,10 @@ interface ReactPlaythroughAssertContext {
     user: UserEvent;
     view: RenderResult;
 }
+/**
+ * 每个阶段独立声明完成条件、断言和推进上限。确定性 `step` 属于具体阶段，
+ * 不存在 playthrough 顶层的共享 step；这样失败 TRACE 才能归属到准确区间。
+ */
 interface ReactPlaythroughStageShared {
     until: () => boolean;
     assert: (context: ReactPlaythroughAssertContext) => void | Promise<void>;
@@ -129,7 +133,13 @@ interface ReactPlaythroughArguments {
 }
 type ReactPlaythroughRun = (arguments_: ReactPlaythroughArguments) => void | Promise<void>;
 interface ReactPlaythroughTest {
+    /** 第一个参数是实际渲染的 ReactNode；简单游戏直接传 `<App />`。 */
     (element: ReactNode, run: ReactPlaythroughRun): void;
+    /**
+     * Controller/Canvas 游戏仍传生产 `<App gameFactory={factory} />`，通过
+     * options.observe 读取同一个 Controller。不要把 `(clock) => <App />`
+     * 之类的元素工厂传到这里；clock 应由 App 的 Controller factory 闭包注入。
+     */
     (element: ReactNode, options: ReactPlaythroughOptions, run: ReactPlaythroughRun): void;
     skip(reason: string, element: ReactNode): void;
 }

package/dist/react/testing.js

@@ -341,10 +341,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}`
   );
 }

package/dist/react/testing.mjs

@@ -303,10 +303,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}`
   );
 }

package/dist/react/vitest-config.d.mts

@@ -3,6 +3,11 @@ import { ViteUserConfig } from 'vitest/config';
 interface ReactGameVitestConfigOptions {
     /** React 模板的绝对根目录，通常传入 `import.meta.dirname`。 */
     projectRoot: string;
+    /**
+     * Opt in to the legacy structured playthrough gate. Ordinary React game
+     * projects should use independent Vitest scenarios and leave this disabled.
+     */
+    enablePlaythroughReporter?: boolean;
     aliases?: Record<string, string>;
     additionalSetupFiles?: string[];
     testTimeout?: number;

package/dist/react/vitest-config.d.ts

@@ -3,6 +3,11 @@ import { ViteUserConfig } from 'vitest/config';
 interface ReactGameVitestConfigOptions {
     /** React 模板的绝对根目录，通常传入 `import.meta.dirname`。 */
     projectRoot: string;
+    /**
+     * Opt in to the legacy structured playthrough gate. Ordinary React game
+     * projects should use independent Vitest scenarios and leave this disabled.
+     */
+    enablePlaythroughReporter?: boolean;
     aliases?: Record<string, string>;
     additionalSetupFiles?: string[];
     testTimeout?: number;

package/dist/react/vitest-config.js

@@ -295,10 +295,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}`
   );
 }
@@ -1047,6 +1047,7 @@ ${lines.join("\n")}`;
 // src/cli/react-authoritative-playthrough.ts
 var import_node_fs = require("fs");
 var import_node_path2 = require("path");
+var import_oxc_parser = require("oxc-parser");
 var PRODUCTION_PLAYTHROUGH = "tests/production-playthrough.test.tsx";
 var PRODUCTION_APP = "src/App.tsx";
 var EXAMPLE_IMPORT_PREFIX = "@/game/example/";
@@ -1090,89 +1091,36 @@ function sourceFiles(root, directory = (0, import_node_path2.join)(root, "src"))
   }
   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 parseSource(file, source) {
+  return (0, import_oxc_parser.parseSync)(file, source, { sourceType: "module" });
+}
+function staticImports(file, source) {
+  return parseSource(file, source).module.staticImports;
 }
-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]);
+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 = (0, import_node_path2.join)(projectRoot, "src/game/example");
-  return importedModuleSpecifiers((0, import_node_fs.readFileSync)(file, "utf8")).some(
+  return importedModuleSpecifiers(file, (0, import_node_fs.readFileSync)(file, "utf8")).some(
     (moduleName) => {
       if (moduleName.startsWith(EXAMPLE_IMPORT_PREFIX)) return true;
       if (!moduleName.startsWith(".")) return false;
@@ -1181,25 +1129,19 @@ function productionFileImportsExample(file, projectRoot) {
     }
   );
 }
-function importsExampleAlias(source) {
-  return importedModuleSpecifiers(source).some(
+function importsExampleAlias(file, source) {
+  return importedModuleSpecifiers(file, source).some(
     (moduleName) => moduleName.startsWith(EXAMPLE_IMPORT_PREFIX)
   );
 }
-function namedImports(source, moduleName) {
+function namedImports(file, 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);
+  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;
@@ -1207,13 +1149,20 @@ function namedImports(source, moduleName) {
 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;
+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 false;
+  return Object.values(value).some(containsObserveProperty);
+}
+function declaresObserve(file, source) {
+  return containsObserveProperty(parseSource(file, source).program);
 }
 function auditReactAuthoritativePlaythrough(projectRoot) {
   const clockFiles = [];
@@ -1221,6 +1170,7 @@ function auditReactAuthoritativePlaythrough(projectRoot) {
   const productionFiles = sourceFiles(projectRoot);
   for (const file of productionFiles) {
     const imports = namedImports(
+      file,
       (0, import_node_fs.readFileSync)(file, "utf8"),
       REACT_RUNTIME_ENTRY
     );
@@ -1234,7 +1184,9 @@ function auditReactAuthoritativePlaythrough(projectRoot) {
   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_path2.relative)(projectRoot, file).replaceAll("\\", "/"));
+  const staleExampleTestFiles = productionUsesExample ? [] : runnableTestFiles(projectRoot).filter(
+    (file) => importsExampleAlias(file, (0, import_node_fs.readFileSync)(file, "utf8"))
+  ).map((file) => (0, import_node_path2.relative)(projectRoot, file).replaceAll("\\", "/"));
   const issues = [];
   if (staleExampleTestFiles.length > 0) {
     issues.push(
@@ -1254,8 +1206,12 @@ function auditReactAuthoritativePlaythrough(projectRoot) {
   }
   const testPath = (0, import_node_path2.join)(projectRoot, PRODUCTION_PLAYTHROUGH);
   const testSource = (0, import_node_fs.existsSync)(testPath) ? (0, import_node_fs.readFileSync)(testPath, "utf8") : "";
-  const testingImports = namedImports(testSource, REACT_TESTING_ENTRY);
-  const hasObserve = declaresObserve(testSource);
+  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.`
@@ -1311,6 +1267,8 @@ 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":
@@ -1528,8 +1486,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,

package/dist/react/vitest-config.mjs

@@ -261,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}`
   );
 }
@@ -1013,6 +1013,7 @@ ${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/";
@@ -1056,89 +1057,36 @@ function sourceFiles(root, directory = join(root, "src")) {
   }
   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 parseSource(file, source) {
+  return parseSync(file, source, { sourceType: "module" });
+}
+function staticImports(file, source) {
+  return parseSource(file, source).module.staticImports;
 }
-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]);
+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(readFileSync(file, "utf8")).some(
+  return importedModuleSpecifiers(file, readFileSync(file, "utf8")).some(
     (moduleName) => {
       if (moduleName.startsWith(EXAMPLE_IMPORT_PREFIX)) return true;
       if (!moduleName.startsWith(".")) return false;
@@ -1147,25 +1095,19 @@ function productionFileImportsExample(file, projectRoot) {
     }
   );
 }
-function importsExampleAlias(source) {
-  return importedModuleSpecifiers(source).some(
+function importsExampleAlias(file, source) {
+  return importedModuleSpecifiers(file, source).some(
     (moduleName) => moduleName.startsWith(EXAMPLE_IMPORT_PREFIX)
   );
 }
-function namedImports(source, moduleName) {
+function namedImports(file, 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);
+  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;
@@ -1173,13 +1115,20 @@ function namedImports(source, moduleName) {
 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;
+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 false;
+  return Object.values(value).some(containsObserveProperty);
+}
+function declaresObserve(file, source) {
+  return containsObserveProperty(parseSource(file, source).program);
 }
 function auditReactAuthoritativePlaythrough(projectRoot) {
   const clockFiles = [];
@@ -1187,6 +1136,7 @@ function auditReactAuthoritativePlaythrough(projectRoot) {
   const productionFiles = sourceFiles(projectRoot);
   for (const file of productionFiles) {
     const imports = namedImports(
+      file,
       readFileSync(file, "utf8"),
       REACT_RUNTIME_ENTRY
     );
@@ -1200,7 +1150,9 @@ function auditReactAuthoritativePlaythrough(projectRoot) {
   const productionUsesExample = productionFiles.some(
     (file) => productionFileImportsExample(file, projectRoot)
   );
-  const staleExampleTestFiles = productionUsesExample ? [] : runnableTestFiles(projectRoot).filter((file) => importsExampleAlias(readFileSync(file, "utf8"))).map((file) => relative2(projectRoot, file).replaceAll("\\", "/"));
+  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(
@@ -1220,8 +1172,12 @@ function auditReactAuthoritativePlaythrough(projectRoot) {
   }
   const testPath = join(projectRoot, PRODUCTION_PLAYTHROUGH);
   const testSource = existsSync(testPath) ? readFileSync(testPath, "utf8") : "";
-  const testingImports = namedImports(testSource, REACT_TESTING_ENTRY);
-  const hasObserve = declaresObserve(testSource);
+  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.`
@@ -1277,6 +1233,8 @@ 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":
@@ -1494,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miaoda-game-devkit",
-  "version": "0.6.6",
+  "version": "0.7.0",
   "description": "Shared React and Phaser game lint plus deterministic testing tools for Miaoda games",
   "license": "MIT",
   "main": "./dist/index.js",
@@ -119,6 +119,7 @@
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "jsdom": "29.1.1",
     "oxc-resolver": "11.24.2",
+    "oxc-parser": "0.144.0",
     "oxlint": "1.76.0",
     "tailwindcss": "3.4.19",
     "vitest": "4.1.10"