miaoda-game-devkit 0.4.0 → 0.6.0

package/dist/react/testing.mjs

@@ -60,6 +60,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 {
@@ -88,11 +95,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);
@@ -113,13 +122,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 sampleObservation(observe, stage) {
+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);
+}
+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();
@@ -129,222 +160,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) => {
@@ -352,19 +433,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(
@@ -373,13 +464,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.`
@@ -389,9 +478,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)}.`
         );
       }
     }