miaoda-game-devkit 0.2.14 → 0.2.16

package/README.md

@@ -4,9 +4,11 @@
 
 该开发工具包提供：
 
-- React 游戏的生产/手动时钟、Strict Mode 安全 Session ownership、JSDOM
+- React 游戏的生产/手动时钟、Strict Mode 安全 Controller ownership、JSDOM
   Vitest 配置和自动收集运行错误的 Testing Library setup，分别从 `miaoda-game-devkit/react`、
   `miaoda-game-devkit/react/testing` 和 `miaoda-game-devkit/react/vitest-config` 导入；
+- React 的 `playthroughTest` 与项目级 reporter 自动验证生产入口、真实 DOM 输入、
+  有界推进和结果断言；聚焦运行只提示未检查，完整运行缺少有效流程时失败；
 
 - React Vitest 在项目声明 Phaser 3 时使用其 browser bundle，并提供仅供模块能力探测的
   最小 Canvas 2D 边界，使 Phaser 3 代码不会阻断普通 JSDOM 测试；Storage 使用 JSDOM
@@ -62,10 +64,11 @@ Phaser 4 模板对应使用 `miaoda-phaser-game-lint`。命令类型不通过依
 模板即使预装 Phaser 3 及相关插件，也不会解析 Phaser 或运行 Phaser 4 检查。旧的
 `miaoda-game-lint` 不再发布，避免在同时包含 React 与 Phaser 依赖的项目中产生歧义。
 
-开发工具包自行维护工具版本，并从自身依赖中解析可执行文件，使用方不需要重复声明
+开发工具包自行维护并精确固定 Vitest 等工具版本，从自身依赖中解析可执行文件，使用方不需要重复声明
 Biome、Oxlint 或 tsgo。仓库中保留稳定的命令入口，因此 `dist/` 尚未生成时，pnpm
 也能正确建立命令链接；工作区开发状态下由 Nx 在模板检查前构建开发工具包，发布包则
-直接携带运行时 `dist/`。开发工具包内部的 `*.test.*` 与构建后的 `*.contract.mjs` 都不会
+直接携带运行时 `dist/`。打包消费者契约会验证固定 Vitest 版本以及 reporter 的通过、聚焦和
+缺失流程行为。开发工具包内部的 `*.test.*` 与构建后的 `*.contract.mjs` 都不会
 进入 npm 包；这些契约只由 devkit 自己的测试目标执行。
 
 monorepo 中的模板可以放置只包含 `extends: ["miaoda-game-devkit/biome"]` 的薄配置，
@@ -139,7 +142,9 @@ DOM 到 Phaser 的输入、命中测试和游戏状态变化，不验证 Canvas/
 
 ## 发布顺序
 
-1. 在开发工具包中运行类型检查和测试。
+1. 在开发工具包中运行类型检查和测试。`pnpm test` 会额外生成经过
+   `clean-publish` 清理的 tarball，在隔离项目中按发布目录结构解包，并以
+   `NODE_ENV=production` 运行真实 React DOM 输入测试。
 2. 使用 `pnpm run release:dry-run` 检查将要发布的文件和清理后的 `package.json`。
 3. 根据版本类型运行 `pnpm run release:patch`、`release:minor` 或 `release:major`。
    发布脚本会先测试和构建，再通过 `clean-publish` 从临时目录发布；发布包会移除

package/dist/cli/phaser-lint.js

@@ -115,13 +115,14 @@ function checkVitestConfig(target) {
 }
 async function runAllChecks(target) {
   const targetChecks = target === "react" ? [checkVitestConfig("react")] : [checkPhaser4Dependency(), checkPhaserViteConfig(), checkVitestConfig("phaser")];
+  const lintRoots = target === "react" && (0, import_node_fs.existsSync)((0, import_node_path.join)(projectRoot, "tests")) ? ["src", "tests"] : ["src"];
   const [tsgo, biome] = await Promise.all([
     run("tsgo", "@typescript/native-preview", "tsgo", ["-p", "tsconfig.json"]),
     run("biome", "@biomejs/biome", "biome", [
       "lint",
       "--config-path",
       biomeConfig,
-      "src"
+      ...lintRoots
     ])
   ]);
   const tailwindOutput = (0, import_node_path.join)((0, import_node_os.tmpdir)(), `miaoda-game-devkit-${process.pid}.css`);
@@ -135,7 +136,7 @@ async function runAllChecks(target) {
   const oxlint = await run("oxlint", "oxlint", "oxlint", [
     "-c",
     (0, import_node_path.join)(devkitRoot, "oxlint-config.json"),
-    "src"
+    ...lintRoots
   ]);
   return [...targetChecks, tsgo, biome, tailwind, oxlint];
 }

package/dist/cli/react-lint.js

@@ -115,13 +115,14 @@ function checkVitestConfig(target) {
 }
 async function runAllChecks(target) {
   const targetChecks = target === "react" ? [checkVitestConfig("react")] : [checkPhaser4Dependency(), checkPhaserViteConfig(), checkVitestConfig("phaser")];
+  const lintRoots = target === "react" && (0, import_node_fs.existsSync)((0, import_node_path.join)(projectRoot, "tests")) ? ["src", "tests"] : ["src"];
   const [tsgo, biome] = await Promise.all([
     run("tsgo", "@typescript/native-preview", "tsgo", ["-p", "tsconfig.json"]),
     run("biome", "@biomejs/biome", "biome", [
       "lint",
       "--config-path",
       biomeConfig,
-      "src"
+      ...lintRoots
     ])
   ]);
   const tailwindOutput = (0, import_node_path.join)((0, import_node_os.tmpdir)(), `miaoda-game-devkit-${process.pid}.css`);
@@ -135,7 +136,7 @@ async function runAllChecks(target) {
   const oxlint = await run("oxlint", "oxlint", "oxlint", [
     "-c",
     (0, import_node_path.join)(devkitRoot, "oxlint-config.json"),
-    "src"
+    ...lintRoots
   ]);
   return [...targetChecks, tsgo, biome, tailwind, oxlint];
 }

package/dist/react/index.d.mts

@@ -1,13 +1,13 @@
 export { G as GameClock, a as GameFrameCallback, b as browserGameClock } from '../game-clock-suUidZdT.mjs';
 
-interface DisposableGameSession {
+interface DisposableGameController {
     destroy(): void;
 }
 /**
- * 创建由当前组件拥有的 Session，并在真实卸载后销毁。
- * 微任务检查避免 React Strict Mode 的 effect 探测误销毁仍在使用的 Session。
- * createSession 必须只创建内存状态；监听器、定时器等外部资源应在订阅或操作时启用。
+ * Creates a Controller owned by the current component and destroys it after a
+ * real unmount. The microtask check ignores React Strict Mode effect probing.
+ * Construction must not start external work; controls or subscriptions may do so.
  */
-declare function useOwnedGameSession<TSession extends DisposableGameSession>(createSession: () => TSession): TSession;
+declare function useOwnedGameController<TController extends DisposableGameController>(createController: () => TController): TController;
 
-export { type DisposableGameSession, useOwnedGameSession };
+export { type DisposableGameController, useOwnedGameController };

package/dist/react/index.d.ts

@@ -1,13 +1,13 @@
 export { G as GameClock, a as GameFrameCallback, b as browserGameClock } from '../game-clock-suUidZdT.js';
 
-interface DisposableGameSession {
+interface DisposableGameController {
     destroy(): void;
 }
 /**
- * 创建由当前组件拥有的 Session，并在真实卸载后销毁。
- * 微任务检查避免 React Strict Mode 的 effect 探测误销毁仍在使用的 Session。
- * createSession 必须只创建内存状态；监听器、定时器等外部资源应在订阅或操作时启用。
+ * Creates a Controller owned by the current component and destroys it after a
+ * real unmount. The microtask check ignores React Strict Mode effect probing.
+ * Construction must not start external work; controls or subscriptions may do so.
  */
-declare function useOwnedGameSession<TSession extends DisposableGameSession>(createSession: () => TSession): TSession;
+declare function useOwnedGameController<TController extends DisposableGameController>(createController: () => TController): TController;
 
-export { type DisposableGameSession, useOwnedGameSession };
+export { type DisposableGameController, useOwnedGameController };

package/dist/react/index.js

@@ -21,7 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var react_exports = {};
 __export(react_exports, {
   browserGameClock: () => browserGameClock,
-  useOwnedGameSession: () => useOwnedGameSession
+  useOwnedGameController: () => useOwnedGameController
 });
 module.exports = __toCommonJS(react_exports);
 
@@ -34,24 +34,24 @@ var browserGameClock = {
   clearTimeout: (id) => window.clearTimeout(id)
 };
 
-// src/react/use-owned-game-session.ts
+// src/react/use-owned-game-controller.ts
 var import_react = require("react");
-function useOwnedGameSession(createSession) {
-  const [session] = (0, import_react.useState)(createSession);
+function useOwnedGameController(createController) {
+  const [controller] = (0, import_react.useState)(createController);
   const mounted = (0, import_react.useRef)(false);
   (0, import_react.useEffect)(() => {
     mounted.current = true;
     return () => {
       mounted.current = false;
       queueMicrotask(() => {
-        if (!mounted.current) session.destroy();
+        if (!mounted.current) controller.destroy();
       });
     };
-  }, [session]);
-  return session;
+  }, [controller]);
+  return controller;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   browserGameClock,
-  useOwnedGameSession
+  useOwnedGameController
 });

package/dist/react/index.mjs

@@ -7,23 +7,23 @@ var browserGameClock = {
   clearTimeout: (id) => window.clearTimeout(id)
 };
 
-// src/react/use-owned-game-session.ts
+// src/react/use-owned-game-controller.ts
 import { useEffect, useRef, useState } from "react";
-function useOwnedGameSession(createSession) {
-  const [session] = useState(createSession);
+function useOwnedGameController(createController) {
+  const [controller] = useState(createController);
   const mounted = useRef(false);
   useEffect(() => {
     mounted.current = true;
     return () => {
       mounted.current = false;
       queueMicrotask(() => {
-        if (!mounted.current) session.destroy();
+        if (!mounted.current) controller.destroy();
       });
     };
-  }, [session]);
-  return session;
+  }, [controller]);
+  return controller;
 }
 export {
   browserGameClock,
-  useOwnedGameSession
+  useOwnedGameController
 };

package/dist/react/testing.d.mts

@@ -1,4 +1,6 @@
 import { G as GameClock, a as GameFrameCallback } from '../game-clock-suUidZdT.mjs';
+import { RenderResult } from '@testing-library/react';
+import { ReactNode } from 'react';
 
 /** 测试用确定性时钟；应用测试推进它，不直接伪造游戏状态。 */
 declare class ManualGameClock implements GameClock {
@@ -18,4 +20,86 @@ declare class ManualGameClock implements GameClock {
     pendingTimerCount(): number;
 }
 
-export { ManualGameClock };
+/** 有界推进的通用配置，不绑定任何特定 Core、phase 或时钟实现。 */
+interface StepUntilOptions {
+    /** 条件仍不成立时允许执行的最大生产步数，默认 120。 */
+    maxSteps?: number;
+    /** 每轮推进一单位游戏自有时间或工作；即时回合制结果可以省略。 */
+    step?: (step: number) => void | Promise<void>;
+}
+
+/** 单条 React 主流程测试留下的可序列化运行期证据。 */
+interface ReactPlaythroughEvidence {
+    /** 捕获阶段观察到的键盘、指针或触摸类 DOM 输入总数。 */
+    domInputEvents: number;
+    /** 在步数上限内成功满足条件的 stepUntil 次数。 */
+    boundedRuns: number;
+    /** 最后一次 stepUntil 成功后新增的 Vitest 断言数。 */
+    assertionsAfterOutcome: number;
+    /** helper 是否已经完成全部证据校验。 */
+    verified: boolean;
+}
+/** 通过 Vitest task metadata 从 worker 传递给主线程 reporter 的数据。 */
+interface ReactPlaythroughMetadata {
+    /** metadata 结构版本，用于拒绝无法识别的旧数据。 */
+    version: 1;
+    /** 静态、非交互项目跳过主流程验证时必须提供的理由。 */
+    waiverReason?: string;
+    /** 测试执行期间持续更新的客观证据。 */
+    evidence: ReactPlaythroughEvidence;
+}
+
+/** 主流程回调唯一需要学习的测试工具。 */
+interface ReactPlaythroughArguments {
+    /** Testing Library 对生产游戏入口的渲染结果。 */
+    view: RenderResult;
+    /**
+     * 在硬性步数上限内等待权威结果。
+     * 返回后必须再断言该结果，进入中间 active/running 状态不算完成。
+     */
+    stepUntil(condition: () => boolean, options?: StepUntilOptions): Promise<number>;
+}
+/** 使用方编写的生产玩法步骤；既支持同步游戏，也支持异步 DOM 输入。 */
+type ReactPlaythroughRun = (arguments_: ReactPlaythroughArguments) => void | Promise<void>;
+/** 低配置主流程测试函数及其结构化豁免入口。 */
+interface ReactPlaythroughTest {
+    /** 渲染生产入口并声明一条最低可玩主流程。 */
+    (element: ReactNode, run: ReactPlaythroughRun): void;
+    /** 仅允许带充分理由地豁免确实没有玩家输入的项目。 */
+    skip(reason: string, element: ReactNode, run: ReactPlaythroughRun): void;
+}
+/** reporter 从单个 Vitest TestCase 提取出的稳定审计输入。 */
+interface ReactPlaythroughAuditInput {
+    /** 包含 describe 层级的完整测试名，仅用于诊断输出。 */
+    name: string;
+    /** Vitest 报告的最终执行状态。 */
+    state: "passed" | "failed" | "skipped" | "pending";
+    /** 只有 playthroughTest 声明的测试才具备该字段。 */
+    metadata?: ReactPlaythroughMetadata;
+}
+/** 整次 Vitest 运行的最低可玩性审计结果。 */
+interface ReactPlaythroughAuditResult {
+    /** 是否满足有效主流程或有效豁免。 */
+    passed: boolean;
+    /** 是否依靠显式非交互理由通过，而非执行了主流程。 */
+    waived: boolean;
+    /** 可直接指导模型补测的稳定问题列表。 */
+    issues: string[];
+}
+/** React 游戏测试的最低可玩主流程入口。 */
+declare const playthroughTest: ReactPlaythroughTest;
+/**
+ * 供 Vitest reporter 与确定性契约测试共用的纯审计函数。
+ *
+ * 它只验证客观流程证据，不能理解任意游戏的胜负语义；具体结果仍由
+ * 使用方在 stepUntil 返回后通过权威状态或玩家可见结果断言。
+ */
+declare function auditReactPlaythroughRun(tests: ReactPlaythroughAuditInput[]): ReactPlaythroughAuditResult;
+declare module "vitest" {
+    interface TaskMeta {
+        /** 供 ReactPlaythroughReporter 汇总的可序列化主流程证据。 */
+        reactPlaythrough?: ReactPlaythroughMetadata;
+    }
+}
+
+export { ManualGameClock, type ReactPlaythroughArguments, type ReactPlaythroughAuditInput, type ReactPlaythroughAuditResult, type ReactPlaythroughEvidence, type ReactPlaythroughMetadata, type ReactPlaythroughTest, type StepUntilOptions, auditReactPlaythroughRun, playthroughTest };

package/dist/react/testing.d.ts

@@ -1,4 +1,6 @@
 import { G as GameClock, a as GameFrameCallback } from '../game-clock-suUidZdT.js';
+import { RenderResult } from '@testing-library/react';
+import { ReactNode } from 'react';
 
 /** 测试用确定性时钟；应用测试推进它，不直接伪造游戏状态。 */
 declare class ManualGameClock implements GameClock {
@@ -18,4 +20,86 @@ declare class ManualGameClock implements GameClock {
     pendingTimerCount(): number;
 }
 
-export { ManualGameClock };
+/** 有界推进的通用配置，不绑定任何特定 Core、phase 或时钟实现。 */
+interface StepUntilOptions {
+    /** 条件仍不成立时允许执行的最大生产步数，默认 120。 */
+    maxSteps?: number;
+    /** 每轮推进一单位游戏自有时间或工作；即时回合制结果可以省略。 */
+    step?: (step: number) => void | Promise<void>;
+}
+
+/** 单条 React 主流程测试留下的可序列化运行期证据。 */
+interface ReactPlaythroughEvidence {
+    /** 捕获阶段观察到的键盘、指针或触摸类 DOM 输入总数。 */
+    domInputEvents: number;
+    /** 在步数上限内成功满足条件的 stepUntil 次数。 */
+    boundedRuns: number;
+    /** 最后一次 stepUntil 成功后新增的 Vitest 断言数。 */
+    assertionsAfterOutcome: number;
+    /** helper 是否已经完成全部证据校验。 */
+    verified: boolean;
+}
+/** 通过 Vitest task metadata 从 worker 传递给主线程 reporter 的数据。 */
+interface ReactPlaythroughMetadata {
+    /** metadata 结构版本，用于拒绝无法识别的旧数据。 */
+    version: 1;
+    /** 静态、非交互项目跳过主流程验证时必须提供的理由。 */
+    waiverReason?: string;
+    /** 测试执行期间持续更新的客观证据。 */
+    evidence: ReactPlaythroughEvidence;
+}
+
+/** 主流程回调唯一需要学习的测试工具。 */
+interface ReactPlaythroughArguments {
+    /** Testing Library 对生产游戏入口的渲染结果。 */
+    view: RenderResult;
+    /**
+     * 在硬性步数上限内等待权威结果。
+     * 返回后必须再断言该结果，进入中间 active/running 状态不算完成。
+     */
+    stepUntil(condition: () => boolean, options?: StepUntilOptions): Promise<number>;
+}
+/** 使用方编写的生产玩法步骤；既支持同步游戏，也支持异步 DOM 输入。 */
+type ReactPlaythroughRun = (arguments_: ReactPlaythroughArguments) => void | Promise<void>;
+/** 低配置主流程测试函数及其结构化豁免入口。 */
+interface ReactPlaythroughTest {
+    /** 渲染生产入口并声明一条最低可玩主流程。 */
+    (element: ReactNode, run: ReactPlaythroughRun): void;
+    /** 仅允许带充分理由地豁免确实没有玩家输入的项目。 */
+    skip(reason: string, element: ReactNode, run: ReactPlaythroughRun): void;
+}
+/** reporter 从单个 Vitest TestCase 提取出的稳定审计输入。 */
+interface ReactPlaythroughAuditInput {
+    /** 包含 describe 层级的完整测试名，仅用于诊断输出。 */
+    name: string;
+    /** Vitest 报告的最终执行状态。 */
+    state: "passed" | "failed" | "skipped" | "pending";
+    /** 只有 playthroughTest 声明的测试才具备该字段。 */
+    metadata?: ReactPlaythroughMetadata;
+}
+/** 整次 Vitest 运行的最低可玩性审计结果。 */
+interface ReactPlaythroughAuditResult {
+    /** 是否满足有效主流程或有效豁免。 */
+    passed: boolean;
+    /** 是否依靠显式非交互理由通过，而非执行了主流程。 */
+    waived: boolean;
+    /** 可直接指导模型补测的稳定问题列表。 */
+    issues: string[];
+}
+/** React 游戏测试的最低可玩主流程入口。 */
+declare const playthroughTest: ReactPlaythroughTest;
+/**
+ * 供 Vitest reporter 与确定性契约测试共用的纯审计函数。
+ *
+ * 它只验证客观流程证据，不能理解任意游戏的胜负语义；具体结果仍由
+ * 使用方在 stepUntil 返回后通过权威状态或玩家可见结果断言。
+ */
+declare function auditReactPlaythroughRun(tests: ReactPlaythroughAuditInput[]): ReactPlaythroughAuditResult;
+declare module "vitest" {
+    interface TaskMeta {
+        /** 供 ReactPlaythroughReporter 汇总的可序列化主流程证据。 */
+        reactPlaythrough?: ReactPlaythroughMetadata;
+    }
+}
+
+export { ManualGameClock, type ReactPlaythroughArguments, type ReactPlaythroughAuditInput, type ReactPlaythroughAuditResult, type ReactPlaythroughEvidence, type ReactPlaythroughMetadata, type ReactPlaythroughTest, type StepUntilOptions, auditReactPlaythroughRun, playthroughTest };

package/dist/react/testing.js

@@ -17,12 +17,16 @@ var __copyProps = (to, from, except, desc) => {
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// src/react/manual-game-clock.ts
-var manual_game_clock_exports = {};
-__export(manual_game_clock_exports, {
-  ManualGameClock: () => ManualGameClock
+// src/react/testing.ts
+var testing_exports = {};
+__export(testing_exports, {
+  ManualGameClock: () => ManualGameClock,
+  auditReactPlaythroughRun: () => auditReactPlaythroughRun,
+  playthroughTest: () => playthroughTest
 });
-module.exports = __toCommonJS(manual_game_clock_exports);
+module.exports = __toCommonJS(testing_exports);
+
+// src/react/manual-game-clock.ts
 var ManualGameClock = class {
   time = 0;
   nextId = 1;
@@ -76,7 +80,170 @@ var ManualGameClock = class {
     return this.timers.size;
   }
 };
+
+// src/react/react-playthrough.ts
+var import_react2 = require("@testing-library/react");
+var import_vitest = require("vitest");
+
+// src/react/react-playthrough-core.ts
+var import_react = require("@testing-library/react");
+function normalizePlaythroughWaiverReason(waiverReason) {
+  if (waiverReason === void 0) return void 0;
+  const reason = waiverReason.trim();
+  if (reason.length < 20) {
+    throw new Error(
+      "playthroughTest.skip reason must contain at least 20 characters."
+    );
+  }
+  return reason;
+}
+async function runBoundedUntil(condition, options = {}) {
+  const maxSteps = options.maxSteps ?? 120;
+  if (!Number.isSafeInteger(maxSteps) || maxSteps < 0 || maxSteps > 1e4) {
+    throw new RangeError(
+      "stepUntil maxSteps must be a safe integer between 0 and 10000."
+    );
+  }
+  for (let step = 0; step <= maxSteps; step += 1) {
+    if (condition()) return step;
+    if (step < maxSteps) {
+      await (0, import_react.act)(async () => {
+        await options.step?.(step + 1);
+      });
+    }
+  }
+  throw new Error(
+    `Playthrough outcome was not reached within ${maxSteps} steps.`
+  );
+}
+
+// src/react/react-playthrough.ts
+var INPUT_EVENTS = [
+  "click",
+  "keydown",
+  "keyup",
+  "pointerdown",
+  "pointerup",
+  "touchstart",
+  "touchend"
+];
+function createMetadata(waiverReason) {
+  return {
+    version: 1,
+    waiverReason,
+    evidence: {
+      domInputEvents: 0,
+      boundedRuns: 0,
+      assertionsAfterOutcome: 0,
+      verified: false
+    }
+  };
+}
+function definePlaythrough(element, run, waiverReason) {
+  const reason = normalizePlaythroughWaiverReason(waiverReason);
+  const metadata = createMetadata(reason);
+  (0, import_vitest.test)("production game completes a bounded playthrough", {
+    skip: Boolean(reason),
+    meta: { reactPlaythrough: metadata }
+  }, async () => {
+    const evidence = metadata.evidence;
+    let assertionsAtOutcome;
+    const recordInput = () => {
+      evidence.domInputEvents += 1;
+    };
+    for (const event of INPUT_EVENTS) {
+      document.addEventListener(event, recordInput, true);
+    }
+    try {
+      const view = (0, import_react2.render)(element);
+      if (view.container.childNodes.length === 0) {
+        throw new Error(
+          "playthroughTest must render the production game entry."
+        );
+      }
+      await run({
+        view,
+        async stepUntil(condition, options = {}) {
+          const steps = await runBoundedUntil(condition, options);
+          if (evidence.domInputEvents === 0) {
+            throw new Error(
+              "stepUntil reached an outcome before any production DOM input."
+            );
+          }
+          evidence.boundedRuns += 1;
+          assertionsAtOutcome = import_vitest.expect.getState().assertionCalls;
+          return steps;
+        }
+      });
+      const assertionCalls = import_vitest.expect.getState().assertionCalls;
+      evidence.assertionsAfterOutcome = assertionsAtOutcome === void 0 ? 0 : assertionCalls - assertionsAtOutcome;
+      if (evidence.domInputEvents === 0) {
+        throw new Error(
+          "playthroughTest did not observe production DOM input."
+        );
+      }
+      if (evidence.boundedRuns === 0) {
+        throw new Error("playthroughTest must complete one bounded stepUntil.");
+      }
+      if (evidence.assertionsAfterOutcome === 0) {
+        throw new Error(
+          "Assert an authoritative game outcome after stepUntil returns."
+        );
+      }
+      evidence.verified = true;
+    } finally {
+      for (const event of INPUT_EVENTS) {
+        document.removeEventListener(event, recordInput, true);
+      }
+    }
+  });
+}
+var playthroughTest = Object.assign(
+  (element, run) => definePlaythrough(element, run),
+  {
+    skip: (reason, element, run) => definePlaythrough(element, run, reason)
+  }
+);
+function auditReactPlaythroughRun(tests) {
+  const declared = tests.filter((candidate) => candidate.metadata);
+  const valid = declared.filter(({ state, metadata }) => {
+    const evidence = metadata?.evidence;
+    return state === "passed" && evidence?.verified === true && evidence.domInputEvents > 0 && evidence.boundedRuns > 0 && evidence.assertionsAfterOutcome > 0;
+  });
+  const waivers = declared.filter(
+    ({ state, metadata }) => state === "skipped" && (metadata?.waiverReason?.trim().length ?? 0) >= 20
+  );
+  const issues = [];
+  if (declared.length === 0) {
+    issues.push(
+      "\u7F3A\u5C11\u751F\u4EA7\u6E38\u620F\u53EF\u73A9\u6027\u9A8C\u8BC1\uFF1A\u4F7F\u7528 playthroughTest \u6E32\u67D3 <App />\uFF0C\u901A\u8FC7\u771F\u5B9E DOM \u8F93\u5165\u5B8C\u6210\u4E00\u4E2A\u6709\u6B65\u6570\u4E0A\u9650\u7684\u5173\u952E\u6D41\u7A0B\u3002"
+    );
+  } else {
+    for (const candidate of declared) {
+      const isValid = valid.includes(candidate);
+      const isWaived = waivers.includes(candidate);
+      if (isValid || isWaived) continue;
+      if (candidate.state === "skipped") {
+        issues.push(
+          `\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u88AB\u8DF3\u8FC7\uFF0C\u4F46\u6CA1\u6709\u81F3\u5C11 20 \u4E2A\u5B57\u7B26\u7684\u660E\u786E\u7406\u7531\u3002`
+        );
+      } else if (candidate.state !== "passed") {
+        issues.push(`\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u7684\u72B6\u6001\u4E3A ${candidate.state}\u3002`);
+      } else {
+        issues.push(
+          `\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u6CA1\u6709\u7559\u4E0B\u5B8C\u6574\u7684\u8F93\u5165\u3001\u6709\u9650\u63A8\u8FDB\u548C\u7ED3\u679C\u65AD\u8A00\u8BC1\u636E\u3002`
+        );
+      }
+    }
+  }
+  if (issues.length > 0) return { passed: false, waived: false, issues };
+  if (valid.length > 0) return { passed: true, waived: false, issues: [] };
+  if (waivers.length > 0) return { passed: true, waived: true, issues: [] };
+  return { passed: false, waived: false, issues };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  ManualGameClock
+  ManualGameClock,
+  auditReactPlaythroughRun,
+  playthroughTest
 });