miaoda-game-devkit 0.2.16 → 0.2.17

package/README.md

@@ -10,6 +10,17 @@
 - React 的 `playthroughTest` 与项目级 reporter 自动验证生产入口、真实 DOM 输入、
   有界推进和结果断言；聚焦运行只提示未检查，完整运行缺少有效流程时失败；
 
+`playthroughTest` 的主流程回调从参数接收已配置好的 `user`，不要再调用
+`userEvent.setup()`。这避免生成测试自行处理输入实例，但不会隐式接管全局 timer。
+时间、帧或自定义 scheduler 流程必须显式传入确定性 `step`；精确物理时间、暂停恢复
+或调度清理测试可使用 `ManualGameClock`。
+
+Vitest 的 fake timers（包括 `vi.advanceTimersToNextFrame()`）适合在 devkit 自身的
+专门 scheduler 合约中使用，但不在所有 production playthrough 中全局启用；React
+Testing Library 的 `asyncWrapper` 和 user-event 内部 timer 会因此互相影响。使用自定义
+scheduler、Worker 或未通过浏览器 timer 接入的引擎时，应传显式 `step` 并通过
+`diagnostics` 暴露权威状态。
+
 - React Vitest 在项目声明 Phaser 3 时使用其 browser bundle，并提供仅供模块能力探测的
   最小 Canvas 2D 边界，使 Phaser 3 代码不会阻断普通 JSDOM 测试；Storage 使用 JSDOM
   按 origin 提供的原生实现，Node 25+ worker 会关闭冲突的 Node Web Storage，

package/dist/react/testing.d.mts

@@ -1,5 +1,6 @@
 import { G as GameClock, a as GameFrameCallback } from '../game-clock-suUidZdT.mjs';
 import { RenderResult } from '@testing-library/react';
+import { UserEvent } from '@testing-library/user-event';
 import { ReactNode } from 'react';
 
 /** 测试用确定性时钟；应用测试推进它，不直接伪造游戏状态。 */
@@ -26,6 +27,11 @@ interface StepUntilOptions {
     maxSteps?: number;
     /** 每轮推进一单位游戏自有时间或工作；即时回合制结果可以省略。 */
     step?: (step: number) => void | Promise<void>;
+    /**
+     * Optional read-only state used to make bounded failures actionable.
+     * The value is sampled only when the bound is exhausted.
+     */
+    diagnostics?: () => unknown;
 }
 
 /** 单条 React 主流程测试留下的可序列化运行期证据。 */
@@ -53,9 +59,12 @@ interface ReactPlaythroughMetadata {
 interface ReactPlaythroughArguments {
     /** Testing Library 对生产游戏入口的渲染结果。 */
     view: RenderResult;
+    /** 已由 playthroughTest 创建的真实 DOM 用户输入驱动。 */
+    user: UserEvent;
     /**
      * 在硬性步数上限内等待权威结果。
      * 返回后必须再断言该结果，进入中间 active/running 状态不算完成。
+     * 即时结果不需要 step；时间、帧或自定义 scheduler 流程必须传入确定性 step。
      */
     stepUntil(condition: () => boolean, options?: StepUntilOptions): Promise<number>;
 }

package/dist/react/testing.d.ts

@@ -1,5 +1,6 @@
 import { G as GameClock, a as GameFrameCallback } from '../game-clock-suUidZdT.js';
 import { RenderResult } from '@testing-library/react';
+import { UserEvent } from '@testing-library/user-event';
 import { ReactNode } from 'react';
 
 /** 测试用确定性时钟；应用测试推进它，不直接伪造游戏状态。 */
@@ -26,6 +27,11 @@ interface StepUntilOptions {
     maxSteps?: number;
     /** 每轮推进一单位游戏自有时间或工作；即时回合制结果可以省略。 */
     step?: (step: number) => void | Promise<void>;
+    /**
+     * Optional read-only state used to make bounded failures actionable.
+     * The value is sampled only when the bound is exhausted.
+     */
+    diagnostics?: () => unknown;
 }
 
 /** 单条 React 主流程测试留下的可序列化运行期证据。 */
@@ -53,9 +59,12 @@ interface ReactPlaythroughMetadata {
 interface ReactPlaythroughArguments {
     /** Testing Library 对生产游戏入口的渲染结果。 */
     view: RenderResult;
+    /** 已由 playthroughTest 创建的真实 DOM 用户输入驱动。 */
+    user: UserEvent;
     /**
      * 在硬性步数上限内等待权威结果。
      * 返回后必须再断言该结果，进入中间 active/running 状态不算完成。
+     * 即时结果不需要 step；时间、帧或自定义 scheduler 流程必须传入确定性 step。
      */
     stepUntil(condition: () => boolean, options?: StepUntilOptions): Promise<number>;
 }

package/dist/react/testing.js

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/react/testing.ts
@@ -83,10 +93,21 @@ var ManualGameClock = class {
 
 // src/react/react-playthrough.ts
 var import_react2 = require("@testing-library/react");
+var import_user_event = __toESM(require("@testing-library/user-event"));
 var import_vitest = require("vitest");
 
 // src/react/react-playthrough-core.ts
 var import_react = require("@testing-library/react");
+function formatDiagnostics(read) {
+  if (!read) return void 0;
+  try {
+    const value = read();
+    if (typeof value === "string") return value;
+    return JSON.stringify(value);
+  } catch (error) {
+    return `diagnostics() threw: ${String(error)}`;
+  }
+}
 function normalizePlaythroughWaiverReason(waiverReason) {
   if (waiverReason === void 0) return void 0;
   const reason = waiverReason.trim();
@@ -112,8 +133,11 @@ 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 suffix = diagnostics ? ` Last diagnostics: ${diagnostics}` : "";
   throw new Error(
-    `Playthrough outcome was not reached within ${maxSteps} steps.`
+    `Playthrough outcome was not reached within ${maxSteps} steps. ${guidance}${suffix}`
   );
 }
 
@@ -161,8 +185,10 @@ function definePlaythrough(element, run, waiverReason) {
           "playthroughTest must render the production game entry."
         );
       }
+      const user = import_user_event.default.setup();
       await run({
         view,
+        user,
         async stepUntil(condition, options = {}) {
           const steps = await runBoundedUntil(condition, options);
           if (evidence.domInputEvents === 0) {

package/dist/react/testing.mjs

@@ -55,10 +55,21 @@ var ManualGameClock = class {
 
 // src/react/react-playthrough.ts
 import { render } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
 import { expect, test } from "vitest";
 
 // src/react/react-playthrough-core.ts
 import { act } from "@testing-library/react";
+function formatDiagnostics(read) {
+  if (!read) return void 0;
+  try {
+    const value = read();
+    if (typeof value === "string") return value;
+    return JSON.stringify(value);
+  } catch (error) {
+    return `diagnostics() threw: ${String(error)}`;
+  }
+}
 function normalizePlaythroughWaiverReason(waiverReason) {
   if (waiverReason === void 0) return void 0;
   const reason = waiverReason.trim();
@@ -84,8 +95,11 @@ 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 suffix = diagnostics ? ` Last diagnostics: ${diagnostics}` : "";
   throw new Error(
-    `Playthrough outcome was not reached within ${maxSteps} steps.`
+    `Playthrough outcome was not reached within ${maxSteps} steps. ${guidance}${suffix}`
   );
 }
 
@@ -133,8 +147,10 @@ function definePlaythrough(element, run, waiverReason) {
           "playthroughTest must render the production game entry."
         );
       }
+      const user = userEvent.setup();
       await run({
         view,
+        user,
         async stepUntil(condition, options = {}) {
           const steps = await runBoundedUntil(condition, options);
           if (evidence.domInputEvents === 0) {

package/dist/react/vitest-config.js

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/react-vitest-config.ts
@@ -33,10 +43,21 @@ var import_node_path = require("path");
 
 // src/react/react-playthrough.ts
 var import_react2 = require("@testing-library/react");
+var import_user_event = __toESM(require("@testing-library/user-event"));
 var import_vitest = require("vitest");
 
 // src/react/react-playthrough-core.ts
 var import_react = require("@testing-library/react");
+function formatDiagnostics(read) {
+  if (!read) return void 0;
+  try {
+    const value = read();
+    if (typeof value === "string") return value;
+    return JSON.stringify(value);
+  } catch (error) {
+    return `diagnostics() threw: ${String(error)}`;
+  }
+}
 function normalizePlaythroughWaiverReason(waiverReason) {
   if (waiverReason === void 0) return void 0;
   const reason = waiverReason.trim();
@@ -62,8 +83,11 @@ 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 suffix = diagnostics ? ` Last diagnostics: ${diagnostics}` : "";
   throw new Error(
-    `Playthrough outcome was not reached within ${maxSteps} steps.`
+    `Playthrough outcome was not reached within ${maxSteps} steps. ${guidance}${suffix}`
   );
 }
 
@@ -111,8 +135,10 @@ function definePlaythrough(element, run, waiverReason) {
           "playthroughTest must render the production game entry."
         );
       }
+      const user = import_user_event.default.setup();
       await run({
         view,
+        user,
         async stepUntil(condition, options = {}) {
           const steps = await runBoundedUntil(condition, options);
           if (evidence.domInputEvents === 0) {
@@ -273,11 +299,12 @@ function assessReactPlaythroughReport(input) {
   if (!audit.passed) {
     const cause = productionModule.errors[0] ?? input.unhandledErrors?.[0] ?? audit.issues[0] ?? "\u751F\u4EA7\u53EF\u73A9\u6D41\u7A0B\u6CA1\u6709\u7559\u4E0B\u5B8C\u6574\u8BC1\u636E\u3002";
     const timedOut = /outcome was not reached within \d+ steps/i.test(cause);
+    const missingStep = /No step callback was provided/i.test(cause);
     return {
       ...base,
       status: "FAILED",
       cause,
-      next: timedOut ? "\u771F\u5B9E\u8F93\u5165\u5DF2\u6267\u884C\uFF0C\u4F46\u73A9\u6CD5\u6CA1\u6709\u5728\u4E0A\u9650\u5185\u4EA7\u751F\u7ED3\u679C\uFF1B\u68C0\u67E5\u70B9\u51FB\u6216\u6309\u952E\u662F\u5426\u771F\u7684\u8C03\u7528\u6E38\u620F\u7684\u751F\u4EA7\u63A7\u5236\u65B9\u6CD5\uFF0C\u4EE5\u53CA\u6E38\u620F\u771F\u5B9E\u72B6\u6001\u662F\u5426\u5230\u8FBE\u5E76\u663E\u793A\u7ED3\u679C\u3002" : "\u4ECE\u751F\u4EA7\u5165\u53E3\u6267\u884C\u771F\u5B9E DOM \u8F93\u5165\uFF0C\u7528 stepUntil \u6709\u754C\u63A8\u8FDB\u5230\u73A9\u5BB6\u53EF\u89C1\u7ED3\u679C\u6216\u6E38\u620F\u771F\u5B9E\u72B6\u6001\u7684\u53EA\u8BFB snapshot\uFF0C\u5E76\u5728\u5176\u540E\u65AD\u8A00\uFF1B\u4E0D\u8981\u76F4\u8FBE\u5185\u90E8\u5173\u5361\u6216\u4FEE\u6539\u73A9\u6CD5\u72B6\u6001\u3002",
+      next: missingStep ? "\u8BE5\u6D41\u7A0B\u662F\u65F6\u95F4\u6216\u5E27\u9A71\u52A8\u7684\uFF0C\u4F46 stepUntil \u6CA1\u6709\u63A8\u8FDB\u6E38\u620F\u65F6\u95F4\uFF1B\u4E3A\u751F\u4EA7\u6E38\u620F\u6CE8\u5165 devkit \u7684 GameClock\uFF0C\u5E76\u4F20\u5165 step: () => clock.stepFrame()\u3002\u4E0D\u8981\u7528\u771F\u5B9E setTimeout\u3002" : timedOut ? "\u771F\u5B9E\u8F93\u5165\u5DF2\u6267\u884C\uFF0C\u4F46\u73A9\u6CD5\u6CA1\u6709\u5728\u4E0A\u9650\u5185\u4EA7\u751F\u7ED3\u679C\uFF1B\u68C0\u67E5\u751F\u4EA7\u63A7\u5236\u662F\u5426\u6536\u5230\u8F93\u5165\uFF0C\u518D\u67E5\u770B\u8D85\u65F6\u9519\u8BEF\u4E2D\u7684 Last diagnostics \u5224\u65AD\u662F\u6E38\u620F\u5FAA\u73AF\u3001\u89C4\u5219\u72B6\u6001\u8FD8\u662F UI \u540C\u6B65\u672A\u63A8\u8FDB\u3002" : "\u4ECE\u751F\u4EA7\u5165\u53E3\u6267\u884C\u771F\u5B9E DOM \u8F93\u5165\uFF0C\u7528 stepUntil \u6709\u754C\u63A8\u8FDB\u5230\u73A9\u5BB6\u53EF\u89C1\u7ED3\u679C\u6216\u6E38\u620F\u771F\u5B9E\u72B6\u6001\u7684\u53EA\u8BFB snapshot\uFF0C\u5E76\u5728\u5176\u540E\u65AD\u8A00\uFF1B\u4E0D\u8981\u76F4\u8FBE\u5185\u90E8\u5173\u5361\u6216\u4FEE\u6539\u73A9\u6CD5\u72B6\u6001\u3002",
       failsRun: true
     };
   }

package/dist/react/vitest-config.mjs

@@ -9,10 +9,21 @@ import { relative, resolve } from "path";
 
 // src/react/react-playthrough.ts
 import { render } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
 import { expect, test } from "vitest";
 
 // src/react/react-playthrough-core.ts
 import { act } from "@testing-library/react";
+function formatDiagnostics(read) {
+  if (!read) return void 0;
+  try {
+    const value = read();
+    if (typeof value === "string") return value;
+    return JSON.stringify(value);
+  } catch (error) {
+    return `diagnostics() threw: ${String(error)}`;
+  }
+}
 function normalizePlaythroughWaiverReason(waiverReason) {
   if (waiverReason === void 0) return void 0;
   const reason = waiverReason.trim();
@@ -38,8 +49,11 @@ 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 suffix = diagnostics ? ` Last diagnostics: ${diagnostics}` : "";
   throw new Error(
-    `Playthrough outcome was not reached within ${maxSteps} steps.`
+    `Playthrough outcome was not reached within ${maxSteps} steps. ${guidance}${suffix}`
   );
 }
 
@@ -87,8 +101,10 @@ function definePlaythrough(element, run, waiverReason) {
           "playthroughTest must render the production game entry."
         );
       }
+      const user = userEvent.setup();
       await run({
         view,
+        user,
         async stepUntil(condition, options = {}) {
           const steps = await runBoundedUntil(condition, options);
           if (evidence.domInputEvents === 0) {
@@ -249,11 +265,12 @@ function assessReactPlaythroughReport(input) {
   if (!audit.passed) {
     const cause = productionModule.errors[0] ?? input.unhandledErrors?.[0] ?? audit.issues[0] ?? "\u751F\u4EA7\u53EF\u73A9\u6D41\u7A0B\u6CA1\u6709\u7559\u4E0B\u5B8C\u6574\u8BC1\u636E\u3002";
     const timedOut = /outcome was not reached within \d+ steps/i.test(cause);
+    const missingStep = /No step callback was provided/i.test(cause);
     return {
       ...base,
       status: "FAILED",
       cause,
-      next: timedOut ? "\u771F\u5B9E\u8F93\u5165\u5DF2\u6267\u884C\uFF0C\u4F46\u73A9\u6CD5\u6CA1\u6709\u5728\u4E0A\u9650\u5185\u4EA7\u751F\u7ED3\u679C\uFF1B\u68C0\u67E5\u70B9\u51FB\u6216\u6309\u952E\u662F\u5426\u771F\u7684\u8C03\u7528\u6E38\u620F\u7684\u751F\u4EA7\u63A7\u5236\u65B9\u6CD5\uFF0C\u4EE5\u53CA\u6E38\u620F\u771F\u5B9E\u72B6\u6001\u662F\u5426\u5230\u8FBE\u5E76\u663E\u793A\u7ED3\u679C\u3002" : "\u4ECE\u751F\u4EA7\u5165\u53E3\u6267\u884C\u771F\u5B9E DOM \u8F93\u5165\uFF0C\u7528 stepUntil \u6709\u754C\u63A8\u8FDB\u5230\u73A9\u5BB6\u53EF\u89C1\u7ED3\u679C\u6216\u6E38\u620F\u771F\u5B9E\u72B6\u6001\u7684\u53EA\u8BFB snapshot\uFF0C\u5E76\u5728\u5176\u540E\u65AD\u8A00\uFF1B\u4E0D\u8981\u76F4\u8FBE\u5185\u90E8\u5173\u5361\u6216\u4FEE\u6539\u73A9\u6CD5\u72B6\u6001\u3002",
+      next: missingStep ? "\u8BE5\u6D41\u7A0B\u662F\u65F6\u95F4\u6216\u5E27\u9A71\u52A8\u7684\uFF0C\u4F46 stepUntil \u6CA1\u6709\u63A8\u8FDB\u6E38\u620F\u65F6\u95F4\uFF1B\u4E3A\u751F\u4EA7\u6E38\u620F\u6CE8\u5165 devkit \u7684 GameClock\uFF0C\u5E76\u4F20\u5165 step: () => clock.stepFrame()\u3002\u4E0D\u8981\u7528\u771F\u5B9E setTimeout\u3002" : timedOut ? "\u771F\u5B9E\u8F93\u5165\u5DF2\u6267\u884C\uFF0C\u4F46\u73A9\u6CD5\u6CA1\u6709\u5728\u4E0A\u9650\u5185\u4EA7\u751F\u7ED3\u679C\uFF1B\u68C0\u67E5\u751F\u4EA7\u63A7\u5236\u662F\u5426\u6536\u5230\u8F93\u5165\uFF0C\u518D\u67E5\u770B\u8D85\u65F6\u9519\u8BEF\u4E2D\u7684 Last diagnostics \u5224\u65AD\u662F\u6E38\u620F\u5FAA\u73AF\u3001\u89C4\u5219\u72B6\u6001\u8FD8\u662F UI \u540C\u6B65\u672A\u63A8\u8FDB\u3002" : "\u4ECE\u751F\u4EA7\u5165\u53E3\u6267\u884C\u771F\u5B9E DOM \u8F93\u5165\uFF0C\u7528 stepUntil \u6709\u754C\u63A8\u8FDB\u5230\u73A9\u5BB6\u53EF\u89C1\u7ED3\u679C\u6216\u6E38\u620F\u771F\u5B9E\u72B6\u6001\u7684\u53EA\u8BFB snapshot\uFF0C\u5E76\u5728\u5176\u540E\u65AD\u8A00\uFF1B\u4E0D\u8981\u76F4\u8FBE\u5185\u90E8\u5173\u5361\u6216\u4FEE\u6539\u73A9\u6CD5\u72B6\u6001\u3002",
       failsRun: true
     };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miaoda-game-devkit",
-  "version": "0.2.16",
+  "version": "0.2.17",
   "description": "Shared React and Phaser game lint plus deterministic testing tools for Miaoda games",
   "license": "MIT",
   "main": "./dist/index.js",
@@ -126,6 +126,7 @@
   "peerDependencies": {
     "@testing-library/jest-dom": ">=6 <8",
     "@testing-library/react": ">=16 <17",
+    "@testing-library/user-event": ">=14 <15",
     "phaser": ">=4.0.0 <5",
     "phaser4-rex-plugins": ">=4.0.0 <5",
     "react": ">=19 <20",
@@ -139,6 +140,9 @@
     "@testing-library/react": {
       "optional": true
     },
+    "@testing-library/user-event": {
+      "optional": true
+    },
     "phaser": {
       "optional": true
     },