miaoda-game-devkit 0.4.0 → 0.5.0

package/README.md

@@ -21,6 +21,13 @@
 或调度清理测试可使用 `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 会因此互相影响。使用自定义
@@ -85,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/testing.d.mts

@@ -58,6 +58,8 @@ interface ReactPlaythroughMetadata {
     version: 3;
     /** 静态、非交互项目跳过主流程验证时必须提供的理由。 */
     waiverReason?: string;
+    /** 仅供失败 reporter 兜底读取；成功运行不会输出。 */
+    trace?: string;
     /** 测试执行期间持续更新的客观证据。 */
     evidence: ReactPlaythroughEvidence;
 }

package/dist/react/testing.d.ts

@@ -58,6 +58,8 @@ interface ReactPlaythroughMetadata {
     version: 3;
     /** 静态、非交互项目跳过主流程验证时必须提供的理由。 */
     waiverReason?: string;
+    /** 仅供失败 reporter 兜底读取；成功运行不会输出。 */
+    trace?: string;
     /** 测试执行期间持续更新的客观证据。 */
     evidence: ReactPlaythroughEvidence;
 }

package/dist/react/testing.js

@@ -152,6 +152,29 @@ 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;
@@ -197,34 +220,55 @@ function describeMissingEvidence(evidence) {
   }
   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 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;
     };
@@ -269,6 +313,9 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
                 playthroughOptions.observe,
                 "after-primary"
               );
+              afterPrimaryTrace = afterPrimaryObservation.formatted;
+            } else {
+              afterPrimaryTrace = sampleDomTrace();
             }
           }
         },
@@ -290,8 +337,10 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
                 playthroughOptions.observe,
                 "entered"
               );
+              enteredTrace = enteredObservation.formatted;
             } else {
               domTextAtEntered = document.body.textContent ?? "";
+              enteredTrace = sampleDomTrace();
             }
             evidence.checkpoints.push(kind);
             return;
@@ -314,11 +363,14 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
           evidence.checkpoints.push(kind);
         },
         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.'
@@ -334,15 +386,19 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
               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 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.'
-            );
+          } 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;
@@ -377,7 +433,15 @@ function definePlaythrough(element, run, playthroughOptions, 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);
       }

package/dist/react/testing.mjs

@@ -114,6 +114,29 @@ 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;
@@ -159,34 +182,55 @@ function describeMissingEvidence(evidence) {
   }
   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 createMetadata(waiverReason) {
+  return { version: 3, waiverReason, evidence: createEvidence() };
+}
 function definePlaythrough(element, run, playthroughOptions, waiverReason) {
   const reason = normalizePlaythroughWaiverReason(waiverReason);
   const metadata = createMetadata(reason);
   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;
     };
@@ -231,6 +275,9 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
                 playthroughOptions.observe,
                 "after-primary"
               );
+              afterPrimaryTrace = afterPrimaryObservation.formatted;
+            } else {
+              afterPrimaryTrace = sampleDomTrace();
             }
           }
         },
@@ -252,8 +299,10 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
                 playthroughOptions.observe,
                 "entered"
               );
+              enteredTrace = enteredObservation.formatted;
             } else {
               domTextAtEntered = document.body.textContent ?? "";
+              enteredTrace = sampleDomTrace();
             }
             evidence.checkpoints.push(kind);
             return;
@@ -276,11 +325,14 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
           evidence.checkpoints.push(kind);
         },
         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.'
@@ -296,15 +348,19 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
               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 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.'
-            );
+          } 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;
@@ -339,7 +395,15 @@ function definePlaythrough(element, run, playthroughOptions, 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);
       }

package/dist/react/vitest-config.js

@@ -103,6 +103,29 @@ 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;
@@ -148,34 +171,55 @@ function describeMissingEvidence(evidence) {
   }
   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 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;
     };
@@ -220,6 +264,9 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
                 playthroughOptions.observe,
                 "after-primary"
               );
+              afterPrimaryTrace = afterPrimaryObservation.formatted;
+            } else {
+              afterPrimaryTrace = sampleDomTrace();
             }
           }
         },
@@ -241,8 +288,10 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
                 playthroughOptions.observe,
                 "entered"
               );
+              enteredTrace = enteredObservation.formatted;
             } else {
               domTextAtEntered = document.body.textContent ?? "";
+              enteredTrace = sampleDomTrace();
             }
             evidence.checkpoints.push(kind);
             return;
@@ -265,11 +314,14 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
           evidence.checkpoints.push(kind);
         },
         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.'
@@ -285,15 +337,19 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
               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 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.'
-            );
+          } 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;
@@ -328,7 +384,15 @@ function definePlaythrough(element, run, playthroughOptions, 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);
       }
@@ -421,21 +485,41 @@ function errorLocation(value) {
   const match = value.match(/(?:^|\n)\s*at\s+(.*?\.(?:test|spec)\.[^\n]+:\d+:\d+)/);
   return match?.[1];
 }
+function failureTrace(test2) {
+  const annotations = test2.annotations();
+  let annotationTrace;
+  for (let index = annotations.length - 1; index >= 0; index -= 1) {
+    if (annotations[index].type === REACT_PLAYTHROUGH_TRACE_ANNOTATION) {
+      annotationTrace = annotations[index].message;
+      break;
+    }
+  }
+  const metadata = test2.meta().reactPlaythrough;
+  const trace = annotationTrace ?? (isMetadata(metadata) ? metadata.trace : void 0);
+  return trace ? truncateReporterLine(trace, 720) : void 0;
+}
+function truncateReporterLine(value, limit) {
+  const compact = (0, import_node_util.stripVTControlCharacters)(value).replace(/\s+/g, " ").trim();
+  if (compact.length <= limit) return compact;
+  return `${compact.slice(0, Math.max(0, limit - 1))}\u2026`;
+}
 function toModuleResult(module2, projectRoot) {
   const tests = [...module2.children.allTests()];
+  const moduleErrors = module2.errors().map((error) => firstLine(error.message)).filter((message) => Boolean(message));
   const errors = [
-    ...module2.errors().map((error) => firstLine(error.message)),
+    ...moduleErrors,
     ...tests.flatMap(
       (test2) => (test2.result().errors ?? []).map((error) => firstLine(error.message))
     )
   ].filter((message) => Boolean(message));
   const failures = tests.filter((test2) => test2.result().state === "failed").map((test2) => {
-    const raw = test2.result().errors?.[0]?.message ?? module2.errors()[0]?.message ?? "Unknown failure";
+    const raw = test2.result().errors?.at(-1)?.message ?? module2.errors()[0]?.message ?? "Unknown failure";
     return {
       test: test2.fullName,
       cause: firstLine(raw) ?? "Unknown failure",
       location: test2.location ? `${(0, import_node_path.relative)(projectRoot, module2.moduleId).replaceAll("\\", "/")}:${test2.location.line}:${test2.location.column}` : errorLocation(raw),
-      hint: failureHint(raw)
+      hint: failureHint(raw),
+      trace: failureTrace(test2)
     };
   });
   if (failures.length === 0 && tests.length === 0 && module2.errors().length > 0) {
@@ -451,11 +535,12 @@ function toModuleResult(module2, projectRoot) {
     file: (0, import_node_path.relative)(projectRoot, module2.moduleId).replaceAll("\\", "/"),
     state: module2.state(),
     errors,
+    primaryError: moduleErrors[0] ?? failures[0]?.cause,
     tests: tests.map(toAuditInput),
     failures
   };
 }
-function formatFailureSummary(modules) {
+function formatReactFailureSummary(modules) {
   const failures = modules.flatMap(
     (module2) => (module2.failures ?? []).map((failure) => ({ ...failure, file: module2.file }))
   );
@@ -465,6 +550,7 @@ function formatFailureSummary(modules) {
     lines.push(`FAILURE_${index + 1}: ${failure.file}`);
     lines.push(`TEST: ${failure.test}`);
     lines.push(`CAUSE: ${failure.cause}`);
+    if (failure.trace) lines.push(`TRACE: ${failure.trace}`);
     if (failure.location) lines.push(`AT: ${failure.location}`);
     if (failure.hint) lines.push(`HINT: ${failure.hint}`);
   }
@@ -539,7 +625,7 @@ function assessReactPlaythroughReport(input) {
   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] ?? "The production playthrough did not leave complete gameplay evidence.";
+    const cause = productionModule.primaryError ?? productionModule.errors[0] ?? input.unhandledErrors?.[0] ?? audit.issues[0] ?? "The production playthrough did not leave complete gameplay evidence.";
     return {
       ...base,
       status: "FAILED",
@@ -609,7 +695,7 @@ var ReactPlaythroughReporter = class {
     } else {
       console.log(output);
     }
-    const summary = formatFailureSummary(
+    const summary = formatReactFailureSummary(
       testModules.map((module2) => toModuleResult(module2, this.projectRoot))
     );
     if (report.failsRun && summary[0] === "TEST_RESULT: PASS") {

package/dist/react/vitest-config.mjs

@@ -69,6 +69,29 @@ 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;
@@ -114,34 +137,55 @@ function describeMissingEvidence(evidence) {
   }
   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 createMetadata(waiverReason) {
+  return { version: 3, waiverReason, evidence: createEvidence() };
+}
 function definePlaythrough(element, run, playthroughOptions, waiverReason) {
   const reason = normalizePlaythroughWaiverReason(waiverReason);
   const metadata = createMetadata(reason);
   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;
     };
@@ -186,6 +230,9 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
                 playthroughOptions.observe,
                 "after-primary"
               );
+              afterPrimaryTrace = afterPrimaryObservation.formatted;
+            } else {
+              afterPrimaryTrace = sampleDomTrace();
             }
           }
         },
@@ -207,8 +254,10 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
                 playthroughOptions.observe,
                 "entered"
               );
+              enteredTrace = enteredObservation.formatted;
             } else {
               domTextAtEntered = document.body.textContent ?? "";
+              enteredTrace = sampleDomTrace();
             }
             evidence.checkpoints.push(kind);
             return;
@@ -231,11 +280,14 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
           evidence.checkpoints.push(kind);
         },
         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.'
@@ -251,15 +303,19 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
               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 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.'
-            );
+          } 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;
@@ -294,7 +350,15 @@ function definePlaythrough(element, run, playthroughOptions, 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);
       }
@@ -387,21 +451,41 @@ function errorLocation(value) {
   const match = value.match(/(?:^|\n)\s*at\s+(.*?\.(?:test|spec)\.[^\n]+:\d+:\d+)/);
   return match?.[1];
 }
+function failureTrace(test2) {
+  const annotations = test2.annotations();
+  let annotationTrace;
+  for (let index = annotations.length - 1; index >= 0; index -= 1) {
+    if (annotations[index].type === REACT_PLAYTHROUGH_TRACE_ANNOTATION) {
+      annotationTrace = annotations[index].message;
+      break;
+    }
+  }
+  const metadata = test2.meta().reactPlaythrough;
+  const trace = annotationTrace ?? (isMetadata(metadata) ? metadata.trace : void 0);
+  return trace ? truncateReporterLine(trace, 720) : void 0;
+}
+function truncateReporterLine(value, limit) {
+  const compact = stripVTControlCharacters(value).replace(/\s+/g, " ").trim();
+  if (compact.length <= limit) return compact;
+  return `${compact.slice(0, Math.max(0, limit - 1))}\u2026`;
+}
 function toModuleResult(module, projectRoot) {
   const tests = [...module.children.allTests()];
+  const moduleErrors = module.errors().map((error) => firstLine(error.message)).filter((message) => Boolean(message));
   const errors = [
-    ...module.errors().map((error) => firstLine(error.message)),
+    ...moduleErrors,
     ...tests.flatMap(
       (test2) => (test2.result().errors ?? []).map((error) => firstLine(error.message))
     )
   ].filter((message) => Boolean(message));
   const failures = tests.filter((test2) => test2.result().state === "failed").map((test2) => {
-    const raw = test2.result().errors?.[0]?.message ?? module.errors()[0]?.message ?? "Unknown failure";
+    const raw = test2.result().errors?.at(-1)?.message ?? module.errors()[0]?.message ?? "Unknown failure";
     return {
       test: test2.fullName,
       cause: firstLine(raw) ?? "Unknown failure",
       location: test2.location ? `${relative(projectRoot, module.moduleId).replaceAll("\\", "/")}:${test2.location.line}:${test2.location.column}` : errorLocation(raw),
-      hint: failureHint(raw)
+      hint: failureHint(raw),
+      trace: failureTrace(test2)
     };
   });
   if (failures.length === 0 && tests.length === 0 && module.errors().length > 0) {
@@ -417,11 +501,12 @@ function toModuleResult(module, projectRoot) {
     file: relative(projectRoot, module.moduleId).replaceAll("\\", "/"),
     state: module.state(),
     errors,
+    primaryError: moduleErrors[0] ?? failures[0]?.cause,
     tests: tests.map(toAuditInput),
     failures
   };
 }
-function formatFailureSummary(modules) {
+function formatReactFailureSummary(modules) {
   const failures = modules.flatMap(
     (module) => (module.failures ?? []).map((failure) => ({ ...failure, file: module.file }))
   );
@@ -431,6 +516,7 @@ function formatFailureSummary(modules) {
     lines.push(`FAILURE_${index + 1}: ${failure.file}`);
     lines.push(`TEST: ${failure.test}`);
     lines.push(`CAUSE: ${failure.cause}`);
+    if (failure.trace) lines.push(`TRACE: ${failure.trace}`);
     if (failure.location) lines.push(`AT: ${failure.location}`);
     if (failure.hint) lines.push(`HINT: ${failure.hint}`);
   }
@@ -505,7 +591,7 @@ function assessReactPlaythroughReport(input) {
   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] ?? "The production playthrough did not leave complete gameplay evidence.";
+    const cause = productionModule.primaryError ?? productionModule.errors[0] ?? input.unhandledErrors?.[0] ?? audit.issues[0] ?? "The production playthrough did not leave complete gameplay evidence.";
     return {
       ...base,
       status: "FAILED",
@@ -575,7 +661,7 @@ var ReactPlaythroughReporter = class {
     } else {
       console.log(output);
     }
-    const summary = formatFailureSummary(
+    const summary = formatReactFailureSummary(
       testModules.map((module) => toModuleResult(module, this.projectRoot))
     );
     if (report.failsRun && summary[0] === "TEST_RESULT: PASS") {

package/package.json

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