miaoda-game-devkit 0.2.10 → 0.2.11

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

@@ -5,6 +5,75 @@ 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) {
@@ -14,12 +83,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;
 }
@@ -195,12 +267,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;
 }
@@ -241,6 +316,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);
@@ -378,7 +459,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;
@@ -387,6 +474,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 = [];
@@ -472,6 +569,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",
@@ -484,7 +600,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 });
@@ -612,6 +733,7 @@ async function createHeadlessGame(scene, options = {}) {
       game.headlessStep(game.loop.lastTime, 0);
     }
     restoreHostGuards();
+    stopObservingEngineDiagnostics();
     throw error;
   }
   const readyGame = game;
@@ -619,11 +741,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");
@@ -632,6 +782,7 @@ async function createHeadlessGame(scene, options = {}) {
   if (!inputWindow) {
     removeRuntimeListeners();
     restoreHostGuards();
+    stopObservingEngineDiagnostics();
     readyGame.destroy(true);
     readyGame.headlessStep(readyGame.loop.lastTime, 0);
     throw new Error(
@@ -687,6 +838,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);
@@ -912,6 +1071,7 @@ async function createHeadlessGame(scene, options = {}) {
   } catch (error) {
     removeRuntimeListeners();
     restoreHostGuards();
+    stopObservingEngineDiagnostics();
     readyGame.destroy(true);
     readyGame.headlessStep(readyGame.loop.lastTime, 0);
     throw error;
@@ -1043,6 +1203,7 @@ async function createHeadlessGame(scene, options = {}) {
       } finally {
         removeRuntimeListeners();
         restoreHostGuards();
+        stopObservingEngineDiagnostics();
       }
     }
   };
@@ -1298,6 +1459,14 @@ describe("Phaser HEADLESS host", () => {
     });
     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() {
@@ -1422,6 +1591,69 @@ describe("Phaser HEADLESS host", () => {
       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() {
@@ -1495,6 +1727,51 @@ describe("Phaser HEADLESS host", () => {
     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() {

package/dist/lint/vitest-config.contract.mjs

@@ -672,6 +672,8 @@ GAMEPLAY_AUDIT: ALL CONTRACTS PASSED (${tests.filter((test) => test.metadata).le
 };
 
 // src/vitest-config.ts
+var PHASER_FACADE_DEPENDENCY = /miaoda-game-devkit[\\/]dist[\\/]phaser-facade\.mjs$/;
+var REXUI_DEPENDENCY = /phaser4-rex-plugins/;
 function defineGameVitestConfig(options) {
   const auditIssues = validateGameplayAuditOptions(options.gameplayAudit, options.projectRoot);
   if (auditIssues.length > 0) {
@@ -703,7 +705,11 @@ function defineGameVitestConfig(options) {
           // 如果强制内联，Vite 会把这些模块按浏览器模块转换，
           // 最终触发 "No such built-in module: node:"。
           external: [/miaoda-game-devkit/],
-          inline: options.inlineDependencies
+          inline: [
+            PHASER_FACADE_DEPENDENCY,
+            REXUI_DEPENDENCY,
+            ...options.inlineDependencies ?? []
+          ]
         }
       },
       environment: "jsdom",
@@ -877,7 +883,10 @@ describe("defineGameVitestConfig", () => {
       server: {
         deps: {
           external: [/miaoda-game-devkit/],
-          inline: void 0
+          inline: [
+            /miaoda-game-devkit[\\/]dist[\\/]phaser-facade\.mjs$/,
+            /phaser4-rex-plugins/
+          ]
         }
       },
       environment: "jsdom",
@@ -907,7 +916,7 @@ describe("defineGameVitestConfig", () => {
     const config = defineGameVitestConfig({
       projectRoot,
       gameplayAudit,
-      inlineDependencies: [/phaser4-rex-plugins/],
+      inlineDependencies: [/project-specific-inline-dependency/],
       additionalSetupFiles: ["tests/custom-setup.ts"],
       testTimeout: 5e3,
       hookTimeout: 2e3
@@ -915,6 +924,15 @@ describe("defineGameVitestConfig", () => {
     expect(config.test).toMatchObject({
       include: ["tests/**/*.test.ts"],
       setupFiles: ["miaoda-game-devkit/vitest-setup", "tests/custom-setup.ts"],
+      server: {
+        deps: {
+          inline: [
+            /miaoda-game-devkit[\\/]dist[\\/]phaser-facade\.mjs$/,
+            /phaser4-rex-plugins/,
+            /project-specific-inline-dependency/
+          ]
+        }
+      },
       testTimeout: 5e3,
       hookTimeout: 2e3
     });

package/dist/vitest-config.d.mts

@@ -1,5 +1,5 @@
 import { ViteUserConfig } from 'vitest/config';
-import { G as GameplayAuditOptions } from './gameplay-audit-BwAobjIX.mjs';
+import { G as GameplayAuditOptions } from './gameplay-audit-DmbBA0M_.mjs';
 import 'phaser';
 
 interface GameVitestConfigOptions {
@@ -11,7 +11,7 @@ interface GameVitestConfigOptions {
     aliases?: Record<string, string>;
     /** 在 devkit 基础 setup 之后执行的项目级 setup 文件。 */
     additionalSetupFiles?: string[];
-    /** 需要由 Vite 转换的项目依赖，例如包含无扩展名 import 的插件。 */
+    /** 除 devkit 内置 Phaser/RexUI 边界外，还需要由 Vite 转换的项目依赖。 */
     inlineDependencies?: RegExp[];
     /** 单个游戏运行时测试的超时时间。 */
     testTimeout?: number;

package/dist/vitest-config.d.ts

@@ -1,5 +1,5 @@
 import { ViteUserConfig } from 'vitest/config';
-import { G as GameplayAuditOptions } from './gameplay-audit-BwAobjIX.js';
+import { G as GameplayAuditOptions } from './gameplay-audit-DmbBA0M_.js';
 import 'phaser';
 
 interface GameVitestConfigOptions {
@@ -11,7 +11,7 @@ interface GameVitestConfigOptions {
     aliases?: Record<string, string>;
     /** 在 devkit 基础 setup 之后执行的项目级 setup 文件。 */
     additionalSetupFiles?: string[];
-    /** 需要由 Vite 转换的项目依赖，例如包含无扩展名 import 的插件。 */
+    /** 除 devkit 内置 Phaser/RexUI 边界外，还需要由 Vite 转换的项目依赖。 */
     inlineDependencies?: RegExp[];
     /** 单个游戏运行时测试的超时时间。 */
     testTimeout?: number;

package/dist/vitest-config.js

@@ -671,6 +671,8 @@ function phaserRexUIScenePlugin(projectRoot) {
 }
 
 // src/vitest-config.ts
+var PHASER_FACADE_DEPENDENCY = /miaoda-game-devkit[\\/]dist[\\/]phaser-facade\.mjs$/;
+var REXUI_DEPENDENCY = /phaser4-rex-plugins/;
 function defineGameVitestConfig(options) {
   const auditIssues = validateGameplayAuditOptions(options.gameplayAudit, options.projectRoot);
   if (auditIssues.length > 0) {
@@ -702,7 +704,11 @@ function defineGameVitestConfig(options) {
           // 如果强制内联，Vite 会把这些模块按浏览器模块转换，
           // 最终触发 "No such built-in module: node:"。
           external: [/miaoda-game-devkit/],
-          inline: options.inlineDependencies
+          inline: [
+            PHASER_FACADE_DEPENDENCY,
+            REXUI_DEPENDENCY,
+            ...options.inlineDependencies ?? []
+          ]
         }
       },
       environment: "jsdom",

package/dist/vitest-config.mjs

@@ -647,6 +647,8 @@ function phaserRexUIScenePlugin(projectRoot) {
 }
 
 // src/vitest-config.ts
+var PHASER_FACADE_DEPENDENCY = /miaoda-game-devkit[\\/]dist[\\/]phaser-facade\.mjs$/;
+var REXUI_DEPENDENCY = /phaser4-rex-plugins/;
 function defineGameVitestConfig(options) {
   const auditIssues = validateGameplayAuditOptions(options.gameplayAudit, options.projectRoot);
   if (auditIssues.length > 0) {
@@ -678,7 +680,11 @@ function defineGameVitestConfig(options) {
           // 如果强制内联，Vite 会把这些模块按浏览器模块转换，
           // 最终触发 "No such built-in module: node:"。
           external: [/miaoda-game-devkit/],
-          inline: options.inlineDependencies
+          inline: [
+            PHASER_FACADE_DEPENDENCY,
+            REXUI_DEPENDENCY,
+            ...options.inlineDependencies ?? []
+          ]
         }
       },
       environment: "jsdom",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miaoda-game-devkit",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "description": "Shared lint and deterministic Phaser HEADLESS testing tools for Miaoda games",
   "license": "MIT",
   "main": "./dist/index.js",