miaoda-game-devkit 0.1.0 → 0.2.0

package/dist/index.mjs

@@ -21,7 +21,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) {
@@ -75,7 +77,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;
 }
@@ -100,19 +104,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({
@@ -146,11 +160,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
@@ -162,8 +178,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;
@@ -197,7 +215,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)}`
+      );
     }
   }
 }
@@ -265,7 +285,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) {
@@ -276,22 +298,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) {
@@ -314,20 +352,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
@@ -342,11 +384,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) => {
@@ -392,7 +455,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);
@@ -404,7 +469,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) => {
@@ -420,29 +491,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);
@@ -471,13 +562,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,
@@ -503,7 +587,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
+              );
             };
           }
         },
@@ -543,7 +630,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,
@@ -579,7 +668,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,
@@ -588,7 +679,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);
@@ -599,17 +693,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 = {
@@ -627,6 +870,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);
@@ -635,6 +896,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();
@@ -658,21 +920,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) {
@@ -680,6 +980,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()) {
@@ -692,13 +993,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();
@@ -707,6 +1013,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);
     },
@@ -719,6 +1034,7 @@ async function createHeadlessGame(scene, options = {}) {
         readyGame.destroy(true);
         readyGame.headlessStep(readyGame.loop.lastTime, 0);
         throwRuntimeError();
+        evidence.destroyed = true;
       } finally {
         removeRuntimeListeners();
         restoreHostGuards();
@@ -728,18 +1044,79 @@ async function createHeadlessGame(scene, options = {}) {
 }
 
 // src/gameplay-contracts.ts
-function registerGameplayContract(context, options) {
-  const task = context;
-  const metadata = {
-    id: options.id,
-    requirements: {
-      requireInput: options.requireInput,
-      requireFrameAdvance: options.requireFrameAdvance,
-      requirePhysicsStep: options.requirePhysicsStep,
-      requireTransition: options.requireTransition
-    }
+import { test } from "vitest";
+
+// src/gameplay-audit.ts
+function normalizeList(value) {
+  if (value === void 0) return [];
+  const values = typeof value === "string" ? [value] : value;
+  return [...new Set(values.map((item) => item.trim()).filter(Boolean))];
+}
+function normalizeSet(values) {
+  return [
+    ...new Set(values.map((value) => value.trim()).filter(Boolean))
+  ].sort();
+}
+function normalizeGameplayRequirements(requirements, scenes) {
+  const requiredScenes = normalizeSet([
+    ...scenes,
+    ...normalizeList(requirements.requireScene)
+  ]);
+  return {
+    requireInput: requirements.requireInput || void 0,
+    requireFrameAdvance: requirements.requireFrameAdvance || void 0,
+    requirePhysicsStep: requirements.requirePhysicsStep || void 0,
+    requireTransition: normalizeList(requirements.requireTransition),
+    requireScene: requiredScenes,
+    requireRestart: normalizeList(requirements.requireRestart),
+    requireCheckpoint: normalizeList(requirements.requireCheckpoint),
+    requireDestroy: true
+  };
+}
+function createGameplayContractMetadata(contract) {
+  const scenes = normalizeSet(contract.scenes);
+  return {
+    id: contract.id.trim(),
+    scenes,
+    requirements: normalizeGameplayRequirements(contract, scenes),
+    verified: false
+  };
+}
+
+// src/gameplay-contracts.ts
+function snapshotEvidence(evidence) {
+  return {
+    frames: evidence.frames,
+    physicsSteps: evidence.physicsSteps,
+    mouseEvents: evidence.mouseEvents,
+    keyboardEvents: evidence.keyboardEvents,
+    touchEvents: evidence.touchEvents,
+    clicks: evidence.clicks,
+    registeredScenes: [...evidence.registeredScenes],
+    visitedScenes: [...evidence.visitedScenes],
+    restartedScenes: [...evidence.restartedScenes],
+    checkpoints: [...evidence.checkpoints],
+    destroyed: evidence.destroyed,
+    transitions: evidence.transitions.map((transition) => ({ ...transition }))
   };
-  task.task.meta.gameplayContract = metadata;
+}
+function readStaticMetadata(context, options) {
+  const metadata = context.task.meta.gameplayContract;
+  if (!metadata || typeof metadata !== "object") return void 0;
+  const candidate = metadata;
+  if (candidate.id !== options.id) {
+    throw new Error(
+      `\u9759\u6001 gameplay contract "${candidate.id}" \u4E0E\u8FD0\u884C\u65F6 contract "${options.id}" \u4E0D\u4E00\u81F4\u3002`
+    );
+  }
+  return candidate;
+}
+function registerGameplayContract(context, options) {
+  const metadata = readStaticMetadata(context, options) ?? createGameplayContractMetadata({
+    ...options,
+    scenes: options.scenes ?? []
+  });
+  context.task.meta.gameplayContract = metadata;
   let host;
   let verified = false;
   let testFailed = false;
@@ -749,16 +1126,13 @@ function registerGameplayContract(context, options) {
   const verify = () => {
     if (verified) return;
     if (!host) {
-      throw new Error(`Gameplay contract "${options.id}" did not attach a HEADLESS host.`);
+      throw new Error(
+        `Gameplay contract "${options.id}" \u6CA1\u6709\u7ED1\u5B9A HEADLESS host\u3002`
+      );
     }
     host.assertGameplayEvidence(metadata.requirements);
-    metadata.evidence = {
-      frames: host.evidence.frames,
-      physicsSteps: host.evidence.physicsSteps,
-      mouseEvents: host.evidence.mouseEvents,
-      clicks: host.evidence.clicks,
-      transitions: host.evidence.transitions.map((transition) => ({ ...transition }))
-    };
+    metadata.evidence = snapshotEvidence(host.evidence);
+    metadata.verified = true;
     verified = true;
   };
   context.onTestFinished(() => {
@@ -768,18 +1142,31 @@ function registerGameplayContract(context, options) {
   return {
     attachHost(currentHost) {
       if (host) {
-        throw new Error(`Gameplay contract "${options.id}" attached more than one host.`);
+        throw new Error(
+          `Gameplay contract "${options.id}" \u91CD\u590D\u7ED1\u5B9A\u4E86 HEADLESS host\u3002`
+        );
       }
       host = currentHost;
     },
     verify
   };
 }
+function gameplayTest(name, options, run) {
+  const metadata = createGameplayContractMetadata(options);
+  test(name, {
+    ...options.testOptions,
+    meta: { gameplayContract: metadata }
+  }, async (context) => {
+    const contract = registerGameplayContract(context, options);
+    await run({ context, contract });
+  });
+}
 export {
   assertSceneInteractiveHealth,
   assertSceneRuntimeHealth,
   assertSceneTextHealth,
   collectMissingBitmapGlyphs,
   createHeadlessGame,
+  gameplayTest,
   registerGameplayContract
 };