miaoda-game-devkit 0.10.0 → 0.10.2

package/dist/lint/setup.mjs

@@ -1,8 +1,92 @@
 // src/lint/setup.ts
 import { afterEach } from "vitest";
 
-// src/testing/jsdom-canvas.ts
+// src/testing/jsdom-webgl.ts
+var CONSTANT_NAME = /^[A-Z][A-Z0-9_]*$/;
+var TEXTURE_UNIT_LIMIT = 32;
+var TEXTURE_SIZE_LIMIT = 4096;
+var VIEWPORT_LIMIT = 4096;
+function parameterValue(name) {
+  if (name === "VERSION") return "WebGL 2.0 (miaoda-game-devkit stub)";
+  if (name === "SHADING_LANGUAGE_VERSION") return "WebGL GLSL ES 3.00 (stub)";
+  if (name === "VENDOR" || name === "RENDERER") return "miaoda-game-devkit";
+  if (name === "MAX_VIEWPORT_DIMS") {
+    return new Int32Array([VIEWPORT_LIMIT, VIEWPORT_LIMIT]);
+  }
+  if (name === "VIEWPORT" || name === "SCISSOR_BOX") {
+    return new Int32Array([0, 0, VIEWPORT_LIMIT, VIEWPORT_LIMIT]);
+  }
+  if (name.includes("MAX_") && name.includes("SIZE")) return TEXTURE_SIZE_LIMIT;
+  if (name.startsWith("MAX_")) return TEXTURE_UNIT_LIMIT;
+  if (name.endsWith("_BITS")) return 8;
+  return 0;
+}
+function createWebGLContext(canvas, attributes) {
+  const constants = /* @__PURE__ */ new Map();
+  const constantNames = /* @__PURE__ */ new Map();
+  const state = {
+    canvas,
+    drawingBufferWidth: canvas.width,
+    drawingBufferHeight: canvas.height
+  };
+  const method = (name) => {
+    if (name === "getContextAttributes") return () => attributes;
+    if (name === "getExtension") return () => null;
+    if (name === "getSupportedExtensions") return () => [];
+    if (name === "getParameter") {
+      return (pname) => parameterValue(constantNames.get(pname) ?? "UNKNOWN");
+    }
+    if (name === "getShaderPrecisionFormat") {
+      return () => ({ rangeMin: 127, rangeMax: 127, precision: 23 });
+    }
+    if (name === "getShaderInfoLog" || name === "getProgramInfoLog") return () => "";
+    if (name === "getError") return () => 0;
+    if (name === "isContextLost") return () => false;
+    if (name.startsWith("get") && name.endsWith("Parameter")) return () => true;
+    if (name.startsWith("get")) return () => null;
+    if (name.startsWith("create") || name.startsWith("getUniformLocation")) {
+      return () => ({});
+    }
+    return () => void 0;
+  };
+  return new Proxy(state, {
+    get(target, property) {
+      if (property in target) return target[property];
+      if (typeof property !== "string") return void 0;
+      if (CONSTANT_NAME.test(property)) {
+        const existing = constants.get(property);
+        if (existing !== void 0) return existing;
+        const value = constants.size + 1;
+        constants.set(property, value);
+        constantNames.set(value, property);
+        return value;
+      }
+      const implementation = method(property);
+      target[property] = implementation;
+      return implementation;
+    }
+  });
+}
 var contexts = /* @__PURE__ */ new WeakMap();
+function getJSDOMWebGLContext(canvas, options) {
+  const existing = contexts.get(canvas);
+  if (existing) return existing;
+  const attributes = {
+    alpha: true,
+    antialias: false,
+    depth: true,
+    premultipliedAlpha: true,
+    preserveDrawingBuffer: false,
+    stencil: false,
+    ...typeof options === "object" && options !== null ? options : {}
+  };
+  const context = createWebGLContext(canvas, attributes);
+  contexts.set(canvas, context);
+  return context;
+}
+
+// src/testing/jsdom-canvas.ts
+var contexts2 = /* @__PURE__ */ new WeakMap();
 function createCanvasContext(canvas) {
   const imageData = (width = 1, height = 1) => ({
     data: new Uint8ClampedArray(width * height * 4),
@@ -49,12 +133,15 @@ function createCanvasContext(canvas) {
   return context;
 }
 function installJSDOMCanvasContext() {
-  HTMLCanvasElement.prototype.getContext = function getContext(contextId) {
+  HTMLCanvasElement.prototype.getContext = function getContext(contextId, options) {
+    if (contextId === "webgl" || contextId === "webgl2") {
+      return getJSDOMWebGLContext(this, options);
+    }
     if (contextId !== "2d") return null;
-    const existing = contexts.get(this);
+    const existing = contexts2.get(this);
     if (existing) return existing;
     const context = createCanvasContext(this);
-    contexts.set(this, context);
+    contexts2.set(this, context);
     return context;
   };
 }

package/dist/react/testing.d.mts

@@ -50,7 +50,10 @@ interface StepUntilOptions {
     step?: (step: number) => void | Promise<void>;
     /**
      * Optional read-only state used to make bounded failures actionable.
-     * The value is sampled only when the bound is exhausted.
+     *
+     * The value is sampled when the bound is exhausted, and additionally at a fixed
+     * step interval so an exhausted bound can distinguish a run that is still
+     * progressing from one whose state already settled.
      */
     diagnostics?: () => unknown;
     /** 测试超时或运行取消时停止继续推进，通常由 playthroughTest 自动传入。 */

package/dist/react/testing.d.ts

@@ -50,7 +50,10 @@ interface StepUntilOptions {
     step?: (step: number) => void | Promise<void>;
     /**
      * Optional read-only state used to make bounded failures actionable.
-     * The value is sampled only when the bound is exhausted.
+     *
+     * The value is sampled when the bound is exhausted, and additionally at a fixed
+     * step interval so an exhausted bound can distinguish a run that is still
+     * progressing from one whose state already settled.
      */
     diagnostics?: () => unknown;
     /** 测试超时或运行取消时停止继续推进，通常由 playthroughTest 自动传入。 */

package/dist/react/testing.js

@@ -311,6 +311,39 @@ function formatDiagnostics(read) {
     return `diagnostics() threw: ${String(error)}`;
   }
 }
+var STAGNATION_SAMPLE_INTERVAL = 32;
+var STAGNATION_SAMPLE_MINIMUM = 3;
+var StagnationProbe = class {
+  constructor(read) {
+    this.read = read;
+    this.disabled = !read;
+  }
+  read;
+  fingerprint;
+  unchangedSamples = 0;
+  disabled = false;
+  settledAtStep;
+  sample(step) {
+    if (this.disabled || step % STAGNATION_SAMPLE_INTERVAL !== 0) return;
+    let next;
+    try {
+      next = JSON.stringify(this.read?.()) ?? "undefined";
+    } catch {
+      this.disabled = true;
+      return;
+    }
+    if (this.fingerprint === next) {
+      this.unchangedSamples += 1;
+      return;
+    }
+    this.fingerprint = next;
+    this.unchangedSamples = 1;
+    this.settledAtStep = step;
+  }
+  get settled() {
+    return !this.disabled && this.unchangedSamples >= STAGNATION_SAMPLE_MINIMUM;
+  }
+};
 function normalizePlaythroughWaiverReason(waiverReason) {
   if (waiverReason === void 0) return void 0;
   const reason = waiverReason.trim();
@@ -330,6 +363,7 @@ async function runBoundedUntil(condition, options = {}) {
       "stepUntil maxSteps must be a safe integer between 0 and 10000."
     );
   }
+  const probe = new StagnationProbe(options.diagnostics);
   for (let step = 0; step <= maxSteps; step += 1) {
     throwIfAborted(options.signal);
     if (condition()) return step;
@@ -338,11 +372,18 @@ async function runBoundedUntil(condition, options = {}) {
         await options.step?.(step + 1);
       });
       throwIfAborted(options.signal);
+      probe.sample(step + 1);
     }
   }
   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, and the condition did not become true after the stage action. This does not identify a clock problem; inspect the condition, production input wiring, and observed state boundary.";
   const suffix = diagnostics ? ` Last diagnostics: ${diagnostics}` : "";
+  if (probe.settled) {
+    throw codedError(
+      "PLAYTHROUGH_STATE_STAGNANT",
+      `Playthrough state stopped changing at step ${probe.settledAtStep} of ${maxSteps} and stayed identical until the bound. The run is already settled, so raising maxSteps cannot help: compare the settled state against the outcome this stage asserts. A settled state usually means the game reached a terminal result other than the asserted one, or that the stage never advances the production Controller at all.${suffix}`
+    );
+  }
+  const guidance = options.step ? "The step callback ran, but the authoritative outcome did not change." : "No step callback was provided, and the condition did not become true after the stage action. This does not identify a clock problem; inspect the condition, production input wiring, and observed state boundary.";
   throw codedError(
     options.step ? "PLAYTHROUGH_BOUND_EXHAUSTED" : "PLAYTHROUGH_OUTCOME_NOT_REACHED",
     `Playthrough outcome was not reached within ${maxSteps} steps. ${guidance}${suffix}`

package/dist/react/testing.mjs

@@ -273,6 +273,39 @@ function formatDiagnostics(read) {
     return `diagnostics() threw: ${String(error)}`;
   }
 }
+var STAGNATION_SAMPLE_INTERVAL = 32;
+var STAGNATION_SAMPLE_MINIMUM = 3;
+var StagnationProbe = class {
+  constructor(read) {
+    this.read = read;
+    this.disabled = !read;
+  }
+  read;
+  fingerprint;
+  unchangedSamples = 0;
+  disabled = false;
+  settledAtStep;
+  sample(step) {
+    if (this.disabled || step % STAGNATION_SAMPLE_INTERVAL !== 0) return;
+    let next;
+    try {
+      next = JSON.stringify(this.read?.()) ?? "undefined";
+    } catch {
+      this.disabled = true;
+      return;
+    }
+    if (this.fingerprint === next) {
+      this.unchangedSamples += 1;
+      return;
+    }
+    this.fingerprint = next;
+    this.unchangedSamples = 1;
+    this.settledAtStep = step;
+  }
+  get settled() {
+    return !this.disabled && this.unchangedSamples >= STAGNATION_SAMPLE_MINIMUM;
+  }
+};
 function normalizePlaythroughWaiverReason(waiverReason) {
   if (waiverReason === void 0) return void 0;
   const reason = waiverReason.trim();
@@ -292,6 +325,7 @@ async function runBoundedUntil(condition, options = {}) {
       "stepUntil maxSteps must be a safe integer between 0 and 10000."
     );
   }
+  const probe = new StagnationProbe(options.diagnostics);
   for (let step = 0; step <= maxSteps; step += 1) {
     throwIfAborted(options.signal);
     if (condition()) return step;
@@ -300,11 +334,18 @@ async function runBoundedUntil(condition, options = {}) {
         await options.step?.(step + 1);
       });
       throwIfAborted(options.signal);
+      probe.sample(step + 1);
     }
   }
   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, and the condition did not become true after the stage action. This does not identify a clock problem; inspect the condition, production input wiring, and observed state boundary.";
   const suffix = diagnostics ? ` Last diagnostics: ${diagnostics}` : "";
+  if (probe.settled) {
+    throw codedError(
+      "PLAYTHROUGH_STATE_STAGNANT",
+      `Playthrough state stopped changing at step ${probe.settledAtStep} of ${maxSteps} and stayed identical until the bound. The run is already settled, so raising maxSteps cannot help: compare the settled state against the outcome this stage asserts. A settled state usually means the game reached a terminal result other than the asserted one, or that the stage never advances the production Controller at all.${suffix}`
+    );
+  }
+  const guidance = options.step ? "The step callback ran, but the authoritative outcome did not change." : "No step callback was provided, and the condition did not become true after the stage action. This does not identify a clock problem; inspect the condition, production input wiring, and observed state boundary.";
   throw codedError(
     options.step ? "PLAYTHROUGH_BOUND_EXHAUSTED" : "PLAYTHROUGH_OUTCOME_NOT_REACHED",
     `Playthrough outcome was not reached within ${maxSteps} steps. ${guidance}${suffix}`

package/dist/react/vitest-config.js

@@ -265,6 +265,39 @@ function formatDiagnostics(read) {
     return `diagnostics() threw: ${String(error)}`;
   }
 }
+var STAGNATION_SAMPLE_INTERVAL = 32;
+var STAGNATION_SAMPLE_MINIMUM = 3;
+var StagnationProbe = class {
+  constructor(read) {
+    this.read = read;
+    this.disabled = !read;
+  }
+  read;
+  fingerprint;
+  unchangedSamples = 0;
+  disabled = false;
+  settledAtStep;
+  sample(step) {
+    if (this.disabled || step % STAGNATION_SAMPLE_INTERVAL !== 0) return;
+    let next;
+    try {
+      next = JSON.stringify(this.read?.()) ?? "undefined";
+    } catch {
+      this.disabled = true;
+      return;
+    }
+    if (this.fingerprint === next) {
+      this.unchangedSamples += 1;
+      return;
+    }
+    this.fingerprint = next;
+    this.unchangedSamples = 1;
+    this.settledAtStep = step;
+  }
+  get settled() {
+    return !this.disabled && this.unchangedSamples >= STAGNATION_SAMPLE_MINIMUM;
+  }
+};
 function normalizePlaythroughWaiverReason(waiverReason) {
   if (waiverReason === void 0) return void 0;
   const reason = waiverReason.trim();
@@ -284,6 +317,7 @@ async function runBoundedUntil(condition, options = {}) {
       "stepUntil maxSteps must be a safe integer between 0 and 10000."
     );
   }
+  const probe = new StagnationProbe(options.diagnostics);
   for (let step = 0; step <= maxSteps; step += 1) {
     throwIfAborted(options.signal);
     if (condition()) return step;
@@ -292,11 +326,18 @@ async function runBoundedUntil(condition, options = {}) {
         await options.step?.(step + 1);
       });
       throwIfAborted(options.signal);
+      probe.sample(step + 1);
     }
   }
   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, and the condition did not become true after the stage action. This does not identify a clock problem; inspect the condition, production input wiring, and observed state boundary.";
   const suffix = diagnostics ? ` Last diagnostics: ${diagnostics}` : "";
+  if (probe.settled) {
+    throw codedError(
+      "PLAYTHROUGH_STATE_STAGNANT",
+      `Playthrough state stopped changing at step ${probe.settledAtStep} of ${maxSteps} and stayed identical until the bound. The run is already settled, so raising maxSteps cannot help: compare the settled state against the outcome this stage asserts. A settled state usually means the game reached a terminal result other than the asserted one, or that the stage never advances the production Controller at all.${suffix}`
+    );
+  }
+  const guidance = options.step ? "The step callback ran, but the authoritative outcome did not change." : "No step callback was provided, and the condition did not become true after the stage action. This does not identify a clock problem; inspect the condition, production input wiring, and observed state boundary.";
   throw codedError(
     options.step ? "PLAYTHROUGH_BOUND_EXHAUSTED" : "PLAYTHROUGH_OUTCOME_NOT_REACHED",
     `Playthrough outcome was not reached within ${maxSteps} steps. ${guidance}${suffix}`
@@ -1266,7 +1307,9 @@ function repairGuidance(code) {
     case "STAGE_STATE_UNCHANGED":
       return "The stage ran and asserted, but its observable state matched the previous milestone. Preserve the intended gameplay result and observe the same production Controller rendered by <App />. Do not substitute arbitrary labels or a weaker state change.";
     case "PLAYTHROUGH_BOUND_EXHAUSTED":
-      return "Keep the intended outcome unchanged. The stage driver ran, but gameplay did not reach it within the bound. Inspect TRACE and Last diagnostics, then confirm that each deterministic step advances the same production Controller rendered by <App />. If state remains unchanged, inject ManualGameClock through the production App factory and observe that Controller through Telemetry. Do not replace the outcome with navigation, an intermediate phase, a no-op step, or a weaker assertion.";
+      return "First read the phase or result field of Last diagnostics. If the run already reached a terminal result other than the one asserted, the game is over and the bound is irrelevant: assert the result the shipped constants actually produce (loss, draw, and ranking are legitimate terminal results), or fix the mechanic that was supposed to make the intended objective reachable. Raising maxSteps or rewriting the in-test play order cannot pass a finished game. If the run is still mid-game, keep the intended outcome unchanged and confirm that each deterministic step advances the same production Controller rendered by <App />; if state remains unchanged, inject ManualGameClock through the production App factory and observe that Controller through Telemetry. Never replace the outcome with navigation, an intermediate phase, a no-op step, or a weaker assertion, and never retune the production constants that define the challenge.";
+    case "PLAYTHROUGH_STATE_STAGNANT":
+      return "The observed state stopped changing well before the bound, so the bound is not the problem and raising maxSteps cannot help. Two causes: the run already reached a terminal result other than the one asserted \u2014 assert the result the shipped constants actually produce, or fix the mechanic meant to make the intended objective reachable \u2014 or the stage never advances the production Controller at all, in which case inject ManualGameClock through the production App factory and observe that Controller through Telemetry. Do not retune production constants and do not weaken the assertion.";
     case "PLAYTHROUGH_OUTCOME_NOT_REACHED":
       return "The stage action completed, but its until condition never became true. Inspect TRACE and Last diagnostics, then confirm that the production DOM input reaches the rendered App, until describes the result caused by this stage, and observe reads the matching authoritative state when used. Add a deterministic step only if the gameplay is actually driven by time or frames; do not add a no-op step or weaken the intended outcome.";
     case "PLAYTHROUGH_CLOCK_NOT_ADVANCED":
@@ -1452,7 +1495,36 @@ function resolvePhaser3BrowserEntry(projectRoot) {
     return void 0;
   }
 }
+var COVERAGE_INCLUDE = [
+  "src/game/core/**/*.{ts,tsx}",
+  "src/game/runtime/**/*.{ts,tsx}"
+];
+var COVERAGE_EXCLUDE = [
+  "src/game/{core,runtime}/**/*.d.ts",
+  "src/game/{core,runtime}/**/*.{spec,test}.{ts,tsx}"
+];
+var GATE_SCAN_EXCLUDE = [
+  "src/**/*.d.ts",
+  "src/**/*.{spec,test}.{ts,tsx}",
+  "src/game/example/**"
+];
+function assertCoverageScopeIsPopulated(projectRoot) {
+  const scan = (pattern) => (0, import_node_fs3.globSync)(pattern, { cwd: projectRoot, exclude: GATE_SCAN_EXCLUDE });
+  if (COVERAGE_INCLUDE.flatMap(scan).length > 0) return;
+  const misplaced = scan("src/**/{core,runtime}/**/*.{ts,tsx}");
+  if (misplaced.length === 0) return;
+  throw new Error(
+    [
+      "The coverage gate matched no source file, so it proves nothing.",
+      "Deterministic rules belong in src/game/core/; the loop, scheduling,",
+      "Controller, and Telemetry belong in src/game/runtime/.",
+      "Move these files under those two directories:",
+      ...misplaced.slice(0, 10).map((file) => `  ${file}`)
+    ].join("\n")
+  );
+}
 function defineReactGameVitestConfig(options) {
+  assertCoverageScopeIsPopulated(options.projectRoot);
   const phaser3BrowserEntry = resolvePhaser3BrowserEntry(options.projectRoot);
   return (0, import_config.defineConfig)({
     // Keep discovery and dependency resolution anchored to the generated app even
@@ -1495,14 +1567,8 @@ function defineReactGameVitestConfig(options) {
       clearMocks: true,
       coverage: {
         provider: "v8",
-        include: [
-          "src/game/core/**/*.{ts,tsx}",
-          "src/game/runtime/**/*.{ts,tsx}"
-        ],
-        exclude: [
-          "src/game/{core,runtime}/**/*.d.ts",
-          "src/game/{core,runtime}/**/*.{spec,test}.{ts,tsx}"
-        ],
+        include: COVERAGE_INCLUDE,
+        exclude: COVERAGE_EXCLUDE,
         reporter: ["text-summary"],
         thresholds: {
           perFile: true,

package/dist/react/vitest-config.mjs

@@ -1,5 +1,5 @@
 // src/react-vitest-config.ts
-import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync3, globSync, readFileSync as readFileSync2 } from "fs";
 import { dirname as dirname2, resolve as resolve3 } from "path";
 import { defineConfig } from "vitest/config";
 
@@ -231,6 +231,39 @@ function formatDiagnostics(read) {
     return `diagnostics() threw: ${String(error)}`;
   }
 }
+var STAGNATION_SAMPLE_INTERVAL = 32;
+var STAGNATION_SAMPLE_MINIMUM = 3;
+var StagnationProbe = class {
+  constructor(read) {
+    this.read = read;
+    this.disabled = !read;
+  }
+  read;
+  fingerprint;
+  unchangedSamples = 0;
+  disabled = false;
+  settledAtStep;
+  sample(step) {
+    if (this.disabled || step % STAGNATION_SAMPLE_INTERVAL !== 0) return;
+    let next;
+    try {
+      next = JSON.stringify(this.read?.()) ?? "undefined";
+    } catch {
+      this.disabled = true;
+      return;
+    }
+    if (this.fingerprint === next) {
+      this.unchangedSamples += 1;
+      return;
+    }
+    this.fingerprint = next;
+    this.unchangedSamples = 1;
+    this.settledAtStep = step;
+  }
+  get settled() {
+    return !this.disabled && this.unchangedSamples >= STAGNATION_SAMPLE_MINIMUM;
+  }
+};
 function normalizePlaythroughWaiverReason(waiverReason) {
   if (waiverReason === void 0) return void 0;
   const reason = waiverReason.trim();
@@ -250,6 +283,7 @@ async function runBoundedUntil(condition, options = {}) {
       "stepUntil maxSteps must be a safe integer between 0 and 10000."
     );
   }
+  const probe = new StagnationProbe(options.diagnostics);
   for (let step = 0; step <= maxSteps; step += 1) {
     throwIfAborted(options.signal);
     if (condition()) return step;
@@ -258,11 +292,18 @@ async function runBoundedUntil(condition, options = {}) {
         await options.step?.(step + 1);
       });
       throwIfAborted(options.signal);
+      probe.sample(step + 1);
     }
   }
   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, and the condition did not become true after the stage action. This does not identify a clock problem; inspect the condition, production input wiring, and observed state boundary.";
   const suffix = diagnostics ? ` Last diagnostics: ${diagnostics}` : "";
+  if (probe.settled) {
+    throw codedError(
+      "PLAYTHROUGH_STATE_STAGNANT",
+      `Playthrough state stopped changing at step ${probe.settledAtStep} of ${maxSteps} and stayed identical until the bound. The run is already settled, so raising maxSteps cannot help: compare the settled state against the outcome this stage asserts. A settled state usually means the game reached a terminal result other than the asserted one, or that the stage never advances the production Controller at all.${suffix}`
+    );
+  }
+  const guidance = options.step ? "The step callback ran, but the authoritative outcome did not change." : "No step callback was provided, and the condition did not become true after the stage action. This does not identify a clock problem; inspect the condition, production input wiring, and observed state boundary.";
   throw codedError(
     options.step ? "PLAYTHROUGH_BOUND_EXHAUSTED" : "PLAYTHROUGH_OUTCOME_NOT_REACHED",
     `Playthrough outcome was not reached within ${maxSteps} steps. ${guidance}${suffix}`
@@ -1232,7 +1273,9 @@ function repairGuidance(code) {
     case "STAGE_STATE_UNCHANGED":
       return "The stage ran and asserted, but its observable state matched the previous milestone. Preserve the intended gameplay result and observe the same production Controller rendered by <App />. Do not substitute arbitrary labels or a weaker state change.";
     case "PLAYTHROUGH_BOUND_EXHAUSTED":
-      return "Keep the intended outcome unchanged. The stage driver ran, but gameplay did not reach it within the bound. Inspect TRACE and Last diagnostics, then confirm that each deterministic step advances the same production Controller rendered by <App />. If state remains unchanged, inject ManualGameClock through the production App factory and observe that Controller through Telemetry. Do not replace the outcome with navigation, an intermediate phase, a no-op step, or a weaker assertion.";
+      return "First read the phase or result field of Last diagnostics. If the run already reached a terminal result other than the one asserted, the game is over and the bound is irrelevant: assert the result the shipped constants actually produce (loss, draw, and ranking are legitimate terminal results), or fix the mechanic that was supposed to make the intended objective reachable. Raising maxSteps or rewriting the in-test play order cannot pass a finished game. If the run is still mid-game, keep the intended outcome unchanged and confirm that each deterministic step advances the same production Controller rendered by <App />; if state remains unchanged, inject ManualGameClock through the production App factory and observe that Controller through Telemetry. Never replace the outcome with navigation, an intermediate phase, a no-op step, or a weaker assertion, and never retune the production constants that define the challenge.";
+    case "PLAYTHROUGH_STATE_STAGNANT":
+      return "The observed state stopped changing well before the bound, so the bound is not the problem and raising maxSteps cannot help. Two causes: the run already reached a terminal result other than the one asserted \u2014 assert the result the shipped constants actually produce, or fix the mechanic meant to make the intended objective reachable \u2014 or the stage never advances the production Controller at all, in which case inject ManualGameClock through the production App factory and observe that Controller through Telemetry. Do not retune production constants and do not weaken the assertion.";
     case "PLAYTHROUGH_OUTCOME_NOT_REACHED":
       return "The stage action completed, but its until condition never became true. Inspect TRACE and Last diagnostics, then confirm that the production DOM input reaches the rendered App, until describes the result caused by this stage, and observe reads the matching authoritative state when used. Add a deterministic step only if the gameplay is actually driven by time or frames; do not add a no-op step or weaken the intended outcome.";
     case "PLAYTHROUGH_CLOCK_NOT_ADVANCED":
@@ -1418,7 +1461,36 @@ function resolvePhaser3BrowserEntry(projectRoot) {
     return void 0;
   }
 }
+var COVERAGE_INCLUDE = [
+  "src/game/core/**/*.{ts,tsx}",
+  "src/game/runtime/**/*.{ts,tsx}"
+];
+var COVERAGE_EXCLUDE = [
+  "src/game/{core,runtime}/**/*.d.ts",
+  "src/game/{core,runtime}/**/*.{spec,test}.{ts,tsx}"
+];
+var GATE_SCAN_EXCLUDE = [
+  "src/**/*.d.ts",
+  "src/**/*.{spec,test}.{ts,tsx}",
+  "src/game/example/**"
+];
+function assertCoverageScopeIsPopulated(projectRoot) {
+  const scan = (pattern) => globSync(pattern, { cwd: projectRoot, exclude: GATE_SCAN_EXCLUDE });
+  if (COVERAGE_INCLUDE.flatMap(scan).length > 0) return;
+  const misplaced = scan("src/**/{core,runtime}/**/*.{ts,tsx}");
+  if (misplaced.length === 0) return;
+  throw new Error(
+    [
+      "The coverage gate matched no source file, so it proves nothing.",
+      "Deterministic rules belong in src/game/core/; the loop, scheduling,",
+      "Controller, and Telemetry belong in src/game/runtime/.",
+      "Move these files under those two directories:",
+      ...misplaced.slice(0, 10).map((file) => `  ${file}`)
+    ].join("\n")
+  );
+}
 function defineReactGameVitestConfig(options) {
+  assertCoverageScopeIsPopulated(options.projectRoot);
   const phaser3BrowserEntry = resolvePhaser3BrowserEntry(options.projectRoot);
   return defineConfig({
     // Keep discovery and dependency resolution anchored to the generated app even
@@ -1461,14 +1533,8 @@ function defineReactGameVitestConfig(options) {
       clearMocks: true,
       coverage: {
         provider: "v8",
-        include: [
-          "src/game/core/**/*.{ts,tsx}",
-          "src/game/runtime/**/*.{ts,tsx}"
-        ],
-        exclude: [
-          "src/game/{core,runtime}/**/*.d.ts",
-          "src/game/{core,runtime}/**/*.{spec,test}.{ts,tsx}"
-        ],
+        include: COVERAGE_INCLUDE,
+        exclude: COVERAGE_EXCLUDE,
         reporter: ["text-summary"],
         thresholds: {
           perFile: true,

package/dist/react/vitest-setup.js

@@ -184,8 +184,92 @@ function runtimeFailureError(code, value) {
   return error;
 }
 
-// src/testing/jsdom-canvas.ts
+// src/testing/jsdom-webgl.ts
+var CONSTANT_NAME = /^[A-Z][A-Z0-9_]*$/;
+var TEXTURE_UNIT_LIMIT = 32;
+var TEXTURE_SIZE_LIMIT = 4096;
+var VIEWPORT_LIMIT = 4096;
+function parameterValue(name) {
+  if (name === "VERSION") return "WebGL 2.0 (miaoda-game-devkit stub)";
+  if (name === "SHADING_LANGUAGE_VERSION") return "WebGL GLSL ES 3.00 (stub)";
+  if (name === "VENDOR" || name === "RENDERER") return "miaoda-game-devkit";
+  if (name === "MAX_VIEWPORT_DIMS") {
+    return new Int32Array([VIEWPORT_LIMIT, VIEWPORT_LIMIT]);
+  }
+  if (name === "VIEWPORT" || name === "SCISSOR_BOX") {
+    return new Int32Array([0, 0, VIEWPORT_LIMIT, VIEWPORT_LIMIT]);
+  }
+  if (name.includes("MAX_") && name.includes("SIZE")) return TEXTURE_SIZE_LIMIT;
+  if (name.startsWith("MAX_")) return TEXTURE_UNIT_LIMIT;
+  if (name.endsWith("_BITS")) return 8;
+  return 0;
+}
+function createWebGLContext(canvas, attributes) {
+  const constants = /* @__PURE__ */ new Map();
+  const constantNames = /* @__PURE__ */ new Map();
+  const state = {
+    canvas,
+    drawingBufferWidth: canvas.width,
+    drawingBufferHeight: canvas.height
+  };
+  const method = (name) => {
+    if (name === "getContextAttributes") return () => attributes;
+    if (name === "getExtension") return () => null;
+    if (name === "getSupportedExtensions") return () => [];
+    if (name === "getParameter") {
+      return (pname) => parameterValue(constantNames.get(pname) ?? "UNKNOWN");
+    }
+    if (name === "getShaderPrecisionFormat") {
+      return () => ({ rangeMin: 127, rangeMax: 127, precision: 23 });
+    }
+    if (name === "getShaderInfoLog" || name === "getProgramInfoLog") return () => "";
+    if (name === "getError") return () => 0;
+    if (name === "isContextLost") return () => false;
+    if (name.startsWith("get") && name.endsWith("Parameter")) return () => true;
+    if (name.startsWith("get")) return () => null;
+    if (name.startsWith("create") || name.startsWith("getUniformLocation")) {
+      return () => ({});
+    }
+    return () => void 0;
+  };
+  return new Proxy(state, {
+    get(target, property) {
+      if (property in target) return target[property];
+      if (typeof property !== "string") return void 0;
+      if (CONSTANT_NAME.test(property)) {
+        const existing = constants.get(property);
+        if (existing !== void 0) return existing;
+        const value = constants.size + 1;
+        constants.set(property, value);
+        constantNames.set(value, property);
+        return value;
+      }
+      const implementation = method(property);
+      target[property] = implementation;
+      return implementation;
+    }
+  });
+}
 var contexts = /* @__PURE__ */ new WeakMap();
+function getJSDOMWebGLContext(canvas, options) {
+  const existing = contexts.get(canvas);
+  if (existing) return existing;
+  const attributes = {
+    alpha: true,
+    antialias: false,
+    depth: true,
+    premultipliedAlpha: true,
+    preserveDrawingBuffer: false,
+    stencil: false,
+    ...typeof options === "object" && options !== null ? options : {}
+  };
+  const context = createWebGLContext(canvas, attributes);
+  contexts.set(canvas, context);
+  return context;
+}
+
+// src/testing/jsdom-canvas.ts
+var contexts2 = /* @__PURE__ */ new WeakMap();
 function createCanvasContext(canvas) {
   const imageData = (width = 1, height = 1) => ({
     data: new Uint8ClampedArray(width * height * 4),
@@ -232,12 +316,15 @@ function createCanvasContext(canvas) {
   return context;
 }
 function installJSDOMCanvasContext() {
-  HTMLCanvasElement.prototype.getContext = function getContext(contextId) {
+  HTMLCanvasElement.prototype.getContext = function getContext(contextId, options) {
+    if (contextId === "webgl" || contextId === "webgl2") {
+      return getJSDOMWebGLContext(this, options);
+    }
     if (contextId !== "2d") return null;
-    const existing = contexts.get(this);
+    const existing = contexts2.get(this);
     if (existing) return existing;
     const context = createCanvasContext(this);
-    contexts.set(this, context);
+    contexts2.set(this, context);
     return context;
   };
 }

package/dist/react/vitest-setup.mjs

@@ -182,8 +182,92 @@ function runtimeFailureError(code, value) {
   return error;
 }
 
-// src/testing/jsdom-canvas.ts
+// src/testing/jsdom-webgl.ts
+var CONSTANT_NAME = /^[A-Z][A-Z0-9_]*$/;
+var TEXTURE_UNIT_LIMIT = 32;
+var TEXTURE_SIZE_LIMIT = 4096;
+var VIEWPORT_LIMIT = 4096;
+function parameterValue(name) {
+  if (name === "VERSION") return "WebGL 2.0 (miaoda-game-devkit stub)";
+  if (name === "SHADING_LANGUAGE_VERSION") return "WebGL GLSL ES 3.00 (stub)";
+  if (name === "VENDOR" || name === "RENDERER") return "miaoda-game-devkit";
+  if (name === "MAX_VIEWPORT_DIMS") {
+    return new Int32Array([VIEWPORT_LIMIT, VIEWPORT_LIMIT]);
+  }
+  if (name === "VIEWPORT" || name === "SCISSOR_BOX") {
+    return new Int32Array([0, 0, VIEWPORT_LIMIT, VIEWPORT_LIMIT]);
+  }
+  if (name.includes("MAX_") && name.includes("SIZE")) return TEXTURE_SIZE_LIMIT;
+  if (name.startsWith("MAX_")) return TEXTURE_UNIT_LIMIT;
+  if (name.endsWith("_BITS")) return 8;
+  return 0;
+}
+function createWebGLContext(canvas, attributes) {
+  const constants = /* @__PURE__ */ new Map();
+  const constantNames = /* @__PURE__ */ new Map();
+  const state = {
+    canvas,
+    drawingBufferWidth: canvas.width,
+    drawingBufferHeight: canvas.height
+  };
+  const method = (name) => {
+    if (name === "getContextAttributes") return () => attributes;
+    if (name === "getExtension") return () => null;
+    if (name === "getSupportedExtensions") return () => [];
+    if (name === "getParameter") {
+      return (pname) => parameterValue(constantNames.get(pname) ?? "UNKNOWN");
+    }
+    if (name === "getShaderPrecisionFormat") {
+      return () => ({ rangeMin: 127, rangeMax: 127, precision: 23 });
+    }
+    if (name === "getShaderInfoLog" || name === "getProgramInfoLog") return () => "";
+    if (name === "getError") return () => 0;
+    if (name === "isContextLost") return () => false;
+    if (name.startsWith("get") && name.endsWith("Parameter")) return () => true;
+    if (name.startsWith("get")) return () => null;
+    if (name.startsWith("create") || name.startsWith("getUniformLocation")) {
+      return () => ({});
+    }
+    return () => void 0;
+  };
+  return new Proxy(state, {
+    get(target, property) {
+      if (property in target) return target[property];
+      if (typeof property !== "string") return void 0;
+      if (CONSTANT_NAME.test(property)) {
+        const existing = constants.get(property);
+        if (existing !== void 0) return existing;
+        const value = constants.size + 1;
+        constants.set(property, value);
+        constantNames.set(value, property);
+        return value;
+      }
+      const implementation = method(property);
+      target[property] = implementation;
+      return implementation;
+    }
+  });
+}
 var contexts = /* @__PURE__ */ new WeakMap();
+function getJSDOMWebGLContext(canvas, options) {
+  const existing = contexts.get(canvas);
+  if (existing) return existing;
+  const attributes = {
+    alpha: true,
+    antialias: false,
+    depth: true,
+    premultipliedAlpha: true,
+    preserveDrawingBuffer: false,
+    stencil: false,
+    ...typeof options === "object" && options !== null ? options : {}
+  };
+  const context = createWebGLContext(canvas, attributes);
+  contexts.set(canvas, context);
+  return context;
+}
+
+// src/testing/jsdom-canvas.ts
+var contexts2 = /* @__PURE__ */ new WeakMap();
 function createCanvasContext(canvas) {
   const imageData = (width = 1, height = 1) => ({
     data: new Uint8ClampedArray(width * height * 4),
@@ -230,12 +314,15 @@ function createCanvasContext(canvas) {
   return context;
 }
 function installJSDOMCanvasContext() {
-  HTMLCanvasElement.prototype.getContext = function getContext(contextId) {
+  HTMLCanvasElement.prototype.getContext = function getContext(contextId, options) {
+    if (contextId === "webgl" || contextId === "webgl2") {
+      return getJSDOMWebGLContext(this, options);
+    }
     if (contextId !== "2d") return null;
-    const existing = contexts.get(this);
+    const existing = contexts2.get(this);
     if (existing) return existing;
     const context = createCanvasContext(this);
-    contexts.set(this, context);
+    contexts2.set(this, context);
     return context;
   };
 }

package/package.json

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