miaoda-game-devkit 0.1.0 → 0.2.0

package/dist/lint/phaser-headless.contract.mjs

@@ -0,0 +1,1575 @@
+// src/lint/phaser-headless.test.ts
+import * as Phaser4 from "phaser";
+import { afterEach, describe, expect, it } from "vitest";
+
+// 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 registeredScenes = [];
+  const visitedScenes = [];
+  const restartedScenes = [];
+  const checkpoints = [];
+  const appendUnique = (values, value) => {
+    if (value && !values.includes(value)) values.push(value);
+  };
+  const assertStepCount = (value, name) => {
+    if (!Number.isSafeInteger(value) || value < 0) {
+      throw new Error(
+        `${name} must be a non-negative safe integer; received ${value}`
+      );
+    }
+  };
+  const evidence = {
+    frames: 0,
+    physicsSteps: 0,
+    mouseEvents: 0,
+    keyboardEvents: 0,
+    touchEvents: 0,
+    clicks: 0,
+    registeredScenes,
+    visitedScenes,
+    restartedScenes,
+    checkpoints,
+    destroyed: false,
+    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;
+        });
+      }
+      const originalRestart = scenePlugin.restart;
+      if (typeof originalRestart === "function") {
+        scenePlugin.restart = (...args) => {
+          appendUnique(restartedScenes, currentScene.sys.settings.key);
+          return Reflect.apply(originalRestart, currentScene.scene, args);
+        };
+        restoreGuards.push(() => {
+          scenePlugin.restart = originalRestart;
+        });
+      }
+      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"],
+        ...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)) {
+      appendUnique(registeredScenes, currentScene.sys.settings.key);
+      if (!currentScene.sys.isActive() && !currentScene.sys.isPaused())
+        continue;
+      appendUnique(visitedScenes, currentScene.sys.settings.key);
+      assertSceneTextHealth(currentScene);
+      assertSceneInteractiveHealth(currentScene);
+      assertSceneRuntimeHealth(currentScene);
+    }
+  };
+  const settleRuntime = async () => {
+    await new Promise((resolve) => inputWindow.setTimeout(resolve, 0));
+    throwRuntimeError();
+    assertHealth();
+  };
+  const getEventTarget = (target, kind) => {
+    if (!target || typeof Reflect.get(target, "dispatchEvent") !== "function") {
+      throw new Error(
+        `Phaser HEADLESS ${kind} input target cannot dispatch DOM events`
+      );
+    }
+    return target;
+  };
+  const dispatchMouse = async (type, x, y, buttons) => {
+    const { clientX, clientY } = gameToClient(x, y);
+    const mouseTarget = getEventTarget(readyGame.input.mouse?.target, "mouse");
+    mouseTarget.dispatchEvent(
+      new inputWindow.MouseEvent(type, {
+        bubbles: true,
+        cancelable: true,
+        button: 0,
+        buttons,
+        clientX,
+        clientY
+      })
+    );
+    evidence.mouseEvents += 1;
+    await settleRuntime();
+  };
+  const keyIdentity = (keyCode) => {
+    if (keyCode >= 65 && keyCode <= 90) {
+      const letter = String.fromCharCode(keyCode);
+      return { key: letter.toLowerCase(), code: `Key${letter}` };
+    }
+    if (keyCode >= 48 && keyCode <= 57) {
+      const digit = String.fromCharCode(keyCode);
+      return { key: digit, code: `Digit${digit}` };
+    }
+    const identities = /* @__PURE__ */ new Map([
+      [
+        Phaser3.Input.Keyboard.KeyCodes.LEFT,
+        { key: "ArrowLeft", code: "ArrowLeft" }
+      ],
+      [
+        Phaser3.Input.Keyboard.KeyCodes.RIGHT,
+        { key: "ArrowRight", code: "ArrowRight" }
+      ],
+      [Phaser3.Input.Keyboard.KeyCodes.UP, { key: "ArrowUp", code: "ArrowUp" }],
+      [
+        Phaser3.Input.Keyboard.KeyCodes.DOWN,
+        { key: "ArrowDown", code: "ArrowDown" }
+      ],
+      [Phaser3.Input.Keyboard.KeyCodes.SPACE, { key: " ", code: "Space" }],
+      [Phaser3.Input.Keyboard.KeyCodes.ENTER, { key: "Enter", code: "Enter" }],
+      [Phaser3.Input.Keyboard.KeyCodes.ESC, { key: "Escape", code: "Escape" }]
+    ]);
+    return identities.get(keyCode) ?? { key: "", code: "" };
+  };
+  const dispatchKeyboard = async (type, keyCode, options2 = {}) => {
+    if (!Number.isInteger(keyCode) || keyCode < 0) {
+      throw new Error(
+        `HEADLESS keyboard keyCode must be a non-negative integer; received ${keyCode}`
+      );
+    }
+    const identity = keyIdentity(keyCode);
+    const event = new inputWindow.KeyboardEvent(type, {
+      bubbles: true,
+      cancelable: true,
+      key: options2.key ?? identity.key,
+      code: options2.code ?? identity.code,
+      repeat: options2.repeat ?? false,
+      altKey: options2.altKey ?? false,
+      ctrlKey: options2.ctrlKey ?? false,
+      metaKey: options2.metaKey ?? false,
+      shiftKey: options2.shiftKey ?? false
+    });
+    Object.defineProperties(event, {
+      // Phaser KeyboardManager 仍使用这些兼容旧浏览器的数字字段。
+      keyCode: { value: keyCode },
+      which: { value: keyCode }
+    });
+    const keyboardTarget = getEventTarget(
+      readyGame.input.keyboard?.target,
+      "keyboard"
+    );
+    keyboardTarget.dispatchEvent(event);
+    evidence.keyboardEvents += 1;
+    await settleRuntime();
+  };
+  const activeTouches = /* @__PURE__ */ new Map();
+  const createTouch = (x, y, identifier, target) => {
+    if (!Number.isInteger(identifier) || identifier < 0) {
+      throw new Error(
+        `HEADLESS touch identifier must be a non-negative integer; received ${identifier}`
+      );
+    }
+    const { clientX, clientY } = gameToClient(x, y);
+    return {
+      identifier,
+      target,
+      clientX,
+      clientY,
+      pageX: clientX,
+      pageY: clientY,
+      screenX: clientX,
+      screenY: clientY,
+      radiusX: 1,
+      radiusY: 1,
+      rotationAngle: 0,
+      force: 1
+    };
+  };
+  const dispatchTouch = async (type, x, y, identifier) => {
+    if (type === "touchstart" && activeTouches.has(identifier)) {
+      throw new Error(
+        `HEADLESS touch identifier ${identifier} is already active`
+      );
+    }
+    if (type !== "touchstart" && !activeTouches.has(identifier)) {
+      throw new Error(`HEADLESS touch identifier ${identifier} is not active`);
+    }
+    const touchTarget = getEventTarget(readyGame.input.touch?.target, "touch");
+    const changedTouch = createTouch(x, y, identifier, touchTarget);
+    if (type === "touchstart" || type === "touchmove") {
+      activeTouches.set(identifier, changedTouch);
+    } else {
+      activeTouches.delete(identifier);
+    }
+    const touches = [...activeTouches.values()];
+    const event = new inputWindow.Event(type, {
+      bubbles: true,
+      cancelable: true
+    });
+    Object.defineProperties(event, {
+      changedTouches: { value: [changedTouch] },
+      targetTouches: { value: touches },
+      touches: { value: touches }
+    });
+    const document = inputWindow.document;
+    const originalElementFromPoint = document.elementFromPoint;
+    const originalElementFromPointDescriptor = Object.getOwnPropertyDescriptor(
+      document,
+      "elementFromPoint"
+    );
+    Object.defineProperty(document, "elementFromPoint", {
+      configurable: true,
+      value(clientX, clientY) {
+        const insideCanvas = clientX >= canvasBounds.left && clientX <= canvasBounds.left + canvasBounds.width && clientY >= canvasBounds.top && clientY <= canvasBounds.top + canvasBounds.height;
+        return insideCanvas ? canvas : originalElementFromPoint?.call(document, clientX, clientY) ?? null;
+      }
+    });
+    try {
+      touchTarget.dispatchEvent(event);
+      evidence.touchEvents += 1;
+    } finally {
+      if (originalElementFromPointDescriptor) {
+        Object.defineProperty(
+          document,
+          "elementFromPoint",
+          originalElementFromPointDescriptor
+        );
+      } else {
+        Reflect.deleteProperty(document, "elementFromPoint");
+      }
+    }
+    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);
+      }
+    },
+    keyboard: {
+      down: (keyCode, options2) => dispatchKeyboard("keydown", keyCode, options2),
+      up: (keyCode, options2) => dispatchKeyboard("keyup", keyCode, options2),
+      async press(keyCode, options2) {
+        await dispatchKeyboard("keydown", keyCode, options2);
+        await dispatchKeyboard("keyup", keyCode, options2);
+      }
+    },
+    touch: {
+      start: (x, y, identifier = 1) => dispatchTouch("touchstart", x, y, identifier),
+      move: (x, y, identifier = 1) => dispatchTouch("touchmove", x, y, identifier),
+      end: (x, y, identifier = 1) => dispatchTouch("touchend", x, y, identifier),
+      cancel: (x, y, identifier = 1) => dispatchTouch("touchcancel", x, y, identifier),
+      async tap(x, y, identifier = 1) {
+        await dispatchTouch("touchstart", x, y, identifier);
+        await dispatchTouch("touchend", x, y, identifier);
+      }
+    }
+  };
+  const frameDurationMs = 1e3 / (config.fps?.target ?? 60);
+  const stepFrame = () => {
+    readyGame.loop.step(readyGame.loop.lastTime + frameDurationMs);
+    evidence.frames += 1;
+  };
+  const stepFrames = (count = 1) => {
+    assertStepCount(count, "stepFrames count");
+    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 = {}) {
+      const inputEvents = evidence.mouseEvents + evidence.keyboardEvents + evidence.touchEvents;
+      if (requirements.requireInput && inputEvents === 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}.`
+          );
+        }
+      }
+      const requiredScenes = requirements.requireScene === void 0 ? [] : typeof requirements.requireScene === "string" ? [requirements.requireScene] : requirements.requireScene;
+      for (const sceneKey of requiredScenes) {
+        if (!evidence.visitedScenes.includes(sceneKey)) {
+          throw new Error(
+            `Gameplay evidence is missing a visit to Scene ${sceneKey}.`
+          );
+        }
+      }
+      const requiredRestarts = requirements.requireRestart === void 0 ? [] : typeof requirements.requireRestart === "string" ? [requirements.requireRestart] : requirements.requireRestart;
+      for (const sceneKey of requiredRestarts) {
+        if (!evidence.restartedScenes.includes(sceneKey)) {
+          throw new Error(
+            `Gameplay evidence is missing a restart of Scene ${sceneKey}.`
+          );
+        }
+      }
+      const requiredCheckpoints = requirements.requireCheckpoint === void 0 ? [] : typeof requirements.requireCheckpoint === "string" ? [requirements.requireCheckpoint] : requirements.requireCheckpoint;
+      for (const checkpoint of requiredCheckpoints) {
+        if (!evidence.checkpoints.includes(checkpoint)) {
+          throw new Error(
+            `Gameplay evidence is missing checkpoint ${checkpoint}.`
+          );
+        }
+      }
+      if (requirements.requireDestroy && !evidence.destroyed) {
+        throw new Error(
+          "Gameplay evidence is missing HEADLESS host destruction."
+        );
+      }
+    },
+    stepFrames,
+    async stepFramesAsync(count = 1) {
+      stepFrames(count);
+      await settleRuntime();
+    },
+    stepUntil(condition, maxFrames = 120) {
+      assertStepCount(maxFrames, "stepUntil maxFrames");
+      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) {
+      assertStepCount(steps, "stepPhysics steps");
+      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();
+    },
+    checkpoint(id) {
+      const normalizedId = id.trim();
+      if (!normalizedId || normalizedId.length > 120) {
+        throw new Error(
+          "Gameplay checkpoint id must contain 1 to 120 non-whitespace characters."
+        );
+      }
+      appendUnique(checkpoints, normalizedId);
+    },
+    assertTextHealth() {
+      assertSceneTextHealth(scene);
+    },
+    destroy() {
+      if (destroyed) {
+        return;
+      }
+      destroyed = true;
+      try {
+        readyGame.destroy(true);
+        readyGame.headlessStep(readyGame.loop.lastTime, 0);
+        throwRuntimeError();
+        evidence.destroyed = true;
+      } finally {
+        removeRuntimeListeners();
+        restoreHostGuards();
+      }
+    }
+  };
+}
+
+// src/lint/phaser-headless.test.ts
+var SmokeScene = class extends Phaser4.Scene {
+  movingObject;
+  randomValue = 0;
+  updates = 0;
+  textObject;
+  constructor() {
+    super("SmokeScene");
+  }
+  create() {
+    this.randomValue = Phaser4.Math.RND.frac();
+    this.movingObject = this.add.zone(40, 50, 16, 16);
+    this.textObject = this.add.text(8, 8, "READY", { fontSize: "16px" });
+    if (this.physics) {
+      this.physics.add.existing(this.movingObject);
+      const body = this.movingObject.body;
+      body.setVelocityX(60);
+    }
+  }
+  update() {
+    this.updates += 1;
+  }
+};
+var LayeredInputScene = class extends Phaser4.Scene {
+  firstHits = 0;
+  secondHits = 0;
+  constructor() {
+    super("LayeredInputScene");
+  }
+  create() {
+    this.add.zone(80, 60, 40, 40).setInteractive().on("pointerup", () => {
+      this.firstHits += 1;
+    });
+    this.add.zone(80, 60, 40, 40).setInteractive().on("pointerup", () => {
+      this.secondHits += 1;
+    });
+  }
+};
+var KeyboardInputScene = class extends Phaser4.Scene {
+  playerX = 0;
+  rightKey;
+  constructor() {
+    super("KeyboardInputScene");
+  }
+  create() {
+    this.rightKey = this.input.keyboard.addKey(
+      Phaser4.Input.Keyboard.KeyCodes.RIGHT
+    );
+  }
+  update() {
+    if (this.rightKey.isDown) this.playerX += 1;
+  }
+};
+var TouchInputScene = class extends Phaser4.Scene {
+  moves = 0;
+  taps = 0;
+  wasTouch = false;
+  constructor() {
+    super("TouchInputScene");
+  }
+  create() {
+    this.add.zone(80, 60, 40, 40).setInteractive().on("pointerup", (pointer) => {
+      this.taps += 1;
+      this.wasTouch = pointer.wasTouch;
+    });
+    this.input.on("pointermove", (pointer) => {
+      if (pointer.wasTouch) this.moves += 1;
+    });
+  }
+};
+describe("Phaser HEADLESS host", () => {
+  let host;
+  afterEach(() => {
+    host?.destroy();
+    host = void 0;
+  });
+  it("boots a scene without a renderer and advances Arcade Physics", async () => {
+    host = await createHeadlessGame(new SmokeScene(), {
+      physics: {
+        default: "arcade",
+        arcade: { gravity: { x: 0, y: 0 }, fixedStep: true }
+      }
+    });
+    expect(host.game.renderer).toBeNull();
+    expect(host.scene.sys.isActive()).toBe(true);
+    const initialX = host.scene.movingObject.x;
+    host.stepPhysics();
+    expect(host.scene.movingObject.x).toBeGreaterThan(initialX);
+    expect(host.scene.physics.world.bodies.size).toBe(1);
+    expect(host.scene.textObject.width).toBeGreaterThan(0);
+    const initialUpdates = host.scene.updates;
+    host.stepFrames(3);
+    expect(host.scene.updates).toBe(initialUpdates + 3);
+  });
+  it("rejects invalid advancement counts instead of entering an unbounded loop", async () => {
+    const boundedHost = await createHeadlessGame(new LayeredInputScene());
+    expect(() => boundedHost.stepFrames(Number.POSITIVE_INFINITY)).toThrow(
+      "stepFrames count must be a non-negative safe integer"
+    );
+    expect(() => boundedHost.stepUntil(() => false, 1.5)).toThrow(
+      "stepUntil maxFrames must be a non-negative safe integer"
+    );
+    expect(() => boundedHost.stepPhysics(-1)).toThrow(
+      "stepPhysics steps must be a non-negative safe integer"
+    );
+    boundedHost.destroy();
+  });
+  it("drives scaled DOM mouse input through hit testing and top-only dispatch", async () => {
+    const inputHost = await createHeadlessGame(new LayeredInputScene(), {
+      width: 160,
+      height: 120
+    });
+    inputHost.stepFrames();
+    inputHost.input.setCanvasBounds({
+      left: 20,
+      top: 30,
+      width: 80,
+      height: 60
+    });
+    expect(inputHost.input.gameToClient(80, 60)).toEqual({
+      clientX: 60,
+      clientY: 60
+    });
+    await inputHost.input.mouse.click(80, 60);
+    expect({
+      pointerX: inputHost.scene.input.activePointer.x,
+      pointerY: inputHost.scene.input.activePointer.y,
+      totalHits: inputHost.scene.firstHits + inputHost.scene.secondHits
+    }).toEqual({
+      pointerX: 80,
+      pointerY: 60,
+      totalHits: 1
+    });
+    await inputHost.input.mouse.click(10, 10);
+    expect(inputHost.scene.firstHits + inputHost.scene.secondHits).toBe(1);
+    inputHost.assertGameplayEvidence({
+      requireInput: true,
+      requireFrameAdvance: true
+    });
+    expect(inputHost.evidence.clicks).toBe(2);
+    inputHost.destroy();
+  });
+  it("drives held DOM keyboard input through Phaser's configured target", async () => {
+    const keyboardHost = await createHeadlessGame(new KeyboardInputScene());
+    await keyboardHost.input.keyboard.down(
+      Phaser4.Input.Keyboard.KeyCodes.RIGHT
+    );
+    keyboardHost.stepFrames(3);
+    expect(keyboardHost.scene.playerX).toBe(3);
+    await keyboardHost.input.keyboard.up(Phaser4.Input.Keyboard.KeyCodes.RIGHT);
+    keyboardHost.stepFrames(2);
+    expect(keyboardHost.scene.playerX).toBe(3);
+    expect(keyboardHost.evidence.keyboardEvents).toBe(2);
+    expect(
+      () => keyboardHost.assertGameplayEvidence({ requireInput: true })
+    ).not.toThrow();
+    keyboardHost.destroy();
+  });
+  it("drives DOM touch input through pointer conversion and hit testing", async () => {
+    const touchHost = await createHeadlessGame(new TouchInputScene(), {
+      width: 160,
+      height: 120
+    });
+    touchHost.stepFrames();
+    touchHost.input.setCanvasBounds({
+      left: 20,
+      top: 30,
+      width: 80,
+      height: 60
+    });
+    await touchHost.input.touch.start(40, 40);
+    await touchHost.input.touch.move(80, 60);
+    await touchHost.input.touch.end(80, 60);
+    expect({
+      moves: touchHost.scene.moves,
+      pointerX: touchHost.scene.input.activePointer.x,
+      pointerY: touchHost.scene.input.activePointer.y,
+      taps: touchHost.scene.taps,
+      wasTouch: touchHost.scene.wasTouch
+    }).toEqual({
+      moves: 1,
+      pointerX: 80,
+      pointerY: 60,
+      taps: 1,
+      wasTouch: true
+    });
+    expect(touchHost.evidence.touchEvents).toBe(3);
+    expect(
+      () => touchHost.assertGameplayEvidence({ requireInput: true })
+    ).not.toThrow();
+    touchHost.destroy();
+  });
+  it("boots when a production input family is disabled", async () => {
+    const mouseOnlyHost = await createHeadlessGame(new SmokeScene(), {
+      input: { keyboard: false, touch: false }
+    });
+    await expect(
+      mouseOnlyHost.input.keyboard.press(Phaser4.Input.Keyboard.KeyCodes.SPACE)
+    ).rejects.toThrow("keyboard input target cannot dispatch DOM events");
+    await expect(mouseOnlyHost.input.touch.tap(20, 20)).rejects.toThrow(
+      "touch input target cannot dispatch DOM events"
+    );
+    mouseOnlyHost.destroy();
+  });
+  it("registers transition targets before boot and settles queued transitions", async () => {
+    class TargetScene extends Phaser4.Scene {
+      receivedValue = 0;
+      constructor() {
+        super("TargetScene");
+      }
+      init(data) {
+        this.receivedValue = data.value;
+      }
+    }
+    class SourceScene extends Phaser4.Scene {
+      constructor() {
+        super("SourceScene");
+      }
+      create() {
+        this.add.zone(40, 40, 30, 30).setInteractive().on("pointerup", () => {
+          this.scene.start("TargetScene", { value: 7 });
+        });
+      }
+    }
+    const transitionHost = await createHeadlessGame(new SourceScene(), {
+      width: 100,
+      height: 100,
+      additionalScenes: [TargetScene]
+    });
+    transitionHost.stepFrames();
+    expect(transitionHost.game.scene.isActive("TargetScene")).toBe(false);
+    await transitionHost.input.mouse.click(40, 40);
+    transitionHost.stepUntil(
+      () => transitionHost.game.scene.isActive("TargetScene")
+    );
+    const target = transitionHost.game.scene.getScene(
+      "TargetScene"
+    );
+    expect(target.receivedValue).toBe(7);
+    expect(transitionHost.game.scene.isActive("SourceScene")).toBe(false);
+    transitionHost.assertGameplayEvidence({
+      requireInput: true,
+      requireFrameAdvance: true,
+      requireTransition: "TargetScene"
+    });
+    transitionHost.destroy();
+  });
+  it("preserves Scene sleep and wake commands that omit their optional key", async () => {
+    class OptionalCommandScene extends Phaser4.Scene {
+      constructor() {
+        super("OptionalCommandScene");
+      }
+    }
+    const optionalHost = await createHeadlessGame(new OptionalCommandScene());
+    optionalHost.scene.scene.sleep();
+    optionalHost.stepFrames();
+    expect(optionalHost.scene.sys.isSleeping()).toBe(true);
+    optionalHost.scene.scene.wake();
+    optionalHost.stepFrames();
+    expect(optionalHost.scene.sys.isActive()).toBe(true);
+    expect(optionalHost.evidence.transitions).toEqual([
+      {
+        from: "OptionalCommandScene",
+        to: "OptionalCommandScene",
+        method: "sleep"
+      },
+      {
+        from: "OptionalCommandScene",
+        to: "OptionalCommandScene",
+        method: "wake"
+      }
+    ]);
+    optionalHost.destroy();
+  });
+  it("records Scene visits, restart, checkpoints, and destruction", async () => {
+    const evidenceHost = await createHeadlessGame(new SmokeScene());
+    evidenceHost.checkpoint("progress");
+    evidenceHost.scene.scene.restart();
+    evidenceHost.stepFrames();
+    evidenceHost.destroy();
+    expect(evidenceHost.evidence.registeredScenes).toContain("SmokeScene");
+    expect(evidenceHost.evidence.visitedScenes).toContain("SmokeScene");
+    expect(evidenceHost.evidence.restartedScenes).toContain("SmokeScene");
+    expect(evidenceHost.evidence.checkpoints).toEqual(["progress"]);
+    expect(evidenceHost.evidence.destroyed).toBe(true);
+    expect(
+      () => evidenceHost.assertGameplayEvidence({
+        requireScene: "SmokeScene",
+        requireRestart: "SmokeScene",
+        requireCheckpoint: "progress",
+        requireDestroy: true
+      })
+    ).not.toThrow();
+  });
+  it("surfaces exceptions thrown by DOM-driven input callbacks", async () => {
+    class BrokenInputScene extends Phaser4.Scene {
+      create() {
+        this.add.zone(40, 40, 30, 30).setInteractive().on("pointerup", () => {
+          throw new Error("expected DOM input failure");
+        });
+      }
+    }
+    const brokenHost = await createHeadlessGame(new BrokenInputScene(), {
+      width: 100,
+      height: 100
+    });
+    brokenHost.stepFrames();
+    await expect(brokenHost.input.mouse.click(40, 40)).rejects.toThrow(
+      "expected DOM input failure"
+    );
+    expect(() => brokenHost.destroy()).toThrow("expected DOM input failure");
+  });
+  it("automatically rejects invalid Phaser Text dimensions with repair guidance", async () => {
+    class InvalidTextScene extends Phaser4.Scene {
+      create() {
+        const label = this.add.text(8, 8, "BROKEN", {
+          fixedWidth: void 0
+        });
+        this.add.container(0, 0, label);
+      }
+    }
+    await expect(createHeadlessGame(new InvalidTextScene())).rejects.toThrow(
+      /non-finite width.*fixedWidth: value \?\? 0/s
+    );
+  });
+  it("rechecks Text after manually advancing the game", async () => {
+    host = await createHeadlessGame(new SmokeScene());
+    host.scene.textObject.setStyle({
+      fixedWidth: void 0
+    });
+    expect(() => host?.stepFrames()).toThrow(
+      /non-finite width.*fixedWidth: value \?\? 0/s
+    );
+  });
+  it("rejects an enabled interactive object with unusable hit-test bounds", async () => {
+    class InvalidInteractiveScene extends Phaser4.Scene {
+      create() {
+        const zone = this.add.zone(80, 80, 20, 20).setInteractive();
+        (zone.input?.hitArea).width = 0;
+      }
+    }
+    await expect(
+      createHeadlessGame(new InvalidInteractiveScene())
+    ).rejects.toThrow(
+      /interactive health check failed.*invalid default hit area/s
+    );
+  });
+  it("allows dormant objects and zero-scale transitions", async () => {
+    class DormantObjectScene extends Phaser4.Scene {
+      create() {
+        this.add.zone(Number.NaN, 20, 10, 10).setActive(false).setVisible(false);
+        this.add.zone(20, 20, 10, 10).setInteractive().setScale(0);
+        this.add.text(20, 20, "hidden", { fontSize: "0px" }).setVisible(false);
+        const child = this.add.zone(20, 20, 10, 10).setInteractive();
+        (child.input?.hitArea).width = 0;
+        this.add.container(0, 0, child).setVisible(false);
+      }
+    }
+    const dormantHost = await createHeadlessGame(new DormantObjectScene());
+    expect(() => dormantHost.destroy()).not.toThrow();
+  });
+  it("rejects non-finite live GameObject transforms", async () => {
+    class InvalidTransformScene extends Phaser4.Scene {
+      create() {
+        this.add.zone(Number.NaN, 20, 10, 10);
+      }
+    }
+    await expect(
+      createHeadlessGame(new InvalidTransformScene())
+    ).rejects.toThrow(/runtime health check failed.*non-finite x: NaN/s);
+  });
+  it("rejects zero Camera zoom but allows negative zoom", async () => {
+    class InvalidCameraScene extends Phaser4.Scene {
+      create() {
+        this.cameras.main.zoomX = 0;
+      }
+    }
+    await expect(createHeadlessGame(new InvalidCameraScene())).rejects.toThrow(
+      /runtime health check failed.*zero zoom/s
+    );
+    class MirroredCameraScene extends Phaser4.Scene {
+      create() {
+        this.cameras.main.setZoom(-1, 1);
+      }
+    }
+    const mirroredHost = await createHeadlessGame(new MirroredCameraScene());
+    expect(() => mirroredHost.destroy()).not.toThrow();
+  });
+  it("rejects non-finite enabled Arcade Body state and ignores disabled Bodies", async () => {
+    class InvalidBodyScene extends Phaser4.Scene {
+      create() {
+        const object = this.add.zone(20, 20, 10, 10);
+        this.physics.add.existing(object);
+        object.body.velocity.x = Number.NaN;
+      }
+    }
+    await expect(
+      createHeadlessGame(new InvalidBodyScene(), {
+        physics: { default: "arcade" }
+      })
+    ).rejects.toThrow(/runtime health check failed.*velocity.x: NaN/s);
+    class DisabledBodyScene extends Phaser4.Scene {
+      create() {
+        const object = this.add.zone(20, 20, 10, 10);
+        this.physics.add.existing(object);
+        const body = object.body;
+        body.enable = false;
+        body.velocity.x = Number.NaN;
+      }
+    }
+    const disabledHost = await createHeadlessGame(new DisabledBodyScene(), {
+      physics: { default: "arcade" }
+    });
+    expect(() => disabledHost.destroy()).not.toThrow();
+  });
+  it("captures rejected async lifecycle hooks", async () => {
+    class AsyncFailureScene extends Phaser4.Scene {
+      async create() {
+        await Promise.resolve();
+        throw new Error("expected async create failure");
+      }
+    }
+    await expect(createHeadlessGame(new AsyncFailureScene())).rejects.toThrow(
+      "expected async create failure"
+    );
+  });
+  it("waits for preload to finish before resolving", async () => {
+    class PreloadScene extends Phaser4.Scene {
+      created = false;
+      preload() {
+        this.load.image(
+          "pixel",
+          "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M/wHwAF/gL+Avz9WQAAAABJRU5ErkJggg=="
+        );
+      }
+      create() {
+        this.created = true;
+      }
+    }
+    const preloadHost = await createHeadlessGame(new PreloadScene());
+    expect(preloadHost.scene.created).toBe(true);
+    expect(preloadHost.scene.textures.exists("pixel")).toBe(true);
+    preloadHost.destroy();
+  });
+  it("captures lifecycle Promise rejections without an Error reason", async () => {
+    class EmptyRejectionScene extends Phaser4.Scene {
+      create() {
+        return Promise.reject(void 0);
+      }
+    }
+    await expect(createHeadlessGame(new EmptyRejectionScene())).rejects.toThrow(
+      "Unhandled Phaser runtime error: undefined"
+    );
+  });
+  it("does not apply Arcade checks to Matter Physics", async () => {
+    class MatterScene extends Phaser4.Scene {
+      create() {
+        this.matter.add.rectangle(40, 40, 12, 12);
+      }
+    }
+    const matterHost = await createHeadlessGame(new MatterScene(), {
+      physics: { default: "matter" }
+    });
+    expect(() => matterHost.stepFrames()).not.toThrow();
+    expect(() => matterHost.stepPhysics()).toThrow(
+      "stepPhysics() requires an Arcade Physics world"
+    );
+    matterHost.destroy();
+  });
+  it("does not require a physics system", async () => {
+    class NoPhysicsScene extends Phaser4.Scene {
+      create() {
+        this.add.text(8, 8, "NO PHYSICS");
+      }
+    }
+    const noPhysicsHost = await createHeadlessGame(new NoPhysicsScene());
+    expect(noPhysicsHost.scene.physics).toBeUndefined();
+    expect(() => noPhysicsHost.stepFrames()).not.toThrow();
+    expect(() => noPhysicsHost.stepPhysics()).toThrow(
+      "stepPhysics() requires an Arcade Physics world"
+    );
+    noPhysicsHost.destroy();
+  });
+  it("can create a fresh game after destroying the previous instance", async () => {
+    const firstHost = await createHeadlessGame(new SmokeScene());
+    firstHost.destroy();
+    expect(() => firstHost.destroy()).not.toThrow();
+    host = await createHeadlessGame(new SmokeScene());
+    expect(host.scene.sys.isActive()).toBe(true);
+  });
+  it("accepts game config overrides and reproduces a fixed seed", async () => {
+    host = await createHeadlessGame(new SmokeScene(), {
+      width: 640,
+      height: 360,
+      seed: ["repeatable"],
+      physics: {
+        default: "arcade",
+        arcade: { gravity: { x: 0, y: 120 } }
+      }
+    });
+    const firstRandomValue = host.scene.randomValue;
+    expect(host.game.config.width).toBe(640);
+    expect(host.game.config.height).toBe(360);
+    expect(host.scene.physics.world.gravity.y).toBe(120);
+    host.destroy();
+    host = await createHeadlessGame(new SmokeScene(), { seed: ["repeatable"] });
+    expect(host.scene.randomValue).toBe(firstRandomValue);
+  });
+  it("rejects promptly when scene creation fails", async () => {
+    class BrokenScene extends Phaser4.Scene {
+      create() {
+        throw new Error("expected boot failure");
+      }
+    }
+    await expect(
+      createHeadlessGame(new BrokenScene(), { bootTimeoutMs: 250 })
+    ).rejects.toThrow("expected boot failure");
+  });
+  it("times out instead of hanging when boot cannot complete in time", async () => {
+    await expect(
+      createHeadlessGame(new SmokeScene(), { bootTimeoutMs: 0 })
+    ).rejects.toThrow("Phaser HEADLESS boot timed out after 0ms");
+    host = await createHeadlessGame(new SmokeScene());
+    expect(host.scene.sys.isActive()).toBe(true);
+  });
+});