miaoda-game-devkit 0.10.1 → 0.10.2

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":

package/dist/react/vitest-config.mjs

@@ -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":

package/package.json

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