miaoda-game-devkit 0.3.0 → 0.4.0

package/README.md

@@ -18,13 +18,14 @@
 这两次 checkpoint；checkpoint 只负责签到，不携带或验证状态。大型游戏仍只保留一条最短关键流程；
 分支、关卡规则和恢复清理由专门测试覆盖。不要再次调用 `userEvent.setup()`。
 时间、帧或自定义 scheduler 流程必须显式传入确定性 `step`；精确物理时间、暂停恢复
-或调度清理测试可使用 `ManualGameClock`。
+或调度清理测试可使用 `ManualGameClock`。Canvas/Controller 流程在 `playthroughTest` 上声明一次
+`observe`，返回 JSON 可序列化的权威 Telemetry 状态；框架自动比较流程状态并复用为超时诊断。
 
 Vitest 的 fake timers（包括 `vi.advanceTimersToNextFrame()`）适合在 devkit 自身的
 专门 scheduler 合约中使用，但不在所有 production playthrough 中全局启用；React
 Testing Library 的 `asyncWrapper` 和 user-event 内部 timer 会因此互相影响。使用自定义
 scheduler、Worker 或未通过浏览器 timer 接入的引擎时，应传显式 `step` 并通过
-`diagnostics` 暴露权威状态。
+`diagnostics` 暴露权威状态；已声明 `observe` 的流程无需重复提供 `diagnostics`。
 
 - React Vitest 在项目声明 Phaser 3 时使用其 browser bundle，并提供仅供模块能力探测的
   最小 Canvas 2D 边界，使 Phaser 3 代码不会阻断普通 JSDOM 测试；Storage 使用 JSDOM

package/dist/react/index.js

@@ -92,7 +92,7 @@ function useSnapshotIntegrityCheck(game) {
       if (previousJson !== void 0 && nextJson !== previousJson) {
         reported.current = true;
         throw new Error(
-          "Game state changed while snapshot() returned the same reference \u2014 React compares snapshots by reference and skips the re-render, so the UI freezes. \u539F\u56E0\uFF1AReact \u9760\u6BD4\u8F83\u5F15\u7528\u5224\u65AD\u72B6\u6001\u53D8\u6CA1\u53D8\uFF0C\u5F15\u7528\u76F8\u540C\u5C31\u5F53\u4F5C\u6CA1\u53D8\u5316\u3002\u4FEE\u590D\uFF1A\u6BCF\u6B21 notify \u524D\u6362\u4E00\u4E2A\u65B0\u5BF9\u8C61\uFF0C\u4F8B\u5982\u5728 controller \u91CC cachedSnapshot = { ...state }\uFF1B\u4E0D\u8981\u628A\u88AB\u539F\u5730\u4FEE\u6539\u7684\u5185\u90E8\u5BF9\u8C61\u76F4\u63A5\u7ED9 React\u3002"
+          "Game state changed while snapshot() returned the same reference. React compares snapshots by reference and skips the render when Object.is(previous, next) is true, so the UI freezes. Publish a new top-level snapshot before each notification, for example cachedSnapshot = { ...state }, and never expose a mutable internal object as the snapshot."
         );
       }
       previousJson = nextJson;

package/dist/react/index.mjs

@@ -64,7 +64,7 @@ function useSnapshotIntegrityCheck(game) {
       if (previousJson !== void 0 && nextJson !== previousJson) {
         reported.current = true;
         throw new Error(
-          "Game state changed while snapshot() returned the same reference \u2014 React compares snapshots by reference and skips the re-render, so the UI freezes. \u539F\u56E0\uFF1AReact \u9760\u6BD4\u8F83\u5F15\u7528\u5224\u65AD\u72B6\u6001\u53D8\u6CA1\u53D8\uFF0C\u5F15\u7528\u76F8\u540C\u5C31\u5F53\u4F5C\u6CA1\u53D8\u5316\u3002\u4FEE\u590D\uFF1A\u6BCF\u6B21 notify \u524D\u6362\u4E00\u4E2A\u65B0\u5BF9\u8C61\uFF0C\u4F8B\u5982\u5728 controller \u91CC cachedSnapshot = { ...state }\uFF1B\u4E0D\u8981\u628A\u88AB\u539F\u5730\u4FEE\u6539\u7684\u5185\u90E8\u5BF9\u8C61\u76F4\u63A5\u7ED9 React\u3002"
+          "Game state changed while snapshot() returned the same reference. React compares snapshots by reference and skips the render when Object.is(previous, next) is true, so the UI freezes. Publish a new top-level snapshot before each notification, for example cachedSnapshot = { ...state }, and never expose a mutable internal object as the snapshot."
         );
       }
       previousJson = nextJson;

package/dist/react/testing.d.mts

@@ -33,16 +33,6 @@ interface StepUntilOptions {
      * The value is sampled only when the bound is exhausted.
      */
     diagnostics?: () => unknown;
-    /**
-     * 默认有一道检查：如果等待的结果"不用玩就已经成立"（第 0 步即成立，
-     * 且页面文本从进入游戏起一个字都没变），说明这个结果跟游戏过程无关，
-     * 判为失败——它能抓住输入没接上、界面卡死、断言了静态标题这类假通过。
-     *
-     * 例外：Canvas 游戏的结果画在画布上，页面文本本来就不会变。这类游戏
-     * 观察的是 Telemetry 等页面外的权威状态，此时置 true 跳过该检查。
-     * 结果通过 DOM 呈现的游戏不要传。
-     */
-    allowStaticDom?: boolean;
 }
 
 /** 单条 React 主流程测试留下的可序列化运行期证据。 */
@@ -76,6 +66,11 @@ interface ReactPlaythroughMetadata {
 type ReactPlaythroughInputKind = "entry" | "primary";
 /** 可审计流程签到；entered 是入口，progress/terminal 是有效结果。 */
 type ReactPlaythroughCheckpointKind = "entered" | "progress" | "terminal";
+/** Canvas/Controller flows declare one authoritative read; simple DOM flows omit it. */
+interface ReactPlaythroughOptions {
+    /** Stable, JSON-serializable production state sampled across the audited flow. */
+    observe: () => unknown;
+}
 /** 主流程回调唯一需要学习的测试工具。 */
 interface ReactPlaythroughArguments {
     /** Testing Library 对生产游戏入口的渲染结果。 */
@@ -107,6 +102,8 @@ type ReactPlaythroughRun = (arguments_: ReactPlaythroughArguments) => void | Pro
 interface ReactPlaythroughTest {
     /** 渲染生产入口并声明一条最低可玩主流程。 */
     (element: ReactNode, run: ReactPlaythroughRun): void;
+    /** Use one authoritative observer when gameplay results live outside the DOM. */
+    (element: ReactNode, options: ReactPlaythroughOptions, run: ReactPlaythroughRun): void;
     /** 仅允许带充分理由地豁免确实没有玩家输入的项目。 */
     skip(reason: string, element: ReactNode, run: ReactPlaythroughRun): void;
 }
@@ -144,4 +141,4 @@ declare module "vitest" {
     }
 }
 
-export { ManualGameClock, type ReactPlaythroughArguments, type ReactPlaythroughAuditInput, type ReactPlaythroughAuditResult, type ReactPlaythroughCheckpointKind, type ReactPlaythroughEvidence, type ReactPlaythroughInputKind, type ReactPlaythroughMetadata, type ReactPlaythroughTest, type StepUntilOptions, auditReactPlaythroughRun, playthroughTest };
+export { ManualGameClock, type ReactPlaythroughArguments, type ReactPlaythroughAuditInput, type ReactPlaythroughAuditResult, type ReactPlaythroughCheckpointKind, type ReactPlaythroughEvidence, type ReactPlaythroughInputKind, type ReactPlaythroughMetadata, type ReactPlaythroughOptions, type ReactPlaythroughTest, type StepUntilOptions, auditReactPlaythroughRun, playthroughTest };

package/dist/react/testing.d.ts

@@ -33,16 +33,6 @@ interface StepUntilOptions {
      * The value is sampled only when the bound is exhausted.
      */
     diagnostics?: () => unknown;
-    /**
-     * 默认有一道检查：如果等待的结果"不用玩就已经成立"（第 0 步即成立，
-     * 且页面文本从进入游戏起一个字都没变），说明这个结果跟游戏过程无关，
-     * 判为失败——它能抓住输入没接上、界面卡死、断言了静态标题这类假通过。
-     *
-     * 例外：Canvas 游戏的结果画在画布上，页面文本本来就不会变。这类游戏
-     * 观察的是 Telemetry 等页面外的权威状态，此时置 true 跳过该检查。
-     * 结果通过 DOM 呈现的游戏不要传。
-     */
-    allowStaticDom?: boolean;
 }
 
 /** 单条 React 主流程测试留下的可序列化运行期证据。 */
@@ -76,6 +66,11 @@ interface ReactPlaythroughMetadata {
 type ReactPlaythroughInputKind = "entry" | "primary";
 /** 可审计流程签到；entered 是入口，progress/terminal 是有效结果。 */
 type ReactPlaythroughCheckpointKind = "entered" | "progress" | "terminal";
+/** Canvas/Controller flows declare one authoritative read; simple DOM flows omit it. */
+interface ReactPlaythroughOptions {
+    /** Stable, JSON-serializable production state sampled across the audited flow. */
+    observe: () => unknown;
+}
 /** 主流程回调唯一需要学习的测试工具。 */
 interface ReactPlaythroughArguments {
     /** Testing Library 对生产游戏入口的渲染结果。 */
@@ -107,6 +102,8 @@ type ReactPlaythroughRun = (arguments_: ReactPlaythroughArguments) => void | Pro
 interface ReactPlaythroughTest {
     /** 渲染生产入口并声明一条最低可玩主流程。 */
     (element: ReactNode, run: ReactPlaythroughRun): void;
+    /** Use one authoritative observer when gameplay results live outside the DOM. */
+    (element: ReactNode, options: ReactPlaythroughOptions, run: ReactPlaythroughRun): void;
     /** 仅允许带充分理由地豁免确实没有玩家输入的项目。 */
     skip(reason: string, element: ReactNode, run: ReactPlaythroughRun): void;
 }
@@ -144,4 +141,4 @@ declare module "vitest" {
     }
 }
 
-export { ManualGameClock, type ReactPlaythroughArguments, type ReactPlaythroughAuditInput, type ReactPlaythroughAuditResult, type ReactPlaythroughCheckpointKind, type ReactPlaythroughEvidence, type ReactPlaythroughInputKind, type ReactPlaythroughMetadata, type ReactPlaythroughTest, type StepUntilOptions, auditReactPlaythroughRun, playthroughTest };
+export { ManualGameClock, type ReactPlaythroughArguments, type ReactPlaythroughAuditInput, type ReactPlaythroughAuditResult, type ReactPlaythroughCheckpointKind, type ReactPlaythroughEvidence, type ReactPlaythroughInputKind, type ReactPlaythroughMetadata, type ReactPlaythroughOptions, type ReactPlaythroughTest, type StepUntilOptions, auditReactPlaythroughRun, playthroughTest };

package/dist/react/testing.js

@@ -152,20 +152,50 @@ var INPUT_EVENTS = [
   "touchend"
 ];
 var MIN_CHECKPOINTS = 2;
+var MAX_FORMATTED_OBSERVATION_LENGTH = 500;
+function formatObservation(fingerprint) {
+  if (fingerprint.length <= MAX_FORMATTED_OBSERVATION_LENGTH) return fingerprint;
+  return `${fingerprint.slice(0, MAX_FORMATTED_OBSERVATION_LENGTH)}\u2026 (${fingerprint.length} chars)`;
+}
+function sampleObservation(observe, stage) {
+  let value;
+  try {
+    value = observe();
+  } catch (error) {
+    throw new Error(`observe() threw at ${stage}: ${String(error)}`);
+  }
+  try {
+    const fingerprint = JSON.stringify(value);
+    if (fingerprint === void 0) throw new Error("unsupported value");
+    return { fingerprint, formatted: formatObservation(fingerprint) };
+  } catch {
+    throw new Error(
+      `observe() must return JSON-serializable read-only state; sampling failed at ${stage}.`
+    );
+  }
+}
+function formatObservationTimeline(entered, afterPrimary, outcome) {
+  return [
+    `entered=${entered.formatted}`,
+    `after-primary=${afterPrimary?.formatted ?? "<not sampled>"}`,
+    `outcome=${outcome.formatted}`
+  ].join(", ");
+}
 function describeMissingEvidence(evidence) {
-  if (!evidence || evidence.entryInputs === 0) return "entry \u8F93\u5165";
-  if (evidence.primaryInputs === 0) return "primary \u8F93\u5165";
+  if (!evidence || evidence.entryInputs === 0) return "an entry input";
+  if (evidence.primaryInputs === 0) return "a primary gameplay input";
   if (!evidence.checkpoints.includes("entered")) return "entered checkpoint";
-  if (evidence.boundedRuns === 0) return "\u6709\u754C stepUntil";
-  if (evidence.assertionsAfterOutcome === 0) return "stepUntil \u540E\u7684\u7ED3\u679C\u65AD\u8A00";
+  if (evidence.boundedRuns === 0) return "a bounded stepUntil call";
+  if (evidence.assertionsAfterOutcome === 0)
+    return "an outcome assertion after stepUntil";
   if (evidence.checkpoints.length < MIN_CHECKPOINTS)
-    return `\u81F3\u5C11 ${MIN_CHECKPOINTS} \u4E2A checkpoint`;
+    return `at least ${MIN_CHECKPOINTS} checkpoints`;
   if (!evidence.checkpoints.some(
     (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
   )) {
     return "progress/terminal checkpoint";
   }
-  return "\u5B8C\u6574\u7684 playthrough \u6821\u9A8C\u6807\u8BB0";
+  return "a complete playthrough verification marker";
 }
 function createMetadata(waiverReason) {
   return {
@@ -182,7 +212,7 @@ function createMetadata(waiverReason) {
     }
   };
 }
-function definePlaythrough(element, run, waiverReason) {
+function definePlaythrough(element, run, playthroughOptions, waiverReason) {
   const reason = normalizePlaythroughWaiverReason(waiverReason);
   const metadata = createMetadata(reason);
   (0, import_vitest.test)("production game completes a bounded playthrough", {
@@ -193,6 +223,8 @@ function definePlaythrough(element, run, waiverReason) {
     let assertionsAtOutcome;
     let enteredRecorded = false;
     let domTextAtEntered;
+    let enteredObservation;
+    let afterPrimaryObservation;
     const recordInput = () => {
       evidence.domInputEvents += 1;
     };
@@ -230,7 +262,15 @@ function definePlaythrough(element, run, waiverReason) {
             );
           }
           if (kind === "entry") evidence.entryInputs += 1;
-          else evidence.primaryInputs += 1;
+          else {
+            evidence.primaryInputs += 1;
+            if (playthroughOptions?.observe) {
+              afterPrimaryObservation = sampleObservation(
+                playthroughOptions.observe,
+                "after-primary"
+              );
+            }
+          }
         },
         checkpoint(kind) {
           if (kind === "entered") {
@@ -245,7 +285,14 @@ function definePlaythrough(element, run, waiverReason) {
               );
             }
             enteredRecorded = true;
-            domTextAtEntered = document.body.textContent ?? "";
+            if (playthroughOptions?.observe) {
+              enteredObservation = sampleObservation(
+                playthroughOptions.observe,
+                "entered"
+              );
+            } else {
+              domTextAtEntered = document.body.textContent ?? "";
+            }
             evidence.checkpoints.push(kind);
             return;
           }
@@ -266,16 +313,35 @@ function definePlaythrough(element, run, waiverReason) {
           }
           evidence.checkpoints.push(kind);
         },
-        async stepUntil(condition, options = {}) {
-          const steps = await runBoundedUntil(condition, options);
+        async stepUntil(condition, stepOptions = {}) {
+          const boundedOptions = stepOptions.diagnostics || !playthroughOptions?.observe ? stepOptions : {
+            ...stepOptions,
+            diagnostics: playthroughOptions.observe
+          };
+          const steps = await runBoundedUntil(condition, boundedOptions);
           if (evidence.primaryInputs === 0) {
             throw new Error(
               'stepUntil must follow performInput("primary", ...). A menu/help click is not gameplay evidence.'
             );
           }
-          if (steps === 0 && options.allowStaticDom !== true && domTextAtEntered !== void 0 && (document.body.textContent ?? "") === domTextAtEntered) {
+          if (playthroughOptions?.observe) {
+            if (!enteredObservation) {
+              throw new Error(
+                'observe requires checkpoint("entered") before primary gameplay input.'
+              );
+            }
+            const outcomeObservation = sampleObservation(
+              playthroughOptions.observe,
+              "outcome"
+            );
+            if (outcomeObservation.fingerprint === enteredObservation.fingerprint) {
+              throw new Error(
+                `The authoritative observation did not change from checkpoint("entered") to the outcome. Timeline: ${formatObservationTimeline(enteredObservation, afterPrimaryObservation, outcomeObservation)}`
+              );
+            }
+          } else if (steps === 0 && domTextAtEntered !== void 0 && (document.body.textContent ?? "") === domTextAtEntered) {
             throw new Error(
-              'stepUntil outcome was already true at step 0 and the DOM has not changed since checkpoint("entered"), so the flow cannot prove that gameplay changed anything. \u610F\u601D\uFF1A\u6E38\u620F\u4E00\u6B65\u90FD\u6CA1\u73A9\uFF0C\u7B49\u5F85\u7684"\u7ED3\u679C"\u5C31\u5DF2\u7ECF\u6210\u7ACB\uFF0C\u9875\u9762\u4E5F\u4E00\u4E2A\u5B57\u6CA1\u53D8\u2014\u2014\u8FD9\u4E2A\u7ED3\u679C\u8BC1\u660E\u4E0D\u4E86\u4EFB\u4F55\u4E8B\u3002\u5E38\u89C1\u539F\u56E0\uFF1A\u2460 \u8F93\u5165\u6CA1\u6709\u63A5\u5230\u6E38\u620F\u4E0A\uFF1B\u2461 \u754C\u9762\u5361\u6B7B\uFF08\u72B6\u6001\u6539\u4E86\u4F46 snapshot \u5F15\u7528\u6CA1\u6362\uFF0CReact \u6CA1\u6709\u5237\u65B0\uFF09\uFF1B\u2462 \u65AD\u8A00\u4E86\u5F00\u5C40\u524D\u5C31\u5B58\u5728\u7684\u9759\u6001\u6587\u672C\u3002\u4FEE\u590D\uFF1A\u7B49\u5F85\u5E76\u65AD\u8A00\u53EA\u6709\u73A9\u8D77\u6765\u4E4B\u540E\u624D\u4F1A\u51FA\u73B0\u7684\u4E1C\u897F\uFF08\u5F00\u59CB\u906E\u7F69\u6D88\u5931\u3001\u6BD4\u5206\u53D8\u5316\u3001\u7ED3\u7B97\u753B\u9762\u51FA\u73B0\uFF09\u3002\u4F8B\u5916\uFF1A\u7ED3\u679C\u753B\u5728 Canvas \u4E0A\u3001\u7ECF Telemetry \u7B49\u9875\u9762\u5916\u72B6\u6001\u89C2\u5BDF\u7684\u6E38\u620F\uFF0C\u663E\u5F0F\u4F20 { allowStaticDom: true }\u3002'
+              'stepUntil found the outcome at step 0, and the DOM has not changed since checkpoint("entered"). The flow therefore provides no evidence that the primary gameplay input produced a result. For Canvas or Controller state outside the DOM, declare one playthrough observe callback.'
             );
           }
           evidence.boundedRuns += 1;
@@ -319,9 +385,16 @@ function definePlaythrough(element, run, waiverReason) {
   });
 }
 var playthroughTest = Object.assign(
-  (element, run) => definePlaythrough(element, run),
+  (element, optionsOrRun, maybeRun) => {
+    if (typeof optionsOrRun === "function") {
+      definePlaythrough(element, optionsOrRun);
+      return;
+    }
+    if (!maybeRun) throw new TypeError("playthroughTest requires a run callback.");
+    definePlaythrough(element, maybeRun, optionsOrRun);
+  },
   {
-    skip: (reason, element, run) => definePlaythrough(element, run, reason)
+    skip: (reason, element, run) => definePlaythrough(element, run, void 0, reason)
   }
 );
 function auditReactPlaythroughRun(tests) {
@@ -338,7 +411,7 @@ function auditReactPlaythroughRun(tests) {
   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\u4F9D\u6B21\u6267\u884C performInput("entry")\u3001checkpoint("entered")\u3001performInput("primary")\u3001stepUntil\u3001\u7528 playthroughTest \u63D0\u4F9B\u7684 expect \u65AD\u8A00\u6743\u5A01\u7ED3\u679C\uFF0C\u5E76\u8BB0\u5F55 checkpoint("progress") \u6216 checkpoint("terminal")\uFF1B\u81F3\u5C11\u5B8C\u6210\u8FD9\u4E24\u6B21 checkpoint \u7B7E\u5230\u3002'
+      'No production gameplay verification was declared. Use playthroughTest to render <App />, then run performInput("entry"), checkpoint("entered"), performInput("primary"), and a bounded stepUntil. Assert the authoritative outcome with the expect provided by playthroughTest, then record checkpoint("progress") or checkpoint("terminal").'
     );
   } else {
     for (const candidate of declared) {
@@ -347,13 +420,17 @@ function auditReactPlaythroughRun(tests) {
       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`
+          `Playthrough ${JSON.stringify(candidate.name)} was skipped without an explicit reason of at least 20 characters.`
         );
       } else if (candidate.state !== "passed") {
-        issues.push(`\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u7684\u72B6\u6001\u4E3A ${candidate.state}\u3002`);
+        issues.push(
+          `Playthrough ${JSON.stringify(candidate.name)} finished with state ${candidate.state}.`
+        );
       } else {
         const missing = describeMissingEvidence(candidate.metadata?.evidence);
-        issues.push(`\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u7F3A\u5C11${missing}\u3002`);
+        issues.push(
+          `Playthrough ${JSON.stringify(candidate.name)} is missing ${missing}.`
+        );
       }
     }
   }

package/dist/react/testing.mjs

@@ -114,20 +114,50 @@ var INPUT_EVENTS = [
   "touchend"
 ];
 var MIN_CHECKPOINTS = 2;
+var MAX_FORMATTED_OBSERVATION_LENGTH = 500;
+function formatObservation(fingerprint) {
+  if (fingerprint.length <= MAX_FORMATTED_OBSERVATION_LENGTH) return fingerprint;
+  return `${fingerprint.slice(0, MAX_FORMATTED_OBSERVATION_LENGTH)}\u2026 (${fingerprint.length} chars)`;
+}
+function sampleObservation(observe, stage) {
+  let value;
+  try {
+    value = observe();
+  } catch (error) {
+    throw new Error(`observe() threw at ${stage}: ${String(error)}`);
+  }
+  try {
+    const fingerprint = JSON.stringify(value);
+    if (fingerprint === void 0) throw new Error("unsupported value");
+    return { fingerprint, formatted: formatObservation(fingerprint) };
+  } catch {
+    throw new Error(
+      `observe() must return JSON-serializable read-only state; sampling failed at ${stage}.`
+    );
+  }
+}
+function formatObservationTimeline(entered, afterPrimary, outcome) {
+  return [
+    `entered=${entered.formatted}`,
+    `after-primary=${afterPrimary?.formatted ?? "<not sampled>"}`,
+    `outcome=${outcome.formatted}`
+  ].join(", ");
+}
 function describeMissingEvidence(evidence) {
-  if (!evidence || evidence.entryInputs === 0) return "entry \u8F93\u5165";
-  if (evidence.primaryInputs === 0) return "primary \u8F93\u5165";
+  if (!evidence || evidence.entryInputs === 0) return "an entry input";
+  if (evidence.primaryInputs === 0) return "a primary gameplay input";
   if (!evidence.checkpoints.includes("entered")) return "entered checkpoint";
-  if (evidence.boundedRuns === 0) return "\u6709\u754C stepUntil";
-  if (evidence.assertionsAfterOutcome === 0) return "stepUntil \u540E\u7684\u7ED3\u679C\u65AD\u8A00";
+  if (evidence.boundedRuns === 0) return "a bounded stepUntil call";
+  if (evidence.assertionsAfterOutcome === 0)
+    return "an outcome assertion after stepUntil";
   if (evidence.checkpoints.length < MIN_CHECKPOINTS)
-    return `\u81F3\u5C11 ${MIN_CHECKPOINTS} \u4E2A checkpoint`;
+    return `at least ${MIN_CHECKPOINTS} checkpoints`;
   if (!evidence.checkpoints.some(
     (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
   )) {
     return "progress/terminal checkpoint";
   }
-  return "\u5B8C\u6574\u7684 playthrough \u6821\u9A8C\u6807\u8BB0";
+  return "a complete playthrough verification marker";
 }
 function createMetadata(waiverReason) {
   return {
@@ -144,7 +174,7 @@ function createMetadata(waiverReason) {
     }
   };
 }
-function definePlaythrough(element, run, waiverReason) {
+function definePlaythrough(element, run, playthroughOptions, waiverReason) {
   const reason = normalizePlaythroughWaiverReason(waiverReason);
   const metadata = createMetadata(reason);
   test("production game completes a bounded playthrough", {
@@ -155,6 +185,8 @@ function definePlaythrough(element, run, waiverReason) {
     let assertionsAtOutcome;
     let enteredRecorded = false;
     let domTextAtEntered;
+    let enteredObservation;
+    let afterPrimaryObservation;
     const recordInput = () => {
       evidence.domInputEvents += 1;
     };
@@ -192,7 +224,15 @@ function definePlaythrough(element, run, waiverReason) {
             );
           }
           if (kind === "entry") evidence.entryInputs += 1;
-          else evidence.primaryInputs += 1;
+          else {
+            evidence.primaryInputs += 1;
+            if (playthroughOptions?.observe) {
+              afterPrimaryObservation = sampleObservation(
+                playthroughOptions.observe,
+                "after-primary"
+              );
+            }
+          }
         },
         checkpoint(kind) {
           if (kind === "entered") {
@@ -207,7 +247,14 @@ function definePlaythrough(element, run, waiverReason) {
               );
             }
             enteredRecorded = true;
-            domTextAtEntered = document.body.textContent ?? "";
+            if (playthroughOptions?.observe) {
+              enteredObservation = sampleObservation(
+                playthroughOptions.observe,
+                "entered"
+              );
+            } else {
+              domTextAtEntered = document.body.textContent ?? "";
+            }
             evidence.checkpoints.push(kind);
             return;
           }
@@ -228,16 +275,35 @@ function definePlaythrough(element, run, waiverReason) {
           }
           evidence.checkpoints.push(kind);
         },
-        async stepUntil(condition, options = {}) {
-          const steps = await runBoundedUntil(condition, options);
+        async stepUntil(condition, stepOptions = {}) {
+          const boundedOptions = stepOptions.diagnostics || !playthroughOptions?.observe ? stepOptions : {
+            ...stepOptions,
+            diagnostics: playthroughOptions.observe
+          };
+          const steps = await runBoundedUntil(condition, boundedOptions);
           if (evidence.primaryInputs === 0) {
             throw new Error(
               'stepUntil must follow performInput("primary", ...). A menu/help click is not gameplay evidence.'
             );
           }
-          if (steps === 0 && options.allowStaticDom !== true && domTextAtEntered !== void 0 && (document.body.textContent ?? "") === domTextAtEntered) {
+          if (playthroughOptions?.observe) {
+            if (!enteredObservation) {
+              throw new Error(
+                'observe requires checkpoint("entered") before primary gameplay input.'
+              );
+            }
+            const outcomeObservation = sampleObservation(
+              playthroughOptions.observe,
+              "outcome"
+            );
+            if (outcomeObservation.fingerprint === enteredObservation.fingerprint) {
+              throw new Error(
+                `The authoritative observation did not change from checkpoint("entered") to the outcome. Timeline: ${formatObservationTimeline(enteredObservation, afterPrimaryObservation, outcomeObservation)}`
+              );
+            }
+          } else if (steps === 0 && domTextAtEntered !== void 0 && (document.body.textContent ?? "") === domTextAtEntered) {
             throw new Error(
-              'stepUntil outcome was already true at step 0 and the DOM has not changed since checkpoint("entered"), so the flow cannot prove that gameplay changed anything. \u610F\u601D\uFF1A\u6E38\u620F\u4E00\u6B65\u90FD\u6CA1\u73A9\uFF0C\u7B49\u5F85\u7684"\u7ED3\u679C"\u5C31\u5DF2\u7ECF\u6210\u7ACB\uFF0C\u9875\u9762\u4E5F\u4E00\u4E2A\u5B57\u6CA1\u53D8\u2014\u2014\u8FD9\u4E2A\u7ED3\u679C\u8BC1\u660E\u4E0D\u4E86\u4EFB\u4F55\u4E8B\u3002\u5E38\u89C1\u539F\u56E0\uFF1A\u2460 \u8F93\u5165\u6CA1\u6709\u63A5\u5230\u6E38\u620F\u4E0A\uFF1B\u2461 \u754C\u9762\u5361\u6B7B\uFF08\u72B6\u6001\u6539\u4E86\u4F46 snapshot \u5F15\u7528\u6CA1\u6362\uFF0CReact \u6CA1\u6709\u5237\u65B0\uFF09\uFF1B\u2462 \u65AD\u8A00\u4E86\u5F00\u5C40\u524D\u5C31\u5B58\u5728\u7684\u9759\u6001\u6587\u672C\u3002\u4FEE\u590D\uFF1A\u7B49\u5F85\u5E76\u65AD\u8A00\u53EA\u6709\u73A9\u8D77\u6765\u4E4B\u540E\u624D\u4F1A\u51FA\u73B0\u7684\u4E1C\u897F\uFF08\u5F00\u59CB\u906E\u7F69\u6D88\u5931\u3001\u6BD4\u5206\u53D8\u5316\u3001\u7ED3\u7B97\u753B\u9762\u51FA\u73B0\uFF09\u3002\u4F8B\u5916\uFF1A\u7ED3\u679C\u753B\u5728 Canvas \u4E0A\u3001\u7ECF Telemetry \u7B49\u9875\u9762\u5916\u72B6\u6001\u89C2\u5BDF\u7684\u6E38\u620F\uFF0C\u663E\u5F0F\u4F20 { allowStaticDom: true }\u3002'
+              'stepUntil found the outcome at step 0, and the DOM has not changed since checkpoint("entered"). The flow therefore provides no evidence that the primary gameplay input produced a result. For Canvas or Controller state outside the DOM, declare one playthrough observe callback.'
             );
           }
           evidence.boundedRuns += 1;
@@ -281,9 +347,16 @@ function definePlaythrough(element, run, waiverReason) {
   });
 }
 var playthroughTest = Object.assign(
-  (element, run) => definePlaythrough(element, run),
+  (element, optionsOrRun, maybeRun) => {
+    if (typeof optionsOrRun === "function") {
+      definePlaythrough(element, optionsOrRun);
+      return;
+    }
+    if (!maybeRun) throw new TypeError("playthroughTest requires a run callback.");
+    definePlaythrough(element, maybeRun, optionsOrRun);
+  },
   {
-    skip: (reason, element, run) => definePlaythrough(element, run, reason)
+    skip: (reason, element, run) => definePlaythrough(element, run, void 0, reason)
   }
 );
 function auditReactPlaythroughRun(tests) {
@@ -300,7 +373,7 @@ function auditReactPlaythroughRun(tests) {
   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\u4F9D\u6B21\u6267\u884C performInput("entry")\u3001checkpoint("entered")\u3001performInput("primary")\u3001stepUntil\u3001\u7528 playthroughTest \u63D0\u4F9B\u7684 expect \u65AD\u8A00\u6743\u5A01\u7ED3\u679C\uFF0C\u5E76\u8BB0\u5F55 checkpoint("progress") \u6216 checkpoint("terminal")\uFF1B\u81F3\u5C11\u5B8C\u6210\u8FD9\u4E24\u6B21 checkpoint \u7B7E\u5230\u3002'
+      'No production gameplay verification was declared. Use playthroughTest to render <App />, then run performInput("entry"), checkpoint("entered"), performInput("primary"), and a bounded stepUntil. Assert the authoritative outcome with the expect provided by playthroughTest, then record checkpoint("progress") or checkpoint("terminal").'
     );
   } else {
     for (const candidate of declared) {
@@ -309,13 +382,17 @@ function auditReactPlaythroughRun(tests) {
       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`
+          `Playthrough ${JSON.stringify(candidate.name)} was skipped without an explicit reason of at least 20 characters.`
         );
       } else if (candidate.state !== "passed") {
-        issues.push(`\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u7684\u72B6\u6001\u4E3A ${candidate.state}\u3002`);
+        issues.push(
+          `Playthrough ${JSON.stringify(candidate.name)} finished with state ${candidate.state}.`
+        );
       } else {
         const missing = describeMissingEvidence(candidate.metadata?.evidence);
-        issues.push(`\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u7F3A\u5C11${missing}\u3002`);
+        issues.push(
+          `Playthrough ${JSON.stringify(candidate.name)} is missing ${missing}.`
+        );
       }
     }
   }

package/dist/react/vitest-config.js

@@ -103,20 +103,50 @@ var INPUT_EVENTS = [
   "touchend"
 ];
 var MIN_CHECKPOINTS = 2;
+var MAX_FORMATTED_OBSERVATION_LENGTH = 500;
+function formatObservation(fingerprint) {
+  if (fingerprint.length <= MAX_FORMATTED_OBSERVATION_LENGTH) return fingerprint;
+  return `${fingerprint.slice(0, MAX_FORMATTED_OBSERVATION_LENGTH)}\u2026 (${fingerprint.length} chars)`;
+}
+function sampleObservation(observe, stage) {
+  let value;
+  try {
+    value = observe();
+  } catch (error) {
+    throw new Error(`observe() threw at ${stage}: ${String(error)}`);
+  }
+  try {
+    const fingerprint = JSON.stringify(value);
+    if (fingerprint === void 0) throw new Error("unsupported value");
+    return { fingerprint, formatted: formatObservation(fingerprint) };
+  } catch {
+    throw new Error(
+      `observe() must return JSON-serializable read-only state; sampling failed at ${stage}.`
+    );
+  }
+}
+function formatObservationTimeline(entered, afterPrimary, outcome) {
+  return [
+    `entered=${entered.formatted}`,
+    `after-primary=${afterPrimary?.formatted ?? "<not sampled>"}`,
+    `outcome=${outcome.formatted}`
+  ].join(", ");
+}
 function describeMissingEvidence(evidence) {
-  if (!evidence || evidence.entryInputs === 0) return "entry \u8F93\u5165";
-  if (evidence.primaryInputs === 0) return "primary \u8F93\u5165";
+  if (!evidence || evidence.entryInputs === 0) return "an entry input";
+  if (evidence.primaryInputs === 0) return "a primary gameplay input";
   if (!evidence.checkpoints.includes("entered")) return "entered checkpoint";
-  if (evidence.boundedRuns === 0) return "\u6709\u754C stepUntil";
-  if (evidence.assertionsAfterOutcome === 0) return "stepUntil \u540E\u7684\u7ED3\u679C\u65AD\u8A00";
+  if (evidence.boundedRuns === 0) return "a bounded stepUntil call";
+  if (evidence.assertionsAfterOutcome === 0)
+    return "an outcome assertion after stepUntil";
   if (evidence.checkpoints.length < MIN_CHECKPOINTS)
-    return `\u81F3\u5C11 ${MIN_CHECKPOINTS} \u4E2A checkpoint`;
+    return `at least ${MIN_CHECKPOINTS} checkpoints`;
   if (!evidence.checkpoints.some(
     (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
   )) {
     return "progress/terminal checkpoint";
   }
-  return "\u5B8C\u6574\u7684 playthrough \u6821\u9A8C\u6807\u8BB0";
+  return "a complete playthrough verification marker";
 }
 function createMetadata(waiverReason) {
   return {
@@ -133,7 +163,7 @@ function createMetadata(waiverReason) {
     }
   };
 }
-function definePlaythrough(element, run, waiverReason) {
+function definePlaythrough(element, run, playthroughOptions, waiverReason) {
   const reason = normalizePlaythroughWaiverReason(waiverReason);
   const metadata = createMetadata(reason);
   (0, import_vitest.test)("production game completes a bounded playthrough", {
@@ -144,6 +174,8 @@ function definePlaythrough(element, run, waiverReason) {
     let assertionsAtOutcome;
     let enteredRecorded = false;
     let domTextAtEntered;
+    let enteredObservation;
+    let afterPrimaryObservation;
     const recordInput = () => {
       evidence.domInputEvents += 1;
     };
@@ -181,7 +213,15 @@ function definePlaythrough(element, run, waiverReason) {
             );
           }
           if (kind === "entry") evidence.entryInputs += 1;
-          else evidence.primaryInputs += 1;
+          else {
+            evidence.primaryInputs += 1;
+            if (playthroughOptions?.observe) {
+              afterPrimaryObservation = sampleObservation(
+                playthroughOptions.observe,
+                "after-primary"
+              );
+            }
+          }
         },
         checkpoint(kind) {
           if (kind === "entered") {
@@ -196,7 +236,14 @@ function definePlaythrough(element, run, waiverReason) {
               );
             }
             enteredRecorded = true;
-            domTextAtEntered = document.body.textContent ?? "";
+            if (playthroughOptions?.observe) {
+              enteredObservation = sampleObservation(
+                playthroughOptions.observe,
+                "entered"
+              );
+            } else {
+              domTextAtEntered = document.body.textContent ?? "";
+            }
             evidence.checkpoints.push(kind);
             return;
           }
@@ -217,16 +264,35 @@ function definePlaythrough(element, run, waiverReason) {
           }
           evidence.checkpoints.push(kind);
         },
-        async stepUntil(condition, options = {}) {
-          const steps = await runBoundedUntil(condition, options);
+        async stepUntil(condition, stepOptions = {}) {
+          const boundedOptions = stepOptions.diagnostics || !playthroughOptions?.observe ? stepOptions : {
+            ...stepOptions,
+            diagnostics: playthroughOptions.observe
+          };
+          const steps = await runBoundedUntil(condition, boundedOptions);
           if (evidence.primaryInputs === 0) {
             throw new Error(
               'stepUntil must follow performInput("primary", ...). A menu/help click is not gameplay evidence.'
             );
           }
-          if (steps === 0 && options.allowStaticDom !== true && domTextAtEntered !== void 0 && (document.body.textContent ?? "") === domTextAtEntered) {
+          if (playthroughOptions?.observe) {
+            if (!enteredObservation) {
+              throw new Error(
+                'observe requires checkpoint("entered") before primary gameplay input.'
+              );
+            }
+            const outcomeObservation = sampleObservation(
+              playthroughOptions.observe,
+              "outcome"
+            );
+            if (outcomeObservation.fingerprint === enteredObservation.fingerprint) {
+              throw new Error(
+                `The authoritative observation did not change from checkpoint("entered") to the outcome. Timeline: ${formatObservationTimeline(enteredObservation, afterPrimaryObservation, outcomeObservation)}`
+              );
+            }
+          } else if (steps === 0 && domTextAtEntered !== void 0 && (document.body.textContent ?? "") === domTextAtEntered) {
             throw new Error(
-              'stepUntil outcome was already true at step 0 and the DOM has not changed since checkpoint("entered"), so the flow cannot prove that gameplay changed anything. \u610F\u601D\uFF1A\u6E38\u620F\u4E00\u6B65\u90FD\u6CA1\u73A9\uFF0C\u7B49\u5F85\u7684"\u7ED3\u679C"\u5C31\u5DF2\u7ECF\u6210\u7ACB\uFF0C\u9875\u9762\u4E5F\u4E00\u4E2A\u5B57\u6CA1\u53D8\u2014\u2014\u8FD9\u4E2A\u7ED3\u679C\u8BC1\u660E\u4E0D\u4E86\u4EFB\u4F55\u4E8B\u3002\u5E38\u89C1\u539F\u56E0\uFF1A\u2460 \u8F93\u5165\u6CA1\u6709\u63A5\u5230\u6E38\u620F\u4E0A\uFF1B\u2461 \u754C\u9762\u5361\u6B7B\uFF08\u72B6\u6001\u6539\u4E86\u4F46 snapshot \u5F15\u7528\u6CA1\u6362\uFF0CReact \u6CA1\u6709\u5237\u65B0\uFF09\uFF1B\u2462 \u65AD\u8A00\u4E86\u5F00\u5C40\u524D\u5C31\u5B58\u5728\u7684\u9759\u6001\u6587\u672C\u3002\u4FEE\u590D\uFF1A\u7B49\u5F85\u5E76\u65AD\u8A00\u53EA\u6709\u73A9\u8D77\u6765\u4E4B\u540E\u624D\u4F1A\u51FA\u73B0\u7684\u4E1C\u897F\uFF08\u5F00\u59CB\u906E\u7F69\u6D88\u5931\u3001\u6BD4\u5206\u53D8\u5316\u3001\u7ED3\u7B97\u753B\u9762\u51FA\u73B0\uFF09\u3002\u4F8B\u5916\uFF1A\u7ED3\u679C\u753B\u5728 Canvas \u4E0A\u3001\u7ECF Telemetry \u7B49\u9875\u9762\u5916\u72B6\u6001\u89C2\u5BDF\u7684\u6E38\u620F\uFF0C\u663E\u5F0F\u4F20 { allowStaticDom: true }\u3002'
+              'stepUntil found the outcome at step 0, and the DOM has not changed since checkpoint("entered"). The flow therefore provides no evidence that the primary gameplay input produced a result. For Canvas or Controller state outside the DOM, declare one playthrough observe callback.'
             );
           }
           evidence.boundedRuns += 1;
@@ -270,9 +336,16 @@ function definePlaythrough(element, run, waiverReason) {
   });
 }
 var playthroughTest = Object.assign(
-  (element, run) => definePlaythrough(element, run),
+  (element, optionsOrRun, maybeRun) => {
+    if (typeof optionsOrRun === "function") {
+      definePlaythrough(element, optionsOrRun);
+      return;
+    }
+    if (!maybeRun) throw new TypeError("playthroughTest requires a run callback.");
+    definePlaythrough(element, maybeRun, optionsOrRun);
+  },
   {
-    skip: (reason, element, run) => definePlaythrough(element, run, reason)
+    skip: (reason, element, run) => definePlaythrough(element, run, void 0, reason)
   }
 );
 function auditReactPlaythroughRun(tests) {
@@ -289,7 +362,7 @@ function auditReactPlaythroughRun(tests) {
   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\u4F9D\u6B21\u6267\u884C performInput("entry")\u3001checkpoint("entered")\u3001performInput("primary")\u3001stepUntil\u3001\u7528 playthroughTest \u63D0\u4F9B\u7684 expect \u65AD\u8A00\u6743\u5A01\u7ED3\u679C\uFF0C\u5E76\u8BB0\u5F55 checkpoint("progress") \u6216 checkpoint("terminal")\uFF1B\u81F3\u5C11\u5B8C\u6210\u8FD9\u4E24\u6B21 checkpoint \u7B7E\u5230\u3002'
+      'No production gameplay verification was declared. Use playthroughTest to render <App />, then run performInput("entry"), checkpoint("entered"), performInput("primary"), and a bounded stepUntil. Assert the authoritative outcome with the expect provided by playthroughTest, then record checkpoint("progress") or checkpoint("terminal").'
     );
   } else {
     for (const candidate of declared) {
@@ -298,13 +371,17 @@ function auditReactPlaythroughRun(tests) {
       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`
+          `Playthrough ${JSON.stringify(candidate.name)} was skipped without an explicit reason of at least 20 characters.`
         );
       } else if (candidate.state !== "passed") {
-        issues.push(`\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u7684\u72B6\u6001\u4E3A ${candidate.state}\u3002`);
+        issues.push(
+          `Playthrough ${JSON.stringify(candidate.name)} finished with state ${candidate.state}.`
+        );
       } else {
         const missing = describeMissingEvidence(candidate.metadata?.evidence);
-        issues.push(`\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u7F3A\u5C11${missing}\u3002`);
+        issues.push(
+          `Playthrough ${JSON.stringify(candidate.name)} is missing ${missing}.`
+        );
       }
     }
   }
@@ -394,6 +471,29 @@ function formatFailureSummary(modules) {
   lines.push("TEST_RESULT: FAIL");
   return lines;
 }
+function repairGuidance(cause) {
+  if (/snapshot\(\) returned the same reference/i.test(cause)) {
+    return "The game mutated state without publishing a new snapshot reference, so React skipped the render after an Object.is comparison. Publish a new top-level object before notifying subscribers, for example cachedSnapshot = { ...state }, and never expose a mutable internal object as the snapshot.";
+  }
+  if (/(?:already true|found the outcome) at step 0.*DOM has not changed/i.test(
+    cause
+  )) {
+    return 'Make the stepUntil condition false at checkpoint("entered"). Verify that the primary input reaches the production control, then wait for a post-input outcome such as a changed score, a removed entry overlay, a completed turn, or a result screen. For Canvas or Controller state outside the DOM, declare observe once on playthroughTest and return the read-only production Telemetry snapshot.';
+  }
+  if (/authoritative observation did not change/i.test(cause)) {
+    return "The flow reached its condition while observe still returned the same authoritative state. Make observe read the same production Controller that React renders, verify the primary input changes that Controller, and wait for a post-input result. Inspect the Timeline values to locate the disconnected stage.";
+  }
+  if (/No step callback was provided/i.test(cause)) {
+    return "This flow is driven by time or frames, but stepUntil 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.";
+  }
+  if (/outcome was not reached within \d+ steps/i.test(cause)) {
+    return "The real input was dispatched, but gameplay did not reach the outcome within the bound. Confirm that the production control received the input, then inspect Last diagnostics to determine whether the game loop, rule state, or UI synchronization failed to advance.";
+  }
+  if (/performInput|checkpoint/.test(cause)) {
+    return 'Complete the evidence sequence in order: performInput("entry"), checkpoint("entered"), performInput("primary"), bounded stepUntil, an authoritative result assertion using the provided expect, then checkpoint("progress") or checkpoint("terminal").';
+  }
+  return "Start from the production entry, dispatch real DOM input, and use stepUntil to reach a bounded player-visible or authoritative game outcome before asserting it. Do not jump to an internal level or mutate gameplay state.";
+}
 function assessReactPlaythroughReport(input) {
   const base = { file: input.expectedFile };
   if (!input.expectedFileScheduled) {
@@ -401,15 +501,15 @@ function assessReactPlaythroughReport(input) {
       return {
         ...base,
         status: "NOT_CHECKED",
-        next: `\u672C\u6B21\u662F\u805A\u7126\u8FD0\u884C\uFF0C\u672A\u68C0\u67E5\u6700\u4F4E\u53EF\u73A9\u6D41\u7A0B\uFF1B\u63D0\u4EA4\u524D\u8FD0\u884C pnpm test\uFF0C\u786E\u4FDD ${input.expectedFile} \u901A\u8FC7\u3002`,
+        next: `This focused run did not execute the minimum production playthrough. Run pnpm test before submitting and make sure ${input.expectedFile} passes.`,
         failsRun: false
       };
     }
     return {
       ...base,
       status: "FAILED",
-      cause: "\u751F\u4EA7\u53EF\u73A9\u6027\u6D4B\u8BD5\u6587\u4EF6\u4E0D\u5B58\u5728\u3002",
-      next: '\u521B\u5EFA\u8BE5\u6587\u4EF6\uFF1A\u4ECE <App /> \u901A\u8FC7\u771F\u5B9E DOM \u8F93\u5165\u4F9D\u6B21\u6267\u884C performInput("entry")\u3001checkpoint("entered")\u3001performInput("primary")\u3001stepUntil\u3001\u7528 playthroughTest \u63D0\u4F9B\u7684 expect \u65AD\u8A00\u6743\u5A01\u7ED3\u679C\uFF0C\u5E76\u8BB0\u5F55 checkpoint("progress") \u6216 checkpoint("terminal")\u3002\u6BCF\u6761\u4E3B\u6D41\u7A0B\u81F3\u5C11\u9700\u8981\u8FD9\u4E24\u6B21 checkpoint \u7B7E\u5230\u3002',
+      cause: "The required production playthrough test file does not exist.",
+      next: 'Create the file and render <App />. Drive a legal entry with performInput("entry"), record checkpoint("entered"), perform a core game action with performInput("primary"), and use a bounded stepUntil. Assert the authoritative result with the provided expect, then record checkpoint("progress") or checkpoint("terminal").',
       failsRun: true
     };
   }
@@ -423,7 +523,7 @@ function assessReactPlaythroughReport(input) {
     return {
       ...base,
       status: "NOT_CHECKED",
-      next: `\u672C\u6B21\u540D\u79F0\u6216\u884C\u53F7\u8FC7\u6EE4\u6CA1\u6709\u6267\u884C\u6700\u4F4E\u53EF\u73A9\u6D41\u7A0B\uFF1B\u63D0\u4EA4\u524D\u8FD0\u884C pnpm test\uFF0C\u786E\u4FDD ${input.expectedFile} \u901A\u8FC7\u3002`,
+      next: `The name or line filter did not execute the minimum production playthrough. Run pnpm test before submitting and make sure ${input.expectedFile} passes.`,
       failsRun: false
     };
   }
@@ -431,25 +531,20 @@ function assessReactPlaythroughReport(input) {
     return {
       ...base,
       status: "NOT_RUN",
-      cause: productionModule?.errors[0] ?? input.unhandledErrors?.[0] ?? "\u751F\u4EA7\u53EF\u73A9\u6027\u6D4B\u8BD5\u672A\u5B8C\u6210\u6536\u96C6\u6216\u6267\u884C\u3002",
-      next: "\u5148\u4FEE\u590D Vitest \u4E0A\u65B9\u9996\u4E2A\u8BED\u6CD5\u3001\u5BFC\u5165\u6216\u6536\u96C6\u9519\u8BEF\uFF0C\u518D\u8FD0\u884C pnpm test\uFF1B\u4E0D\u8981\u7528 skip \u63A9\u76D6\u52A0\u8F7D\u5931\u8D25\u3002",
+      cause: productionModule?.errors[0] ?? input.unhandledErrors?.[0] ?? "The production playthrough could not be collected or executed.",
+      next: "Fix the first Vitest syntax, import, environment, or collection error shown above, then run pnpm test again. Do not use skip to hide a load failure.",
       failsRun: true
     };
   }
   const tests = input.modules.flatMap((module2) => module2.tests);
   const audit = auditReactPlaythroughRun(tests);
   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);
-    const staticOutcome = /already true at step 0 and the DOM has not changed/i.test(cause);
-    const staleSnapshot = /snapshot\(\) returned the same reference/i.test(cause);
-    const missingStructuredEvidence = /performInput|checkpoint/.test(cause);
+    const cause = productionModule.errors[0] ?? input.unhandledErrors?.[0] ?? audit.issues[0] ?? "The production playthrough did not leave complete gameplay evidence.";
     return {
       ...base,
       status: "FAILED",
       cause,
-      next: staleSnapshot ? "\u6E38\u620F\u539F\u5730\u4FEE\u6539\u72B6\u6001\u540E\u6CA1\u6709\u53D1\u5E03\u65B0\u7684\u5FEB\u7167\u5F15\u7528\uFF0CReact \u56E0 Object.is \u6BD4\u8F83\u76F8\u540C\u800C\u8DF3\u8FC7\u91CD\u6E32\u3002\u5728 controller \u7684 notify \u8DEF\u5F84\u4E0A\u53D1\u5E03\u65B0\u9876\u5C42\u5BF9\u8C61\uFF08cachedSnapshot = { ...state }\uFF09\uFF0C\u4E0D\u8981\u628A\u53EF\u53D8\u7684\u5185\u90E8\u5BF9\u8C61\u76F4\u63A5\u4F5C\u4E3A\u5FEB\u7167\u66B4\u9732\u3002" : staticOutcome ? "\u7ED3\u679C\u5728\u63A8\u8FDB\u524D\u5DF2\u6210\u7ACB\u4E14 DOM \u81EA entered \u4EE5\u6765\u65E0\u53D8\u5316\uFF1A\u8F93\u5165\u53EF\u80FD\u672A\u63A5\u5230\u751F\u4EA7\u63A7\u5236\uFF0CUI \u53EF\u80FD\u51BB\u7ED3\uFF0C\u4E5F\u53EF\u80FD\u65AD\u8A00\u4E86\u6E38\u620F\u5F00\u59CB\u524D\u5C31\u5B58\u5728\u7684\u9759\u6001\u6587\u672C\u3002\u6539\u4E3A\u7B49\u5F85\u5E76\u65AD\u8A00\u53EA\u6709\u73A9\u6CD5\u63A8\u8FDB\u540E\u624D\u51FA\u73B0\u7684\u72B6\u6001\uFF08\u5F00\u59CB\u906E\u7F69\u6D88\u5931\u3001\u6BD4\u5206\u53D8\u5316\u3001\u7ED3\u7B97\u51FA\u73B0\uFF09\uFF1B\u7ECF Canvas/Telemetry \u7B49 DOM \u5916\u6743\u5A01\u72B6\u6001\u89C2\u5BDF\u7684\u6D41\u7A0B\u4F20 { allowStaticDom: true }\u3002" : 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" : missingStructuredEvidence ? '\u6309\u987A\u5E8F\u8865\u9F50\u81F3\u5C11\u4E24\u6B21\u7B7E\u5230\uFF1AperformInput("entry") \u540E\u8C03\u7528 checkpoint("entered")\uFF1B\u518D\u7528 performInput("primary") \u6267\u884C\u6838\u5FC3\u64CD\u4F5C\uFF0CstepUntil \u7B49\u5F85\u7ED3\u679C\uFF0C\u7528\u56DE\u8C03\u63D0\u4F9B\u7684 expect \u65AD\u8A00\u540E\u8C03\u7528 checkpoint("progress") \u6216 checkpoint("terminal")\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\u6743\u5A01\u72B6\u6001\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: repairGuidance(cause),
       failsRun: true
     };
   }
@@ -467,7 +562,7 @@ function formatReactPlaythroughReport(report) {
   const lines = [`REACT_PLAYTHROUGH: ${report.status}`, `FILE: ${report.file}`];
   if (report.cause) lines.push(`CAUSE: ${report.cause}`);
   if (report.waiverReasons?.length) {
-    lines.push(`REASON: ${report.waiverReasons.join("\uFF1B")}`);
+    lines.push(`REASON: ${report.waiverReasons.join("; ")}`);
   }
   if (report.next) lines.push(`NEXT: ${report.next}`);
   return `
@@ -550,6 +645,9 @@ function resolvePhaser3BrowserEntry(projectRoot) {
 function defineReactGameVitestConfig(options) {
   const phaser3BrowserEntry = resolvePhaser3BrowserEntry(options.projectRoot);
   return (0, import_config.defineConfig)({
+    // Keep discovery and dependency resolution anchored to the generated app even
+    // when an external runner invokes Vitest from a parent workspace directory.
+    root: options.projectRoot,
     resolve: {
       alias: {
         ...phaser3BrowserEntry ? { phaser: phaser3BrowserEntry } : {},

package/dist/react/vitest-config.mjs

@@ -69,20 +69,50 @@ var INPUT_EVENTS = [
   "touchend"
 ];
 var MIN_CHECKPOINTS = 2;
+var MAX_FORMATTED_OBSERVATION_LENGTH = 500;
+function formatObservation(fingerprint) {
+  if (fingerprint.length <= MAX_FORMATTED_OBSERVATION_LENGTH) return fingerprint;
+  return `${fingerprint.slice(0, MAX_FORMATTED_OBSERVATION_LENGTH)}\u2026 (${fingerprint.length} chars)`;
+}
+function sampleObservation(observe, stage) {
+  let value;
+  try {
+    value = observe();
+  } catch (error) {
+    throw new Error(`observe() threw at ${stage}: ${String(error)}`);
+  }
+  try {
+    const fingerprint = JSON.stringify(value);
+    if (fingerprint === void 0) throw new Error("unsupported value");
+    return { fingerprint, formatted: formatObservation(fingerprint) };
+  } catch {
+    throw new Error(
+      `observe() must return JSON-serializable read-only state; sampling failed at ${stage}.`
+    );
+  }
+}
+function formatObservationTimeline(entered, afterPrimary, outcome) {
+  return [
+    `entered=${entered.formatted}`,
+    `after-primary=${afterPrimary?.formatted ?? "<not sampled>"}`,
+    `outcome=${outcome.formatted}`
+  ].join(", ");
+}
 function describeMissingEvidence(evidence) {
-  if (!evidence || evidence.entryInputs === 0) return "entry \u8F93\u5165";
-  if (evidence.primaryInputs === 0) return "primary \u8F93\u5165";
+  if (!evidence || evidence.entryInputs === 0) return "an entry input";
+  if (evidence.primaryInputs === 0) return "a primary gameplay input";
   if (!evidence.checkpoints.includes("entered")) return "entered checkpoint";
-  if (evidence.boundedRuns === 0) return "\u6709\u754C stepUntil";
-  if (evidence.assertionsAfterOutcome === 0) return "stepUntil \u540E\u7684\u7ED3\u679C\u65AD\u8A00";
+  if (evidence.boundedRuns === 0) return "a bounded stepUntil call";
+  if (evidence.assertionsAfterOutcome === 0)
+    return "an outcome assertion after stepUntil";
   if (evidence.checkpoints.length < MIN_CHECKPOINTS)
-    return `\u81F3\u5C11 ${MIN_CHECKPOINTS} \u4E2A checkpoint`;
+    return `at least ${MIN_CHECKPOINTS} checkpoints`;
   if (!evidence.checkpoints.some(
     (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
   )) {
     return "progress/terminal checkpoint";
   }
-  return "\u5B8C\u6574\u7684 playthrough \u6821\u9A8C\u6807\u8BB0";
+  return "a complete playthrough verification marker";
 }
 function createMetadata(waiverReason) {
   return {
@@ -99,7 +129,7 @@ function createMetadata(waiverReason) {
     }
   };
 }
-function definePlaythrough(element, run, waiverReason) {
+function definePlaythrough(element, run, playthroughOptions, waiverReason) {
   const reason = normalizePlaythroughWaiverReason(waiverReason);
   const metadata = createMetadata(reason);
   test("production game completes a bounded playthrough", {
@@ -110,6 +140,8 @@ function definePlaythrough(element, run, waiverReason) {
     let assertionsAtOutcome;
     let enteredRecorded = false;
     let domTextAtEntered;
+    let enteredObservation;
+    let afterPrimaryObservation;
     const recordInput = () => {
       evidence.domInputEvents += 1;
     };
@@ -147,7 +179,15 @@ function definePlaythrough(element, run, waiverReason) {
             );
           }
           if (kind === "entry") evidence.entryInputs += 1;
-          else evidence.primaryInputs += 1;
+          else {
+            evidence.primaryInputs += 1;
+            if (playthroughOptions?.observe) {
+              afterPrimaryObservation = sampleObservation(
+                playthroughOptions.observe,
+                "after-primary"
+              );
+            }
+          }
         },
         checkpoint(kind) {
           if (kind === "entered") {
@@ -162,7 +202,14 @@ function definePlaythrough(element, run, waiverReason) {
               );
             }
             enteredRecorded = true;
-            domTextAtEntered = document.body.textContent ?? "";
+            if (playthroughOptions?.observe) {
+              enteredObservation = sampleObservation(
+                playthroughOptions.observe,
+                "entered"
+              );
+            } else {
+              domTextAtEntered = document.body.textContent ?? "";
+            }
             evidence.checkpoints.push(kind);
             return;
           }
@@ -183,16 +230,35 @@ function definePlaythrough(element, run, waiverReason) {
           }
           evidence.checkpoints.push(kind);
         },
-        async stepUntil(condition, options = {}) {
-          const steps = await runBoundedUntil(condition, options);
+        async stepUntil(condition, stepOptions = {}) {
+          const boundedOptions = stepOptions.diagnostics || !playthroughOptions?.observe ? stepOptions : {
+            ...stepOptions,
+            diagnostics: playthroughOptions.observe
+          };
+          const steps = await runBoundedUntil(condition, boundedOptions);
           if (evidence.primaryInputs === 0) {
             throw new Error(
               'stepUntil must follow performInput("primary", ...). A menu/help click is not gameplay evidence.'
             );
           }
-          if (steps === 0 && options.allowStaticDom !== true && domTextAtEntered !== void 0 && (document.body.textContent ?? "") === domTextAtEntered) {
+          if (playthroughOptions?.observe) {
+            if (!enteredObservation) {
+              throw new Error(
+                'observe requires checkpoint("entered") before primary gameplay input.'
+              );
+            }
+            const outcomeObservation = sampleObservation(
+              playthroughOptions.observe,
+              "outcome"
+            );
+            if (outcomeObservation.fingerprint === enteredObservation.fingerprint) {
+              throw new Error(
+                `The authoritative observation did not change from checkpoint("entered") to the outcome. Timeline: ${formatObservationTimeline(enteredObservation, afterPrimaryObservation, outcomeObservation)}`
+              );
+            }
+          } else if (steps === 0 && domTextAtEntered !== void 0 && (document.body.textContent ?? "") === domTextAtEntered) {
             throw new Error(
-              'stepUntil outcome was already true at step 0 and the DOM has not changed since checkpoint("entered"), so the flow cannot prove that gameplay changed anything. \u610F\u601D\uFF1A\u6E38\u620F\u4E00\u6B65\u90FD\u6CA1\u73A9\uFF0C\u7B49\u5F85\u7684"\u7ED3\u679C"\u5C31\u5DF2\u7ECF\u6210\u7ACB\uFF0C\u9875\u9762\u4E5F\u4E00\u4E2A\u5B57\u6CA1\u53D8\u2014\u2014\u8FD9\u4E2A\u7ED3\u679C\u8BC1\u660E\u4E0D\u4E86\u4EFB\u4F55\u4E8B\u3002\u5E38\u89C1\u539F\u56E0\uFF1A\u2460 \u8F93\u5165\u6CA1\u6709\u63A5\u5230\u6E38\u620F\u4E0A\uFF1B\u2461 \u754C\u9762\u5361\u6B7B\uFF08\u72B6\u6001\u6539\u4E86\u4F46 snapshot \u5F15\u7528\u6CA1\u6362\uFF0CReact \u6CA1\u6709\u5237\u65B0\uFF09\uFF1B\u2462 \u65AD\u8A00\u4E86\u5F00\u5C40\u524D\u5C31\u5B58\u5728\u7684\u9759\u6001\u6587\u672C\u3002\u4FEE\u590D\uFF1A\u7B49\u5F85\u5E76\u65AD\u8A00\u53EA\u6709\u73A9\u8D77\u6765\u4E4B\u540E\u624D\u4F1A\u51FA\u73B0\u7684\u4E1C\u897F\uFF08\u5F00\u59CB\u906E\u7F69\u6D88\u5931\u3001\u6BD4\u5206\u53D8\u5316\u3001\u7ED3\u7B97\u753B\u9762\u51FA\u73B0\uFF09\u3002\u4F8B\u5916\uFF1A\u7ED3\u679C\u753B\u5728 Canvas \u4E0A\u3001\u7ECF Telemetry \u7B49\u9875\u9762\u5916\u72B6\u6001\u89C2\u5BDF\u7684\u6E38\u620F\uFF0C\u663E\u5F0F\u4F20 { allowStaticDom: true }\u3002'
+              'stepUntil found the outcome at step 0, and the DOM has not changed since checkpoint("entered"). The flow therefore provides no evidence that the primary gameplay input produced a result. For Canvas or Controller state outside the DOM, declare one playthrough observe callback.'
             );
           }
           evidence.boundedRuns += 1;
@@ -236,9 +302,16 @@ function definePlaythrough(element, run, waiverReason) {
   });
 }
 var playthroughTest = Object.assign(
-  (element, run) => definePlaythrough(element, run),
+  (element, optionsOrRun, maybeRun) => {
+    if (typeof optionsOrRun === "function") {
+      definePlaythrough(element, optionsOrRun);
+      return;
+    }
+    if (!maybeRun) throw new TypeError("playthroughTest requires a run callback.");
+    definePlaythrough(element, maybeRun, optionsOrRun);
+  },
   {
-    skip: (reason, element, run) => definePlaythrough(element, run, reason)
+    skip: (reason, element, run) => definePlaythrough(element, run, void 0, reason)
   }
 );
 function auditReactPlaythroughRun(tests) {
@@ -255,7 +328,7 @@ function auditReactPlaythroughRun(tests) {
   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\u4F9D\u6B21\u6267\u884C performInput("entry")\u3001checkpoint("entered")\u3001performInput("primary")\u3001stepUntil\u3001\u7528 playthroughTest \u63D0\u4F9B\u7684 expect \u65AD\u8A00\u6743\u5A01\u7ED3\u679C\uFF0C\u5E76\u8BB0\u5F55 checkpoint("progress") \u6216 checkpoint("terminal")\uFF1B\u81F3\u5C11\u5B8C\u6210\u8FD9\u4E24\u6B21 checkpoint \u7B7E\u5230\u3002'
+      'No production gameplay verification was declared. Use playthroughTest to render <App />, then run performInput("entry"), checkpoint("entered"), performInput("primary"), and a bounded stepUntil. Assert the authoritative outcome with the expect provided by playthroughTest, then record checkpoint("progress") or checkpoint("terminal").'
     );
   } else {
     for (const candidate of declared) {
@@ -264,13 +337,17 @@ function auditReactPlaythroughRun(tests) {
       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`
+          `Playthrough ${JSON.stringify(candidate.name)} was skipped without an explicit reason of at least 20 characters.`
         );
       } else if (candidate.state !== "passed") {
-        issues.push(`\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u7684\u72B6\u6001\u4E3A ${candidate.state}\u3002`);
+        issues.push(
+          `Playthrough ${JSON.stringify(candidate.name)} finished with state ${candidate.state}.`
+        );
       } else {
         const missing = describeMissingEvidence(candidate.metadata?.evidence);
-        issues.push(`\u73A9\u6CD5\u9A8C\u8BC1\u201C${candidate.name}\u201D\u7F3A\u5C11${missing}\u3002`);
+        issues.push(
+          `Playthrough ${JSON.stringify(candidate.name)} is missing ${missing}.`
+        );
       }
     }
   }
@@ -360,6 +437,29 @@ function formatFailureSummary(modules) {
   lines.push("TEST_RESULT: FAIL");
   return lines;
 }
+function repairGuidance(cause) {
+  if (/snapshot\(\) returned the same reference/i.test(cause)) {
+    return "The game mutated state without publishing a new snapshot reference, so React skipped the render after an Object.is comparison. Publish a new top-level object before notifying subscribers, for example cachedSnapshot = { ...state }, and never expose a mutable internal object as the snapshot.";
+  }
+  if (/(?:already true|found the outcome) at step 0.*DOM has not changed/i.test(
+    cause
+  )) {
+    return 'Make the stepUntil condition false at checkpoint("entered"). Verify that the primary input reaches the production control, then wait for a post-input outcome such as a changed score, a removed entry overlay, a completed turn, or a result screen. For Canvas or Controller state outside the DOM, declare observe once on playthroughTest and return the read-only production Telemetry snapshot.';
+  }
+  if (/authoritative observation did not change/i.test(cause)) {
+    return "The flow reached its condition while observe still returned the same authoritative state. Make observe read the same production Controller that React renders, verify the primary input changes that Controller, and wait for a post-input result. Inspect the Timeline values to locate the disconnected stage.";
+  }
+  if (/No step callback was provided/i.test(cause)) {
+    return "This flow is driven by time or frames, but stepUntil 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.";
+  }
+  if (/outcome was not reached within \d+ steps/i.test(cause)) {
+    return "The real input was dispatched, but gameplay did not reach the outcome within the bound. Confirm that the production control received the input, then inspect Last diagnostics to determine whether the game loop, rule state, or UI synchronization failed to advance.";
+  }
+  if (/performInput|checkpoint/.test(cause)) {
+    return 'Complete the evidence sequence in order: performInput("entry"), checkpoint("entered"), performInput("primary"), bounded stepUntil, an authoritative result assertion using the provided expect, then checkpoint("progress") or checkpoint("terminal").';
+  }
+  return "Start from the production entry, dispatch real DOM input, and use stepUntil to reach a bounded player-visible or authoritative game outcome before asserting it. Do not jump to an internal level or mutate gameplay state.";
+}
 function assessReactPlaythroughReport(input) {
   const base = { file: input.expectedFile };
   if (!input.expectedFileScheduled) {
@@ -367,15 +467,15 @@ function assessReactPlaythroughReport(input) {
       return {
         ...base,
         status: "NOT_CHECKED",
-        next: `\u672C\u6B21\u662F\u805A\u7126\u8FD0\u884C\uFF0C\u672A\u68C0\u67E5\u6700\u4F4E\u53EF\u73A9\u6D41\u7A0B\uFF1B\u63D0\u4EA4\u524D\u8FD0\u884C pnpm test\uFF0C\u786E\u4FDD ${input.expectedFile} \u901A\u8FC7\u3002`,
+        next: `This focused run did not execute the minimum production playthrough. Run pnpm test before submitting and make sure ${input.expectedFile} passes.`,
         failsRun: false
       };
     }
     return {
       ...base,
       status: "FAILED",
-      cause: "\u751F\u4EA7\u53EF\u73A9\u6027\u6D4B\u8BD5\u6587\u4EF6\u4E0D\u5B58\u5728\u3002",
-      next: '\u521B\u5EFA\u8BE5\u6587\u4EF6\uFF1A\u4ECE <App /> \u901A\u8FC7\u771F\u5B9E DOM \u8F93\u5165\u4F9D\u6B21\u6267\u884C performInput("entry")\u3001checkpoint("entered")\u3001performInput("primary")\u3001stepUntil\u3001\u7528 playthroughTest \u63D0\u4F9B\u7684 expect \u65AD\u8A00\u6743\u5A01\u7ED3\u679C\uFF0C\u5E76\u8BB0\u5F55 checkpoint("progress") \u6216 checkpoint("terminal")\u3002\u6BCF\u6761\u4E3B\u6D41\u7A0B\u81F3\u5C11\u9700\u8981\u8FD9\u4E24\u6B21 checkpoint \u7B7E\u5230\u3002',
+      cause: "The required production playthrough test file does not exist.",
+      next: 'Create the file and render <App />. Drive a legal entry with performInput("entry"), record checkpoint("entered"), perform a core game action with performInput("primary"), and use a bounded stepUntil. Assert the authoritative result with the provided expect, then record checkpoint("progress") or checkpoint("terminal").',
       failsRun: true
     };
   }
@@ -389,7 +489,7 @@ function assessReactPlaythroughReport(input) {
     return {
       ...base,
       status: "NOT_CHECKED",
-      next: `\u672C\u6B21\u540D\u79F0\u6216\u884C\u53F7\u8FC7\u6EE4\u6CA1\u6709\u6267\u884C\u6700\u4F4E\u53EF\u73A9\u6D41\u7A0B\uFF1B\u63D0\u4EA4\u524D\u8FD0\u884C pnpm test\uFF0C\u786E\u4FDD ${input.expectedFile} \u901A\u8FC7\u3002`,
+      next: `The name or line filter did not execute the minimum production playthrough. Run pnpm test before submitting and make sure ${input.expectedFile} passes.`,
       failsRun: false
     };
   }
@@ -397,25 +497,20 @@ function assessReactPlaythroughReport(input) {
     return {
       ...base,
       status: "NOT_RUN",
-      cause: productionModule?.errors[0] ?? input.unhandledErrors?.[0] ?? "\u751F\u4EA7\u53EF\u73A9\u6027\u6D4B\u8BD5\u672A\u5B8C\u6210\u6536\u96C6\u6216\u6267\u884C\u3002",
-      next: "\u5148\u4FEE\u590D Vitest \u4E0A\u65B9\u9996\u4E2A\u8BED\u6CD5\u3001\u5BFC\u5165\u6216\u6536\u96C6\u9519\u8BEF\uFF0C\u518D\u8FD0\u884C pnpm test\uFF1B\u4E0D\u8981\u7528 skip \u63A9\u76D6\u52A0\u8F7D\u5931\u8D25\u3002",
+      cause: productionModule?.errors[0] ?? input.unhandledErrors?.[0] ?? "The production playthrough could not be collected or executed.",
+      next: "Fix the first Vitest syntax, import, environment, or collection error shown above, then run pnpm test again. Do not use skip to hide a load failure.",
       failsRun: true
     };
   }
   const tests = input.modules.flatMap((module) => module.tests);
   const audit = auditReactPlaythroughRun(tests);
   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);
-    const staticOutcome = /already true at step 0 and the DOM has not changed/i.test(cause);
-    const staleSnapshot = /snapshot\(\) returned the same reference/i.test(cause);
-    const missingStructuredEvidence = /performInput|checkpoint/.test(cause);
+    const cause = productionModule.errors[0] ?? input.unhandledErrors?.[0] ?? audit.issues[0] ?? "The production playthrough did not leave complete gameplay evidence.";
     return {
       ...base,
       status: "FAILED",
       cause,
-      next: staleSnapshot ? "\u6E38\u620F\u539F\u5730\u4FEE\u6539\u72B6\u6001\u540E\u6CA1\u6709\u53D1\u5E03\u65B0\u7684\u5FEB\u7167\u5F15\u7528\uFF0CReact \u56E0 Object.is \u6BD4\u8F83\u76F8\u540C\u800C\u8DF3\u8FC7\u91CD\u6E32\u3002\u5728 controller \u7684 notify \u8DEF\u5F84\u4E0A\u53D1\u5E03\u65B0\u9876\u5C42\u5BF9\u8C61\uFF08cachedSnapshot = { ...state }\uFF09\uFF0C\u4E0D\u8981\u628A\u53EF\u53D8\u7684\u5185\u90E8\u5BF9\u8C61\u76F4\u63A5\u4F5C\u4E3A\u5FEB\u7167\u66B4\u9732\u3002" : staticOutcome ? "\u7ED3\u679C\u5728\u63A8\u8FDB\u524D\u5DF2\u6210\u7ACB\u4E14 DOM \u81EA entered \u4EE5\u6765\u65E0\u53D8\u5316\uFF1A\u8F93\u5165\u53EF\u80FD\u672A\u63A5\u5230\u751F\u4EA7\u63A7\u5236\uFF0CUI \u53EF\u80FD\u51BB\u7ED3\uFF0C\u4E5F\u53EF\u80FD\u65AD\u8A00\u4E86\u6E38\u620F\u5F00\u59CB\u524D\u5C31\u5B58\u5728\u7684\u9759\u6001\u6587\u672C\u3002\u6539\u4E3A\u7B49\u5F85\u5E76\u65AD\u8A00\u53EA\u6709\u73A9\u6CD5\u63A8\u8FDB\u540E\u624D\u51FA\u73B0\u7684\u72B6\u6001\uFF08\u5F00\u59CB\u906E\u7F69\u6D88\u5931\u3001\u6BD4\u5206\u53D8\u5316\u3001\u7ED3\u7B97\u51FA\u73B0\uFF09\uFF1B\u7ECF Canvas/Telemetry \u7B49 DOM \u5916\u6743\u5A01\u72B6\u6001\u89C2\u5BDF\u7684\u6D41\u7A0B\u4F20 { allowStaticDom: true }\u3002" : 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" : missingStructuredEvidence ? '\u6309\u987A\u5E8F\u8865\u9F50\u81F3\u5C11\u4E24\u6B21\u7B7E\u5230\uFF1AperformInput("entry") \u540E\u8C03\u7528 checkpoint("entered")\uFF1B\u518D\u7528 performInput("primary") \u6267\u884C\u6838\u5FC3\u64CD\u4F5C\uFF0CstepUntil \u7B49\u5F85\u7ED3\u679C\uFF0C\u7528\u56DE\u8C03\u63D0\u4F9B\u7684 expect \u65AD\u8A00\u540E\u8C03\u7528 checkpoint("progress") \u6216 checkpoint("terminal")\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\u6743\u5A01\u72B6\u6001\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: repairGuidance(cause),
       failsRun: true
     };
   }
@@ -433,7 +528,7 @@ function formatReactPlaythroughReport(report) {
   const lines = [`REACT_PLAYTHROUGH: ${report.status}`, `FILE: ${report.file}`];
   if (report.cause) lines.push(`CAUSE: ${report.cause}`);
   if (report.waiverReasons?.length) {
-    lines.push(`REASON: ${report.waiverReasons.join("\uFF1B")}`);
+    lines.push(`REASON: ${report.waiverReasons.join("; ")}`);
   }
   if (report.next) lines.push(`NEXT: ${report.next}`);
   return `
@@ -516,6 +611,9 @@ function resolvePhaser3BrowserEntry(projectRoot) {
 function defineReactGameVitestConfig(options) {
   const phaser3BrowserEntry = resolvePhaser3BrowserEntry(options.projectRoot);
   return defineConfig({
+    // Keep discovery and dependency resolution anchored to the generated app even
+    // when an external runner invokes Vitest from a parent workspace directory.
+    root: options.projectRoot,
     resolve: {
       alias: {
         ...phaser3BrowserEntry ? { phaser: phaser3BrowserEntry } : {},

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

@@ -0,0 +1,97 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/rules/react-test-boundary-plugin.ts
+var react_test_boundary_plugin_exports = {};
+__export(react_test_boundary_plugin_exports, {
+  default: () => react_test_boundary_plugin_default
+});
+module.exports = __toCommonJS(react_test_boundary_plugin_exports);
+var PRODUCTION_PLAYTHROUGH = "/tests/production-playthrough.test.tsx";
+function normalizedFilename(filename) {
+  return filename.replaceAll("\\", "/");
+}
+function importedName(specifier) {
+  const imported = specifier.imported;
+  return imported.type === "Identifier" ? imported.name : String(imported.value);
+}
+function internalGameImports(node) {
+  if (typeof node.source.value !== "string") return [];
+  if (!node.source.value.startsWith("@/game/")) return [];
+  if (node.importKind === "type") return [];
+  return node.specifiers.flatMap((specifier) => {
+    const importKind = specifier.importKind;
+    return importKind === "type" ? [] : [specifier.local.name];
+  });
+}
+var rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Protect production React game and playthrough boundaries"
+    },
+    messages: {
+      boundExpect: "Use the expect provided by playthroughTest. An imported Vitest expect may belong to a different module instance and cannot provide reliable assertion evidence.",
+      providedUser: "Use the user provided by playthroughTest; do not import or create another userEvent instance in the production playthrough.",
+      productionTestingImport: "Production source must not import miaoda-game-devkit/react/testing. Inject test clocks and observers through the production App factory boundary.",
+      productionEntry: "Render <App /> from the production playthrough. Import Controller and Telemetry helpers when needed, but do not render an internal game component directly."
+    },
+    schema: []
+  },
+  create(context) {
+    const filename = normalizedFilename(context.filename);
+    const isProductionPlaythrough = filename.endsWith(PRODUCTION_PLAYTHROUGH);
+    const isProductionSource = filename.includes("/src/");
+    const internalGameBindings = /* @__PURE__ */ new Set();
+    return {
+      ImportDeclaration(node) {
+        const source = node.source.value;
+        if (typeof source !== "string") return;
+        if (isProductionSource && source === "miaoda-game-devkit/react/testing") {
+          context.report({ node: node.source, messageId: "productionTestingImport" });
+        }
+        if (!isProductionPlaythrough) return;
+        if (source === "vitest" && node.specifiers.some(
+          (specifier) => specifier.type === "ImportSpecifier" && importedName(specifier) === "expect"
+        )) {
+          context.report({ node: node.source, messageId: "boundExpect" });
+        }
+        if (source === "@testing-library/user-event") {
+          context.report({ node: node.source, messageId: "providedUser" });
+        }
+        for (const name of internalGameImports(node)) {
+          internalGameBindings.add(name);
+        }
+      },
+      JSXOpeningElement(node) {
+        if (!isProductionPlaythrough) return;
+        const opening = node;
+        if (opening.name?.type === "JSXIdentifier" && opening.name.name && internalGameBindings.has(opening.name.name)) {
+          context.report({ node, messageId: "productionEntry" });
+        }
+      }
+    };
+  }
+};
+var plugin = {
+  meta: { name: "react-game-boundaries" },
+  rules: { "no-test-bypass": rule }
+};
+var react_test_boundary_plugin_default = plugin;
+module.exports = module.exports.default;

package/oxlint-config.json

@@ -5,10 +5,12 @@
   },
   "jsPlugins": [
     "./dist/rules/check-image-import-plugin.js",
-    "./dist/rules/check-style-import-plugin.js"
+    "./dist/rules/check-style-import-plugin.js",
+    "./dist/rules/react-test-boundary-plugin.js"
   ],
   "rules": {
     "check-image-exists/no-missing-image": "error",
-    "check-style-exists/no-missing-style": "error"
+    "check-style-exists/no-missing-style": "error",
+    "react-game-boundaries/no-test-bypass": "error"
   }
 }

package/package.json

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