miaoda-game-devkit 0.2.9 → 0.2.11

package/README.md

@@ -1,9 +1,13 @@
 # miaoda-game-devkit
 
-妙搭 Phaser 4 游戏模板的共享开发基础设施。
+妙搭 Phaser 4 与 React 游戏模板的共享开发基础设施。
 
 该开发工具包提供：
 
+- React 游戏的生产/手动时钟、Strict Mode 安全 Session ownership、JSDOM
+  Vitest 配置和自动收集运行错误的 Testing Library setup，分别从 `miaoda-game-devkit/react`、
+  `miaoda-game-devkit/react/testing` 和 `miaoda-game-devkit/react/vitest-config` 导入；
+
 - 支持 DOM 鼠标、键盘和触摸输入的确定性 Phaser 无头测试宿主；
 - 不依赖渲染器的运行时、交互区域和文字健康检查；
 - 由模板平台维护的通用 Vitest 契约测试；
@@ -11,6 +15,8 @@
   Oxlint 和 Phaser 通用契约检查。
 - 统一的 `defineGameVitestConfig` 配置工厂，固定 Phaser 无头测试依赖的基础配置，
   同时允许每个游戏声明 Scene 审计范围，并配置额外 alias、setup 文件和超时。
+- 与 Vite `defineConfig` 同签名的 `defineGameViteConfig` 配置工厂，统一维护生产 Scene
+  的运行时基础能力，同时完整保留游戏自己的 Vite 配置。
 
 互动游戏的长流程优先使用游戏自己暴露的 `globalThis.gameTelemetry`。稳定 façade 通常调用
 `installGameTelemetry(this.game, telemetry)` 绑定 Game 生命周期；只有刻意局部的 façade 才绑定
@@ -24,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 汇总交互项目的最低
@@ -54,6 +66,20 @@ monorepo 中的模板可以放置只包含 `extends: ["miaoda-game-devkit/biome"
 别名等项目差异。TypeScript 严格模式、bundler 模块解析和无输出检查等平台基线由开发
 工具包集中维护，`miaoda-game-lint` 会直接检查模板的这个配置。
 
+Phaser4 模板的 `vite.config.ts` 应从 `miaoda-game-devkit/vite` 导入 `defineGameViteConfig`，调用方式
+与 Vite 的 `defineConfig` 相同，支持配置对象、Promise、同步配置函数和异步配置函数：
+
+```ts
+export default defineGameViteConfig({
+  plugins: [miaodaDevPlugin()],
+});
+```
+
+该入口只增强 `src/scenes` 中对 Phaser 的导入。游戏 Scene 仍按标准方式继承
+`Phaser.Scene`；devkit 在 Scene 创建前提供 RexUI，并在创建后验证业务确实完成了 RexUI
+根布局。RexUI 的加载、Phaser 4.0 兼容和 Scene Plugin 生命周期属于 devkit 责任，游戏
+配置不重复注册。
+
 具体游戏的玩法测试仍由模板使用方放在 `tests/`。运行时测试从本开发工具包
 导入 `createHeadlessGame`；有限目标游戏通过合法 Telemetry controls 走到正常成功终局，
 无尽或沙盒游戏证明有意义的持续进展。短输入测试从入口操作走到一个主要操作，用真实 DOM

package/dist/cli/lint.js

@@ -49,10 +49,41 @@ async function runContracts() {
     ["run", "--config", (0, import_node_path.join)(devkitRoot, "dist/lint/contracts.config.mjs")]
   );
 }
+function checkGameViteConfig() {
+  const viteConfigPath = (0, import_node_path.join)(projectRoot, "vite.config.ts");
+  if (!(0, import_node_fs.existsSync)(viteConfigPath)) {
+    console.error(
+      "[vite-config] \u7F3A\u5C11\u6A21\u677F\u5FC5\u9700\u7684 vite.config.ts\u3002\u8BF7\u6062\u590D\u6A21\u677F\u539F\u6587\u4EF6\u540E\u91CD\u65B0\u8FD0\u884C pnpm lint\u3002"
+    );
+    return { name: "vite-config", ok: false };
+  }
+  const source = (0, import_node_fs.readFileSync)(viteConfigPath, "utf8");
+  const hasDevkitImport = /from\s+["']miaoda-game-devkit\/vite["']/.test(source);
+  const hasConfigCall = /defineGameViteConfig\s*\(/.test(source);
+  if (!hasDevkitImport || !hasConfigCall) {
+    console.error(
+      "[vite-config] vite.config.ts \u672A\u4F7F\u7528\u6A21\u677F\u89C4\u5B9A\u7684\u914D\u7F6E\u5165\u53E3\u3002\n\u8BF7\u4ECE miaoda-game-devkit/vite \u5BFC\u5165 defineGameViteConfig\uFF0C\u5E76\u7528 defineGameViteConfig({ ... }) \u5305\u4F4F\u5F53\u524D\u7684\u914D\u7F6E\u5BF9\u8C61\u3002\n\u53EA\u66FF\u6362\u914D\u7F6E\u51FD\u6570\uFF0C\u4FDD\u7559\u73B0\u6709 plugins\u3001resolve \u7B49\u5BF9\u8C61\u5185\u5BB9\u4E0D\u53D8\u3002"
+    );
+    return { name: "vite-config", ok: false };
+  }
+  return { name: "vite-config", ok: true };
+}
+function projectUsesPhaser4() {
+  const manifestPath = (0, import_node_path.join)(projectRoot, "package.json");
+  if (!(0, import_node_fs.existsSync)(manifestPath)) return false;
+  try {
+    const manifest = JSON.parse((0, import_node_fs.readFileSync)(manifestPath, "utf8"));
+    const version = manifest.dependencies?.phaser ?? manifest.devDependencies?.phaser;
+    return typeof version === "string" && /(?:^|[^0-9])4(?:\.|$)/.test(version);
+  } catch {
+    return false;
+  }
+}
 async function runAllChecks() {
   if (contractsOnly) {
     return [await runContracts()];
   }
+  const viteConfig = projectUsesPhaser4() ? [checkGameViteConfig()] : [];
   const [tsgo, biome] = await Promise.all([
     run("tsgo", "@typescript/native-preview", "tsgo", ["-p", "tsconfig.json"]),
     run("biome", "@biomejs/biome", "biome", [
@@ -76,7 +107,7 @@ async function runAllChecks() {
     "src"
   ]);
   const contracts = await runContracts();
-  return [tsgo, biome, tailwind, oxlint, contracts];
+  return [...viteConfig, tsgo, biome, tailwind, oxlint, contracts];
 }
 async function main() {
   const results = await runAllChecks();

package/dist/game-clock-suUidZdT.d.mts

@@ -0,0 +1,11 @@
+type GameFrameCallback = (timestamp: number) => void;
+interface GameClock {
+    now(): number;
+    requestFrame(callback: GameFrameCallback): number;
+    cancelFrame(id: number): void;
+    setTimeout(callback: () => void, delayMs: number): number;
+    clearTimeout(id: number): void;
+}
+declare const browserGameClock: GameClock;
+
+export { type GameClock as G, type GameFrameCallback as a, browserGameClock as b };

package/dist/game-clock-suUidZdT.d.ts

@@ -0,0 +1,11 @@
+type GameFrameCallback = (timestamp: number) => void;
+interface GameClock {
+    now(): number;
+    requestFrame(callback: GameFrameCallback): number;
+    cancelFrame(id: number): void;
+    setTimeout(callback: () => void, delayMs: number): number;
+    clearTimeout(id: number): void;
+}
+declare const browserGameClock: GameClock;
+
+export { type GameClock as G, type GameFrameCallback as a, browserGameClock as b };

package/dist/{gameplay-audit-CCJo4Qhk.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 GameplayContractMetadata as G, type HeadlessGameHost as H, type HeadlessGameplayEvidenceRequirements as a, type GameplayAuditContract as b, type GameplayAuditOptions 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-CCJo4Qhk.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 GameplayContractMetadata as G, type HeadlessGameHost as H, type HeadlessGameplayEvidenceRequirements as a, type GameplayAuditContract as b, type GameplayAuditOptions 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 { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-CCJo4Qhk.mjs';
-export { b as GameplayAuditContract, c 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-CCJo4Qhk.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 { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-CCJo4Qhk.js';
-export { b as GameplayAuditContract, c 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-CCJo4Qhk.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();
       }
     }
   };