miaoda-game-devkit 0.4.0 → 0.6.0

package/dist/react/vitest-config.mjs

@@ -15,6 +15,13 @@ import { test } from "vitest";
 
 // src/react/react-playthrough-core.ts
 import { act } from "@testing-library/react";
+function throwIfAborted(signal) {
+  if (!signal?.aborted) return;
+  if (signal.reason instanceof Error) throw signal.reason;
+  throw new Error("Playthrough advancement was cancelled.", {
+    cause: signal.reason
+  });
+}
 function formatDiagnostics(read) {
   if (!read) return void 0;
   try {
@@ -43,11 +50,13 @@ async function runBoundedUntil(condition, options = {}) {
     );
   }
   for (let step = 0; step <= maxSteps; step += 1) {
+    throwIfAborted(options.signal);
     if (condition()) return step;
     if (step < maxSteps) {
       await act(async () => {
         await options.step?.(step + 1);
       });
+      throwIfAborted(options.signal);
     }
   }
   const diagnostics = formatDiagnostics(options.diagnostics);
@@ -68,13 +77,35 @@ var INPUT_EVENTS = [
   "touchstart",
   "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)`;
+var MIN_STAGES = 5;
+var MIN_MILESTONES = 3;
+var MAX_TRACE_VALUE_LENGTH = 140;
+var MAX_TRACE_LENGTH = 720;
+var REACT_PLAYTHROUGH_TRACE_ANNOTATION = "miaoda:react-playthrough-trace";
+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 = trace.stages.map(
+    (stage) => `${stage.kind}:${stage.name}=${truncateTraceValue(stage.state, MAX_TRACE_VALUE_LENGTH)}`
+  );
+  if (trace.current) {
+    stages.push(
+      `current:${trace.current.name}=${truncateTraceValue(trace.current.before, 70)}\u2192${truncateTraceValue(trace.current.last, 70)}`
+    );
+  }
+  const step = trace.step ? `stepUntil=${trace.step.completed ?? "failed"}/${trace.step.bound}` : void 0;
+  const formatted = `${stages.length > 0 ? stages.join(" -> ") : "stages=none"}${step ? `; ${step}` : ""}`;
+  return truncateTraceValue(formatted, MAX_TRACE_LENGTH);
 }
-function sampleObservation(observe, stage) {
+var MAX_FORMATTED_STATE_LENGTH = 500;
+function formatState(fingerprint) {
+  if (fingerprint.length <= MAX_FORMATTED_STATE_LENGTH) return fingerprint;
+  return `${fingerprint.slice(0, MAX_FORMATTED_STATE_LENGTH)}\u2026 (${fingerprint.length} chars)`;
+}
+function sampleObservedState(observe, stage) {
   let value;
   try {
     value = observe();
@@ -84,222 +115,272 @@ function sampleObservation(observe, stage) {
   try {
     const fingerprint = JSON.stringify(value);
     if (fingerprint === void 0) throw new Error("unsupported value");
-    return { fingerprint, formatted: formatObservation(fingerprint) };
+    return { fingerprint, formatted: formatState(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 sampleDomState(view) {
+  const fingerprint = view.container.innerHTML.replace(/\s+/g, " ").trim();
+  return { fingerprint, formatted: formatState(JSON.stringify(fingerprint)) };
+}
+function createEvidence() {
+  return { domInputEvents: 0, stages: [], verified: false };
+}
+function createMetadata(waiverReason) {
+  return { version: 4, waiverReason, evidence: createEvidence() };
+}
+function stageLabel(kind, name) {
+  return kind === "entered" ? "entered" : `${kind}(${JSON.stringify(name)})`;
 }
 function describeMissingEvidence(evidence) {
-  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 "a bounded stepUntil call";
-  if (evidence.assertionsAfterOutcome === 0)
-    return "an outcome assertion after stepUntil";
-  if (evidence.checkpoints.length < MIN_CHECKPOINTS)
-    return `at least ${MIN_CHECKPOINTS} checkpoints`;
-  if (!evidence.checkpoints.some(
-    (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
-  )) {
-    return "progress/terminal checkpoint";
+  if (!evidence || evidence.stages.length === 0) return "an enter stage";
+  if (evidence.stages[0]?.kind !== "entered") return "the entered stage";
+  const milestones = evidence.stages.filter(
+    (stage) => stage.kind === "milestone"
+  );
+  if (milestones.length < MIN_MILESTONES) {
+    return `at least ${MIN_MILESTONES} gameplay milestones`;
+  }
+  const finalStage = evidence.stages.at(-1);
+  if (finalStage?.kind !== "progress" && finalStage?.kind !== "terminal") {
+    return "a progress or terminal finish stage";
+  }
+  if (evidence.stages.length < MIN_STAGES) {
+    return `at least ${MIN_STAGES} evidenced stages`;
   }
   return "a complete playthrough verification marker";
 }
-function createMetadata(waiverReason) {
-  return {
-    version: 3,
-    waiverReason,
-    evidence: {
-      domInputEvents: 0,
-      entryInputs: 0,
-      primaryInputs: 0,
-      boundedRuns: 0,
-      assertionsAfterOutcome: 0,
-      checkpoints: [],
-      verified: false
-    }
-  };
-}
 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 }) => {
-    const evidence = metadata.evidence;
-    let assertionsAtOutcome;
-    let enteredRecorded = false;
-    let domTextAtEntered;
-    let enteredObservation;
-    let afterPrimaryObservation;
-    const recordInput = () => {
-      evidence.domInputEvents += 1;
-    };
-    for (const event of INPUT_EVENTS) {
-      document.addEventListener(event, recordInput, true);
-    }
-    try {
-      const view = render(element);
-      if (view.container.childNodes.length === 0) {
-        throw new Error(
-          "playthroughTest must render the production game entry."
-        );
+  test(
+    "production game completes a bounded playthrough",
+    {
+      concurrent: false,
+      skip: Boolean(reason),
+      meta: { reactPlaythrough: metadata }
+    },
+    async ({ annotate, expect, onTestFailed, signal }) => {
+      metadata.evidence = createEvidence();
+      metadata.trace = void 0;
+      const evidence = metadata.evidence;
+      let entered = false;
+      let finished = false;
+      let activeStage;
+      let lastSample;
+      let stepTrace;
+      let failureTraceFactory;
+      let acceptingStageInput = false;
+      let inputCaptureAttached = false;
+      const recordInput = () => {
+        if (acceptingStageInput) evidence.domInputEvents += 1;
+      };
+      const stopInputCapture = () => {
+        acceptingStageInput = false;
+        if (!inputCaptureAttached) return;
+        inputCaptureAttached = false;
+        for (const event of INPUT_EVENTS) {
+          document.removeEventListener(event, recordInput, true);
+        }
+      };
+      const captureFailureTrace = () => {
+        try {
+          return failureTraceFactory?.() ?? "stages=none";
+        } catch {
+          return "stages=none";
+        }
+      };
+      onTestFailed(() => {
+        metadata.trace ??= captureFailureTrace();
+      });
+      for (const event of INPUT_EVENTS) {
+        document.addEventListener(event, recordInput, true);
       }
-      const user = userEvent.setup();
-      await run({
-        view,
-        user,
-        expect,
-        async performInput(kind, input) {
-          if (kind === "entry" && enteredRecorded) {
+      inputCaptureAttached = true;
+      signal.addEventListener("abort", stopInputCapture, { once: true });
+      try {
+        const view = render(element);
+        if (view.container.childNodes.length === 0) {
+          throw new Error(
+            "playthroughTest must render the production game entry."
+          );
+        }
+        const user = userEvent.setup();
+        const sampleState = (label) => playthroughOptions?.observe ? sampleObservedState(playthroughOptions.observe, label) : sampleDomState(view);
+        lastSample = sampleState("initial render");
+        failureTraceFactory = () => formatReactPlaythroughFailureTrace({
+          stages: evidence.stages.map((stage) => ({
+            name: stage.name,
+            kind: stage.kind,
+            state: stage.after
+          })),
+          current: activeStage ? {
+            name: stageLabel(activeStage.kind, activeStage.name),
+            before: activeStage.before.formatted,
+            last: (() => {
+              try {
+                return sampleState("failure").formatted;
+              } catch (error) {
+                return `<state unavailable: ${String(error)}>`;
+              }
+            })()
+          } : void 0,
+          step: stepTrace
+        });
+        const executeStage = async (name, kind, stage) => {
+          const normalizedName = name.trim();
+          if (normalizedName.length === 0) {
+            throw new Error("playthrough stage names must be non-empty strings.");
+          }
+          if (evidence.stages.some(
+            (completed) => completed.name === normalizedName
+          )) {
             throw new Error(
-              'performInput("entry") must run before checkpoint("entered"). Group multiple setup actions in the same callback.'
+              `playthrough stage ${JSON.stringify(normalizedName)} may only be recorded once.`
             );
           }
-          if (kind === "primary" && !enteredRecorded) {
+          if (kind === "milestone" && ["entered", "progress", "terminal"].includes(normalizedName)) {
             throw new Error(
-              'Before performInput("primary"), run an entry input and checkpoint("entered").'
+              `milestone name ${JSON.stringify(normalizedName)} is reserved; use a game-domain name such as "first-point" or "boss-entered".`
             );
           }
-          const inputsBefore = evidence.domInputEvents;
-          await input();
-          if (evidence.domInputEvents === inputsBefore) {
+          const before = lastSample ?? sampleState(`before ${normalizedName}`);
+          activeStage = { name: normalizedName, kind, before };
+          stepTrace = { bound: stage.maxSteps ?? 120 };
+          if (stage.until()) {
             throw new Error(
-              `performInput("${kind}") did not dispatch a supported production DOM input. Use the provided user or dispatch a real keyboard, pointer, or touch event to the production target.`
+              `${stageLabel(kind, normalizedName)} until condition must be false before its driver runs. Wait for a result caused by this stage, not state left by an earlier stage.`
             );
           }
-          if (kind === "entry") evidence.entryInputs += 1;
-          else {
-            evidence.primaryInputs += 1;
-            if (playthroughOptions?.observe) {
-              afterPrimaryObservation = sampleObservation(
-                playthroughOptions.observe,
-                "after-primary"
-              );
-            }
-          }
-        },
-        checkpoint(kind) {
-          if (kind === "entered") {
-            if (enteredRecorded) {
-              throw new Error(
-                'checkpoint("entered") may only be recorded once, before the primary input.'
-              );
+          const inputsBefore = evidence.domInputEvents;
+          if (stage.act) {
+            acceptingStageInput = true;
+            try {
+              await stage.act();
+            } finally {
+              acceptingStageInput = false;
             }
-            if (evidence.entryInputs === 0) {
+            if (evidence.domInputEvents === inputsBefore) {
               throw new Error(
-                'checkpoint("entered") must follow performInput("entry", ...).'
-              );
-            }
-            enteredRecorded = true;
-            if (playthroughOptions?.observe) {
-              enteredObservation = sampleObservation(
-                playthroughOptions.observe,
-                "entered"
+                `${stageLabel(kind, normalizedName)} act did not dispatch a supported production DOM input. Use the provided user to click, type, press, point, or touch the production target; do not call Controller commands directly.`
               );
-            } else {
-              domTextAtEntered = document.body.textContent ?? "";
             }
-            evidence.checkpoints.push(kind);
-            return;
           }
-          if (evidence.primaryInputs === 0) {
+          let advancedSteps = 0;
+          const stepBound = stage.maxSteps ?? 120;
+          stepTrace = { bound: stepBound };
+          const steps = await runBoundedUntil(stage.until, {
+            maxSteps: stage.maxSteps,
+            signal,
+            diagnostics: stage.diagnostics ?? playthroughOptions?.observe,
+            step: stage.step ? async (step) => {
+              advancedSteps += 1;
+              await stage.step?.(step);
+            } : void 0
+          });
+          stepTrace = { bound: stepBound, completed: steps };
+          if (!stage.act && advancedSteps === 0) {
             throw new Error(
-              `checkpoint("${kind}") must follow performInput("primary", ...).`
+              `${stageLabel(kind, normalizedName)} did not execute its deterministic step. Autonomous stages must advance production time or frames at least once.`
             );
           }
-          if (evidence.boundedRuns === 0) {
+          const assertionsBefore = expect.getState().assertionCalls;
+          await stage.assert({ expect, user, view });
+          const assertions = expect.getState().assertionCalls - assertionsBefore;
+          if (assertions === 0) {
             throw new Error(
-              `checkpoint("${kind}") must be recorded after stepUntil returns.`
+              `${stageLabel(kind, normalizedName)} assert must call the expect provided by playthroughTest at least once.`
             );
           }
-          if (assertionsAtOutcome === void 0 || expect.getState().assertionCalls <= assertionsAtOutcome) {
+          const after = sampleState(`after ${normalizedName}`);
+          if (after.fingerprint === before.fingerprint) {
+            const source = playthroughOptions?.observe ? "authoritative observe() state" : "production DOM";
             throw new Error(
-              `Use the expect provided by playthroughTest to assert the authoritative result after stepUntil, then record checkpoint("${kind}").`
+              `${stageLabel(kind, normalizedName)} did not change the ${source} from the previous stage. Each milestone must prove a new gameplay result.`
             );
           }
-          evidence.checkpoints.push(kind);
-        },
-        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.'
-              );
+          evidence.stages.push({
+            name: normalizedName,
+            kind,
+            domInputEvents: evidence.domInputEvents - inputsBefore,
+            advancedSteps,
+            assertions,
+            stateChanged: true,
+            before: before.formatted,
+            after: after.formatted
+          });
+          lastSample = after;
+          activeStage = void 0;
+        };
+        await run({
+          view,
+          user,
+          async enter(stage) {
+            if (entered) {
+              throw new Error("enter may only be called once.");
             }
-            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)}`
-              );
+            if (evidence.stages.length > 0) {
+              throw new Error("enter must be the first playthrough stage.");
             }
-          } 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.'
-            );
+            await executeStage("entered", "entered", stage);
+            entered = true;
+          },
+          async milestone(name, stage) {
+            if (!entered) {
+              throw new Error("milestone must follow enter.");
+            }
+            if (finished) {
+              throw new Error("milestone cannot run after finish.");
+            }
+            await executeStage(name, "milestone", stage);
+          },
+          async finish(name, stage) {
+            if (!entered) throw new Error("finish must follow enter.");
+            if (finished) {
+              throw new Error("finish may only be called once.");
+            }
+            await executeStage(name, stage.kind, stage);
+            finished = true;
           }
-          evidence.boundedRuns += 1;
-          assertionsAtOutcome = expect.getState().assertionCalls;
-          return steps;
-        }
-      });
-      const assertionCalls = expect.getState().assertionCalls;
-      evidence.assertionsAfterOutcome = assertionsAtOutcome === void 0 ? 0 : assertionCalls - assertionsAtOutcome;
-      if (evidence.entryInputs === 0) {
-        throw new Error(
-          'playthroughTest must perform an entry input with performInput("entry", ...).'
-        );
-      }
-      if (evidence.primaryInputs === 0) {
-        throw new Error(
-          'playthroughTest must perform a core game action with performInput("primary", ...).'
+        });
+        const milestones = evidence.stages.filter(
+          (stage) => stage.kind === "milestone"
         );
-      }
-      if (evidence.boundedRuns === 0) {
-        throw new Error("playthroughTest must complete one bounded stepUntil.");
-      }
-      if (evidence.assertionsAfterOutcome === 0) {
-        throw new Error(
-          "Use the expect provided by playthroughTest to assert an authoritative game outcome after stepUntil returns."
-        );
-      }
-      if (evidence.checkpoints.length < MIN_CHECKPOINTS || !evidence.checkpoints.some(
-        (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
-      )) {
-        throw new Error(
-          `playthroughTest requires at least ${MIN_CHECKPOINTS} checkpoints: checkpoint("entered") and, after asserting the result, checkpoint("progress") or checkpoint("terminal").`
-        );
-      }
-      evidence.verified = true;
-    } finally {
-      for (const event of INPUT_EVENTS) {
-        document.removeEventListener(event, recordInput, true);
+        if (!entered) throw new Error("playthroughTest must call enter once.");
+        if (milestones.length < MIN_MILESTONES) {
+          throw new Error(
+            `playthroughTest requires at least ${MIN_MILESTONES} named gameplay milestones between enter and finish; received ${milestones.length}.`
+          );
+        }
+        if (!finished) {
+          throw new Error(
+            'playthroughTest must call finish with kind "progress" or "terminal".'
+          );
+        }
+        if (evidence.stages.length < MIN_STAGES) {
+          throw new Error(
+            `playthroughTest requires at least ${MIN_STAGES} evidenced stages: enter, ${MIN_MILESTONES} named milestones, and finish.`
+          );
+        }
+        evidence.verified = true;
+      } catch (error) {
+        const trace = captureFailureTrace();
+        metadata.trace = trace;
+        try {
+          await annotate(trace, REACT_PLAYTHROUGH_TRACE_ANNOTATION);
+        } catch {
+        }
+        throw error;
+      } finally {
+        metadata.trace ??= failureTraceFactory?.();
+        signal.removeEventListener("abort", stopInputCapture);
+        stopInputCapture();
       }
     }
-  });
+  );
 }
 var playthroughTest = Object.assign(
   (element, optionsOrRun, maybeRun) => {
@@ -307,19 +388,29 @@ var playthroughTest = Object.assign(
       definePlaythrough(element, optionsOrRun);
       return;
     }
-    if (!maybeRun) throw new TypeError("playthroughTest requires a run callback.");
+    if (!maybeRun) {
+      throw new TypeError("playthroughTest requires a run callback.");
+    }
     definePlaythrough(element, maybeRun, optionsOrRun);
   },
   {
-    skip: (reason, element, run) => definePlaythrough(element, run, void 0, reason)
+    skip: (reason, element) => definePlaythrough(element, async () => {
+    }, void 0, reason)
   }
 );
 function auditReactPlaythroughRun(tests) {
   const declared = tests.filter((candidate) => candidate.metadata);
   const valid = declared.filter(({ state, metadata }) => {
     const evidence = metadata?.evidence;
-    return state === "passed" && evidence?.verified === true && evidence.domInputEvents > 0 && evidence.entryInputs > 0 && evidence.primaryInputs > 0 && evidence.boundedRuns > 0 && evidence.assertionsAfterOutcome > 0 && evidence.checkpoints.length >= MIN_CHECKPOINTS && evidence.checkpoints.includes("entered") && evidence.checkpoints.some(
-      (checkpoint) => checkpoint === "progress" || checkpoint === "terminal"
+    if (!evidence || state !== "passed" || evidence.verified !== true) {
+      return false;
+    }
+    const milestones = evidence.stages.filter(
+      (stage) => stage.kind === "milestone"
+    );
+    const finalStage = evidence.stages.at(-1);
+    return evidence.domInputEvents > 0 && evidence.stages.length >= MIN_STAGES && evidence.stages[0]?.kind === "entered" && milestones.length >= MIN_MILESTONES && (finalStage?.kind === "progress" || finalStage?.kind === "terminal") && evidence.stages.every(
+      (stage) => stage.assertions > 0 && (stage.domInputEvents > 0 || stage.advancedSteps > 0) && stage.stateChanged === true
     );
   });
   const waivers = declared.filter(
@@ -328,13 +419,11 @@ function auditReactPlaythroughRun(tests) {
   const issues = [];
   if (declared.length === 0) {
     issues.push(
-      '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").'
+      "No production gameplay verification was declared. Use playthroughTest to render <App />, then compose one real-input enter stage, at least three named milestones, and finish. Later stages may drive production input or deterministic advancement; every stage must reach and assert a bounded new result."
     );
   } else {
     for (const candidate of declared) {
-      const isValid = valid.includes(candidate);
-      const isWaived = waivers.includes(candidate);
-      if (isValid || isWaived) continue;
+      if (valid.includes(candidate) || waivers.includes(candidate)) continue;
       if (candidate.state === "skipped") {
         issues.push(
           `Playthrough ${JSON.stringify(candidate.name)} was skipped without an explicit reason of at least 20 characters.`
@@ -344,9 +433,8 @@ function auditReactPlaythroughRun(tests) {
           `Playthrough ${JSON.stringify(candidate.name)} finished with state ${candidate.state}.`
         );
       } else {
-        const missing = describeMissingEvidence(candidate.metadata?.evidence);
         issues.push(
-          `Playthrough ${JSON.stringify(candidate.name)} is missing ${missing}.`
+          `Playthrough ${JSON.stringify(candidate.name)} is missing ${describeMissingEvidence(candidate.metadata?.evidence)}.`
         );
       }
     }
@@ -362,7 +450,12 @@ var PRODUCTION_PLAYTHROUGH_FILE = "tests/production-playthrough.test.tsx";
 function isMetadata(value) {
   if (!value || typeof value !== "object") return false;
   const metadata = value;
-  return metadata.version === 3 && Boolean(metadata.evidence);
+  if (metadata.version !== 4) return false;
+  const evidence = metadata.evidence;
+  if (!evidence || typeof evidence !== "object") return false;
+  return typeof evidence.domInputEvents === "number" && Array.isArray(evidence.stages) && typeof evidence.verified === "boolean" && evidence.stages.every(
+    (stage) => Boolean(stage) && typeof stage === "object" && typeof stage.name === "string" && typeof stage.kind === "string" && typeof stage.domInputEvents === "number" && typeof stage.advancedSteps === "number" && typeof stage.assertions === "number" && typeof stage.stateChanged === "boolean" && typeof stage.before === "string" && typeof stage.after === "string"
+  );
 }
 function toAuditInput(test2) {
   const metadata = test2.meta().reactPlaythrough;
@@ -384,24 +477,46 @@ function failureHint(value) {
   return `Available button names: ${names.map((name) => JSON.stringify(name)).join(", ")}`;
 }
 function errorLocation(value) {
-  const match = value.match(/(?:^|\n)\s*at\s+(.*?\.(?:test|spec)\.[^\n]+:\d+:\d+)/);
+  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,13 +532,17 @@ 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 }))
+    (module) => (module.failures ?? []).map((failure) => ({
+      ...failure,
+      file: module.file
+    }))
   );
   if (failures.length === 0) return ["TEST_RESULT: PASS"];
   const lines = [`FAILED_TESTS: ${failures.length}`];
@@ -431,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}`);
   }
@@ -441,24 +561,22 @@ function repairGuidance(cause) {
   if (/snapshot\(\) returned the same reference/i.test(cause)) {
     return "The game mutated state without publishing a new snapshot reference, so React skipped the render after an Object.is comparison. Publish a new top-level object before notifying subscribers, for example cachedSnapshot = { ...state }, and never expose a mutable internal object as the snapshot.";
   }
-  if (/(?:already true|found the outcome) at step 0.*DOM has not changed/i.test(
-    cause
-  )) {
-    return 'Make the stepUntil condition false at checkpoint("entered"). Verify that the primary input reaches the production control, then wait for a post-input outcome such as a changed score, a removed entry overlay, a completed turn, or a result screen. For Canvas or Controller state outside the DOM, declare observe once on playthroughTest and return the read-only production Telemetry snapshot.';
+  if (/until condition must be false before its driver runs/i.test(cause)) {
+    return "Make this stage's until condition describe a new result that does not exist before act or step runs. Do not reuse state completed by an earlier milestone.";
   }
-  if (/authoritative observation did not change/i.test(cause)) {
-    return "The flow reached its condition while observe still returned the same authoritative state. Make observe read the same production Controller that React renders, verify the primary input changes that Controller, and wait for a post-input result. Inspect the Timeline values to locate the disconnected stage.";
+  if (/did not change the (?:authoritative observe\(\) state|production DOM)/i.test(cause)) {
+    return "The stage ran and asserted, but its observable state matched the previous milestone. Wait for a genuinely new gameplay result. Canvas or Controller games should make observe read the same production Controller that React renders.";
   }
   if (/No step callback was provided/i.test(cause)) {
-    return "This flow is driven by time or frames, but stepUntil did not advance the game clock. Inject the devkit GameClock into the production game and pass step: () => clock.stepFrame(). Do not replace deterministic advancement with a real setTimeout.";
+    return "This stage is driven by time or frames, but it did not advance the game clock. Inject the devkit GameClock into the production game and pass step: () => clock.stepFrame(). Do not replace deterministic advancement with a real setTimeout.";
   }
   if (/outcome was not reached within \d+ steps/i.test(cause)) {
-    return "The real input was dispatched, but gameplay did not reach the outcome within the bound. Confirm that the production control received the input, then inspect Last diagnostics to determine whether the game loop, rule state, or UI synchronization failed to advance.";
+    return "The stage driver ran, but gameplay did not reach the outcome within the bound. Confirm that its production input or deterministic step changed the intended rule state, then inspect Last diagnostics to locate the stalled stage.";
   }
-  if (/performInput|checkpoint/.test(cause)) {
-    return 'Complete the evidence sequence in order: performInput("entry"), checkpoint("entered"), performInput("primary"), bounded stepUntil, an authoritative result assertion using the provided expect, then checkpoint("progress") or checkpoint("terminal").';
+  if (/enter|milestone|finish|stage| act | assert /.test(cause)) {
+    return "Compose one enter stage, at least three named gameplay milestones, and one finish stage. Enter must drive real DOM input; each later stage must drive input or deterministic steps. Every stage waits for a bounded new result and asserts it with the provided expect.";
   }
-  return "Start from the production entry, dispatch real DOM input, and use stepUntil to reach a bounded player-visible or authoritative game outcome before asserting it. Do not jump to an internal level or mutate gameplay state.";
+  return "Start from the production entry and describe the real game as enter, named milestones, and finish. Enter must act through production input; later stages may act or step. Every stage waits for and asserts a new player-visible or authoritative result. Do not jump to an internal level or mutate gameplay state.";
 }
 function assessReactPlaythroughReport(input) {
   const base = { file: input.expectedFile };
@@ -475,7 +593,7 @@ function assessReactPlaythroughReport(input) {
       ...base,
       status: "FAILED",
       cause: "The required production playthrough test file does not exist.",
-      next: 'Create the file and render <App />. Drive a legal entry with performInput("entry"), record checkpoint("entered"), perform a core game action with performInput("primary"), and use a bounded stepUntil. Assert the authoritative result with the provided expect, then record checkpoint("progress") or checkpoint("terminal").',
+      next: "Create the file and render <App />. Compose one real-input enter stage, at least three named gameplay milestones, and one finish stage. Later stages may drive production input or deterministic advancement; every stage must reach and assert a bounded new result.",
       failsRun: true
     };
   }
@@ -502,10 +620,10 @@ function assessReactPlaythroughReport(input) {
       failsRun: true
     };
   }
-  const tests = input.modules.flatMap((module) => module.tests);
+  const tests = productionModule.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 +693,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") {