miaoda-game-devkit 0.2.21 → 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
@@ -154,8 +155,8 @@ DOM 到 Phaser 的输入、命中测试和游戏状态变化，不验证 Canvas/
 给出直接修复步骤；测试文件无法加载或配置要求的测试尚未建立时，不再继续报告 Scene
 注册等派生问题。先处理第一类错误，再重新运行 `pnpm test`。
 
-共享 Vitest 配置使用 `minimal` reporter 和 `text-summary` coverage reporter，保留失败
-定位、Scene 覆盖摘要和最终机器标识，同时避免输出完整测试列表和逐文件噪声。
+Phaser Vitest 配置使用 `minimal` reporter；React Vitest 配置使用无 ANSI 的精简 reporter。
+两者都保留失败定位、coverage 摘要和最终机器标识，同时避免输出完整 DOM 快照、测试列表和逐文件噪声。
 
 ## 发布顺序
 

package/dist/react/index.d.mts

@@ -10,4 +10,22 @@ interface DisposableGameController {
  */
 declare function useOwnedGameController<TController extends DisposableGameController>(createController: () => TController): TController;
 
-export { type DisposableGameController, useOwnedGameController };
+/** 同时提供订阅与权威快照读取的游戏 Controller，是最小可渲染运行时。 */
+interface SubscribableGameController<TState> extends DisposableGameController {
+    subscribe(listener: () => void): () => void;
+    snapshot(): TState;
+}
+/**
+ * 一次调用接管游戏 Controller 的创建、销毁与状态订阅：
+ * useOwnedGameController 的 ownership，加上 useSyncExternalStore 的渲染桥。
+ *
+ * 附带一道开发期检查：状态内容变了、但 snapshot() 返回的还是原来那个
+ * 对象时，React 会认为"什么都没变"而不刷新界面——游戏悄悄卡死，没有
+ * 任何报错。检测到这种情况就立刻抛错，并直接告诉你怎么修。
+ */
+declare function useGameController<TController extends SubscribableGameController<unknown>>(createController: () => TController): {
+    game: TController;
+    state: ReturnType<TController["snapshot"]>;
+};
+
+export { type DisposableGameController, type SubscribableGameController, useGameController, useOwnedGameController };

package/dist/react/index.d.ts

@@ -10,4 +10,22 @@ interface DisposableGameController {
  */
 declare function useOwnedGameController<TController extends DisposableGameController>(createController: () => TController): TController;
 
-export { type DisposableGameController, useOwnedGameController };
+/** 同时提供订阅与权威快照读取的游戏 Controller，是最小可渲染运行时。 */
+interface SubscribableGameController<TState> extends DisposableGameController {
+    subscribe(listener: () => void): () => void;
+    snapshot(): TState;
+}
+/**
+ * 一次调用接管游戏 Controller 的创建、销毁与状态订阅：
+ * useOwnedGameController 的 ownership，加上 useSyncExternalStore 的渲染桥。
+ *
+ * 附带一道开发期检查：状态内容变了、但 snapshot() 返回的还是原来那个
+ * 对象时，React 会认为"什么都没变"而不刷新界面——游戏悄悄卡死，没有
+ * 任何报错。检测到这种情况就立刻抛错，并直接告诉你怎么修。
+ */
+declare function useGameController<TController extends SubscribableGameController<unknown>>(createController: () => TController): {
+    game: TController;
+    state: ReturnType<TController["snapshot"]>;
+};
+
+export { type DisposableGameController, type SubscribableGameController, useGameController, useOwnedGameController };

package/dist/react/index.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var react_exports = {};
 __export(react_exports, {
   browserGameClock: () => browserGameClock,
+  useGameController: () => useGameController,
   useOwnedGameController: () => useOwnedGameController
 });
 module.exports = __toCommonJS(react_exports);
@@ -50,8 +51,57 @@ function useOwnedGameController(createController) {
   }, [controller]);
   return controller;
 }
+
+// src/react/use-game-controller.ts
+var import_react2 = require("react");
+function useGameController(createController) {
+  const game = useOwnedGameController(createController);
+  useSnapshotIntegrityCheck(game);
+  const state = (0, import_react2.useSyncExternalStore)(
+    game.subscribe,
+    game.snapshot,
+    game.snapshot
+  );
+  return { game, state };
+}
+function useSnapshotIntegrityCheck(game) {
+  const reported = (0, import_react2.useRef)(false);
+  (0, import_react2.useEffect)(() => {
+    if (process.env.NODE_ENV === "production") return void 0;
+    let previous = game.snapshot();
+    let previousJson;
+    try {
+      previousJson = JSON.stringify(previous);
+    } catch {
+      previousJson = void 0;
+    }
+    return game.subscribe(() => {
+      if (reported.current) return;
+      const next = game.snapshot();
+      if (!Object.is(previous, next)) {
+        previous = next;
+        previousJson = void 0;
+        return;
+      }
+      let nextJson;
+      try {
+        nextJson = JSON.stringify(next);
+      } catch {
+        return;
+      }
+      if (previousJson !== void 0 && nextJson !== previousJson) {
+        reported.current = true;
+        throw new Error(
+          "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;
+    });
+  }, [game]);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   browserGameClock,
+  useGameController,
   useOwnedGameController
 });

package/dist/react/index.mjs

@@ -23,7 +23,56 @@ function useOwnedGameController(createController) {
   }, [controller]);
   return controller;
 }
+
+// src/react/use-game-controller.ts
+import { useEffect as useEffect2, useRef as useRef2, useSyncExternalStore } from "react";
+function useGameController(createController) {
+  const game = useOwnedGameController(createController);
+  useSnapshotIntegrityCheck(game);
+  const state = useSyncExternalStore(
+    game.subscribe,
+    game.snapshot,
+    game.snapshot
+  );
+  return { game, state };
+}
+function useSnapshotIntegrityCheck(game) {
+  const reported = useRef2(false);
+  useEffect2(() => {
+    if (process.env.NODE_ENV === "production") return void 0;
+    let previous = game.snapshot();
+    let previousJson;
+    try {
+      previousJson = JSON.stringify(previous);
+    } catch {
+      previousJson = void 0;
+    }
+    return game.subscribe(() => {
+      if (reported.current) return;
+      const next = game.snapshot();
+      if (!Object.is(previous, next)) {
+        previous = next;
+        previousJson = void 0;
+        return;
+      }
+      let nextJson;
+      try {
+        nextJson = JSON.stringify(next);
+      } catch {
+        return;
+      }
+      if (previousJson !== void 0 && nextJson !== previousJson) {
+        reported.current = true;
+        throw new Error(
+          "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;
+    });
+  }, [game]);
+}
 export {
   browserGameClock,
+  useGameController,
   useOwnedGameController
 };

package/dist/react/testing.d.mts

@@ -66,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 对生产游戏入口的渲染结果。 */
@@ -97,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;
 }
@@ -134,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

@@ -66,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 对生产游戏入口的渲染结果。 */
@@ -97,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;
 }
@@ -134,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", {
@@ -192,6 +222,9 @@ function definePlaythrough(element, run, waiverReason) {
     const evidence = metadata.evidence;
     let assertionsAtOutcome;
     let enteredRecorded = false;
+    let domTextAtEntered;
+    let enteredObservation;
+    let afterPrimaryObservation;
     const recordInput = () => {
       evidence.domInputEvents += 1;
     };
@@ -229,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") {
@@ -244,6 +285,14 @@ function definePlaythrough(element, run, waiverReason) {
               );
             }
             enteredRecorded = true;
+            if (playthroughOptions?.observe) {
+              enteredObservation = sampleObservation(
+                playthroughOptions.observe,
+                "entered"
+              );
+            } else {
+              domTextAtEntered = document.body.textContent ?? "";
+            }
             evidence.checkpoints.push(kind);
             return;
           }
@@ -264,13 +313,37 @@ 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 (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 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;
           assertionsAtOutcome = expect.getState().assertionCalls;
           return steps;
@@ -312,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) {
@@ -331,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) {
@@ -340,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", {
@@ -154,6 +184,9 @@ function definePlaythrough(element, run, waiverReason) {
     const evidence = metadata.evidence;
     let assertionsAtOutcome;
     let enteredRecorded = false;
+    let domTextAtEntered;
+    let enteredObservation;
+    let afterPrimaryObservation;
     const recordInput = () => {
       evidence.domInputEvents += 1;
     };
@@ -191,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") {
@@ -206,6 +247,14 @@ function definePlaythrough(element, run, waiverReason) {
               );
             }
             enteredRecorded = true;
+            if (playthroughOptions?.observe) {
+              enteredObservation = sampleObservation(
+                playthroughOptions.observe,
+                "entered"
+              );
+            } else {
+              domTextAtEntered = document.body.textContent ?? "";
+            }
             evidence.checkpoints.push(kind);
             return;
           }
@@ -226,13 +275,37 @@ 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 (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 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;
           assertionsAtOutcome = expect.getState().assertionCalls;
           return steps;
@@ -274,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) {
@@ -293,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) {
@@ -302,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}.`
+        );
       }
     }
   }