miaoda-game-devkit 0.3.0 → 0.5.0

package/README.md

@@ -18,13 +18,21 @@
 这两次 checkpoint；checkpoint 只负责签到，不携带或验证状态。大型游戏仍只保留一条最短关键流程；
 分支、关卡规则和恢复清理由专门测试覆盖。不要再次调用 `userEvent.setup()`。
 时间、帧或自定义 scheduler 流程必须显式传入确定性 `step`；精确物理时间、暂停恢复
-或调度清理测试可使用 `ManualGameClock`。
+或调度清理测试可使用 `ManualGameClock`。Canvas/Controller 流程在 `playthroughTest` 上声明一次
+`observe`，返回 JSON 可序列化的权威 Telemetry 状态；框架自动比较流程状态并复用为超时诊断。
+
+失败的 production playthrough 会额外输出一条有界 `TRACE:`：记录 entry 后、primary 后和
+最后一次可观测状态，以及已完成 checkpoint 与推进步数。通过流程不输出 TRACE，避免增加
+常规 CI 噪声。显式启用 Vitest retry 时，每次尝试会重置证据，最终报告只展示最后一次尝试的
+CAUSE 与 TRACE；若测试主体已完成、随后由 `afterEach` 或运行时错误判失败，reporter 仍会从
+task metadata 恢复这条流程证据。状态优先来自 `observe`，没有 Telemetry 时才使用有界 DOM
+摘要；不要把 TRACE 当作新的断言或第二份业务状态。
 
 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
@@ -84,8 +92,9 @@ Phaser 4 模板对应使用 `miaoda-phaser-game-lint`。命令类型不通过依
 开发工具包自行维护并精确固定 Vitest 等工具版本，从自身依赖中解析可执行文件，使用方不需要重复声明
 Biome、Oxlint 或 tsgo。仓库中保留稳定的命令入口，因此 `dist/` 尚未生成时，pnpm
 也能正确建立命令链接；工作区开发状态下由 Nx 在模板检查前构建开发工具包，发布包则
-直接携带运行时 `dist/`。打包消费者契约会验证固定 Vitest 版本以及 reporter 的通过、聚焦和
-缺失流程行为。开发工具包内部的 `*.test.*` 与构建后的 `*.contract.mjs` 都不会
+直接携带运行时 `dist/`。打包消费者契约会验证固定 Vitest 版本以及 reporter 的通过、聚焦、
+缺失流程、retry 失败诊断和 hook 失败诊断行为。开发工具包内部的 `*.test.*` 与构建后的
+`*.contract.mjs` 都不会
 进入 npm 包；这些契约只由 devkit 自己的测试目标执行。
 
 monorepo 中的模板可以放置只包含 `extends: ["miaoda-game-devkit/biome"]` 的薄配置，

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 主流程测试留下的可序列化运行期证据。 */
@@ -68,6 +58,8 @@ interface ReactPlaythroughMetadata {
     version: 3;
     /** 静态、非交互项目跳过主流程验证时必须提供的理由。 */
     waiverReason?: string;
+    /** 仅供失败 reporter 兜底读取；成功运行不会输出。 */
+    trace?: string;
     /** 测试执行期间持续更新的客观证据。 */
     evidence: ReactPlaythroughEvidence;
 }
@@ -76,6 +68,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 +104,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 +143,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 主流程测试留下的可序列化运行期证据。 */
@@ -68,6 +58,8 @@ interface ReactPlaythroughMetadata {
     version: 3;
     /** 静态、非交互项目跳过主流程验证时必须提供的理由。 */
     waiverReason?: string;
+    /** 仅供失败 reporter 兜底读取；成功运行不会输出。 */
+    trace?: string;
     /** 测试执行期间持续更新的客观证据。 */
     evidence: ReactPlaythroughEvidence;
 }
@@ -76,6 +68,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 +104,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 +143,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,47 +152,123 @@ var INPUT_EVENTS = [
   "touchend"
 ];
 var MIN_CHECKPOINTS = 2;
+var REACT_PLAYTHROUGH_TRACE_ANNOTATION = "miaoda:react-playthrough-trace";
+var MAX_TRACE_VALUE_LENGTH = 180;
+var MAX_TRACE_LENGTH = 720;
+function truncateTraceValue(value, limit) {
+  const compact = value.replace(/\s+/g, " ").trim();
+  if (compact.length <= limit) return compact;
+  return `${compact.slice(0, Math.max(0, limit - 1))}\u2026`;
+}
+function formatReactPlaythroughFailureTrace(trace) {
+  const stages = [
+    ["entered", trace.entered],
+    ["after-primary", trace.afterPrimary],
+    ["last", trace.last]
+  ].filter((stage) => stage[1] !== void 0).map(
+    ([stage, value]) => `${stage}=${truncateTraceValue(value, MAX_TRACE_VALUE_LENGTH)}`
+  );
+  const details = [
+    trace.checkpoints.length > 0 ? `checkpoints=${trace.checkpoints.join(",")}` : "checkpoints=none",
+    trace.step ? `stepUntil=${trace.step.completed ?? "failed"}/${trace.step.bound}` : void 0
+  ].filter((detail) => Boolean(detail));
+  const formatted = `${stages.join(" -> ")}${stages.length ? "; " : ""}${details.join("; ")}`;
+  return truncateTraceValue(formatted, MAX_TRACE_LENGTH);
+}
+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) {
+function createEvidence() {
   return {
-    version: 3,
-    waiverReason,
-    evidence: {
-      domInputEvents: 0,
-      entryInputs: 0,
-      primaryInputs: 0,
-      boundedRuns: 0,
-      assertionsAfterOutcome: 0,
-      checkpoints: [],
-      verified: false
-    }
+    domInputEvents: 0,
+    entryInputs: 0,
+    primaryInputs: 0,
+    boundedRuns: 0,
+    assertionsAfterOutcome: 0,
+    checkpoints: [],
+    verified: false
   };
 }
-function definePlaythrough(element, run, waiverReason) {
+function createMetadata(waiverReason) {
+  return { version: 3, waiverReason, evidence: createEvidence() };
+}
+function definePlaythrough(element, run, playthroughOptions, waiverReason) {
   const reason = normalizePlaythroughWaiverReason(waiverReason);
   const metadata = createMetadata(reason);
   (0, import_vitest.test)("production game completes a bounded playthrough", {
     skip: Boolean(reason),
     meta: { reactPlaythrough: metadata }
-  }, async ({ expect }) => {
+  }, async ({ annotate, expect }) => {
+    metadata.evidence = createEvidence();
+    metadata.trace = void 0;
     const evidence = metadata.evidence;
     let assertionsAtOutcome;
     let enteredRecorded = false;
     let domTextAtEntered;
+    let enteredObservation;
+    let afterPrimaryObservation;
+    let enteredTrace;
+    let afterPrimaryTrace;
+    let outcomeTrace;
+    let stepTrace;
+    const sampleDomTrace = () => JSON.stringify((document.body.textContent ?? "").replace(/\s+/g, " ").trim());
+    const sampleLastTrace = () => {
+      if (!playthroughOptions?.observe) return sampleDomTrace();
+      try {
+        return sampleObservation(playthroughOptions.observe, "outcome").formatted;
+      } catch (error) {
+        return `<observe unavailable: ${String(error)}>`;
+      }
+    };
+    const createFailureTrace = () => formatReactPlaythroughFailureTrace({
+      entered: enteredTrace,
+      afterPrimary: afterPrimaryTrace,
+      last: outcomeTrace ?? sampleLastTrace(),
+      checkpoints: [...evidence.checkpoints],
+      step: stepTrace
+    });
     const recordInput = () => {
       evidence.domInputEvents += 1;
     };
@@ -230,7 +306,18 @@ 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"
+              );
+              afterPrimaryTrace = afterPrimaryObservation.formatted;
+            } else {
+              afterPrimaryTrace = sampleDomTrace();
+            }
+          }
         },
         checkpoint(kind) {
           if (kind === "entered") {
@@ -245,7 +332,16 @@ function definePlaythrough(element, run, waiverReason) {
               );
             }
             enteredRecorded = true;
-            domTextAtEntered = document.body.textContent ?? "";
+            if (playthroughOptions?.observe) {
+              enteredObservation = sampleObservation(
+                playthroughOptions.observe,
+                "entered"
+              );
+              enteredTrace = enteredObservation.formatted;
+            } else {
+              domTextAtEntered = document.body.textContent ?? "";
+              enteredTrace = sampleDomTrace();
+            }
             evidence.checkpoints.push(kind);
             return;
           }
@@ -266,17 +362,43 @@ function definePlaythrough(element, run, waiverReason) {
           }
           evidence.checkpoints.push(kind);
         },
-        async stepUntil(condition, options = {}) {
-          const steps = await runBoundedUntil(condition, options);
+        async stepUntil(condition, stepOptions = {}) {
+          const stepBound = stepOptions.maxSteps ?? 120;
+          stepTrace = { bound: stepBound };
+          const boundedOptions = stepOptions.diagnostics || !playthroughOptions?.observe ? stepOptions : {
+            ...stepOptions,
+            diagnostics: playthroughOptions.observe
+          };
+          const steps = await runBoundedUntil(condition, boundedOptions);
+          stepTrace = { bound: stepBound, completed: steps };
           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) {
-            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'
+          if (playthroughOptions?.observe) {
+            if (!enteredObservation) {
+              throw new Error(
+                'observe requires checkpoint("entered") before primary gameplay input.'
+              );
+            }
+            const outcomeObservation = sampleObservation(
+              playthroughOptions.observe,
+              "outcome"
             );
+            outcomeTrace = outcomeObservation.formatted;
+            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 {
+            outcomeTrace = sampleDomTrace();
+            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;
@@ -311,7 +433,15 @@ function definePlaythrough(element, run, waiverReason) {
         );
       }
       evidence.verified = true;
+    } catch (error) {
+      metadata.trace = createFailureTrace();
+      try {
+        await annotate(metadata.trace, REACT_PLAYTHROUGH_TRACE_ANNOTATION);
+      } catch {
+      }
+      throw error;
     } finally {
+      metadata.trace ??= createFailureTrace();
       for (const event of INPUT_EVENTS) {
         document.removeEventListener(event, recordInput, true);
       }
@@ -319,9 +449,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 +475,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 +484,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}.`
+        );
       }
     }
   }