miaoda-game-devkit 0.6.2 → 0.6.3

package/dist/react/index.js

@@ -54,6 +54,15 @@ function useOwnedGameController(createController) {
 
 // src/react/use-game-controller.ts
 var import_react2 = require("react");
+
+// src/react/react-error-diagnostics.ts
+function codedError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+// src/react/use-game-controller.ts
 function useGameController(createController) {
   const game = useOwnedGameController(createController);
   useSnapshotIntegrityCheck(game);
@@ -91,7 +100,8 @@ function useSnapshotIntegrityCheck(game) {
       }
       if (previousJson !== void 0 && nextJson !== previousJson) {
         reported.current = true;
-        throw new Error(
+        throw codedError(
+          "GAME_SNAPSHOT_REFERENCE_REUSED",
           "Game state changed while snapshot() returned the same reference. React compares snapshots by reference and skips the render when Object.is(previous, next) is true, so the UI freezes. Publish a new top-level snapshot before each notification, for example cachedSnapshot = { ...state }, and never expose a mutable internal object as the snapshot."
         );
       }

package/dist/react/index.mjs

@@ -26,6 +26,15 @@ function useOwnedGameController(createController) {
 
 // src/react/use-game-controller.ts
 import { useEffect as useEffect2, useRef as useRef2, useSyncExternalStore } from "react";
+
+// src/react/react-error-diagnostics.ts
+function codedError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+// src/react/use-game-controller.ts
 function useGameController(createController) {
   const game = useOwnedGameController(createController);
   useSnapshotIntegrityCheck(game);
@@ -63,7 +72,8 @@ function useSnapshotIntegrityCheck(game) {
       }
       if (previousJson !== void 0 && nextJson !== previousJson) {
         reported.current = true;
-        throw new Error(
+        throw codedError(
+          "GAME_SNAPSHOT_REFERENCE_REUSED",
           "Game state changed while snapshot() returned the same reference. React compares snapshots by reference and skips the render when Object.is(previous, next) is true, so the UI freezes. Publish a new top-level snapshot before each notification, for example cachedSnapshot = { ...state }, and never expose a mutable internal object as the snapshot."
         );
       }

package/dist/react/testing.d.mts

@@ -22,6 +22,15 @@ declare class ManualGameClock implements GameClock {
     pendingTimerCount(): number;
 }
 
+interface ReactFailureEntry {
+    code: string;
+    message: string;
+}
+interface ReactFailureDiagnostic {
+    source: "playthrough" | "test-runtime";
+    entries: ReactFailureEntry[];
+}
+
 /** 有界推进的通用配置，不绑定任何特定 Core、phase 或时钟实现。 */
 interface StepUntilOptions {
     /** 条件仍不成立时允许执行的最大生产步数，默认 120。 */
@@ -57,9 +66,10 @@ interface ReactPlaythroughEvidence {
 }
 /** 通过 Vitest task metadata 从 worker 传递给主线程 reporter 的数据。 */
 interface ReactPlaythroughMetadata {
-    version: 4;
+    version: 5;
     waiverReason?: string;
     trace?: string;
+    failure?: ReactFailureDiagnostic;
     evidence: ReactPlaythroughEvidence;
 }
 interface ReactPlaythroughOptions {

package/dist/react/testing.d.ts

@@ -22,6 +22,15 @@ declare class ManualGameClock implements GameClock {
     pendingTimerCount(): number;
 }
 
+interface ReactFailureEntry {
+    code: string;
+    message: string;
+}
+interface ReactFailureDiagnostic {
+    source: "playthrough" | "test-runtime";
+    entries: ReactFailureEntry[];
+}
+
 /** 有界推进的通用配置，不绑定任何特定 Core、phase 或时钟实现。 */
 interface StepUntilOptions {
     /** 条件仍不成立时允许执行的最大生产步数，默认 120。 */
@@ -57,9 +66,10 @@ interface ReactPlaythroughEvidence {
 }
 /** 通过 Vitest task metadata 从 worker 传递给主线程 reporter 的数据。 */
 interface ReactPlaythroughMetadata {
-    version: 4;
+    version: 5;
     waiverReason?: string;
     trace?: string;
+    failure?: ReactFailureDiagnostic;
     evidence: ReactPlaythroughEvidence;
 }
 interface ReactPlaythroughOptions {

package/dist/react/testing.js

@@ -96,14 +96,112 @@ var import_react2 = require("@testing-library/react");
 var import_user_event = __toESM(require("@testing-library/user-event"));
 var import_vitest = require("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
 var import_react = require("@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;
@@ -119,7 +217,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."
     );
   }
@@ -128,7 +227,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."
     );
   }
@@ -145,7 +245,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}`
   );
 }
@@ -198,14 +299,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}.`
     );
   }
@@ -218,7 +323,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)})`;
@@ -254,6 +359,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;
@@ -284,8 +390,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);
@@ -295,7 +405,8 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
       try {
         const view = (0, import_react2.render)(element);
         if (view.container.childNodes.length === 0) {
-          throw new Error(
+          throw codedError(
+            "PRODUCTION_ENTRY_NOT_RENDERED",
             "playthroughTest must render the production game entry."
           );
         }
@@ -324,17 +435,22 @@ 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".`
             );
           }
@@ -342,12 +458,14 @@ function definePlaythrough(element, run, playthroughOptions, waiverReason) {
           activeStage = { name: normalizedName, kind, before };
           stepTrace = { bound: stage.maxSteps ?? 120 };
           if (stage.step && !playthroughOptions?.observe) {
-            throw new Error(
+            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.`
             );
           }
@@ -361,12 +479,14 @@ 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 new Error(
+              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.`
               );
             }
@@ -385,7 +505,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.`
             );
           }
@@ -393,14 +514,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.`
             );
           }
@@ -422,27 +545,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;
@@ -451,19 +574,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.`
           );
         }
@@ -471,6 +597,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 {