miaoda-game-devkit 0.1.1 → 0.2.0

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

@@ -25,7 +25,9 @@ function isEffectivelyRenderable(label) {
 }
 function requireFinite(problems, label, property, value) {
   if (!Number.isFinite(value)) {
-    problems.push(`${describeText(label)} has non-finite ${property}: ${String(value)}`);
+    problems.push(
+      `${describeText(label)} has non-finite ${property}: ${String(value)}`
+    );
   }
 }
 function collectSceneTexts(scene) {
@@ -79,7 +81,9 @@ function collectMissingBitmapGlyphs(text, chars) {
     const code = text.charCodeAt(index);
     if (seen.has(code) || chars[code] !== void 0) continue;
     seen.add(code);
-    missing.push(`${JSON.stringify(character)} (U+${code.toString(16).toUpperCase().padStart(4, "0")})`);
+    missing.push(
+      `${JSON.stringify(character)} (U+${code.toString(16).toUpperCase().padStart(4, "0")})`
+    );
   }
   return missing;
 }
@@ -104,19 +108,29 @@ function collectTextHealthProblems(scene) {
     requireFinite(problems, label, "resolution", label.style.resolution);
     const requiresPositiveSize = /\S/u.test(label.text) && isEffectivelyRenderable(label);
     if (requiresPositiveSize && Number.isFinite(label.width) && label.width <= 0) {
-      problems.push(`${describeText(label)} has non-positive width: ${label.width}`);
+      problems.push(
+        `${describeText(label)} has non-positive width: ${label.width}`
+      );
     }
     if (requiresPositiveSize && Number.isFinite(label.height) && label.height <= 0) {
-      problems.push(`${describeText(label)} has non-positive height: ${label.height}`);
+      problems.push(
+        `${describeText(label)} has non-positive height: ${label.height}`
+      );
     }
     if (Number.isFinite(label.style.fixedWidth) && label.style.fixedWidth < 0) {
-      problems.push(`${describeText(label)} has negative fixedWidth: ${label.style.fixedWidth}`);
+      problems.push(
+        `${describeText(label)} has negative fixedWidth: ${label.style.fixedWidth}`
+      );
     }
     if (Number.isFinite(label.style.fixedHeight) && label.style.fixedHeight < 0) {
-      problems.push(`${describeText(label)} has negative fixedHeight: ${label.style.fixedHeight}`);
+      problems.push(
+        `${describeText(label)} has negative fixedHeight: ${label.style.fixedHeight}`
+      );
     }
     if (Number.isFinite(label.style.resolution) && label.style.resolution <= 0) {
-      problems.push(`${describeText(label)} has non-positive resolution: ${label.style.resolution}`);
+      problems.push(
+        `${describeText(label)} has non-positive resolution: ${label.style.resolution}`
+      );
     }
     const bounds = label.getBounds();
     for (const [property, value] of Object.entries({
@@ -150,11 +164,13 @@ function assertSceneTextHealth(scene) {
     ...collectBitmapTextHealthProblems(scene)
   ];
   if (problems.length === 0) return;
-  throw new Error([
-    `Phaser text health check failed in scene ${JSON.stringify(scene.scene.key)}:`,
-    ...problems.map((problem) => `- ${problem}`),
-    "Fix optional TextStyle values by omitting them or using Phaser defaults (for example fixedWidth: value ?? 0)."
-  ].join("\n"));
+  throw new Error(
+    [
+      `Phaser text health check failed in scene ${JSON.stringify(scene.scene.key)}:`,
+      ...problems.map((problem) => `- ${problem}`),
+      "Fix optional TextStyle values by omitting them or using Phaser defaults (for example fixedWidth: value ?? 0)."
+    ].join("\n")
+  );
 }
 
 // src/phaser-runtime-assertions.ts
@@ -166,8 +182,10 @@ function collectObjects(scene) {
     if (visited.has(object)) return;
     visited.add(object);
     objects.push(object);
-    if (object instanceof Phaser2.GameObjects.Container) object.list.forEach(visit);
-    if (object instanceof Phaser2.GameObjects.Layer) object.getChildren().forEach(visit);
+    if (object instanceof Phaser2.GameObjects.Container)
+      object.list.forEach(visit);
+    if (object instanceof Phaser2.GameObjects.Layer)
+      object.getChildren().forEach(visit);
   };
   scene.children.getChildren().forEach(visit);
   return objects;
@@ -201,7 +219,9 @@ function requireFiniteVector(problems, subject, target, property) {
     if (!(axis in vector)) continue;
     const value = Reflect.get(vector, axis);
     if (typeof value !== "number" || !Number.isFinite(value)) {
-      problems.push(`${subject} has non-finite ${property}.${axis}: ${String(value)}`);
+      problems.push(
+        `${subject} has non-finite ${property}.${axis}: ${String(value)}`
+      );
     }
   }
 }
@@ -269,7 +289,9 @@ function getArcadeBodyCollection(value) {
 function getArcadeWorldBodies(world) {
   if (!world || typeof world !== "object") return void 0;
   const bodies = getArcadeBodyCollection(Reflect.get(world, "bodies"));
-  const staticBodies = getArcadeBodyCollection(Reflect.get(world, "staticBodies"));
+  const staticBodies = getArcadeBodyCollection(
+    Reflect.get(world, "staticBodies")
+  );
   return bodies && staticBodies ? [...bodies, ...staticBodies] : void 0;
 }
 function collectArcadeBodyHealthProblems(scene) {
@@ -280,22 +302,38 @@ function collectArcadeBodyHealthProblems(scene) {
     if (body.enable === false) continue;
     const gameObject = body.gameObject;
     const subject = gameObject ? `Arcade Body for ${describeObject(gameObject)}` : "Arcade Body";
-    for (const property of ["position", "velocity", "acceleration", "gravity", "offset", "center"]) {
+    for (const property of [
+      "position",
+      "velocity",
+      "acceleration",
+      "gravity",
+      "offset",
+      "center"
+    ]) {
       requireFiniteVector(problems, subject, body, property);
     }
-    for (const property of ["width", "height", "halfWidth", "halfHeight", "rotation"]) {
+    for (const property of [
+      "width",
+      "height",
+      "halfWidth",
+      "halfHeight",
+      "rotation"
+    ]) {
       requireFiniteProperty(problems, subject, body, property);
     }
   }
   return problems;
 }
 function usesCustomHitArea(object) {
-  return Boolean(object.input?.customHitArea);
+  return Boolean(
+    object.input?.customHitArea
+  );
 }
 function collectInteractiveHealthProblems(scene) {
   const problems = [];
   for (const object of collectObjects(scene)) {
-    if (object.active === false || !isEffectivelyVisible(object) || !object.input?.enabled) continue;
+    if (object.active === false || !isEffectivelyVisible(object) || !object.input?.enabled)
+      continue;
     if (usesCustomHitArea(object)) continue;
     const hitArea = object.input.hitArea;
     if (!hitArea) {
@@ -318,20 +356,24 @@ function assertSceneRuntimeHealth(scene) {
     ...collectArcadeBodyHealthProblems(scene)
   ];
   if (problems.length === 0) return;
-  throw new Error([
-    `Phaser runtime health check failed in scene ${JSON.stringify(scene.scene.key)}:`,
-    ...problems.map((problem) => `- ${problem}`),
-    "Keep values consumed by Phaser finite; zero size and zero scale remain allowed."
-  ].join("\n"));
+  throw new Error(
+    [
+      `Phaser runtime health check failed in scene ${JSON.stringify(scene.scene.key)}:`,
+      ...problems.map((problem) => `- ${problem}`),
+      "Keep values consumed by Phaser finite; zero size and zero scale remain allowed."
+    ].join("\n")
+  );
 }
 function assertSceneInteractiveHealth(scene) {
   const problems = collectInteractiveHealthProblems(scene);
   if (problems.length === 0) return;
-  throw new Error([
-    `Phaser interactive health check failed in scene ${JSON.stringify(scene.scene.key)}:`,
-    ...problems.map((problem) => `- ${problem}`),
-    "Fix the default hit area or disable input before making the object interactive."
-  ].join("\n"));
+  throw new Error(
+    [
+      `Phaser interactive health check failed in scene ${JSON.stringify(scene.scene.key)}:`,
+      ...problems.map((problem) => `- ${problem}`),
+      "Fix the default hit area or disable input before making the object interactive."
+    ].join("\n")
+  );
 }
 
 // src/phaser-headless-host.ts
@@ -346,11 +388,32 @@ async function createHeadlessGame(scene, options = {}) {
   let removeRuntimeListeners = () => {
   };
   const transitions = [];
+  const registeredScenes = [];
+  const visitedScenes = [];
+  const restartedScenes = [];
+  const checkpoints = [];
+  const appendUnique = (values, value) => {
+    if (value && !values.includes(value)) values.push(value);
+  };
+  const assertStepCount = (value, name) => {
+    if (!Number.isSafeInteger(value) || value < 0) {
+      throw new Error(
+        `${name} must be a non-negative safe integer; received ${value}`
+      );
+    }
+  };
   const evidence = {
     frames: 0,
     physicsSteps: 0,
     mouseEvents: 0,
+    keyboardEvents: 0,
+    touchEvents: 0,
     clicks: 0,
+    registeredScenes,
+    visitedScenes,
+    restartedScenes,
+    checkpoints,
+    destroyed: false,
     transitions
   };
   const created = new Promise((resolve, reject) => {
@@ -396,7 +459,9 @@ async function createHeadlessGame(scene, options = {}) {
       });
     };
     const timeout = window.setTimeout(() => {
-      finish(new Error(`Phaser HEADLESS boot timed out after ${bootTimeoutMs}ms`));
+      finish(
+        new Error(`Phaser HEADLESS boot timed out after ${bootTimeoutMs}ms`)
+      );
     }, bootTimeoutMs);
     window.addEventListener("error", onWindowError, true);
     window.addEventListener("unhandledrejection", onUnhandledRejection);
@@ -408,7 +473,13 @@ async function createHeadlessGame(scene, options = {}) {
       if (guardedScenes.has(currentScene)) return;
       guardedScenes.add(currentScene);
       const scenePlugin = currentScene.scene;
-      for (const method of ["start", "launch", "switch", "sleep", "wake"]) {
+      for (const method of [
+        "start",
+        "launch",
+        "switch",
+        "sleep",
+        "wake"
+      ]) {
         const original = scenePlugin[method];
         if (typeof original !== "function") continue;
         scenePlugin[method] = (key, ...args) => {
@@ -424,29 +495,49 @@ async function createHeadlessGame(scene, options = {}) {
           scenePlugin[method] = original;
         });
       }
+      const originalRestart = scenePlugin.restart;
+      if (typeof originalRestart === "function") {
+        scenePlugin.restart = (...args) => {
+          appendUnique(restartedScenes, currentScene.sys.settings.key);
+          return Reflect.apply(originalRestart, currentScene.scene, args);
+        };
+        restoreGuards.push(() => {
+          scenePlugin.restart = originalRestart;
+        });
+      }
       for (const hook of ["init", "preload", "create", "update"]) {
         const original = Reflect.get(currentScene, hook);
         if (typeof original !== "function") continue;
-        const ownDescriptor = Object.getOwnPropertyDescriptor(currentScene, hook);
-        Reflect.set(currentScene, hook, function guardedLifecycleHook(...args) {
-          try {
-            const result = Reflect.apply(original, this, args);
-            if (result && typeof result === "object" && "then" in result) {
-              const completion = Promise.resolve(result);
-              if (currentScene === scene && hook === "create" && !settled) {
-                completion.then(() => window.setTimeout(() => finish(), 0), reportError);
-              } else {
-                completion.catch(reportError);
+        const ownDescriptor = Object.getOwnPropertyDescriptor(
+          currentScene,
+          hook
+        );
+        Reflect.set(
+          currentScene,
+          hook,
+          function guardedLifecycleHook(...args) {
+            try {
+              const result = Reflect.apply(original, this, args);
+              if (result && typeof result === "object" && "then" in result) {
+                const completion = Promise.resolve(result);
+                if (currentScene === scene && hook === "create" && !settled) {
+                  completion.then(
+                    () => window.setTimeout(() => finish(), 0),
+                    reportError
+                  );
+                } else {
+                  completion.catch(reportError);
+                }
+              } else if (currentScene === scene && hook === "create" && !settled) {
+                window.setTimeout(() => finish(), 0);
               }
-            } else if (currentScene === scene && hook === "create" && !settled) {
-              window.setTimeout(() => finish(), 0);
+              return result;
+            } catch (error) {
+              reportError(error);
+              return void 0;
             }
-            return result;
-          } catch (error) {
-            reportError(error);
-            return void 0;
           }
-        });
+        );
         restoreGuards.push(() => {
           if (ownDescriptor) {
             Object.defineProperty(currentScene, hook, ownDescriptor);
@@ -475,13 +566,6 @@ async function createHeadlessGame(scene, options = {}) {
         banner: false,
         autoFocus: false,
         seed: ["phaser-headless-test"],
-        physics: {
-          default: "arcade",
-          arcade: {
-            gravity: { x: 0, y: 0 },
-            fixedStep: true
-          }
-        },
         ...config,
         type: Phaser3.HEADLESS,
         fps,
@@ -507,7 +591,10 @@ async function createHeadlessGame(scene, options = {}) {
             };
             bootedGame.events.on(Phaser3.Core.Events.POST_STEP, checkReadiness);
             removeReadinessCheck = () => {
-              bootedGame.events.off(Phaser3.Core.Events.POST_STEP, checkReadiness);
+              bootedGame.events.off(
+                Phaser3.Core.Events.POST_STEP,
+                checkReadiness
+              );
             };
           }
         },
@@ -547,7 +634,9 @@ async function createHeadlessGame(scene, options = {}) {
     restoreHostGuards();
     readyGame.destroy(true);
     readyGame.headlessStep(readyGame.loop.lastTime, 0);
-    throw new Error("Phaser HEADLESS input canvas is not attached to a DOM Window");
+    throw new Error(
+      "Phaser HEADLESS input canvas is not attached to a DOM Window"
+    );
   }
   let canvasBounds = {
     left: 0,
@@ -583,7 +672,9 @@ async function createHeadlessGame(scene, options = {}) {
   setCanvasBounds(canvasBounds);
   const gameToClient = (x, y) => {
     if (!Number.isFinite(x) || !Number.isFinite(y)) {
-      throw new Error(`HEADLESS input coordinates must be finite; received (${x}, ${y})`);
+      throw new Error(
+        `HEADLESS input coordinates must be finite; received (${x}, ${y})`
+      );
     }
     return {
       clientX: canvasBounds.left + x / readyGame.scale.displayScale.x,
@@ -592,7 +683,10 @@ async function createHeadlessGame(scene, options = {}) {
   };
   const assertHealth = () => {
     for (const currentScene of readyGame.scene.getScenes(false)) {
-      if (!currentScene.sys.isActive() && !currentScene.sys.isPaused()) continue;
+      appendUnique(registeredScenes, currentScene.sys.settings.key);
+      if (!currentScene.sys.isActive() && !currentScene.sys.isPaused())
+        continue;
+      appendUnique(visitedScenes, currentScene.sys.settings.key);
       assertSceneTextHealth(currentScene);
       assertSceneInteractiveHealth(currentScene);
       assertSceneRuntimeHealth(currentScene);
@@ -603,17 +697,166 @@ async function createHeadlessGame(scene, options = {}) {
     throwRuntimeError();
     assertHealth();
   };
+  const getEventTarget = (target, kind) => {
+    if (!target || typeof Reflect.get(target, "dispatchEvent") !== "function") {
+      throw new Error(
+        `Phaser HEADLESS ${kind} input target cannot dispatch DOM events`
+      );
+    }
+    return target;
+  };
   const dispatchMouse = async (type, x, y, buttons) => {
     const { clientX, clientY } = gameToClient(x, y);
-    canvas.dispatchEvent(new inputWindow.MouseEvent(type, {
+    const mouseTarget = getEventTarget(readyGame.input.mouse?.target, "mouse");
+    mouseTarget.dispatchEvent(
+      new inputWindow.MouseEvent(type, {
+        bubbles: true,
+        cancelable: true,
+        button: 0,
+        buttons,
+        clientX,
+        clientY
+      })
+    );
+    evidence.mouseEvents += 1;
+    await settleRuntime();
+  };
+  const keyIdentity = (keyCode) => {
+    if (keyCode >= 65 && keyCode <= 90) {
+      const letter = String.fromCharCode(keyCode);
+      return { key: letter.toLowerCase(), code: `Key${letter}` };
+    }
+    if (keyCode >= 48 && keyCode <= 57) {
+      const digit = String.fromCharCode(keyCode);
+      return { key: digit, code: `Digit${digit}` };
+    }
+    const identities = /* @__PURE__ */ new Map([
+      [
+        Phaser3.Input.Keyboard.KeyCodes.LEFT,
+        { key: "ArrowLeft", code: "ArrowLeft" }
+      ],
+      [
+        Phaser3.Input.Keyboard.KeyCodes.RIGHT,
+        { key: "ArrowRight", code: "ArrowRight" }
+      ],
+      [Phaser3.Input.Keyboard.KeyCodes.UP, { key: "ArrowUp", code: "ArrowUp" }],
+      [
+        Phaser3.Input.Keyboard.KeyCodes.DOWN,
+        { key: "ArrowDown", code: "ArrowDown" }
+      ],
+      [Phaser3.Input.Keyboard.KeyCodes.SPACE, { key: " ", code: "Space" }],
+      [Phaser3.Input.Keyboard.KeyCodes.ENTER, { key: "Enter", code: "Enter" }],
+      [Phaser3.Input.Keyboard.KeyCodes.ESC, { key: "Escape", code: "Escape" }]
+    ]);
+    return identities.get(keyCode) ?? { key: "", code: "" };
+  };
+  const dispatchKeyboard = async (type, keyCode, options2 = {}) => {
+    if (!Number.isInteger(keyCode) || keyCode < 0) {
+      throw new Error(
+        `HEADLESS keyboard keyCode must be a non-negative integer; received ${keyCode}`
+      );
+    }
+    const identity = keyIdentity(keyCode);
+    const event = new inputWindow.KeyboardEvent(type, {
       bubbles: true,
       cancelable: true,
-      button: 0,
-      buttons,
+      key: options2.key ?? identity.key,
+      code: options2.code ?? identity.code,
+      repeat: options2.repeat ?? false,
+      altKey: options2.altKey ?? false,
+      ctrlKey: options2.ctrlKey ?? false,
+      metaKey: options2.metaKey ?? false,
+      shiftKey: options2.shiftKey ?? false
+    });
+    Object.defineProperties(event, {
+      // Phaser KeyboardManager 仍使用这些兼容旧浏览器的数字字段。
+      keyCode: { value: keyCode },
+      which: { value: keyCode }
+    });
+    const keyboardTarget = getEventTarget(
+      readyGame.input.keyboard?.target,
+      "keyboard"
+    );
+    keyboardTarget.dispatchEvent(event);
+    evidence.keyboardEvents += 1;
+    await settleRuntime();
+  };
+  const activeTouches = /* @__PURE__ */ new Map();
+  const createTouch = (x, y, identifier, target) => {
+    if (!Number.isInteger(identifier) || identifier < 0) {
+      throw new Error(
+        `HEADLESS touch identifier must be a non-negative integer; received ${identifier}`
+      );
+    }
+    const { clientX, clientY } = gameToClient(x, y);
+    return {
+      identifier,
+      target,
       clientX,
-      clientY
-    }));
-    evidence.mouseEvents += 1;
+      clientY,
+      pageX: clientX,
+      pageY: clientY,
+      screenX: clientX,
+      screenY: clientY,
+      radiusX: 1,
+      radiusY: 1,
+      rotationAngle: 0,
+      force: 1
+    };
+  };
+  const dispatchTouch = async (type, x, y, identifier) => {
+    if (type === "touchstart" && activeTouches.has(identifier)) {
+      throw new Error(
+        `HEADLESS touch identifier ${identifier} is already active`
+      );
+    }
+    if (type !== "touchstart" && !activeTouches.has(identifier)) {
+      throw new Error(`HEADLESS touch identifier ${identifier} is not active`);
+    }
+    const touchTarget = getEventTarget(readyGame.input.touch?.target, "touch");
+    const changedTouch = createTouch(x, y, identifier, touchTarget);
+    if (type === "touchstart" || type === "touchmove") {
+      activeTouches.set(identifier, changedTouch);
+    } else {
+      activeTouches.delete(identifier);
+    }
+    const touches = [...activeTouches.values()];
+    const event = new inputWindow.Event(type, {
+      bubbles: true,
+      cancelable: true
+    });
+    Object.defineProperties(event, {
+      changedTouches: { value: [changedTouch] },
+      targetTouches: { value: touches },
+      touches: { value: touches }
+    });
+    const document = inputWindow.document;
+    const originalElementFromPoint = document.elementFromPoint;
+    const originalElementFromPointDescriptor = Object.getOwnPropertyDescriptor(
+      document,
+      "elementFromPoint"
+    );
+    Object.defineProperty(document, "elementFromPoint", {
+      configurable: true,
+      value(clientX, clientY) {
+        const insideCanvas = clientX >= canvasBounds.left && clientX <= canvasBounds.left + canvasBounds.width && clientY >= canvasBounds.top && clientY <= canvasBounds.top + canvasBounds.height;
+        return insideCanvas ? canvas : originalElementFromPoint?.call(document, clientX, clientY) ?? null;
+      }
+    });
+    try {
+      touchTarget.dispatchEvent(event);
+      evidence.touchEvents += 1;
+    } finally {
+      if (originalElementFromPointDescriptor) {
+        Object.defineProperty(
+          document,
+          "elementFromPoint",
+          originalElementFromPointDescriptor
+        );
+      } else {
+        Reflect.deleteProperty(document, "elementFromPoint");
+      }
+    }
     await settleRuntime();
   };
   const input = {
@@ -631,6 +874,24 @@ async function createHeadlessGame(scene, options = {}) {
         await dispatchMouse("mousedown", x, y, 1);
         await dispatchMouse("mouseup", x, y, 0);
       }
+    },
+    keyboard: {
+      down: (keyCode, options2) => dispatchKeyboard("keydown", keyCode, options2),
+      up: (keyCode, options2) => dispatchKeyboard("keyup", keyCode, options2),
+      async press(keyCode, options2) {
+        await dispatchKeyboard("keydown", keyCode, options2);
+        await dispatchKeyboard("keyup", keyCode, options2);
+      }
+    },
+    touch: {
+      start: (x, y, identifier = 1) => dispatchTouch("touchstart", x, y, identifier),
+      move: (x, y, identifier = 1) => dispatchTouch("touchmove", x, y, identifier),
+      end: (x, y, identifier = 1) => dispatchTouch("touchend", x, y, identifier),
+      cancel: (x, y, identifier = 1) => dispatchTouch("touchcancel", x, y, identifier),
+      async tap(x, y, identifier = 1) {
+        await dispatchTouch("touchstart", x, y, identifier);
+        await dispatchTouch("touchend", x, y, identifier);
+      }
     }
   };
   const frameDurationMs = 1e3 / (config.fps?.target ?? 60);
@@ -639,6 +900,7 @@ async function createHeadlessGame(scene, options = {}) {
     evidence.frames += 1;
   };
   const stepFrames = (count = 1) => {
+    assertStepCount(count, "stepFrames count");
     throwRuntimeError();
     for (let frame = 0; frame < count; frame += 1) stepFrame();
     throwRuntimeError();
@@ -662,21 +924,59 @@ async function createHeadlessGame(scene, options = {}) {
     input,
     evidence,
     assertGameplayEvidence(requirements = {}) {
-      if (requirements.requireInput && evidence.mouseEvents === 0) {
-        throw new Error("Gameplay evidence is missing real HEADLESS input events.");
+      const inputEvents = evidence.mouseEvents + evidence.keyboardEvents + evidence.touchEvents;
+      if (requirements.requireInput && inputEvents === 0) {
+        throw new Error(
+          "Gameplay evidence is missing real HEADLESS input events."
+        );
       }
       if (requirements.requireFrameAdvance && evidence.frames === 0) {
-        throw new Error("Gameplay evidence is missing complete Phaser frame advancement.");
+        throw new Error(
+          "Gameplay evidence is missing complete Phaser frame advancement."
+        );
       }
       if (requirements.requirePhysicsStep && evidence.physicsSteps === 0) {
-        throw new Error("Gameplay evidence is missing Arcade Physics advancement.");
+        throw new Error(
+          "Gameplay evidence is missing Arcade Physics advancement."
+        );
       }
       const requiredTransitions = requirements.requireTransition === void 0 ? [] : typeof requirements.requireTransition === "string" ? [requirements.requireTransition] : requirements.requireTransition;
       for (const target of requiredTransitions) {
         if (!evidence.transitions.some((transition) => transition.to === target)) {
-          throw new Error(`Gameplay evidence is missing a transition to ${target}.`);
+          throw new Error(
+            `Gameplay evidence is missing a transition to ${target}.`
+          );
+        }
+      }
+      const requiredScenes = requirements.requireScene === void 0 ? [] : typeof requirements.requireScene === "string" ? [requirements.requireScene] : requirements.requireScene;
+      for (const sceneKey of requiredScenes) {
+        if (!evidence.visitedScenes.includes(sceneKey)) {
+          throw new Error(
+            `Gameplay evidence is missing a visit to Scene ${sceneKey}.`
+          );
         }
       }
+      const requiredRestarts = requirements.requireRestart === void 0 ? [] : typeof requirements.requireRestart === "string" ? [requirements.requireRestart] : requirements.requireRestart;
+      for (const sceneKey of requiredRestarts) {
+        if (!evidence.restartedScenes.includes(sceneKey)) {
+          throw new Error(
+            `Gameplay evidence is missing a restart of Scene ${sceneKey}.`
+          );
+        }
+      }
+      const requiredCheckpoints = requirements.requireCheckpoint === void 0 ? [] : typeof requirements.requireCheckpoint === "string" ? [requirements.requireCheckpoint] : requirements.requireCheckpoint;
+      for (const checkpoint of requiredCheckpoints) {
+        if (!evidence.checkpoints.includes(checkpoint)) {
+          throw new Error(
+            `Gameplay evidence is missing checkpoint ${checkpoint}.`
+          );
+        }
+      }
+      if (requirements.requireDestroy && !evidence.destroyed) {
+        throw new Error(
+          "Gameplay evidence is missing HEADLESS host destruction."
+        );
+      }
     },
     stepFrames,
     async stepFramesAsync(count = 1) {
@@ -684,6 +984,7 @@ async function createHeadlessGame(scene, options = {}) {
       await settleRuntime();
     },
     stepUntil(condition, maxFrames = 120) {
+      assertStepCount(maxFrames, "stepUntil maxFrames");
       throwRuntimeError();
       for (let frame = 0; frame <= maxFrames; frame += 1) {
         if (condition()) {
@@ -696,13 +997,18 @@ async function createHeadlessGame(scene, options = {}) {
         }
       }
       assertHealth();
-      throw new Error(`Condition was not met within ${maxFrames} complete Phaser frames`);
+      throw new Error(
+        `Condition was not met within ${maxFrames} complete Phaser frames`
+      );
     },
     stepPhysics(steps = 1) {
+      assertStepCount(steps, "stepPhysics steps");
       throwRuntimeError();
       const world = scene.physics?.world;
       if (!world || !getArcadeWorldBodies(world) || typeof world.singleStep !== "function") {
-        throw new Error("stepPhysics() requires an Arcade Physics world; use stepFrames() for other configurations.");
+        throw new Error(
+          "stepPhysics() requires an Arcade Physics world; use stepFrames() for other configurations."
+        );
       }
       for (let step = 0; step < steps; step += 1) {
         scene.physics.world.singleStep();
@@ -711,6 +1017,15 @@ async function createHeadlessGame(scene, options = {}) {
       throwRuntimeError();
       assertHealth();
     },
+    checkpoint(id) {
+      const normalizedId = id.trim();
+      if (!normalizedId || normalizedId.length > 120) {
+        throw new Error(
+          "Gameplay checkpoint id must contain 1 to 120 non-whitespace characters."
+        );
+      }
+      appendUnique(checkpoints, normalizedId);
+    },
     assertTextHealth() {
       assertSceneTextHealth(scene);
     },
@@ -723,6 +1038,7 @@ async function createHeadlessGame(scene, options = {}) {
         readyGame.destroy(true);
         readyGame.headlessStep(readyGame.loop.lastTime, 0);
         throwRuntimeError();
+        evidence.destroyed = true;
       } finally {
         removeRuntimeListeners();
         restoreHostGuards();
@@ -744,9 +1060,11 @@ var SmokeScene = class extends Phaser4.Scene {
     this.randomValue = Phaser4.Math.RND.frac();
     this.movingObject = this.add.zone(40, 50, 16, 16);
     this.textObject = this.add.text(8, 8, "READY", { fontSize: "16px" });
-    this.physics.add.existing(this.movingObject);
-    const body = this.movingObject.body;
-    body.setVelocityX(60);
+    if (this.physics) {
+      this.physics.add.existing(this.movingObject);
+      const body = this.movingObject.body;
+      body.setVelocityX(60);
+    }
   }
   update() {
     this.updates += 1;
@@ -767,6 +1085,38 @@ var LayeredInputScene = class extends Phaser4.Scene {
     });
   }
 };
+var KeyboardInputScene = class extends Phaser4.Scene {
+  playerX = 0;
+  rightKey;
+  constructor() {
+    super("KeyboardInputScene");
+  }
+  create() {
+    this.rightKey = this.input.keyboard.addKey(
+      Phaser4.Input.Keyboard.KeyCodes.RIGHT
+    );
+  }
+  update() {
+    if (this.rightKey.isDown) this.playerX += 1;
+  }
+};
+var TouchInputScene = class extends Phaser4.Scene {
+  moves = 0;
+  taps = 0;
+  wasTouch = false;
+  constructor() {
+    super("TouchInputScene");
+  }
+  create() {
+    this.add.zone(80, 60, 40, 40).setInteractive().on("pointerup", (pointer) => {
+      this.taps += 1;
+      this.wasTouch = pointer.wasTouch;
+    });
+    this.input.on("pointermove", (pointer) => {
+      if (pointer.wasTouch) this.moves += 1;
+    });
+  }
+};
 describe("Phaser HEADLESS host", () => {
   let host;
   afterEach(() => {
@@ -774,7 +1124,12 @@ describe("Phaser HEADLESS host", () => {
     host = void 0;
   });
   it("boots a scene without a renderer and advances Arcade Physics", async () => {
-    host = await createHeadlessGame(new SmokeScene());
+    host = await createHeadlessGame(new SmokeScene(), {
+      physics: {
+        default: "arcade",
+        arcade: { gravity: { x: 0, y: 0 }, fixedStep: true }
+      }
+    });
     expect(host.game.renderer).toBeNull();
     expect(host.scene.sys.isActive()).toBe(true);
     const initialX = host.scene.movingObject.x;
@@ -786,14 +1141,35 @@ describe("Phaser HEADLESS host", () => {
     host.stepFrames(3);
     expect(host.scene.updates).toBe(initialUpdates + 3);
   });
+  it("rejects invalid advancement counts instead of entering an unbounded loop", async () => {
+    const boundedHost = await createHeadlessGame(new LayeredInputScene());
+    expect(() => boundedHost.stepFrames(Number.POSITIVE_INFINITY)).toThrow(
+      "stepFrames count must be a non-negative safe integer"
+    );
+    expect(() => boundedHost.stepUntil(() => false, 1.5)).toThrow(
+      "stepUntil maxFrames must be a non-negative safe integer"
+    );
+    expect(() => boundedHost.stepPhysics(-1)).toThrow(
+      "stepPhysics steps must be a non-negative safe integer"
+    );
+    boundedHost.destroy();
+  });
   it("drives scaled DOM mouse input through hit testing and top-only dispatch", async () => {
     const inputHost = await createHeadlessGame(new LayeredInputScene(), {
       width: 160,
       height: 120
     });
     inputHost.stepFrames();
-    inputHost.input.setCanvasBounds({ left: 20, top: 30, width: 80, height: 60 });
-    expect(inputHost.input.gameToClient(80, 60)).toEqual({ clientX: 60, clientY: 60 });
+    inputHost.input.setCanvasBounds({
+      left: 20,
+      top: 30,
+      width: 80,
+      height: 60
+    });
+    expect(inputHost.input.gameToClient(80, 60)).toEqual({
+      clientX: 60,
+      clientY: 60
+    });
     await inputHost.input.mouse.click(80, 60);
     expect({
       pointerX: inputHost.scene.input.activePointer.x,
@@ -813,6 +1189,68 @@ describe("Phaser HEADLESS host", () => {
     expect(inputHost.evidence.clicks).toBe(2);
     inputHost.destroy();
   });
+  it("drives held DOM keyboard input through Phaser's configured target", async () => {
+    const keyboardHost = await createHeadlessGame(new KeyboardInputScene());
+    await keyboardHost.input.keyboard.down(
+      Phaser4.Input.Keyboard.KeyCodes.RIGHT
+    );
+    keyboardHost.stepFrames(3);
+    expect(keyboardHost.scene.playerX).toBe(3);
+    await keyboardHost.input.keyboard.up(Phaser4.Input.Keyboard.KeyCodes.RIGHT);
+    keyboardHost.stepFrames(2);
+    expect(keyboardHost.scene.playerX).toBe(3);
+    expect(keyboardHost.evidence.keyboardEvents).toBe(2);
+    expect(
+      () => keyboardHost.assertGameplayEvidence({ requireInput: true })
+    ).not.toThrow();
+    keyboardHost.destroy();
+  });
+  it("drives DOM touch input through pointer conversion and hit testing", async () => {
+    const touchHost = await createHeadlessGame(new TouchInputScene(), {
+      width: 160,
+      height: 120
+    });
+    touchHost.stepFrames();
+    touchHost.input.setCanvasBounds({
+      left: 20,
+      top: 30,
+      width: 80,
+      height: 60
+    });
+    await touchHost.input.touch.start(40, 40);
+    await touchHost.input.touch.move(80, 60);
+    await touchHost.input.touch.end(80, 60);
+    expect({
+      moves: touchHost.scene.moves,
+      pointerX: touchHost.scene.input.activePointer.x,
+      pointerY: touchHost.scene.input.activePointer.y,
+      taps: touchHost.scene.taps,
+      wasTouch: touchHost.scene.wasTouch
+    }).toEqual({
+      moves: 1,
+      pointerX: 80,
+      pointerY: 60,
+      taps: 1,
+      wasTouch: true
+    });
+    expect(touchHost.evidence.touchEvents).toBe(3);
+    expect(
+      () => touchHost.assertGameplayEvidence({ requireInput: true })
+    ).not.toThrow();
+    touchHost.destroy();
+  });
+  it("boots when a production input family is disabled", async () => {
+    const mouseOnlyHost = await createHeadlessGame(new SmokeScene(), {
+      input: { keyboard: false, touch: false }
+    });
+    await expect(
+      mouseOnlyHost.input.keyboard.press(Phaser4.Input.Keyboard.KeyCodes.SPACE)
+    ).rejects.toThrow("keyboard input target cannot dispatch DOM events");
+    await expect(mouseOnlyHost.input.touch.tap(20, 20)).rejects.toThrow(
+      "touch input target cannot dispatch DOM events"
+    );
+    mouseOnlyHost.destroy();
+  });
   it("registers transition targets before boot and settles queued transitions", async () => {
     class TargetScene extends Phaser4.Scene {
       receivedValue = 0;
@@ -841,8 +1279,12 @@ describe("Phaser HEADLESS host", () => {
     transitionHost.stepFrames();
     expect(transitionHost.game.scene.isActive("TargetScene")).toBe(false);
     await transitionHost.input.mouse.click(40, 40);
-    transitionHost.stepUntil(() => transitionHost.game.scene.isActive("TargetScene"));
-    const target = transitionHost.game.scene.getScene("TargetScene");
+    transitionHost.stepUntil(
+      () => transitionHost.game.scene.isActive("TargetScene")
+    );
+    const target = transitionHost.game.scene.getScene(
+      "TargetScene"
+    );
     expect(target.receivedValue).toBe(7);
     expect(transitionHost.game.scene.isActive("SourceScene")).toBe(false);
     transitionHost.assertGameplayEvidence({
@@ -866,11 +1308,39 @@ describe("Phaser HEADLESS host", () => {
     optionalHost.stepFrames();
     expect(optionalHost.scene.sys.isActive()).toBe(true);
     expect(optionalHost.evidence.transitions).toEqual([
-      { from: "OptionalCommandScene", to: "OptionalCommandScene", method: "sleep" },
-      { from: "OptionalCommandScene", to: "OptionalCommandScene", method: "wake" }
+      {
+        from: "OptionalCommandScene",
+        to: "OptionalCommandScene",
+        method: "sleep"
+      },
+      {
+        from: "OptionalCommandScene",
+        to: "OptionalCommandScene",
+        method: "wake"
+      }
     ]);
     optionalHost.destroy();
   });
+  it("records Scene visits, restart, checkpoints, and destruction", async () => {
+    const evidenceHost = await createHeadlessGame(new SmokeScene());
+    evidenceHost.checkpoint("progress");
+    evidenceHost.scene.scene.restart();
+    evidenceHost.stepFrames();
+    evidenceHost.destroy();
+    expect(evidenceHost.evidence.registeredScenes).toContain("SmokeScene");
+    expect(evidenceHost.evidence.visitedScenes).toContain("SmokeScene");
+    expect(evidenceHost.evidence.restartedScenes).toContain("SmokeScene");
+    expect(evidenceHost.evidence.checkpoints).toEqual(["progress"]);
+    expect(evidenceHost.evidence.destroyed).toBe(true);
+    expect(
+      () => evidenceHost.assertGameplayEvidence({
+        requireScene: "SmokeScene",
+        requireRestart: "SmokeScene",
+        requireCheckpoint: "progress",
+        requireDestroy: true
+      })
+    ).not.toThrow();
+  });
   it("surfaces exceptions thrown by DOM-driven input callbacks", async () => {
     class BrokenInputScene extends Phaser4.Scene {
       create() {
@@ -918,7 +1388,9 @@ describe("Phaser HEADLESS host", () => {
         (zone.input?.hitArea).width = 0;
       }
     }
-    await expect(createHeadlessGame(new InvalidInteractiveScene())).rejects.toThrow(
+    await expect(
+      createHeadlessGame(new InvalidInteractiveScene())
+    ).rejects.toThrow(
       /interactive health check failed.*invalid default hit area/s
     );
   });
@@ -942,9 +1414,9 @@ describe("Phaser HEADLESS host", () => {
         this.add.zone(Number.NaN, 20, 10, 10);
       }
     }
-    await expect(createHeadlessGame(new InvalidTransformScene())).rejects.toThrow(
-      /runtime health check failed.*non-finite x: NaN/s
-    );
+    await expect(
+      createHeadlessGame(new InvalidTransformScene())
+    ).rejects.toThrow(/runtime health check failed.*non-finite x: NaN/s);
   });
   it("rejects zero Camera zoom but allows negative zoom", async () => {
     class InvalidCameraScene extends Phaser4.Scene {
@@ -971,9 +1443,11 @@ describe("Phaser HEADLESS host", () => {
         object.body.velocity.x = Number.NaN;
       }
     }
-    await expect(createHeadlessGame(new InvalidBodyScene())).rejects.toThrow(
-      /runtime health check failed.*velocity.x: NaN/s
-    );
+    await expect(
+      createHeadlessGame(new InvalidBodyScene(), {
+        physics: { default: "arcade" }
+      })
+    ).rejects.toThrow(/runtime health check failed.*velocity.x: NaN/s);
     class DisabledBodyScene extends Phaser4.Scene {
       create() {
         const object = this.add.zone(20, 20, 10, 10);
@@ -983,7 +1457,9 @@ describe("Phaser HEADLESS host", () => {
         body.velocity.x = Number.NaN;
       }
     }
-    const disabledHost = await createHeadlessGame(new DisabledBodyScene());
+    const disabledHost = await createHeadlessGame(new DisabledBodyScene(), {
+      physics: { default: "arcade" }
+    });
     expect(() => disabledHost.destroy()).not.toThrow();
   });
   it("captures rejected async lifecycle hooks", async () => {
@@ -1046,7 +1522,8 @@ describe("Phaser HEADLESS host", () => {
         this.add.text(8, 8, "NO PHYSICS");
       }
     }
-    const noPhysicsHost = await createHeadlessGame(new NoPhysicsScene(), { physics: void 0 });
+    const noPhysicsHost = await createHeadlessGame(new NoPhysicsScene());
+    expect(noPhysicsHost.scene.physics).toBeUndefined();
     expect(() => noPhysicsHost.stepFrames()).not.toThrow();
     expect(() => noPhysicsHost.stepPhysics()).toThrow(
       "stepPhysics() requires an Arcade Physics world"