miaoda-game-devkit 0.2.12 → 0.2.13

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

@@ -1,1856 +0,0 @@
-// 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-engine-warnings.ts
-var originalWarn;
-var originalError;
-var listener;
-function formatWarningArgument(value) {
-  if (typeof value === "string") return value;
-  if (value === null || value === void 0 || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
-    return String(value);
-  }
-  if (value instanceof Error) return value.message;
-  const constructorName = typeof value === "object" ? value.constructor?.name : void 0;
-  return constructorName ? `[${constructorName}]` : String(value);
-}
-function comesFromPhaser(stack) {
-  return /(?:^|[/\\])phaser(?:[/\\]|\.(?:js|mjs|cjs)(?::\d+)?)/m.test(stack);
-}
-function captureEngineDiagnostic(level, original, args) {
-  const stack = new Error(`Phaser engine ${level}`).stack ?? "";
-  if (!comesFromPhaser(stack)) {
-    original(...args);
-    return;
-  }
-  listener?.({
-    level,
-    message: args.map(formatWarningArgument).join(" "),
-    stack
-  });
-}
-function installWarningMultiplexer(currentListener) {
-  if (listener) {
-    throw new Error(
-      "Only one Phaser HEADLESS host may be active in the same Vitest worker. Destroy the current host before creating another one."
-    );
-  }
-  listener = currentListener;
-  const passthroughWarn = console.warn;
-  const passthroughError = console.error;
-  originalWarn = passthroughWarn;
-  originalError = passthroughError;
-  console.warn = (...args) => {
-    captureEngineDiagnostic("warn", passthroughWarn, args);
-  };
-  console.error = (...args) => {
-    captureEngineDiagnostic("error", passthroughError, args);
-  };
-}
-function uninstallWarningMultiplexer() {
-  if (!listener) return;
-  if (originalWarn) console.warn = originalWarn;
-  if (originalError) console.error = originalError;
-  listener = void 0;
-  originalWarn = void 0;
-  originalError = void 0;
-}
-function observeEngineDiagnostics(currentListener) {
-  installWarningMultiplexer(currentListener);
-  let observing = true;
-  return () => {
-    if (!observing) return;
-    observing = false;
-    uninstallWarningMultiplexer();
-  };
-}
-function matchesEngineWarning(message, matcher) {
-  if (typeof matcher === "string") return message.includes(matcher);
-  matcher.lastIndex = 0;
-  return matcher.test(message);
-}
-
-// 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;
-  const visited = /* @__PURE__ */ new Set();
-  while (current) {
-    if (visited.has(current)) return false;
-    visited.add(current);
-    const state = current;
-    if (state.visible === false || state.alpha === 0 || state.scaleX === 0 || state.scaleY === 0) {
-      return false;
-    }
-    current = state.parentContainer ?? (state.displayList instanceof Phaser.GameObjects.Layer ? state.displayList : 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;
-  const visited = /* @__PURE__ */ new Set();
-  while (current) {
-    if (visited.has(current)) return false;
-    visited.add(current);
-    const state = current;
-    if (state.visible === false || state.alpha === 0 || state.scaleX === 0 || state.scaleY === 0) {
-      return false;
-    }
-    current = state.parentContainer ?? (state.displayList instanceof Phaser2.GameObjects.Layer ? state.displayList : 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;
-    const texture = target.texture;
-    if (isEffectivelyVisible(object) && texture && typeof texture === "object" && Reflect.get(texture, "key") === "__MISSING") {
-      problems.push(
-        `${subject} uses Phaser's __MISSING texture; verify the loaded texture key and asset path`
-      );
-    }
-    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 = [],
-    ignoreEngineWarnings = [],
-    allowIdleLoaderQueues = [],
-    ...config
-  } = options;
-  let game;
-  let settled = false;
-  let runtimeError;
-  let hasRuntimeError = false;
-  let restoreHostGuards = () => {
-  };
-  let removeRuntimeListeners = () => {
-  };
-  const engineDiagnostics = [];
-  const loaderFailures = [];
-  const stopObservingEngineDiagnostics = observeEngineDiagnostics((diagnostic) => {
-    if (diagnostic.level === "warn" && ignoreEngineWarnings.some(
-      (matcher) => matchesEngineWarning(diagnostic.message, matcher)
-    )) {
-      return;
-    }
-    engineDiagnostics.push(diagnostic);
-  });
-  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 onFileLoadError = (file) => {
-        const source = file.src || file.url || "unknown source";
-        loaderFailures.push({
-          scene: currentScene.sys.settings.key,
-          type: String(file.type),
-          key: String(file.key),
-          source: String(source)
-        });
-      };
-      currentScene.load.on(
-        Phaser3.Loader.Events.FILE_LOAD_ERROR,
-        onFileLoadError
-      );
-      restoreGuards.push(() => {
-        currentScene.load.off(
-          Phaser3.Loader.Events.FILE_LOAD_ERROR,
-          onFileLoadError
-        );
-      });
-      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) {
-            throw new Error(
-              `[SCENE_NOT_REGISTERED] Scene ${JSON.stringify(currentScene.sys.settings.key)} called ${method}(${JSON.stringify(key)}), but the target Scene is not registered. Add it to the production Scene registry and pass it through additionalScenes in focused HEADLESS tests.`
-            );
-          }
-          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();
-    stopObservingEngineDiagnostics();
-    throw error;
-  }
-  const readyGame = game;
-  const throwRuntimeError = () => {
-    if (hasRuntimeError) {
-      throw runtimeError instanceof Error ? runtimeError : new Error(`Unhandled Phaser runtime error: ${String(runtimeError)}`);
-    }
-    if (loaderFailures.length > 0) {
-      const imageTypes = /* @__PURE__ */ new Set(["image", "normalMap", "spritesheet"]);
-      const hasHeadlessImageFailure = loaderFailures.some(
-        (failure) => imageTypes.has(failure.type)
-      );
-      throw new Error(
-        [
-          "Phaser loader failed to load one or more files:",
-          ...loaderFailures.map(
-            (failure) => `- ${failure.scene}: failed to load ${failure.type} ${JSON.stringify(failure.key)} from ${JSON.stringify(failure.source)}`
-          ),
-          hasHeadlessImageFailure ? "HEADLESS image loading supports data:image/ URLs only; use a data URL or a deliberate loader stub in tests, and verify production asset paths in a browser." : "Verify the resource URL and data, or install a deliberate loader stub for network resources in HEADLESS tests."
-        ].join("\n")
-      );
-    }
-    if (engineDiagnostics.length > 0) {
-      throw new Error(
-        [
-          "Phaser emitted an engine diagnostic:",
-          ...engineDiagnostics.flatMap((diagnostic) => [
-            `- ${diagnostic.level}: ${diagnostic.message}`,
-            ...diagnostic.stack.split("\n").slice(2, 8).map((frame) => `  ${frame.trim()}`)
-          ]),
-          "Fix the invalid Phaser operation. Only known warnings (not errors) may be allowed with ignoreEngineWarnings."
-        ].join("\n")
-      );
-    }
-  };
-  const canvas = readyGame.canvas;
-  if (!canvas) {
-    removeRuntimeListeners();
-    restoreHostGuards();
-    stopObservingEngineDiagnostics();
-    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();
-    stopObservingEngineDiagnostics();
-    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);
-      if (!allowIdleLoaderQueues.includes(currentScene.sys.settings.key) && !currentScene.load.isLoading() && currentScene.load.list.size > 0) {
-        const queuedFiles = [...currentScene.load.list].map(
-          (file) => `${file.type}:${String(file.key)}`
-        );
-        throw new Error(
-          `Phaser loader queue is not running in scene ${JSON.stringify(currentScene.sys.settings.key)}: ${queuedFiles.length} file(s) are queued (${queuedFiles.join(", ")}). Files added outside preload() require this.load.start().`
-        );
-      }
-      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();
-    stopObservingEngineDiagnostics();
-    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, maxFramesOrOptions = 120) {
-      const maxFrames = typeof maxFramesOrOptions === "number" ? maxFramesOrOptions : maxFramesOrOptions.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();
-        stopObservingEngineDiagnostics();
-      }
-    }
-  };
-}
-
-// 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.stepUntil(() => false, { maxFrames: 0 })).toThrow(
-      "Condition was not met within 0 complete Phaser frames"
-    );
-    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("rejects unregistered Scene commands without recording false transition evidence", async () => {
-    const transitionHost = await createHeadlessGame(new LayeredInputScene());
-    expect(() => transitionHost.scene.scene.start("MissingScene")).toThrow(
-      /SCENE_NOT_REGISTERED.*MissingScene.*additionalScenes/s
-    );
-    expect(transitionHost.evidence.transitions).toEqual([]);
-    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 visible GameObjects that silently fall back to __MISSING", async () => {
-    class MissingTextureScene extends Phaser4.Scene {
-      create() {
-        this.add.image(20, 20, "invented-texture-key").setName("player");
-      }
-    }
-    await expect(
-      createHeadlessGame(new MissingTextureScene())
-    ).rejects.toThrow(
-      /runtime health check failed.*Image name="player" uses Phaser's __MISSING texture/s
-    );
-  });
-  it("turns Phaser engine warnings into failures and supports explicit allowlists", async () => {
-    class MissingAnimationScene extends Phaser4.Scene {
-      create() {
-        this.add.sprite(20, 20, "__WHITE").play("missing-animation");
-      }
-    }
-    await expect(
-      createHeadlessGame(new MissingAnimationScene())
-    ).rejects.toThrow(
-      /engine diagnostic.*warn: Missing animation: missing-animation/s
-    );
-    const allowedHost = await createHeadlessGame(new MissingAnimationScene(), {
-      ignoreEngineWarnings: [/^Missing animation: missing-animation$/]
-    });
-    expect(() => allowedHost.stepFrames()).not.toThrow();
-    allowedHost.destroy();
-  });
-  it("turns Phaser console errors into failures without allowing warning exemptions", async () => {
-    class DuplicateTextureScene extends Phaser4.Scene {
-      create() {
-        this.textures.checkKey("__WHITE");
-      }
-    }
-    await expect(
-      createHeadlessGame(new DuplicateTextureScene(), {
-        ignoreEngineWarnings: [/Texture key already in use/]
-      })
-    ).rejects.toThrow(
-      /engine diagnostic.*error: Texture key already in use: __WHITE/s
-    );
-  });
-  it("rejects overlapping hosts and releases the diagnostic boundary on destroy", async () => {
-    const firstHost = await createHeadlessGame(new LayeredInputScene());
-    await expect(createHeadlessGame(new LayeredInputScene())).rejects.toThrow(
-      /Only one Phaser HEADLESS host.*Destroy the current host/s
-    );
-    firstHost.destroy();
-    const nextHost = await createHeadlessGame(new LayeredInputScene());
-    nextHost.destroy();
-  });
-  it("does not treat a missing texture inside a hidden Layer as visible", async () => {
-    class HiddenLayerScene extends Phaser4.Scene {
-      create() {
-        const hiddenLayer = this.add.layer().setVisible(false);
-        hiddenLayer.add(this.add.image(20, 20, "hidden-missing-texture"));
-      }
-    }
-    const hiddenHost = await createHeadlessGame(new HiddenLayerScene());
-    expect(() => hiddenHost.stepFrames()).not.toThrow();
-    hiddenHost.destroy();
-  });
-  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("reports failed Loader files with HEADLESS-specific repair guidance", async () => {
-    class FailedLoaderScene extends Phaser4.Scene {
-      preload() {
-        this.load.image("missing-player", "/assets/missing-player.png");
-      }
-    }
-    await expect(
-      createHeadlessGame(new FailedLoaderScene())
-    ).rejects.toThrow(
-      /loader failed.*missing-player.*missing-player\.png.*data:image\//s
-    );
-  });
-  it("does not give image-only guidance for non-image Loader failures", async () => {
-    class FailedJsonLoaderScene extends Phaser4.Scene {
-      preload() {
-        this.load.json("missing-level", "/assets/missing-level.json");
-      }
-    }
-    await expect(
-      createHeadlessGame(new FailedJsonLoaderScene())
-    ).rejects.toThrow(
-      /loader failed.*json.*missing-level.*Verify the resource URL(?![\s\S]*data:image\/)/s
-    );
-  });
-  it("reports files queued after preload when load.start() was omitted", async () => {
-    class IdleLoaderScene extends Phaser4.Scene {
-      constructor() {
-        super("IdleLoaderScene");
-      }
-      create() {
-        this.load.image(
-          "late-pixel",
-          "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M/wHwAF/gL+Avz9WQAAAABJRU5ErkJggg=="
-        );
-      }
-    }
-    await expect(createHeadlessGame(new IdleLoaderScene())).rejects.toThrow(
-      /loader queue is not running.*image:late-pixel.*load\.start/s
-    );
-    const allowedHost = await createHeadlessGame(new IdleLoaderScene(), {
-      allowIdleLoaderQueues: ["IdleLoaderScene"]
-    });
-    expect(() => allowedHost.stepFrames()).not.toThrow();
-    allowedHost.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);
-  });
-});