miaoda-game-devkit 0.1.0

package/dist/index.mjs

@@ -0,0 +1,785 @@
+// src/phaser-headless-host.ts
+import * as Phaser3 from "phaser";
+
+// src/phaser-text-assertions.ts
+import * as Phaser from "phaser";
+function describeText(label) {
+  const name = label.name ? ` name=${JSON.stringify(label.name)}` : "";
+  const value = label.text.length > 80 ? `${label.text.slice(0, 77)}...` : label.text;
+  return `Text${name} value=${JSON.stringify(value)}`;
+}
+function isEffectivelyRenderable(label) {
+  let current = label;
+  while (current) {
+    const state = current;
+    if (state.visible === false || state.alpha === 0 || state.scaleX === 0 || state.scaleY === 0) {
+      return false;
+    }
+    current = state.parentContainer ?? null;
+  }
+  return true;
+}
+function requireFinite(problems, label, property, value) {
+  if (!Number.isFinite(value)) {
+    problems.push(`${describeText(label)} has non-finite ${property}: ${String(value)}`);
+  }
+}
+function collectSceneTexts(scene) {
+  const labels = [];
+  const visited = /* @__PURE__ */ new Set();
+  const visit = (child) => {
+    if (visited.has(child)) return;
+    visited.add(child);
+    if (child instanceof Phaser.GameObjects.Text) {
+      labels.push(child);
+      return;
+    }
+    if (child instanceof Phaser.GameObjects.Container) {
+      child.list.forEach(visit);
+      return;
+    }
+    if (child instanceof Phaser.GameObjects.Layer) {
+      child.getChildren().forEach(visit);
+    }
+  };
+  scene.children.getChildren().forEach(visit);
+  return labels;
+}
+function collectSceneBitmapTexts(scene) {
+  const labels = [];
+  const visited = /* @__PURE__ */ new Set();
+  const visit = (child) => {
+    if (visited.has(child)) return;
+    visited.add(child);
+    if (child instanceof Phaser.GameObjects.BitmapText) {
+      labels.push(child);
+      return;
+    }
+    if (child instanceof Phaser.GameObjects.Container) {
+      child.list.forEach(visit);
+      return;
+    }
+    if (child instanceof Phaser.GameObjects.Layer) {
+      child.getChildren().forEach(visit);
+    }
+  };
+  scene.children.getChildren().forEach(visit);
+  return labels;
+}
+function collectMissingBitmapGlyphs(text, chars) {
+  const missing = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    if (/\s/u.test(character)) continue;
+    const code = text.charCodeAt(index);
+    if (seen.has(code) || chars[code] !== void 0) continue;
+    seen.add(code);
+    missing.push(`${JSON.stringify(character)} (U+${code.toString(16).toUpperCase().padStart(4, "0")})`);
+  }
+  return missing;
+}
+function collectTextHealthProblems(scene) {
+  const problems = [];
+  const labels = collectSceneTexts(scene);
+  for (const label of labels) {
+    if (label.text.length === 0) continue;
+    requireFinite(problems, label, "x", label.x);
+    requireFinite(problems, label, "y", label.y);
+    requireFinite(problems, label, "width", label.width);
+    requireFinite(problems, label, "height", label.height);
+    requireFinite(problems, label, "displayWidth", label.displayWidth);
+    requireFinite(problems, label, "displayHeight", label.displayHeight);
+    requireFinite(problems, label, "scaleX", label.scaleX);
+    requireFinite(problems, label, "scaleY", label.scaleY);
+    requireFinite(problems, label, "originX", label.originX);
+    requireFinite(problems, label, "originY", label.originY);
+    requireFinite(problems, label, "rotation", label.rotation);
+    requireFinite(problems, label, "fixedWidth", label.style.fixedWidth);
+    requireFinite(problems, label, "fixedHeight", label.style.fixedHeight);
+    requireFinite(problems, label, "resolution", label.style.resolution);
+    const requiresPositiveSize = /\S/u.test(label.text) && isEffectivelyRenderable(label);
+    if (requiresPositiveSize && Number.isFinite(label.width) && label.width <= 0) {
+      problems.push(`${describeText(label)} has non-positive width: ${label.width}`);
+    }
+    if (requiresPositiveSize && Number.isFinite(label.height) && label.height <= 0) {
+      problems.push(`${describeText(label)} has non-positive height: ${label.height}`);
+    }
+    if (Number.isFinite(label.style.fixedWidth) && label.style.fixedWidth < 0) {
+      problems.push(`${describeText(label)} has negative fixedWidth: ${label.style.fixedWidth}`);
+    }
+    if (Number.isFinite(label.style.fixedHeight) && label.style.fixedHeight < 0) {
+      problems.push(`${describeText(label)} has negative fixedHeight: ${label.style.fixedHeight}`);
+    }
+    if (Number.isFinite(label.style.resolution) && label.style.resolution <= 0) {
+      problems.push(`${describeText(label)} has non-positive resolution: ${label.style.resolution}`);
+    }
+    const bounds = label.getBounds();
+    for (const [property, value] of Object.entries({
+      boundsX: bounds.x,
+      boundsY: bounds.y,
+      boundsWidth: bounds.width,
+      boundsHeight: bounds.height
+    })) {
+      requireFinite(problems, label, property, value);
+    }
+  }
+  return problems;
+}
+function collectBitmapTextHealthProblems(scene) {
+  const problems = [];
+  for (const label of collectSceneBitmapTexts(scene)) {
+    const text = Array.isArray(label.text) ? label.text.join("\n") : label.text;
+    if (!/\S/u.test(text)) continue;
+    const missing = collectMissingBitmapGlyphs(text, label.fontData.chars);
+    if (missing.length > 0) {
+      problems.push(
+        `BitmapText${label.name ? ` name=${JSON.stringify(label.name)}` : ""} value=${JSON.stringify(text)} is missing glyphs: ${missing.join(", ")}`
+      );
+    }
+  }
+  return problems;
+}
+function assertSceneTextHealth(scene) {
+  const problems = [
+    ...collectTextHealthProblems(scene),
+    ...collectBitmapTextHealthProblems(scene)
+  ];
+  if (problems.length === 0) return;
+  throw new Error([
+    `Phaser text health check failed in scene ${JSON.stringify(scene.scene.key)}:`,
+    ...problems.map((problem) => `- ${problem}`),
+    "Fix optional TextStyle values by omitting them or using Phaser defaults (for example fixedWidth: value ?? 0)."
+  ].join("\n"));
+}
+
+// src/phaser-runtime-assertions.ts
+import * as Phaser2 from "phaser";
+function collectObjects(scene) {
+  const objects = [];
+  const visited = /* @__PURE__ */ new Set();
+  const visit = (object) => {
+    if (visited.has(object)) return;
+    visited.add(object);
+    objects.push(object);
+    if (object instanceof Phaser2.GameObjects.Container) object.list.forEach(visit);
+    if (object instanceof Phaser2.GameObjects.Layer) object.getChildren().forEach(visit);
+  };
+  scene.children.getChildren().forEach(visit);
+  return objects;
+}
+function describeObject(object) {
+  return `${object.type}${object.name ? ` name=${JSON.stringify(object.name)}` : ""}`;
+}
+function isEffectivelyVisible(object) {
+  let current = object;
+  while (current) {
+    const state = current;
+    if (state.visible === false || state.alpha === 0 || state.scaleX === 0 || state.scaleY === 0) {
+      return false;
+    }
+    current = state.parentContainer ?? null;
+  }
+  return true;
+}
+function requireFiniteProperty(problems, subject, target, property) {
+  if (!(property in target)) return;
+  const value = Reflect.get(target, property);
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    problems.push(`${subject} has non-finite ${property}: ${String(value)}`);
+  }
+}
+function requireFiniteVector(problems, subject, target, property) {
+  if (!(property in target)) return;
+  const vector = Reflect.get(target, property);
+  if (!vector || typeof vector !== "object") return;
+  for (const axis of ["x", "y"]) {
+    if (!(axis in vector)) continue;
+    const value = Reflect.get(vector, axis);
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+      problems.push(`${subject} has non-finite ${property}.${axis}: ${String(value)}`);
+    }
+  }
+}
+function checksObjectState(object) {
+  return object.active !== false || isEffectivelyVisible(object) || Boolean(object.input?.enabled);
+}
+function collectGameObjectHealthProblems(scene) {
+  const problems = [];
+  const transformProperties = ["x", "y", "scaleX", "scaleY", "rotation"];
+  const optionalComponents = [
+    ["setAlpha", ["alpha", "_alphaTL", "_alphaTR", "_alphaBL", "_alphaBR"]],
+    ["setDepth", ["depth"]],
+    ["setOrigin", ["originX", "originY", "displayOriginX", "displayOriginY"]],
+    ["setScrollFactor", ["scrollFactorX", "scrollFactorY"]]
+  ];
+  for (const object of collectObjects(scene)) {
+    if (!checksObjectState(object)) continue;
+    const subject = describeObject(object);
+    const target = object;
+    if (typeof target.setPosition === "function") {
+      for (const property of transformProperties) {
+        requireFiniteProperty(problems, subject, object, property);
+      }
+    }
+    for (const [method, properties] of optionalComponents) {
+      if (typeof target[method] !== "function") continue;
+      for (const property of properties) {
+        requireFiniteProperty(problems, subject, object, property);
+      }
+    }
+  }
+  return problems;
+}
+function collectCameraHealthProblems(scene) {
+  const problems = [];
+  const properties = [
+    "x",
+    "y",
+    "width",
+    "height",
+    "scrollX",
+    "scrollY",
+    "rotation",
+    "zoomX",
+    "zoomY"
+  ];
+  for (const camera of scene.cameras?.cameras ?? []) {
+    if (camera.visible === false) continue;
+    const subject = `Camera ${JSON.stringify(camera.name || String(camera.id))}`;
+    for (const property of properties) {
+      requireFiniteProperty(problems, subject, camera, property);
+    }
+    if (camera.width !== 0 && camera.height !== 0 && (camera.zoomX === 0 || camera.zoomY === 0)) {
+      problems.push(`${subject} has zero zoom while its viewport is active`);
+    }
+  }
+  return problems;
+}
+function getArcadeBodyCollection(value) {
+  if (value instanceof Set) return [...value];
+  if (!value || typeof value !== "object") return void 0;
+  const entries = Reflect.get(value, "entries");
+  return Array.isArray(entries) ? entries : void 0;
+}
+function getArcadeWorldBodies(world) {
+  if (!world || typeof world !== "object") return void 0;
+  const bodies = getArcadeBodyCollection(Reflect.get(world, "bodies"));
+  const staticBodies = getArcadeBodyCollection(Reflect.get(world, "staticBodies"));
+  return bodies && staticBodies ? [...bodies, ...staticBodies] : void 0;
+}
+function collectArcadeBodyHealthProblems(scene) {
+  const problems = [];
+  const bodies = getArcadeWorldBodies(scene.physics?.world);
+  if (!bodies) return problems;
+  for (const body of bodies) {
+    if (body.enable === false) continue;
+    const gameObject = body.gameObject;
+    const subject = gameObject ? `Arcade Body for ${describeObject(gameObject)}` : "Arcade Body";
+    for (const property of ["position", "velocity", "acceleration", "gravity", "offset", "center"]) {
+      requireFiniteVector(problems, subject, body, property);
+    }
+    for (const property of ["width", "height", "halfWidth", "halfHeight", "rotation"]) {
+      requireFiniteProperty(problems, subject, body, property);
+    }
+  }
+  return problems;
+}
+function usesCustomHitArea(object) {
+  return Boolean(object.input?.customHitArea);
+}
+function collectInteractiveHealthProblems(scene) {
+  const problems = [];
+  for (const object of collectObjects(scene)) {
+    if (object.active === false || !isEffectivelyVisible(object) || !object.input?.enabled) continue;
+    if (usesCustomHitArea(object)) continue;
+    const hitArea = object.input.hitArea;
+    if (!hitArea) {
+      problems.push(`${describeObject(object)} has no default hit area`);
+      continue;
+    }
+    const values = [hitArea.x, hitArea.y, hitArea.width, hitArea.height];
+    if (!values.every(Number.isFinite) || hitArea.width <= 0 || hitArea.height <= 0) {
+      problems.push(
+        `${describeObject(object)} has invalid default hit area (${hitArea.x}, ${hitArea.y}, ${hitArea.width}, ${hitArea.height})`
+      );
+    }
+  }
+  return problems;
+}
+function assertSceneRuntimeHealth(scene) {
+  const problems = [
+    ...collectGameObjectHealthProblems(scene),
+    ...collectCameraHealthProblems(scene),
+    ...collectArcadeBodyHealthProblems(scene)
+  ];
+  if (problems.length === 0) return;
+  throw new Error([
+    `Phaser runtime health check failed in scene ${JSON.stringify(scene.scene.key)}:`,
+    ...problems.map((problem) => `- ${problem}`),
+    "Keep values consumed by Phaser finite; zero size and zero scale remain allowed."
+  ].join("\n"));
+}
+function assertSceneInteractiveHealth(scene) {
+  const problems = collectInteractiveHealthProblems(scene);
+  if (problems.length === 0) return;
+  throw new Error([
+    `Phaser interactive health check failed in scene ${JSON.stringify(scene.scene.key)}:`,
+    ...problems.map((problem) => `- ${problem}`),
+    "Fix the default hit area or disable input before making the object interactive."
+  ].join("\n"));
+}
+
+// src/phaser-headless-host.ts
+async function createHeadlessGame(scene, options = {}) {
+  const { bootTimeoutMs = 2e3, additionalScenes = [], ...config } = options;
+  let game;
+  let settled = false;
+  let runtimeError;
+  let hasRuntimeError = false;
+  let restoreHostGuards = () => {
+  };
+  let removeRuntimeListeners = () => {
+  };
+  const transitions = [];
+  const evidence = {
+    frames: 0,
+    physicsSteps: 0,
+    mouseEvents: 0,
+    clicks: 0,
+    transitions
+  };
+  const created = new Promise((resolve, reject) => {
+    const guardedScenes = /* @__PURE__ */ new WeakSet();
+    const restoreGuards = [];
+    let removeReadinessCheck = () => {
+    };
+    const finish = (error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      window.clearTimeout(timeout);
+      removeReadinessCheck();
+      if (error === void 0) {
+        game?.loop.stop();
+        resolve();
+      } else {
+        removeRuntimeListeners();
+        reject(error);
+      }
+    };
+    const reportError = (error) => {
+      const normalizedError = error instanceof Error ? error : new Error(`Unhandled Phaser runtime error: ${String(error)}`);
+      if (!settled) {
+        finish(normalizedError);
+      } else if (!hasRuntimeError) {
+        hasRuntimeError = true;
+        runtimeError = normalizedError;
+      }
+    };
+    const onWindowError = (event) => {
+      if (event.defaultPrevented) return;
+      event.preventDefault();
+      const error = event.error ?? new Error(event.message);
+      queueMicrotask(() => {
+        reportError(error);
+      });
+    };
+    const onUnhandledRejection = (event) => {
+      queueMicrotask(() => {
+        if (!event.defaultPrevented) reportError(event.reason);
+      });
+    };
+    const timeout = window.setTimeout(() => {
+      finish(new Error(`Phaser HEADLESS boot timed out after ${bootTimeoutMs}ms`));
+    }, bootTimeoutMs);
+    window.addEventListener("error", onWindowError, true);
+    window.addEventListener("unhandledrejection", onUnhandledRejection);
+    removeRuntimeListeners = () => {
+      window.removeEventListener("error", onWindowError, true);
+      window.removeEventListener("unhandledrejection", onUnhandledRejection);
+    };
+    const guardScene = (currentScene) => {
+      if (guardedScenes.has(currentScene)) return;
+      guardedScenes.add(currentScene);
+      const scenePlugin = currentScene.scene;
+      for (const method of ["start", "launch", "switch", "sleep", "wake"]) {
+        const original = scenePlugin[method];
+        if (typeof original !== "function") continue;
+        scenePlugin[method] = (key, ...args) => {
+          const target = key === void 0 ? currentScene : typeof key === "string" ? currentScene.scene.get(key) : key;
+          if (target) guardScene(target);
+          const from = currentScene.sys.settings.key;
+          const to = key === void 0 ? from : typeof key === "string" ? key : key.sys.settings.key;
+          if (from && to) transitions.push({ from, to, method });
+          const callArgs = key === void 0 && args.length === 0 ? [] : [key, ...args];
+          return Reflect.apply(original, currentScene.scene, callArgs);
+        };
+        restoreGuards.push(() => {
+          scenePlugin[method] = original;
+        });
+      }
+      for (const hook of ["init", "preload", "create", "update"]) {
+        const original = Reflect.get(currentScene, hook);
+        if (typeof original !== "function") continue;
+        const ownDescriptor = Object.getOwnPropertyDescriptor(currentScene, hook);
+        Reflect.set(currentScene, hook, function guardedLifecycleHook(...args) {
+          try {
+            const result = Reflect.apply(original, this, args);
+            if (result && typeof result === "object" && "then" in result) {
+              const completion = Promise.resolve(result);
+              if (currentScene === scene && hook === "create" && !settled) {
+                completion.then(() => window.setTimeout(() => finish(), 0), reportError);
+              } else {
+                completion.catch(reportError);
+              }
+            } else if (currentScene === scene && hook === "create" && !settled) {
+              window.setTimeout(() => finish(), 0);
+            }
+            return result;
+          } catch (error) {
+            reportError(error);
+            return void 0;
+          }
+        });
+        restoreGuards.push(() => {
+          if (ownDescriptor) {
+            Object.defineProperty(currentScene, hook, ownDescriptor);
+          } else {
+            Reflect.deleteProperty(currentScene, hook);
+          }
+        });
+      }
+    };
+    restoreHostGuards = () => {
+      while (restoreGuards.length > 0) restoreGuards.pop()?.();
+    };
+    const fps = {
+      ...config.fps,
+      target: config.fps?.target ?? 60,
+      forceSetTimeOut: true
+    };
+    const audio = {
+      ...config.audio,
+      noAudio: true
+    };
+    try {
+      game = new Phaser3.Game({
+        width: 320,
+        height: 180,
+        banner: false,
+        autoFocus: false,
+        seed: ["phaser-headless-test"],
+        physics: {
+          default: "arcade",
+          arcade: {
+            gravity: { x: 0, y: 0 },
+            fixedStep: true
+          }
+        },
+        ...config,
+        type: Phaser3.HEADLESS,
+        fps,
+        audio,
+        callbacks: {
+          preBoot(bootedGame) {
+            const manager = bootedGame.scene;
+            const originalStart = manager.start;
+            manager.start = ((key, data) => {
+              const currentScene = typeof key === "string" ? manager.getScene(key) : key;
+              if (currentScene) guardScene(currentScene);
+              return Reflect.apply(originalStart, manager, [key, data]);
+            });
+            restoreGuards.push(() => {
+              manager.start = originalStart;
+            });
+          },
+          postBoot(bootedGame) {
+            const checkReadiness = () => {
+              if (typeof Reflect.get(scene, "create") !== "function" && scene.sys.isActive()) {
+                finish();
+              }
+            };
+            bootedGame.events.on(Phaser3.Core.Events.POST_STEP, checkReadiness);
+            removeReadinessCheck = () => {
+              bootedGame.events.off(Phaser3.Core.Events.POST_STEP, checkReadiness);
+            };
+          }
+        },
+        scene: additionalScenes.length > 0 ? [scene, ...additionalScenes] : scene
+      });
+    } catch (error) {
+      reportError(error);
+    }
+  });
+  try {
+    await created;
+  } catch (error) {
+    if (game) {
+      game.destroy(true);
+      game.headlessStep(game.loop.lastTime, 0);
+    }
+    restoreHostGuards();
+    throw error;
+  }
+  const readyGame = game;
+  const throwRuntimeError = () => {
+    if (hasRuntimeError) {
+      throw runtimeError instanceof Error ? runtimeError : new Error(`Unhandled Phaser runtime error: ${String(runtimeError)}`);
+    }
+  };
+  const canvas = readyGame.canvas;
+  if (!canvas) {
+    removeRuntimeListeners();
+    restoreHostGuards();
+    readyGame.destroy(true);
+    readyGame.headlessStep(readyGame.loop.lastTime, 0);
+    throw new Error("Phaser HEADLESS did not create an input canvas");
+  }
+  const inputWindow = canvas.ownerDocument.defaultView;
+  if (!inputWindow) {
+    removeRuntimeListeners();
+    restoreHostGuards();
+    readyGame.destroy(true);
+    readyGame.headlessStep(readyGame.loop.lastTime, 0);
+    throw new Error("Phaser HEADLESS input canvas is not attached to a DOM Window");
+  }
+  let canvasBounds = {
+    left: 0,
+    top: 0,
+    width: canvas.width,
+    height: canvas.height
+  };
+  const setCanvasBounds = (bounds) => {
+    const values = [bounds.left, bounds.top, bounds.width, bounds.height];
+    if (!values.every(Number.isFinite) || bounds.width <= 0 || bounds.height <= 0) {
+      throw new Error(
+        `HEADLESS canvas bounds must be finite with positive dimensions; received ${JSON.stringify(bounds)}`
+      );
+    }
+    canvasBounds = { ...bounds };
+    canvas.getBoundingClientRect = () => ({
+      x: canvasBounds.left,
+      y: canvasBounds.top,
+      left: canvasBounds.left,
+      top: canvasBounds.top,
+      right: canvasBounds.left + canvasBounds.width,
+      bottom: canvasBounds.top + canvasBounds.height,
+      width: canvasBounds.width,
+      height: canvasBounds.height,
+      toJSON: () => ({ ...canvasBounds })
+    });
+    readyGame.scale.updateBounds();
+    readyGame.scale.displayScale.set(
+      readyGame.scale.baseSize.width / canvasBounds.width,
+      readyGame.scale.baseSize.height / canvasBounds.height
+    );
+  };
+  setCanvasBounds(canvasBounds);
+  const gameToClient = (x, y) => {
+    if (!Number.isFinite(x) || !Number.isFinite(y)) {
+      throw new Error(`HEADLESS input coordinates must be finite; received (${x}, ${y})`);
+    }
+    return {
+      clientX: canvasBounds.left + x / readyGame.scale.displayScale.x,
+      clientY: canvasBounds.top + y / readyGame.scale.displayScale.y
+    };
+  };
+  const assertHealth = () => {
+    for (const currentScene of readyGame.scene.getScenes(false)) {
+      if (!currentScene.sys.isActive() && !currentScene.sys.isPaused()) continue;
+      assertSceneTextHealth(currentScene);
+      assertSceneInteractiveHealth(currentScene);
+      assertSceneRuntimeHealth(currentScene);
+    }
+  };
+  const settleRuntime = async () => {
+    await new Promise((resolve) => inputWindow.setTimeout(resolve, 0));
+    throwRuntimeError();
+    assertHealth();
+  };
+  const dispatchMouse = async (type, x, y, buttons) => {
+    const { clientX, clientY } = gameToClient(x, y);
+    canvas.dispatchEvent(new inputWindow.MouseEvent(type, {
+      bubbles: true,
+      cancelable: true,
+      button: 0,
+      buttons,
+      clientX,
+      clientY
+    }));
+    evidence.mouseEvents += 1;
+    await settleRuntime();
+  };
+  const input = {
+    canvas,
+    setCanvasBounds,
+    gameToClient,
+    settle: settleRuntime,
+    mouse: {
+      move: (x, y, buttons = 0) => dispatchMouse("mousemove", x, y, buttons),
+      down: (x, y) => dispatchMouse("mousedown", x, y, 1),
+      up: (x, y) => dispatchMouse("mouseup", x, y, 0),
+      async click(x, y) {
+        evidence.clicks += 1;
+        await dispatchMouse("mousemove", x, y, 0);
+        await dispatchMouse("mousedown", x, y, 1);
+        await dispatchMouse("mouseup", x, y, 0);
+      }
+    }
+  };
+  const frameDurationMs = 1e3 / (config.fps?.target ?? 60);
+  const stepFrame = () => {
+    readyGame.loop.step(readyGame.loop.lastTime + frameDurationMs);
+    evidence.frames += 1;
+  };
+  const stepFrames = (count = 1) => {
+    throwRuntimeError();
+    for (let frame = 0; frame < count; frame += 1) stepFrame();
+    throwRuntimeError();
+    assertHealth();
+  };
+  try {
+    throwRuntimeError();
+    assertHealth();
+  } catch (error) {
+    removeRuntimeListeners();
+    restoreHostGuards();
+    readyGame.destroy(true);
+    readyGame.headlessStep(readyGame.loop.lastTime, 0);
+    throw error;
+  }
+  let destroyed = false;
+  return {
+    game: readyGame,
+    scene,
+    settle: settleRuntime,
+    input,
+    evidence,
+    assertGameplayEvidence(requirements = {}) {
+      if (requirements.requireInput && evidence.mouseEvents === 0) {
+        throw new Error("Gameplay evidence is missing real HEADLESS input events.");
+      }
+      if (requirements.requireFrameAdvance && evidence.frames === 0) {
+        throw new Error("Gameplay evidence is missing complete Phaser frame advancement.");
+      }
+      if (requirements.requirePhysicsStep && evidence.physicsSteps === 0) {
+        throw new Error("Gameplay evidence is missing Arcade Physics advancement.");
+      }
+      const requiredTransitions = requirements.requireTransition === void 0 ? [] : typeof requirements.requireTransition === "string" ? [requirements.requireTransition] : requirements.requireTransition;
+      for (const target of requiredTransitions) {
+        if (!evidence.transitions.some((transition) => transition.to === target)) {
+          throw new Error(`Gameplay evidence is missing a transition to ${target}.`);
+        }
+      }
+    },
+    stepFrames,
+    async stepFramesAsync(count = 1) {
+      stepFrames(count);
+      await settleRuntime();
+    },
+    stepUntil(condition, maxFrames = 120) {
+      throwRuntimeError();
+      for (let frame = 0; frame <= maxFrames; frame += 1) {
+        if (condition()) {
+          assertHealth();
+          return frame;
+        }
+        if (frame < maxFrames) {
+          stepFrame();
+          throwRuntimeError();
+        }
+      }
+      assertHealth();
+      throw new Error(`Condition was not met within ${maxFrames} complete Phaser frames`);
+    },
+    stepPhysics(steps = 1) {
+      throwRuntimeError();
+      const world = scene.physics?.world;
+      if (!world || !getArcadeWorldBodies(world) || typeof world.singleStep !== "function") {
+        throw new Error("stepPhysics() requires an Arcade Physics world; use stepFrames() for other configurations.");
+      }
+      for (let step = 0; step < steps; step += 1) {
+        scene.physics.world.singleStep();
+        evidence.physicsSteps += 1;
+      }
+      throwRuntimeError();
+      assertHealth();
+    },
+    assertTextHealth() {
+      assertSceneTextHealth(scene);
+    },
+    destroy() {
+      if (destroyed) {
+        return;
+      }
+      destroyed = true;
+      try {
+        readyGame.destroy(true);
+        readyGame.headlessStep(readyGame.loop.lastTime, 0);
+        throwRuntimeError();
+      } finally {
+        removeRuntimeListeners();
+        restoreHostGuards();
+      }
+    }
+  };
+}
+
+// src/gameplay-contracts.ts
+function registerGameplayContract(context, options) {
+  const task = context;
+  const metadata = {
+    id: options.id,
+    requirements: {
+      requireInput: options.requireInput,
+      requireFrameAdvance: options.requireFrameAdvance,
+      requirePhysicsStep: options.requirePhysicsStep,
+      requireTransition: options.requireTransition
+    }
+  };
+  task.task.meta.gameplayContract = metadata;
+  let host;
+  let verified = false;
+  let testFailed = false;
+  context.onTestFailed?.(() => {
+    testFailed = true;
+  });
+  const verify = () => {
+    if (verified) return;
+    if (!host) {
+      throw new Error(`Gameplay contract "${options.id}" did not attach a HEADLESS host.`);
+    }
+    host.assertGameplayEvidence(metadata.requirements);
+    metadata.evidence = {
+      frames: host.evidence.frames,
+      physicsSteps: host.evidence.physicsSteps,
+      mouseEvents: host.evidence.mouseEvents,
+      clicks: host.evidence.clicks,
+      transitions: host.evidence.transitions.map((transition) => ({ ...transition }))
+    };
+    verified = true;
+  };
+  context.onTestFinished(() => {
+    if (testFailed) return;
+    verify();
+  });
+  return {
+    attachHost(currentHost) {
+      if (host) {
+        throw new Error(`Gameplay contract "${options.id}" attached more than one host.`);
+      }
+      host = currentHost;
+    },
+    verify
+  };
+}
+export {
+  assertSceneInteractiveHealth,
+  assertSceneRuntimeHealth,
+  assertSceneTextHealth,
+  collectMissingBitmapGlyphs,
+  createHeadlessGame,
+  registerGameplayContract
+};