miaoda-game-devkit 0.2.7 → 0.2.9

package/README.md

@@ -10,21 +10,25 @@
 - 统一的 `miaoda-game-lint` 命令，聚合 TypeScript、Biome、Tailwind、
   Oxlint 和 Phaser 通用契约检查。
 - 统一的 `defineGameVitestConfig` 配置工厂，固定 Phaser 无头测试依赖的基础配置，
-  同时允许每个游戏声明玩法审计清单，并配置额外 alias、setup 文件和超时。
+  同时允许每个游戏声明 Scene 审计范围，并配置额外 alias、setup 文件和超时。
+
+互动游戏的长流程优先使用游戏自己暴露的 `globalThis.gameTelemetry`。稳定 façade 通常调用
+`installGameTelemetry(this.game, telemetry)` 绑定 Game 生命周期；只有刻意局部的 façade 才绑定
+Scene 生命周期。开发工具包只规定最小
+外壳：`version: 1`、`read.session()` 和游戏自有的 `controls`；`fixtures` 可选。快照字段、
+控制方法名和 Core 适配由游戏负责，controls 必须调用与生产输入共享的权威命令。Telemetry
+不会复制 `host.stepFrames()`、DOM 输入或 Scene 生命周期 API。
 
 `createHeadlessGame` 还记录测试期间真实发生的输入、完整帧、物理步、Scene 注册与访问、
 Scene 命令、restart、业务 checkpoint 和销毁。玩法测试可以调用
 `host.assertGameplayEvidence()` 把这些客观事实设为门禁；它不推断业务语义，
 authoritative state 仍必须由测试显式断言。
 
-玩法测试应优先使用 `gameplayTest`。它在 Vitest 收集阶段写入测试声明，
-在执行阶段绑定 HEADLESS host，并在 `onTestFinished` 校验 Ledger。配置加载阶段会先校验
-交互项目的最低基线：至少一个 `kind: "playthrough"` contract 必须要求真实输入、完整帧和
-语义 checkpoint，每个非入口 Scene 必须有生产转场覆盖；检测到 `scene.restart()` 时还必须
-声明 `flows.restart: true` 和 `kind: "recovery"` contract。配置预检失败时测试和 coverage
-都不会运行。配置通过后，`gameplayAudit` reporter 才会检查测试声明，并在结束时汇总
-缺失、失败、证据不足、Scene 未访问和 registry 不一致。`registerGameplayContract` 保留为
-不参加执行前预检的低层接口。
+玩法测试应优先使用 `gameplayTest`。它是玩法 contract 的唯一权威声明，在执行阶段绑定
+HEADLESS host，并在 `onTestFinished` 校验 Ledger。`vitest.config.ts` 默认只列生产 Scene，
+不再复制 contract id、测试文件和证据要求。Reporter 从测试 metadata 汇总交互项目的最低
+基线、失败、证据不足、Scene 未访问和 registry 不一致。旧项目仍可提供显式
+`gameplayAudit.contracts` 清单，但新游戏通常不需要。
 
 模板直接调用开发工具包提供的命令行程序：
 
@@ -51,7 +55,9 @@ monorepo 中的模板可以放置只包含 `extends: ["miaoda-game-devkit/biome"
 工具包集中维护，`miaoda-game-lint` 会直接检查模板的这个配置。
 
 具体游戏的玩法测试仍由模板使用方放在 `tests/`。运行时测试从本开发工具包
-导入 `createHeadlessGame`，通过真实 DOM 输入驱动游戏，并断言有意义的业务状态变化。
+导入 `createHeadlessGame`；有限目标游戏通过合法 Telemetry controls 走到正常成功终局，
+无尽或沙盒游戏证明有意义的持续进展。短输入测试从入口操作走到一个主要操作，用真实 DOM
+事件证明生产输入接线，并通过 Telemetry 断言业务状态变化。
 同步帧逻辑使用 `stepFrames()`；`update()` 返回 Promise 时使用
 `await stepFramesAsync()`，其他同步操作启动生命周期 Promise 后使用 `await settle()`。
 
@@ -79,13 +85,13 @@ DOM 到 Phaser 的输入、命中测试和游戏状态变化，不验证 Canvas/
 模板的 `vitest.config.ts` 应从 `miaoda-game-devkit/vitest-config` 导入
 `defineGameVitestConfig`。JSDOM 环境、Phaser 浏览器构建别名、通用 setup 和 mock 隔离
 以及 Scene coverage 均由开发工具包统一维护。模板必须传入 `projectRoot` 和
-`gameplayAudit`；清单列出生产 Scene、关键 contract、负责的测试文件和证据要求。
+`gameplayAudit`；默认只列生产 Scene，关键流程及证据要求由 `gameplayTest` 自己声明一次。
 确有需要时，可以通过 `aliases`、`additionalSetupFiles`、`testTimeout` 和 `hookTimeout`
 增加安全的项目配置，不能覆盖测试范围、运行环境、审计 reporter 或 coverage 基线。
 
 `gameplayTest` 会自动要求访问其声明的 Scene 并完成 host 销毁。玩法进展、恢复和终局应在
 断言 authoritative state 后调用 `host.checkpoint("progress")`、
-`host.checkpoint("recovery")` 等稳定检查点，并在清单中通过 `requireCheckpoint` 声明。
+`host.checkpoint("recovery")` 等稳定检查点，并在对应 `gameplayTest` 中通过 `requireCheckpoint` 声明。
 运行结束会输出稳定的 `GAMEPLAY_AUDIT: ALL CONTRACTS PASSED` 或
 `GAMEPLAY_AUDIT: ... FAILED` 标识。该标识只表示玩法证据审计；`pnpm test` 的整体结果
 必须以最后的 `TEST_RESULT: PASS` 或 `TEST_RESULT: FAIL` 为准。失败报告按根因合并问题并

package/dist/{gameplay-audit-CusQfLYQ.d.mts → gameplay-audit-CCJo4Qhk.d.mts}

@@ -186,8 +186,8 @@ interface GameplayAuditOptions {
     };
     /** 生产 Scene registry 中预期出现的全部 Scene key。 */
     scenes: string[];
-    /** 必须定义、执行并满足证据要求的玩法契约。 */
-    contracts: GameplayAuditContract[];
+    /** 可选的兼容清单；省略时以 gameplayTest metadata 作为唯一权威来源。 */
+    contracts?: GameplayAuditContract[];
 }
 /** 通过 Vitest task metadata 在 worker 与 reporter 之间传递的契约数据。 */
 interface GameplayContractMetadata {

package/dist/{gameplay-audit-CusQfLYQ.d.ts → gameplay-audit-CCJo4Qhk.d.ts}

@@ -186,8 +186,8 @@ interface GameplayAuditOptions {
     };
     /** 生产 Scene registry 中预期出现的全部 Scene key。 */
     scenes: string[];
-    /** 必须定义、执行并满足证据要求的玩法契约。 */
-    contracts: GameplayAuditContract[];
+    /** 可选的兼容清单；省略时以 gameplayTest metadata 作为唯一权威来源。 */
+    contracts?: GameplayAuditContract[];
 }
 /** 通过 Vitest task metadata 在 worker 与 reporter 之间传递的契约数据。 */
 interface GameplayContractMetadata {

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-CusQfLYQ.mjs';
-export { b as GameplayAuditContract, c as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-CusQfLYQ.mjs';
+import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-CCJo4Qhk.mjs';
+export { b as GameplayAuditContract, c as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-CCJo4Qhk.mjs';
 import * as Phaser from 'phaser';
 import { TestContext, TestOptions } from 'vitest';
 
@@ -68,6 +68,29 @@ declare module "vitest" {
     }
 }
 
+/** The single global entry point used by game-owned HEADLESS telemetry. */
+declare const GAME_TELEMETRY_GLOBAL: "gameTelemetry";
+/**
+ * A game-owned observation and command boundary for deterministic runtime tests.
+ * Snapshot fields and command names intentionally remain specific to each game.
+ */
+interface GameTelemetry<SessionSnapshot, Controls extends object, Fixtures extends object = Record<string, never>> {
+    version: 1;
+    read: {
+        session(): SessionSnapshot;
+    };
+    controls: Controls;
+    fixtures?: Fixtures;
+}
+type AnyGameTelemetry = GameTelemetry<unknown, object, object>;
+/**
+ * Install a game- or Scene-owned Telemetry handle and remove it on lifecycle exit.
+ * Game ownership survives Scene transitions; Scene ownership is useful for local facades.
+ */
+declare function installGameTelemetry<Telemetry extends AnyGameTelemetry>(owner: Phaser.Game | Phaser.Scene, telemetry: Telemetry): () => void;
+/** Read the current typed game handle or fail with a direct setup diagnosis. */
+declare function getGameTelemetry<Telemetry extends AnyGameTelemetry>(): Telemetry;
+
 declare function assertSceneRuntimeHealth(scene: Phaser.Scene): void;
 declare function assertSceneInteractiveHealth(scene: Phaser.Scene): void;
 
@@ -76,4 +99,4 @@ declare function collectMissingBitmapGlyphs(text: string, chars: Record<number,
 /** 在文字状态损坏时抛出适合 CI 和编码智能体处理的错误。 */
 declare function assertSceneTextHealth(scene: Phaser.Scene): void;
 
-export { type GameplayContractHandle, GameplayContractMetadata, type GameplayContractOptions, type GameplayTestArguments, type GameplayTestContext, type GameplayTestOptions, HeadlessGameHost, HeadlessGameplayEvidenceRequirements, assertSceneInteractiveHealth, assertSceneRuntimeHealth, assertSceneTextHealth, collectMissingBitmapGlyphs, gameplayTest, registerGameplayContract };
+export { type AnyGameTelemetry, GAME_TELEMETRY_GLOBAL, type GameTelemetry, type GameplayContractHandle, GameplayContractMetadata, type GameplayContractOptions, type GameplayTestArguments, type GameplayTestContext, type GameplayTestOptions, HeadlessGameHost, HeadlessGameplayEvidenceRequirements, assertSceneInteractiveHealth, assertSceneRuntimeHealth, assertSceneTextHealth, collectMissingBitmapGlyphs, gameplayTest, getGameTelemetry, installGameTelemetry, registerGameplayContract };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-CusQfLYQ.js';
-export { b as GameplayAuditContract, c as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-CusQfLYQ.js';
+import { G as GameplayContractMetadata, H as HeadlessGameHost, a as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-CCJo4Qhk.js';
+export { b as GameplayAuditContract, c as GameplayAuditOptions, d as HeadlessCanvasBounds, e as HeadlessGameOptions, f as HeadlessGameplayEvidence, g as HeadlessInputDriver, h as HeadlessInputPoint, i as HeadlessKeyboardEventOptions, j as HeadlessKeyboardInput, k as HeadlessMouseInput, l as HeadlessTouchInput, m as createHeadlessGame } from './gameplay-audit-CCJo4Qhk.js';
 import * as Phaser from 'phaser';
 import { TestContext, TestOptions } from 'vitest';
 
@@ -68,6 +68,29 @@ declare module "vitest" {
     }
 }
 
+/** The single global entry point used by game-owned HEADLESS telemetry. */
+declare const GAME_TELEMETRY_GLOBAL: "gameTelemetry";
+/**
+ * A game-owned observation and command boundary for deterministic runtime tests.
+ * Snapshot fields and command names intentionally remain specific to each game.
+ */
+interface GameTelemetry<SessionSnapshot, Controls extends object, Fixtures extends object = Record<string, never>> {
+    version: 1;
+    read: {
+        session(): SessionSnapshot;
+    };
+    controls: Controls;
+    fixtures?: Fixtures;
+}
+type AnyGameTelemetry = GameTelemetry<unknown, object, object>;
+/**
+ * Install a game- or Scene-owned Telemetry handle and remove it on lifecycle exit.
+ * Game ownership survives Scene transitions; Scene ownership is useful for local facades.
+ */
+declare function installGameTelemetry<Telemetry extends AnyGameTelemetry>(owner: Phaser.Game | Phaser.Scene, telemetry: Telemetry): () => void;
+/** Read the current typed game handle or fail with a direct setup diagnosis. */
+declare function getGameTelemetry<Telemetry extends AnyGameTelemetry>(): Telemetry;
+
 declare function assertSceneRuntimeHealth(scene: Phaser.Scene): void;
 declare function assertSceneInteractiveHealth(scene: Phaser.Scene): void;
 
@@ -76,4 +99,4 @@ declare function collectMissingBitmapGlyphs(text: string, chars: Record<number,
 /** 在文字状态损坏时抛出适合 CI 和编码智能体处理的错误。 */
 declare function assertSceneTextHealth(scene: Phaser.Scene): void;
 
-export { type GameplayContractHandle, GameplayContractMetadata, type GameplayContractOptions, type GameplayTestArguments, type GameplayTestContext, type GameplayTestOptions, HeadlessGameHost, HeadlessGameplayEvidenceRequirements, assertSceneInteractiveHealth, assertSceneRuntimeHealth, assertSceneTextHealth, collectMissingBitmapGlyphs, gameplayTest, registerGameplayContract };
+export { type AnyGameTelemetry, GAME_TELEMETRY_GLOBAL, type GameTelemetry, type GameplayContractHandle, GameplayContractMetadata, type GameplayContractOptions, type GameplayTestArguments, type GameplayTestContext, type GameplayTestOptions, HeadlessGameHost, HeadlessGameplayEvidenceRequirements, assertSceneInteractiveHealth, assertSceneRuntimeHealth, assertSceneTextHealth, collectMissingBitmapGlyphs, gameplayTest, getGameTelemetry, installGameTelemetry, registerGameplayContract };

package/dist/index.js

@@ -30,12 +30,15 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  GAME_TELEMETRY_GLOBAL: () => GAME_TELEMETRY_GLOBAL,
   assertSceneInteractiveHealth: () => assertSceneInteractiveHealth,
   assertSceneRuntimeHealth: () => assertSceneRuntimeHealth,
   assertSceneTextHealth: () => assertSceneTextHealth,
   collectMissingBitmapGlyphs: () => collectMissingBitmapGlyphs,
   createHeadlessGame: () => createHeadlessGame,
   gameplayTest: () => gameplayTest,
+  getGameTelemetry: () => getGameTelemetry,
+  installGameTelemetry: () => installGameTelemetry,
   registerGameplayContract: () => registerGameplayContract
 });
 module.exports = __toCommonJS(src_exports);
@@ -1215,13 +1218,62 @@ function gameplayTest(name, options, run) {
     await run({ context, contract });
   });
 }
+
+// src/game-telemetry.ts
+var Phaser4 = __toESM(require("phaser"));
+var GAME_TELEMETRY_GLOBAL = "gameTelemetry";
+function telemetryGlobal() {
+  return globalThis;
+}
+function assertTelemetryShell(value) {
+  if (value.version !== 1 || !value.read || typeof value.read.session !== "function" || !value.controls || typeof value.controls !== "object") {
+    throw new Error(
+      "Game Telemetry must provide version 1, read.session(), and a controls object."
+    );
+  }
+}
+function installGameTelemetry(owner, telemetry) {
+  assertTelemetryShell(telemetry);
+  const scope = telemetryGlobal();
+  if (scope[GAME_TELEMETRY_GLOBAL]) {
+    throw new Error(
+      "Only one active owner may install globalThis.gameTelemetry. Use one game-owned facade or clean up the current Scene-owned facade first."
+    );
+  }
+  const events = owner.events;
+  const lifecycleEvents = owner instanceof Phaser4.Game ? [Phaser4.Core.Events.DESTROY] : [Phaser4.Scenes.Events.SHUTDOWN, Phaser4.Scenes.Events.DESTROY];
+  let installed = true;
+  const cleanup = () => {
+    if (!installed) return;
+    installed = false;
+    for (const event of lifecycleEvents) events.off(event, cleanup);
+    if (scope[GAME_TELEMETRY_GLOBAL] === telemetry) {
+      scope[GAME_TELEMETRY_GLOBAL] = void 0;
+    }
+  };
+  scope[GAME_TELEMETRY_GLOBAL] = telemetry;
+  for (const event of lifecycleEvents) events.once(event, cleanup);
+  return cleanup;
+}
+function getGameTelemetry() {
+  const telemetry = telemetryGlobal()[GAME_TELEMETRY_GLOBAL];
+  if (!telemetry) {
+    throw new Error(
+      "Game Telemetry is not installed. Install it from a Scene create() method with a Game or Scene lifecycle owner."
+    );
+  }
+  return telemetry;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  GAME_TELEMETRY_GLOBAL,
   assertSceneInteractiveHealth,
   assertSceneRuntimeHealth,
   assertSceneTextHealth,
   collectMissingBitmapGlyphs,
   createHeadlessGame,
   gameplayTest,
+  getGameTelemetry,
+  installGameTelemetry,
   registerGameplayContract
 });

package/dist/index.mjs

@@ -1173,12 +1173,61 @@ function gameplayTest(name, options, run) {
     await run({ context, contract });
   });
 }
+
+// src/game-telemetry.ts
+import * as Phaser4 from "phaser";
+var GAME_TELEMETRY_GLOBAL = "gameTelemetry";
+function telemetryGlobal() {
+  return globalThis;
+}
+function assertTelemetryShell(value) {
+  if (value.version !== 1 || !value.read || typeof value.read.session !== "function" || !value.controls || typeof value.controls !== "object") {
+    throw new Error(
+      "Game Telemetry must provide version 1, read.session(), and a controls object."
+    );
+  }
+}
+function installGameTelemetry(owner, telemetry) {
+  assertTelemetryShell(telemetry);
+  const scope = telemetryGlobal();
+  if (scope[GAME_TELEMETRY_GLOBAL]) {
+    throw new Error(
+      "Only one active owner may install globalThis.gameTelemetry. Use one game-owned facade or clean up the current Scene-owned facade first."
+    );
+  }
+  const events = owner.events;
+  const lifecycleEvents = owner instanceof Phaser4.Game ? [Phaser4.Core.Events.DESTROY] : [Phaser4.Scenes.Events.SHUTDOWN, Phaser4.Scenes.Events.DESTROY];
+  let installed = true;
+  const cleanup = () => {
+    if (!installed) return;
+    installed = false;
+    for (const event of lifecycleEvents) events.off(event, cleanup);
+    if (scope[GAME_TELEMETRY_GLOBAL] === telemetry) {
+      scope[GAME_TELEMETRY_GLOBAL] = void 0;
+    }
+  };
+  scope[GAME_TELEMETRY_GLOBAL] = telemetry;
+  for (const event of lifecycleEvents) events.once(event, cleanup);
+  return cleanup;
+}
+function getGameTelemetry() {
+  const telemetry = telemetryGlobal()[GAME_TELEMETRY_GLOBAL];
+  if (!telemetry) {
+    throw new Error(
+      "Game Telemetry is not installed. Install it from a Scene create() method with a Game or Scene lifecycle owner."
+    );
+  }
+  return telemetry;
+}
 export {
+  GAME_TELEMETRY_GLOBAL,
   assertSceneInteractiveHealth,
   assertSceneRuntimeHealth,
   assertSceneTextHealth,
   collectMissingBitmapGlyphs,
   createHeadlessGame,
   gameplayTest,
+  getGameTelemetry,
+  installGameTelemetry,
   registerGameplayContract
 };