miaoda-game-devkit 0.6.1 → 0.6.3

package/dist/react/testing.mjs

@@ -58,14 +58,112 @@ import { render } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { test } from "vitest";
 
+// src/react/react-error-diagnostics.ts
+var MAX_DIAGNOSTIC_LENGTH = 1e3;
+function truncate(value) {
+  const trimmed = value.trim();
+  if (trimmed.length <= MAX_DIAGNOSTIC_LENGTH) return trimmed;
+  return `${trimmed.slice(0, MAX_DIAGNOSTIC_LENGTH - 1)}\u2026`;
+}
+function safeJson(value) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  try {
+    return JSON.stringify(value, (_key, nested) => {
+      if (typeof nested === "bigint") return `${nested}n`;
+      if (typeof nested === "function") {
+        return `Function<${nested.name || "anonymous"}>`;
+      }
+      if (typeof nested === "symbol") return nested.toString();
+      if (nested && typeof nested === "object") {
+        if (seen.has(nested)) return "[Circular]";
+        seen.add(nested);
+      }
+      return nested;
+    });
+  } catch {
+    return void 0;
+  }
+}
+function collectEntries(value, fallbackCode, seen) {
+  if (typeof value === "string") {
+    return value.trim() ? [{ code: fallbackCode, message: truncate(value) }] : [];
+  }
+  if (value === null || value === void 0 || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint" || typeof value === "symbol") {
+    return [{ code: fallbackCode, message: String(value) }];
+  }
+  if (typeof value === "function") {
+    return [
+      { code: fallbackCode, message: `Function<${value.name || "anonymous"}>` }
+    ];
+  }
+  if (seen.has(value)) return [];
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => collectEntries(item, fallbackCode, seen));
+  }
+  const record = value;
+  const code = typeof record.code === "string" && record.code.trim() ? record.code.trim() : fallbackCode;
+  const entries = [];
+  if (typeof record.message === "string" && record.message.trim()) {
+    entries.push({ code, message: truncate(record.message) });
+  }
+  if (record.cause !== void 0) {
+    entries.push(...collectEntries(record.cause, fallbackCode, seen));
+  }
+  if (Array.isArray(record.errors)) {
+    entries.push(...collectEntries(record.errors, fallbackCode, seen));
+  }
+  if (entries.length > 0) return entries;
+  if (typeof record.stack === "string" && record.stack.trim()) {
+    return [{ code, message: truncate(record.stack) }];
+  }
+  const json = safeJson(value);
+  return json && json !== "{}" ? [{ code, message: truncate(json) }] : [];
+}
+function extractFailureEntries(value, fallbackCode = "TEST_FAILURE") {
+  const entries = collectEntries(value, fallbackCode, /* @__PURE__ */ new WeakSet());
+  const keys = /* @__PURE__ */ new Set();
+  return entries.filter((entry) => {
+    const key = `${entry.code}\0${entry.message}`;
+    if (keys.has(key)) return false;
+    keys.add(key);
+    return true;
+  });
+}
+function createFailureDiagnostic(source, value) {
+  return { source, entries: extractFailureEntries(value) };
+}
+function appendCurrentAttemptFailures(current, runnerValue) {
+  const runner = createFailureDiagnostic("test-runtime", runnerValue);
+  if (!current || current.entries.length === 0) return runner;
+  const primary = current.entries[0];
+  const currentStart = runner.entries.findIndex(
+    (entry) => entry.code === primary.code && entry.message === primary.message
+  );
+  if (currentStart < 0) return current;
+  return {
+    source: current.source,
+    entries: extractFailureEntries([
+      ...current.entries,
+      ...runner.entries.slice(currentStart + 1)
+    ])
+  };
+}
+function codedError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
 // 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
-  });
+  throw codedError(
+    "PLAYTHROUGH_CANCELLED",
+    `Playthrough advancement was cancelled. Cause: ${String(signal.reason)}`
+  );
 }
 function formatDiagnostics(read) {
   if (!read) return void 0;
@@ -81,7 +179,8 @@ function normalizePlaythroughWaiverReason(waiverReason) {
   if (waiverReason === void 0) return void 0;
   const reason = waiverReason.trim();
   if (reason.length < 20) {
-    throw new Error(
+    throw codedError(
+      "INVALID_PLAYTHROUGH_WAIVER",
       "playthroughTest.skip reason must contain at least 20 characters."
     );
   }
@@ -90,7 +189,8 @@ function normalizePlaythroughWaiverReason(waiverReason) {
 async function runBoundedUntil(condition, options = {}) {
   const maxSteps = options.maxSteps ?? 120;
   if (!Number.isSafeInteger(maxSteps) || maxSteps < 0 || maxSteps > 1e4) {
-    throw new RangeError(
+    throw codedError(
+      "INVALID_STEP_BOUND",
       "stepUntil maxSteps must be a safe integer between 0 and 10000."
     );
   }
@@ -107,7 +207,8 @@ async function runBoundedUntil(condition, options = {}) {
   const diagnostics = formatDiagnostics(options.diagnostics);
   const guidance = options.step ? "The step callback ran, but the authoritative outcome did not change." : "No step callback was provided, so time-driven gameplay was not advanced. Inject a ManualGameClock for this test and pass step: () => clock.stepFrame().";
   const suffix = diagnostics ? ` Last diagnostics: ${diagnostics}` : "";
-  throw new Error(
+  throw codedError(
+    options.step ? "PLAYTHROUGH_BOUND_EXHAUSTED" : "PLAYTHROUGH_CLOCK_NOT_ADVANCED",
     `Playthrough outcome was not reached within ${maxSteps} steps. ${guidance}${suffix}`
   );
 }
@@ -126,6 +227,11 @@ var MIN_STAGES = 5;
 var MIN_MILESTONES = 3;
 var MAX_TRACE_VALUE_LENGTH = 140;
 var MAX_TRACE_LENGTH = 720;
+function eventTargetsCanvas(event) {
+  const path = typeof event.composedPath === "function" ? event.composedPath() : [];
+  if (path.some((target) => target instanceof HTMLCanvasElement)) return true;
+  return event.target instanceof HTMLCanvasElement;
+}
 var REACT_PLAYTHROUGH_TRACE_ANNOTATION = "miaoda:react-playthrough-trace";
 function truncateTraceValue(value, limit) {
   const compact = value.replace(/\s+/g, " ").trim();
@@ -155,14 +261,18 @@ function sampleObservedState(observe, stage) {
   try {
     value = observe();
   } catch (error) {
-    throw new Error(`observe() threw at ${stage}: ${String(error)}`);
+    throw codedError(
+      "OBSERVE_FAILED",
+      `observe() threw at ${stage}: ${String(error)}`
+    );
   }
   try {
     const fingerprint = JSON.stringify(value);
     if (fingerprint === void 0) throw new Error("unsupported value");
     return { fingerprint, formatted: formatState(fingerprint) };
   } catch {
-    throw new Error(
+    throw codedError(
+      "OBSERVE_NOT_SERIALIZABLE",
       `observe() must return JSON-serializable read-only state; sampling failed at ${stage}.`
     );
   }
@@ -175,7 +285,7 @@ function createEvidence() {
   return { domInputEvents: 0, stages: [], verified: false };
 }
 function createMetadata(waiverReason) {
-  return { version: 4, waiverReason, evidence: createEvidence() };
+  return { version: 5, waiverReason, evidence: createEvidence() };
 }
 function stageLabel(kind, name) {
   return kind === "entered" ? "entered" : `${kind}(${JSON.stringify(name)})`;
@@ -211,6 +321,7 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
     async ({ annotate, expect, onTestFailed, signal }) => {
       metadata.evidence = createEvidence();
       metadata.trace = void 0;
+      metadata.failure = void 0;
       const evidence = metadata.evidence;
       let entered = false;
       let finished = false;
@@ -219,9 +330,12 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
       let stepTrace;
       let failureTraceFactory;
       let acceptingStageInput = false;
+      let activeStageTargetedCanvas = false;
       let inputCaptureAttached = false;
-      const recordInput = () => {
-        if (acceptingStageInput) evidence.domInputEvents += 1;
+      const recordInput = (event) => {
+        if (!acceptingStageInput) return;
+        evidence.domInputEvents += 1;
+        activeStageTargetedCanvas ||= eventTargetsCanvas(event);
       };
       const stopInputCapture = () => {
         acceptingStageInput = false;
@@ -238,8 +352,12 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
           return "stages=none";
         }
       };
-      onTestFailed(() => {
+      onTestFailed(({ task }) => {
         metadata.trace ??= captureFailureTrace();
+        metadata.failure = appendCurrentAttemptFailures(
+          metadata.failure,
+          task.result?.errors ?? []
+        );
       });
       for (const event of INPUT_EVENTS) {
         document.addEventListener(event, recordInput, true);
@@ -249,7 +367,8 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
       try {
         const view = render(element);
         if (view.container.childNodes.length === 0) {
-          throw new Error(
+          throw codedError(
+            "PRODUCTION_ENTRY_NOT_RENDERED",
             "playthroughTest must render the production game entry."
           );
         }
@@ -278,29 +397,42 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
         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.");
+            throw codedError(
+              "INVALID_STAGE_NAME",
+              "playthrough stage names must be non-empty strings."
+            );
           }
           if (evidence.stages.some(
             (completed) => completed.name === normalizedName
           )) {
-            throw new Error(
+            throw codedError(
+              "DUPLICATE_STAGE_NAME",
               `playthrough stage ${JSON.stringify(normalizedName)} may only be recorded once.`
             );
           }
           if (kind === "milestone" && ["entered", "progress", "terminal"].includes(normalizedName)) {
-            throw new Error(
+            throw codedError(
+              "RESERVED_STAGE_NAME",
               `milestone name ${JSON.stringify(normalizedName)} is reserved; use a game-domain name such as "first-point" or "boss-entered".`
             );
           }
           const before = lastSample ?? sampleState(`before ${normalizedName}`);
           activeStage = { name: normalizedName, kind, before };
           stepTrace = { bound: stage.maxSteps ?? 120 };
+          if (stage.step && !playthroughOptions?.observe) {
+            throw codedError(
+              "AUTHORITATIVE_OBSERVE_REQUIRED_FOR_STEP",
+              `${stageLabel(kind, normalizedName)} uses deterministic step advancement without an authoritative observe callback. Time- or frame-driven stages must observe the same production Controller that <App /> renders through Telemetry; DOM labels alone are not deterministic gameplay state.`
+            );
+          }
           if (stage.until()) {
-            throw new Error(
+            throw codedError(
+              "STAGE_OUTCOME_ALREADY_REACHED",
               `${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.`
             );
           }
           const inputsBefore = evidence.domInputEvents;
+          activeStageTargetedCanvas = false;
           if (stage.act) {
             acceptingStageInput = true;
             try {
@@ -309,10 +441,17 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
               acceptingStageInput = false;
             }
             if (evidence.domInputEvents === inputsBefore) {
-              throw new Error(
+              throw codedError(
+                "PRODUCTION_INPUT_NOT_DISPATCHED",
                 `${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.`
               );
             }
+            if (activeStageTargetedCanvas && !playthroughOptions?.observe) {
+              throw codedError(
+                "AUTHORITATIVE_OBSERVE_REQUIRED_FOR_CANVAS",
+                `${stageLabel(kind, normalizedName)} dispatched production input to Canvas without an authoritative observe callback. Canvas pixels and control labels are not gameplay state; observe the same production Controller that <App /> renders through Telemetry.`
+              );
+            }
           }
           let advancedSteps = 0;
           const stepBound = stage.maxSteps ?? 120;
@@ -328,7 +467,8 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
           });
           stepTrace = { bound: stepBound, completed: steps };
           if (!stage.act && advancedSteps === 0) {
-            throw new Error(
+            throw codedError(
+              "AUTONOMOUS_STAGE_NOT_ADVANCED",
               `${stageLabel(kind, normalizedName)} did not execute its deterministic step. Autonomous stages must advance production time or frames at least once.`
             );
           }
@@ -336,14 +476,16 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
           await stage.assert({ expect, user, view });
           const assertions = expect.getState().assertionCalls - assertionsBefore;
           if (assertions === 0) {
-            throw new Error(
+            throw codedError(
+              "STAGE_ASSERTION_MISSING",
               `${stageLabel(kind, normalizedName)} assert must call the expect provided by playthroughTest at least once.`
             );
           }
           const after = sampleState(`after ${normalizedName}`);
           if (after.fingerprint === before.fingerprint) {
             const source = playthroughOptions?.observe ? "authoritative observe() state" : "production DOM";
-            throw new Error(
+            throw codedError(
+              "STAGE_STATE_UNCHANGED",
               `${stageLabel(kind, normalizedName)} did not change the ${source} from the previous stage. Each milestone must prove a new gameplay result.`
             );
           }
@@ -365,27 +507,27 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
           user,
           async enter(stage) {
             if (entered) {
-              throw new Error("enter may only be called once.");
+              throw codedError("INVALID_STAGE_ORDER", "enter may only be called once.");
             }
             if (evidence.stages.length > 0) {
-              throw new Error("enter must be the first playthrough stage.");
+              throw codedError("INVALID_STAGE_ORDER", "enter must be the first playthrough stage.");
             }
             await executeStage("entered", "entered", stage);
             entered = true;
           },
           async milestone(name, stage) {
             if (!entered) {
-              throw new Error("milestone must follow enter.");
+              throw codedError("INVALID_STAGE_ORDER", "milestone must follow enter.");
             }
             if (finished) {
-              throw new Error("milestone cannot run after finish.");
+              throw codedError("INVALID_STAGE_ORDER", "milestone cannot run after finish.");
             }
             await executeStage(name, "milestone", stage);
           },
           async finish(name, stage) {
-            if (!entered) throw new Error("finish must follow enter.");
+            if (!entered) throw codedError("INVALID_STAGE_ORDER", "finish must follow enter.");
             if (finished) {
-              throw new Error("finish may only be called once.");
+              throw codedError("INVALID_STAGE_ORDER", "finish may only be called once.");
             }
             await executeStage(name, stage.kind, stage);
             finished = true;
@@ -394,19 +536,22 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
         const milestones = evidence.stages.filter(
           (stage) => stage.kind === "milestone"
         );
-        if (!entered) throw new Error("playthroughTest must call enter once.");
+        if (!entered) throw codedError("INCOMPLETE_PLAYTHROUGH_EVIDENCE", "playthroughTest must call enter once.");
         if (milestones.length < MIN_MILESTONES) {
-          throw new Error(
+          throw codedError(
+            "INCOMPLETE_PLAYTHROUGH_EVIDENCE",
             `playthroughTest requires at least ${MIN_MILESTONES} named gameplay milestones between enter and finish; received ${milestones.length}.`
           );
         }
         if (!finished) {
-          throw new Error(
+          throw codedError(
+            "INCOMPLETE_PLAYTHROUGH_EVIDENCE",
             'playthroughTest must call finish with kind "progress" or "terminal".'
           );
         }
         if (evidence.stages.length < MIN_STAGES) {
-          throw new Error(
+          throw codedError(
+            "INCOMPLETE_PLAYTHROUGH_EVIDENCE",
             `playthroughTest requires at least ${MIN_STAGES} evidenced stages: enter, ${MIN_MILESTONES} named milestones, and finish.`
           );
         }
@@ -414,6 +559,7 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
       } catch (error) {
         const trace = captureFailureTrace();
         metadata.trace = trace;
+        metadata.failure = createFailureDiagnostic("playthrough", error);
         try {
           await annotate(trace, REACT_PLAYTHROUGH_TRACE_ANNOTATION);
         } catch {