miaoda-game-devkit 0.2.10 → 0.2.11

package/dist/lint/game-telemetry.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();
       }
     }
   };

package/dist/lint/gameplay-contract.contract.mjs

@@ -5,6 +5,75 @@ import { 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();
       }
     }
   };