miaoda-game-devkit 0.2.10 → 0.2.12

package/README.md

@@ -30,6 +30,12 @@ Scene 命令、restart、业务 checkpoint 和销毁。玩法测试可以调用
 `host.assertGameplayEvidence()` 把这些客观事实设为门禁；它不推断业务语义，
 authoritative state 仍必须由测试显式断言。
 
+HEADLESS host 会把 Phaser 自身的 warning/error、Loader 文件失败、漏掉 `load.start()` 的队列、
+未注册 Scene 命令和可见对象的 `__MISSING` 纹理升级为测试失败。只有经过确认的引擎
+warning 才能在创建 host 时通过 `ignoreEngineWarnings: [/pattern/]` 显式豁免；资源 URL
+仍须通过浏览器验证，因为 JSDOM 图片加载只支持测试用的 `data:image/` URL。刻意暂存
+资源供稍后加载的 Scene 可以通过 `allowIdleLoaderQueues: ["SceneKey"]` 精确声明。
+
 玩法测试应优先使用 `gameplayTest`。它是玩法 contract 的唯一权威声明，在执行阶段绑定
 HEADLESS host，并在 `onTestFinished` 校验 Ledger。`vitest.config.ts` 默认只列生产 Scene，
 不再复制 contract id、测试文件和证据要求。Reporter 从测试 metadata 汇总交互项目的最低

package/dist/{gameplay-audit-BwAobjIX.d.mts → gameplay-audit-DmbBA0M_.d.mts}

@@ -1,5 +1,7 @@
 import * as Phaser from 'phaser';
 
+type EngineWarningMatcher = string | RegExp;
+
 interface HeadlessGameHost<TScene extends Phaser.Scene> {
     /** 当前隔离的 Phaser 游戏实例。 */
     game: Phaser.Game;
@@ -158,6 +160,10 @@ type HeadlessGameOptions = Omit<Phaser.Types.Core.GameConfig, "type" | "scene" |
     bootTimeoutMs?: number;
     /** 初始 Scene 启动前必须注册的其他 Scene 类型。 */
     additionalScenes?: Phaser.Types.Scenes.SceneType[];
+    /** 显式允许的 Phaser 引擎 warning；其余引擎 warning 会使测试失败。 */
+    ignoreEngineWarnings?: readonly EngineWarningMatcher[];
+    /** 明确允许 Loader 暂存文件但尚未 start 的 Scene key。 */
+    allowIdleLoaderQueues?: readonly string[];
 };
 /** 创建隔离的 Phaser 游戏，并在入口 Scene 完成 create 后返回。 */
 declare function createHeadlessGame<TScene extends Phaser.Scene>(scene: TScene, options?: HeadlessGameOptions): Promise<HeadlessGameHost<TScene>>;
@@ -205,4 +211,4 @@ interface GameplayContractMetadata {
     verified?: boolean;
 }
 
-export { type GameplayAuditOptions as G, type HeadlessGameHost as H, type GameplayContractMetadata as a, type HeadlessGameplayEvidenceRequirements as b, type GameplayAuditContract as c, type HeadlessCanvasBounds as d, type HeadlessGameOptions as e, type HeadlessGameplayEvidence as f, type HeadlessInputDriver as g, type HeadlessInputPoint as h, type HeadlessKeyboardEventOptions as i, type HeadlessKeyboardInput as j, type HeadlessMouseInput as k, type HeadlessTouchInput as l, createHeadlessGame as m };
+export { type EngineWarningMatcher as E, type GameplayAuditOptions as G, type HeadlessGameHost as H, type GameplayContractMetadata as a, type HeadlessGameplayEvidenceRequirements as b, type GameplayAuditContract as c, type HeadlessCanvasBounds as d, type HeadlessGameOptions as e, type HeadlessGameplayEvidence as f, type HeadlessInputDriver as g, type HeadlessInputPoint as h, type HeadlessKeyboardEventOptions as i, type HeadlessKeyboardInput as j, type HeadlessMouseInput as k, type HeadlessTouchInput as l, createHeadlessGame as m };

package/dist/{gameplay-audit-BwAobjIX.d.ts → gameplay-audit-DmbBA0M_.d.ts}

@@ -1,5 +1,7 @@
 import * as Phaser from 'phaser';
 
+type EngineWarningMatcher = string | RegExp;
+
 interface HeadlessGameHost<TScene extends Phaser.Scene> {
     /** 当前隔离的 Phaser 游戏实例。 */
     game: Phaser.Game;
@@ -158,6 +160,10 @@ type HeadlessGameOptions = Omit<Phaser.Types.Core.GameConfig, "type" | "scene" |
     bootTimeoutMs?: number;
     /** 初始 Scene 启动前必须注册的其他 Scene 类型。 */
     additionalScenes?: Phaser.Types.Scenes.SceneType[];
+    /** 显式允许的 Phaser 引擎 warning；其余引擎 warning 会使测试失败。 */
+    ignoreEngineWarnings?: readonly EngineWarningMatcher[];
+    /** 明确允许 Loader 暂存文件但尚未 start 的 Scene key。 */
+    allowIdleLoaderQueues?: readonly string[];
 };
 /** 创建隔离的 Phaser 游戏，并在入口 Scene 完成 create 后返回。 */
 declare function createHeadlessGame<TScene extends Phaser.Scene>(scene: TScene, options?: HeadlessGameOptions): Promise<HeadlessGameHost<TScene>>;
@@ -205,4 +211,4 @@ interface GameplayContractMetadata {
     verified?: boolean;
 }
 
-export { type GameplayAuditOptions as G, type HeadlessGameHost as H, type GameplayContractMetadata as a, type HeadlessGameplayEvidenceRequirements as b, type GameplayAuditContract as c, type HeadlessCanvasBounds as d, type HeadlessGameOptions as e, type HeadlessGameplayEvidence as f, type HeadlessInputDriver as g, type HeadlessInputPoint as h, type HeadlessKeyboardEventOptions as i, type HeadlessKeyboardInput as j, type HeadlessMouseInput as k, type HeadlessTouchInput as l, createHeadlessGame as m };
+export { type EngineWarningMatcher as E, type GameplayAuditOptions as G, type HeadlessGameHost as H, type GameplayContractMetadata as a, type HeadlessGameplayEvidenceRequirements as b, type GameplayAuditContract as c, type HeadlessCanvasBounds as d, type HeadlessGameOptions as e, type HeadlessGameplayEvidence as f, type HeadlessInputDriver as g, type HeadlessInputPoint as h, type HeadlessKeyboardEventOptions as i, type HeadlessKeyboardInput as j, type HeadlessMouseInput as k, type HeadlessTouchInput as l, createHeadlessGame as m };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { a as GameplayContractMetadata, H as HeadlessGameHost, b as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-BwAobjIX.mjs';
-export { c as GameplayAuditContract, G as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-BwAobjIX.mjs';
+import { a as GameplayContractMetadata, H as HeadlessGameHost, b as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-DmbBA0M_.mjs';
+export { E as EngineWarningMatcher, c as GameplayAuditContract, G as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-DmbBA0M_.mjs';
 import * as Phaser from 'phaser';
 import { TestContext, TestOptions } from 'vitest';
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as GameplayContractMetadata, H as HeadlessGameHost, b as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-BwAobjIX.js';
-export { c as GameplayAuditContract, G as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-BwAobjIX.js';
+import { a as GameplayContractMetadata, H as HeadlessGameHost, b as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-DmbBA0M_.js';
+export { E as EngineWarningMatcher, c as GameplayAuditContract, G as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-DmbBA0M_.js';
 import * as Phaser from 'phaser';
 import { TestContext, TestOptions } from 'vitest';
 

package/dist/index.js

@@ -46,6 +46,75 @@ module.exports = __toCommonJS(src_exports);
 // src/phaser-headless-host.ts
 var Phaser3 = __toESM(require("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
 var Phaser = __toESM(require("phaser"));
 function describeText(label) {
@@ -55,12 +124,15 @@ function describeText(label) {
 }
 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 ?? null;
+    current = state.parentContainer ?? (state.displayList instanceof Phaser.GameObjects.Layer ? state.displayList : null);
   }
   return true;
 }
@@ -236,12 +308,15 @@ function describeObject(object) {
 }
 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 ?? null;
+    current = state.parentContainer ?? (state.displayList instanceof Phaser2.GameObjects.Layer ? state.displayList : null);
   }
   return true;
 }
@@ -282,6 +357,12 @@ function collectGameObjectHealthProblems(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);
@@ -419,7 +500,13 @@ function assertSceneInteractiveHealth(scene) {
 
 // src/phaser-headless-host.ts
 async function createHeadlessGame(scene, options = {}) {
-  const { bootTimeoutMs = 2e3, additionalScenes = [], ...config } = options;
+  const {
+    bootTimeoutMs = 2e3,
+    additionalScenes = [],
+    ignoreEngineWarnings = [],
+    allowIdleLoaderQueues = [],
+    ...config
+  } = options;
   let game;
   let settled = false;
   let runtimeError;
@@ -428,6 +515,16 @@ async function createHeadlessGame(scene, options = {}) {
   };
   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 = [];
@@ -513,6 +610,25 @@ async function createHeadlessGame(scene, options = {}) {
     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",
@@ -525,7 +641,12 @@ async function createHeadlessGame(scene, options = {}) {
         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);
+          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 });
@@ -653,6 +774,7 @@ async function createHeadlessGame(scene, options = {}) {
       game.headlessStep(game.loop.lastTime, 0);
     }
     restoreHostGuards();
+    stopObservingEngineDiagnostics();
     throw error;
   }
   const readyGame = game;
@@ -660,11 +782,39 @@ async function createHeadlessGame(scene, options = {}) {
     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");
@@ -673,6 +823,7 @@ async function createHeadlessGame(scene, options = {}) {
   if (!inputWindow) {
     removeRuntimeListeners();
     restoreHostGuards();
+    stopObservingEngineDiagnostics();
     readyGame.destroy(true);
     readyGame.headlessStep(readyGame.loop.lastTime, 0);
     throw new Error(
@@ -728,6 +879,14 @@ async function createHeadlessGame(scene, options = {}) {
       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);
@@ -953,6 +1112,7 @@ async function createHeadlessGame(scene, options = {}) {
   } catch (error) {
     removeRuntimeListeners();
     restoreHostGuards();
+    stopObservingEngineDiagnostics();
     readyGame.destroy(true);
     readyGame.headlessStep(readyGame.loop.lastTime, 0);
     throw error;
@@ -1084,6 +1244,7 @@ async function createHeadlessGame(scene, options = {}) {
       } finally {
         removeRuntimeListeners();
         restoreHostGuards();
+        stopObservingEngineDiagnostics();
       }
     }
   };

package/dist/index.mjs

@@ -1,6 +1,75 @@
 // 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) {
@@ -10,12 +79,15 @@ function describeText(label) {
 }
 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 ?? null;
+    current = state.parentContainer ?? (state.displayList instanceof Phaser.GameObjects.Layer ? state.displayList : null);
   }
   return true;
 }
@@ -191,12 +263,15 @@ function describeObject(object) {
 }
 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 ?? null;
+    current = state.parentContainer ?? (state.displayList instanceof Phaser2.GameObjects.Layer ? state.displayList : null);
   }
   return true;
 }
@@ -237,6 +312,12 @@ function collectGameObjectHealthProblems(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);
@@ -374,7 +455,13 @@ function assertSceneInteractiveHealth(scene) {
 
 // src/phaser-headless-host.ts
 async function createHeadlessGame(scene, options = {}) {
-  const { bootTimeoutMs = 2e3, additionalScenes = [], ...config } = options;
+  const {
+    bootTimeoutMs = 2e3,
+    additionalScenes = [],
+    ignoreEngineWarnings = [],
+    allowIdleLoaderQueues = [],
+    ...config
+  } = options;
   let game;
   let settled = false;
   let runtimeError;
@@ -383,6 +470,16 @@ async function createHeadlessGame(scene, options = {}) {
   };
   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 = [];
@@ -468,6 +565,25 @@ async function createHeadlessGame(scene, options = {}) {
     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",
@@ -480,7 +596,12 @@ async function createHeadlessGame(scene, options = {}) {
         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);
+          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 });
@@ -608,6 +729,7 @@ async function createHeadlessGame(scene, options = {}) {
       game.headlessStep(game.loop.lastTime, 0);
     }
     restoreHostGuards();
+    stopObservingEngineDiagnostics();
     throw error;
   }
   const readyGame = game;
@@ -615,11 +737,39 @@ async function createHeadlessGame(scene, options = {}) {
     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");
@@ -628,6 +778,7 @@ async function createHeadlessGame(scene, options = {}) {
   if (!inputWindow) {
     removeRuntimeListeners();
     restoreHostGuards();
+    stopObservingEngineDiagnostics();
     readyGame.destroy(true);
     readyGame.headlessStep(readyGame.loop.lastTime, 0);
     throw new Error(
@@ -683,6 +834,14 @@ async function createHeadlessGame(scene, options = {}) {
       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);
@@ -908,6 +1067,7 @@ async function createHeadlessGame(scene, options = {}) {
   } catch (error) {
     removeRuntimeListeners();
     restoreHostGuards();
+    stopObservingEngineDiagnostics();
     readyGame.destroy(true);
     readyGame.headlessStep(readyGame.loop.lastTime, 0);
     throw error;
@@ -1039,6 +1199,7 @@ async function createHeadlessGame(scene, options = {}) {
       } finally {
         removeRuntimeListeners();
         restoreHostGuards();
+        stopObservingEngineDiagnostics();
       }
     }
   };