miaoda-game-devkit 0.6.5 → 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

@@ -25,7 +25,18 @@ declare class ManualGameClock implements GameClock {
 interface ReactFailureEntry {
     code: string;
     message: string;
+    errorName?: string;
+    actual?: string;
+    expected?: string;
+    origin?: ReactFailureOrigin;
+    layer?: ReactFailureLayer;
 }
+interface ReactFailureOrigin {
+    file: string;
+    line: number;
+    column: number;
+}
+type ReactFailureLayer = "product" | "test" | "harness" | "dependency" | "unknown";
 interface ReactFailureDiagnostic {
     source: "playthrough" | "test-runtime";
     entries: ReactFailureEntry[];
@@ -88,6 +99,10 @@ interface ReactPlaythroughAssertContext {
     user: UserEvent;
     view: RenderResult;
 }
+/**
+ * 每个阶段独立声明完成条件、断言和推进上限。确定性 `step` 属于具体阶段，
+ * 不存在 playthrough 顶层的共享 step；这样失败 TRACE 才能归属到准确区间。
+ */
 interface ReactPlaythroughStageShared {
     until: () => boolean;
     assert: (context: ReactPlaythroughAssertContext) => void | Promise<void>;
@@ -118,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;
 }
@@ -126,6 +147,7 @@ interface ReactPlaythroughTest {
 interface ReactPlaythroughAuditInput {
     name: string;
     state: "passed" | "failed" | "skipped" | "pending";
+    mode?: "run" | "only" | "skip" | "todo";
     metadata?: ReactPlaythroughMetadata;
 }
 interface ReactPlaythroughAuditResult {

package/dist/react/testing.d.ts

@@ -25,7 +25,18 @@ declare class ManualGameClock implements GameClock {
 interface ReactFailureEntry {
     code: string;
     message: string;
+    errorName?: string;
+    actual?: string;
+    expected?: string;
+    origin?: ReactFailureOrigin;
+    layer?: ReactFailureLayer;
 }
+interface ReactFailureOrigin {
+    file: string;
+    line: number;
+    column: number;
+}
+type ReactFailureLayer = "product" | "test" | "harness" | "dependency" | "unknown";
 interface ReactFailureDiagnostic {
     source: "playthrough" | "test-runtime";
     entries: ReactFailureEntry[];
@@ -88,6 +99,10 @@ interface ReactPlaythroughAssertContext {
     user: UserEvent;
     view: RenderResult;
 }
+/**
+ * 每个阶段独立声明完成条件、断言和推进上限。确定性 `step` 属于具体阶段，
+ * 不存在 playthrough 顶层的共享 step；这样失败 TRACE 才能归属到准确区间。
+ */
 interface ReactPlaythroughStageShared {
     until: () => boolean;
     assert: (context: ReactPlaythroughAssertContext) => void | Promise<void>;
@@ -118,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;
 }
@@ -126,6 +147,7 @@ interface ReactPlaythroughTest {
 interface ReactPlaythroughAuditInput {
     name: string;
     state: "passed" | "failed" | "skipped" | "pending";
+    mode?: "run" | "only" | "skip" | "todo";
     metadata?: ReactPlaythroughMetadata;
 }
 interface ReactPlaythroughAuditResult {