miaoda-game-devkit 0.2.9 → 0.2.10

package/README.md

@@ -1,9 +1,13 @@
 # miaoda-game-devkit
 
-妙搭 Phaser 4 游戏模板的共享开发基础设施。
+妙搭 Phaser 4 与 React 游戏模板的共享开发基础设施。
 
 该开发工具包提供：
 
+- React 游戏的生产/手动时钟、Strict Mode 安全 Session ownership、JSDOM
+  Vitest 配置和自动收集运行错误的 Testing Library setup，分别从 `miaoda-game-devkit/react`、
+  `miaoda-game-devkit/react/testing` 和 `miaoda-game-devkit/react/vitest-config` 导入；
+
 - 支持 DOM 鼠标、键盘和触摸输入的确定性 Phaser 无头测试宿主；
 - 不依赖渲染器的运行时、交互区域和文字健康检查；
 - 由模板平台维护的通用 Vitest 契约测试；
@@ -11,6 +15,8 @@
   Oxlint 和 Phaser 通用契约检查。
 - 统一的 `defineGameVitestConfig` 配置工厂，固定 Phaser 无头测试依赖的基础配置，
   同时允许每个游戏声明 Scene 审计范围，并配置额外 alias、setup 文件和超时。
+- 与 Vite `defineConfig` 同签名的 `defineGameViteConfig` 配置工厂，统一维护生产 Scene
+  的运行时基础能力，同时完整保留游戏自己的 Vite 配置。
 
 互动游戏的长流程优先使用游戏自己暴露的 `globalThis.gameTelemetry`。稳定 façade 通常调用
 `installGameTelemetry(this.game, telemetry)` 绑定 Game 生命周期；只有刻意局部的 façade 才绑定
@@ -54,6 +60,20 @@ monorepo 中的模板可以放置只包含 `extends: ["miaoda-game-devkit/biome"
 别名等项目差异。TypeScript 严格模式、bundler 模块解析和无输出检查等平台基线由开发
 工具包集中维护，`miaoda-game-lint` 会直接检查模板的这个配置。
 
+Phaser4 模板的 `vite.config.ts` 应从 `miaoda-game-devkit/vite` 导入 `defineGameViteConfig`，调用方式
+与 Vite 的 `defineConfig` 相同，支持配置对象、Promise、同步配置函数和异步配置函数：
+
+```ts
+export default defineGameViteConfig({
+  plugins: [miaodaDevPlugin()],
+});
+```
+
+该入口只增强 `src/scenes` 中对 Phaser 的导入。游戏 Scene 仍按标准方式继承
+`Phaser.Scene`；devkit 在 Scene 创建前提供 RexUI，并在创建后验证业务确实完成了 RexUI
+根布局。RexUI 的加载、Phaser 4.0 兼容和 Scene Plugin 生命周期属于 devkit 责任，游戏
+配置不重复注册。
+
 具体游戏的玩法测试仍由模板使用方放在 `tests/`。运行时测试从本开发工具包
 导入 `createHeadlessGame`；有限目标游戏通过合法 Telemetry controls 走到正常成功终局，
 无尽或沙盒游戏证明有意义的持续进展。短输入测试从入口操作走到一个主要操作，用真实 DOM

package/dist/cli/lint.js

@@ -49,10 +49,41 @@ async function runContracts() {
     ["run", "--config", (0, import_node_path.join)(devkitRoot, "dist/lint/contracts.config.mjs")]
   );
 }
+function checkGameViteConfig() {
+  const viteConfigPath = (0, import_node_path.join)(projectRoot, "vite.config.ts");
+  if (!(0, import_node_fs.existsSync)(viteConfigPath)) {
+    console.error(
+      "[vite-config] \u7F3A\u5C11\u6A21\u677F\u5FC5\u9700\u7684 vite.config.ts\u3002\u8BF7\u6062\u590D\u6A21\u677F\u539F\u6587\u4EF6\u540E\u91CD\u65B0\u8FD0\u884C pnpm lint\u3002"
+    );
+    return { name: "vite-config", ok: false };
+  }
+  const source = (0, import_node_fs.readFileSync)(viteConfigPath, "utf8");
+  const hasDevkitImport = /from\s+["']miaoda-game-devkit\/vite["']/.test(source);
+  const hasConfigCall = /defineGameViteConfig\s*\(/.test(source);
+  if (!hasDevkitImport || !hasConfigCall) {
+    console.error(
+      "[vite-config] vite.config.ts \u672A\u4F7F\u7528\u6A21\u677F\u89C4\u5B9A\u7684\u914D\u7F6E\u5165\u53E3\u3002\n\u8BF7\u4ECE miaoda-game-devkit/vite \u5BFC\u5165 defineGameViteConfig\uFF0C\u5E76\u7528 defineGameViteConfig({ ... }) \u5305\u4F4F\u5F53\u524D\u7684\u914D\u7F6E\u5BF9\u8C61\u3002\n\u53EA\u66FF\u6362\u914D\u7F6E\u51FD\u6570\uFF0C\u4FDD\u7559\u73B0\u6709 plugins\u3001resolve \u7B49\u5BF9\u8C61\u5185\u5BB9\u4E0D\u53D8\u3002"
+    );
+    return { name: "vite-config", ok: false };
+  }
+  return { name: "vite-config", ok: true };
+}
+function projectUsesPhaser4() {
+  const manifestPath = (0, import_node_path.join)(projectRoot, "package.json");
+  if (!(0, import_node_fs.existsSync)(manifestPath)) return false;
+  try {
+    const manifest = JSON.parse((0, import_node_fs.readFileSync)(manifestPath, "utf8"));
+    const version = manifest.dependencies?.phaser ?? manifest.devDependencies?.phaser;
+    return typeof version === "string" && /(?:^|[^0-9])4(?:\.|$)/.test(version);
+  } catch {
+    return false;
+  }
+}
 async function runAllChecks() {
   if (contractsOnly) {
     return [await runContracts()];
   }
+  const viteConfig = projectUsesPhaser4() ? [checkGameViteConfig()] : [];
   const [tsgo, biome] = await Promise.all([
     run("tsgo", "@typescript/native-preview", "tsgo", ["-p", "tsconfig.json"]),
     run("biome", "@biomejs/biome", "biome", [
@@ -76,7 +107,7 @@ async function runAllChecks() {
     "src"
   ]);
   const contracts = await runContracts();
-  return [tsgo, biome, tailwind, oxlint, contracts];
+  return [...viteConfig, tsgo, biome, tailwind, oxlint, contracts];
 }
 async function main() {
   const results = await runAllChecks();

package/dist/game-clock-suUidZdT.d.mts

@@ -0,0 +1,11 @@
+type GameFrameCallback = (timestamp: number) => void;
+interface GameClock {
+    now(): number;
+    requestFrame(callback: GameFrameCallback): number;
+    cancelFrame(id: number): void;
+    setTimeout(callback: () => void, delayMs: number): number;
+    clearTimeout(id: number): void;
+}
+declare const browserGameClock: GameClock;
+
+export { type GameClock as G, type GameFrameCallback as a, browserGameClock as b };

package/dist/game-clock-suUidZdT.d.ts

@@ -0,0 +1,11 @@
+type GameFrameCallback = (timestamp: number) => void;
+interface GameClock {
+    now(): number;
+    requestFrame(callback: GameFrameCallback): number;
+    cancelFrame(id: number): void;
+    setTimeout(callback: () => void, delayMs: number): number;
+    clearTimeout(id: number): void;
+}
+declare const browserGameClock: GameClock;
+
+export { type GameClock as G, type GameFrameCallback as a, browserGameClock as b };

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

@@ -205,4 +205,4 @@ interface GameplayContractMetadata {
     verified?: boolean;
 }
 
-export { type GameplayContractMetadata as G, type HeadlessGameHost as H, type HeadlessGameplayEvidenceRequirements as a, type GameplayAuditContract as b, type GameplayAuditOptions as c, type HeadlessCanvasBounds as d, type HeadlessGameOptions as e, type HeadlessGameplayEvidence as f, type HeadlessInputDriver as g, type HeadlessInputPoint as h, type HeadlessKeyboardEventOptions as i, type HeadlessKeyboardInput as j, type HeadlessMouseInput as k, type HeadlessTouchInput as l, createHeadlessGame as m };
+export { type GameplayAuditOptions as G, type HeadlessGameHost as H, type GameplayContractMetadata as a, type HeadlessGameplayEvidenceRequirements as b, type GameplayAuditContract as c, type HeadlessCanvasBounds as d, type HeadlessGameOptions as e, type HeadlessGameplayEvidence as f, type HeadlessInputDriver as g, type HeadlessInputPoint as h, type HeadlessKeyboardEventOptions as i, type HeadlessKeyboardInput as j, type HeadlessMouseInput as k, type HeadlessTouchInput as l, createHeadlessGame as m };

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

@@ -205,4 +205,4 @@ interface GameplayContractMetadata {
     verified?: boolean;
 }
 
-export { type GameplayContractMetadata as G, type HeadlessGameHost as H, type HeadlessGameplayEvidenceRequirements as a, type GameplayAuditContract as b, type GameplayAuditOptions as c, type HeadlessCanvasBounds as d, type HeadlessGameOptions as e, type HeadlessGameplayEvidence as f, type HeadlessInputDriver as g, type HeadlessInputPoint as h, type HeadlessKeyboardEventOptions as i, type HeadlessKeyboardInput as j, type HeadlessMouseInput as k, type HeadlessTouchInput as l, createHeadlessGame as m };
+export { type GameplayAuditOptions as G, type HeadlessGameHost as H, type GameplayContractMetadata as a, type HeadlessGameplayEvidenceRequirements as b, type GameplayAuditContract as c, type HeadlessCanvasBounds as d, type HeadlessGameOptions as e, type HeadlessGameplayEvidence as f, type HeadlessInputDriver as g, type HeadlessInputPoint as h, type HeadlessKeyboardEventOptions as i, type HeadlessKeyboardInput as j, type HeadlessMouseInput as k, type HeadlessTouchInput as l, createHeadlessGame as m };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-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 { a as GameplayContractMetadata, H as HeadlessGameHost, b as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-BwAobjIX.mjs';
+export { c as GameplayAuditContract, G 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-BwAobjIX.mjs';
 import * as Phaser from 'phaser';
 import { TestContext, TestOptions } from 'vitest';
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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 { a as GameplayContractMetadata, H as HeadlessGameHost, b as HeadlessGameplayEvidenceRequirements } from './gameplay-audit-BwAobjIX.js';
+export { c as GameplayAuditContract, G 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-BwAobjIX.js';
 import * as Phaser from 'phaser';
 import { TestContext, TestOptions } from 'vitest';
 

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

@@ -1,14 +1,78 @@
 // src/lint/vitest-config.test.ts
-import { resolve as resolve2 } from "path";
+import { resolve as resolve4 } from "path";
 import { describe, expect, it } from "vitest";
 
+// src/vite.ts
+import { existsSync } from "fs";
+import { createRequire } from "module";
+import { dirname, join, normalize, resolve, sep } from "path";
+var PHASER_MODULE_ID = "phaser";
+function isPromiseLike(value) {
+  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}
+function resolvePhaserFacade(projectRoot2) {
+  const requireFromProject = createRequire(join(projectRoot2, "package.json"));
+  const viteEntry = requireFromProject.resolve("miaoda-game-devkit/vite");
+  const facade = join(dirname(viteEntry), "phaser-facade.mjs");
+  if (!existsSync(facade)) {
+    throw new Error(
+      `miaoda-game-devkit \u7F3A\u5C11 Phaser facade\uFF1A${facade}`
+    );
+  }
+  return facade;
+}
+function isInsideDirectory(filePath, directory) {
+  const normalizedFile = normalize(filePath);
+  const normalizedDirectory = `${normalize(directory)}${sep}`;
+  return normalizedFile.startsWith(normalizedDirectory);
+}
+function phaserRexUIScenePlugin(projectRoot2) {
+  let scenesRoot = projectRoot2 ? resolve(projectRoot2, "src/scenes") : void 0;
+  let phaserFacade = projectRoot2 ? resolvePhaserFacade(projectRoot2) : void 0;
+  return {
+    name: "miaoda-phaser-rexui-scene",
+    enforce: "pre",
+    configResolved(config) {
+      const resolvedProjectRoot = projectRoot2 ?? config.root;
+      scenesRoot ??= resolve(resolvedProjectRoot, "src/scenes");
+      phaserFacade ??= resolvePhaserFacade(resolvedProjectRoot);
+    },
+    /** 查询参数属于构建工具元数据，去除后才能稳定判断真实源码位置。 */
+    resolveId(source, importer) {
+      if (source !== PHASER_MODULE_ID || !importer || !scenesRoot) {
+        return null;
+      }
+      const cleanImporter = importer.split("?", 1)[0] ?? importer;
+      return isInsideDirectory(cleanImporter, scenesRoot) ? phaserFacade ?? null : null;
+    }
+  };
+}
+function withGameDefaults(config) {
+  return {
+    ...config,
+    plugins: [
+      phaserRexUIScenePlugin(),
+      ...config.plugins ?? []
+    ]
+  };
+}
+function defineGameViteConfig(config) {
+  if (typeof config === "function") {
+    return (env) => {
+      const resolved = config(env);
+      return isPromiseLike(resolved) ? resolved.then(withGameDefaults) : withGameDefaults(resolved);
+    };
+  }
+  return isPromiseLike(config) ? config.then(withGameDefaults) : withGameDefaults(config);
+}
+
 // src/vitest-config.ts
-import { resolve } from "path";
+import { resolve as resolve2 } from "path";
 import { defineConfig } from "vitest/config";
 
 // src/gameplay-audit.ts
 import { readdirSync, readFileSync, statSync } from "fs";
-import { join } from "path";
+import { join as join2 } from "path";
 function normalizeList(value) {
   if (value === void 0) return [];
   const values = typeof value === "string" ? [value] : value;
@@ -157,7 +221,7 @@ function validateGameplayAuditOptions(options, projectRoot2) {
   return issues;
 }
 function containsProductionRestart(projectRoot2) {
-  const sceneRoot = join(projectRoot2, "src", "scenes");
+  const sceneRoot = join2(projectRoot2, "src", "scenes");
   const visit = (directory) => {
     let entries;
     try {
@@ -166,7 +230,7 @@ function containsProductionRestart(projectRoot2) {
       return false;
     }
     for (const entry of entries) {
-      const path = join(directory, entry);
+      const path = join2(directory, entry);
       let stats;
       try {
         stats = statSync(path);
@@ -617,10 +681,11 @@ function defineGameVitestConfig(options) {
     );
   }
   return defineConfig({
+    plugins: [phaserRexUIScenePlugin(options.projectRoot)],
     resolve: {
       alias: {
         ...options.aliases,
-        "@": resolve(options.projectRoot, "src")
+        "@": resolve2(options.projectRoot, "src")
       }
     },
     // devkit 作为 external ESM 加载时，应用测试也必须 externalize Phaser，
@@ -680,8 +745,93 @@ function defineGameVitestConfig(options) {
   });
 }
 
+// src/react-vitest-config.ts
+import { resolve as resolve3 } from "path";
+import { defineConfig as defineConfig2 } from "vitest/config";
+function defineReactGameVitestConfig(options) {
+  return defineConfig2({
+    resolve: {
+      alias: { ...options.aliases, "@": resolve3(options.projectRoot, "src") }
+    },
+    test: {
+      include: [
+        "src/**/*.{test,spec}.{ts,tsx}",
+        "tests/**/*.{test,spec}.{ts,tsx}"
+      ],
+      environment: "jsdom",
+      environmentOptions: {
+        jsdom: { url: "http://localhost/", pretendToBeVisual: true }
+      },
+      setupFiles: [
+        "miaoda-game-devkit/react/vitest-setup",
+        ...options.additionalSetupFiles ?? []
+      ],
+      reporters: ["minimal"],
+      restoreMocks: true,
+      clearMocks: true,
+      testTimeout: options.testTimeout,
+      hookTimeout: options.hookTimeout
+    }
+  });
+}
+
+// src/react/manual-game-clock.ts
+var ManualGameClock = class {
+  time = 0;
+  nextId = 1;
+  frames = /* @__PURE__ */ new Map();
+  timers = /* @__PURE__ */ new Map();
+  now() {
+    return this.time;
+  }
+  requestFrame(callback) {
+    const id = this.nextId++;
+    this.frames.set(id, callback);
+    return id;
+  }
+  cancelFrame(id) {
+    this.frames.delete(id);
+  }
+  setTimeout(callback, delayMs) {
+    const id = this.nextId++;
+    this.timers.set(id, { callback, dueAt: this.time + delayMs });
+    return id;
+  }
+  clearTimeout(id) {
+    this.timers.delete(id);
+  }
+  advanceBy(deltaMs) {
+    if (!Number.isFinite(deltaMs) || deltaMs < 0) {
+      throw new RangeError("deltaMs must be a non-negative finite number");
+    }
+    this.time += deltaMs;
+    const dueTimers = [...this.timers.entries()].filter(([, timer]) => timer.dueAt <= this.time).sort((left, right) => left[1].dueAt - right[1].dueAt);
+    for (const [id, timer] of dueTimers) {
+      if (timer.dueAt <= this.time && this.timers.delete(id)) timer.callback();
+    }
+  }
+  stepFrame(deltaMs = 16) {
+    this.advanceBy(deltaMs);
+    const callbacks = [...this.frames.values()];
+    this.frames.clear();
+    for (const callback of callbacks) callback(this.time);
+  }
+  stepFrames(count, deltaMs = 16) {
+    if (!Number.isInteger(count) || count < 0) {
+      throw new RangeError("count must be a non-negative integer");
+    }
+    for (let index = 0; index < count; index += 1) this.stepFrame(deltaMs);
+  }
+  pendingFrameCount() {
+    return this.frames.size;
+  }
+  pendingTimerCount() {
+    return this.timers.size;
+  }
+};
+
 // src/lint/vitest-config.test.ts
-var projectRoot = resolve2(import.meta.dirname, "../..");
+var projectRoot = resolve4(import.meta.dirname, "../..");
 var gameplayAudit = {
   mode: "non-interactive",
   nonInteractiveJustification: "\u56FA\u5B9A\u5939\u5177\u53EA\u9A8C\u8BC1\u5171\u4EAB host \u57FA\u7EBF\uFF0C\u4E0D\u5305\u542B\u73A9\u6CD5\u8F93\u5165\u3002",
@@ -697,11 +847,29 @@ var gameplayAudit = {
   ]
 };
 describe("defineGameVitestConfig", () => {
+  it("defineGameViteConfig \u4FDD\u6301 Vite defineConfig \u7684\u5E38\u7528\u8F93\u5165\u5F62\u5F0F", async () => {
+    const objectConfig = defineGameViteConfig({ plugins: [] });
+    expect(objectConfig.plugins?.[0]).toMatchObject({
+      name: "miaoda-phaser-rexui-scene"
+    });
+    const promiseConfig = await defineGameViteConfig(Promise.resolve({}));
+    expect(promiseConfig.plugins?.[0]).toMatchObject({
+      name: "miaoda-phaser-rexui-scene"
+    });
+    const functionConfig = defineGameViteConfig(() => ({ resolve: {} }));
+    const resolvedFunctionConfig = functionConfig({ command: "serve", mode: "test" });
+    expect(resolvedFunctionConfig.plugins?.[0]).toMatchObject({
+      name: "miaoda-phaser-rexui-scene"
+    });
+  });
   it("\u63D0\u4F9B Phaser \u8FD0\u884C\u65F6\u6D4B\u8BD5\u9700\u8981\u7684\u56FA\u5B9A\u57FA\u7EBF", () => {
     const config = defineGameVitestConfig({ projectRoot, gameplayAudit });
     expect(config.resolve?.alias).toMatchObject({
-      "@": resolve2(projectRoot, "src")
+      "@": resolve4(projectRoot, "src")
     });
+    expect(config.plugins).toEqual([
+      expect.objectContaining({ name: "miaoda-phaser-rexui-scene" })
+    ]);
     expect(config.resolve?.alias).not.toHaveProperty("phaser");
     expect(config.ssr).toMatchObject({ external: ["phaser"] });
     expect(config.test).toMatchObject({
@@ -775,3 +943,40 @@ describe("defineGameVitestConfig", () => {
     ).toThrow(/缺少最低玩法基线/);
   });
 });
+describe("React game devkit", () => {
+  it("\u63D0\u4F9B\u9694\u79BB\u4E8E Phaser \u5BA1\u8BA1\u7684 JSDOM \u914D\u7F6E", () => {
+    const config = defineReactGameVitestConfig({ projectRoot });
+    expect(config.resolve?.alias).toMatchObject({
+      "@": resolve4(projectRoot, "src")
+    });
+    expect(config.ssr).toBeUndefined();
+    expect(config.test).toMatchObject({
+      environment: "jsdom",
+      environmentOptions: {
+        jsdom: { url: "http://localhost/", pretendToBeVisual: true }
+      },
+      include: [
+        "src/**/*.{test,spec}.{ts,tsx}",
+        "tests/**/*.{test,spec}.{ts,tsx}"
+      ],
+      setupFiles: ["miaoda-game-devkit/react/vitest-setup"],
+      reporters: ["minimal"],
+      restoreMocks: true,
+      clearMocks: true
+    });
+  });
+  it("\u624B\u52A8\u65F6\u949F\u786E\u5B9A\u6027\u63A8\u8FDB\u5E76\u6E05\u7406\u5E27\u548C\u5B9A\u65F6\u5668", () => {
+    const clock = new ManualGameClock();
+    let frames = 0;
+    const timers = [];
+    clock.requestFrame(() => frames++);
+    clock.setTimeout(() => timers.push("late"), 20);
+    clock.setTimeout(() => timers.push("early"), 10);
+    clock.stepFrame(10);
+    expect({ frames, timers }).toEqual({ frames: 1, timers: ["early"] });
+    clock.advanceBy(10);
+    expect({ frames, timers }).toEqual({ frames: 1, timers: ["early", "late"] });
+    expect(clock.pendingFrameCount()).toBe(0);
+    expect(clock.pendingTimerCount()).toBe(0);
+  });
+});

package/dist/phaser-facade.mjs

@@ -0,0 +1,156 @@
+// src/phaser/phaser-facade.js
+import * as PhaserNamespace from "phaser";
+
+// src/phaser/rexui-scene.ts
+import * as Phaser2 from "phaser";
+
+// src/phaser/rexui-plugin.ts
+import * as Phaser from "phaser";
+var globalScope = globalThis;
+globalScope.Phaser ??= Phaser;
+var RexClass = (
+  // @ts-expect-error RexUI 未发布这个内部兼容模块的类型声明。
+  (await import("phaser4-rex-plugins/plugins/utils/object/Class.js")).default
+);
+var phaserNamespace = globalScope.Phaser;
+if (!phaserNamespace.Class) {
+  globalScope.Phaser = { ...globalScope.Phaser, Class: RexClass };
+}
+var RexUIPlugin = (await import("phaser4-rex-plugins/templates/ui/ui-plugin.js")).default;
+
+// src/phaser/rexui-scene.ts
+var REXUI_LAYOUT_INSTRUMENTED = /* @__PURE__ */ Symbol("miaoda.rexui-layout-instrumented");
+function isPromiseLike(value) {
+  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}
+var RexUIScene = class extends Phaser2.Scene {
+  /** 保存真实布局证据，用于排除“只注册或只创建组件但没有布局”的情况。 */
+  rexUILayoutRoots = /* @__PURE__ */ new Set();
+  /** 保证 Scene restart 时不会给同一个 RexUI 工厂重复叠加代理。 */
+  instrumentedFactories = /* @__PURE__ */ new WeakSet();
+  /**
+   * 包装业务 Scene 的 create，而不要求业务代码显式调用 super.create()。
+   * Phaser 执行 create 时插件已完成注入，因此可在业务 create 前安装监测，
+   * 并在业务 create 返回后立即验证最终布局。
+   */
+  constructor(config) {
+    super(config);
+    const scene = this;
+    const create = scene.create;
+    scene.create = (...args) => {
+      this.ensureRexUIPlugin();
+      this.instrumentRexUIFactory();
+      this.sys.events.once(Phaser2.Scenes.Events.SHUTDOWN, () => {
+        this.rexUILayoutRoots.clear();
+      });
+      const result = create?.apply(this, args);
+      if (isPromiseLike(result)) {
+        return result.then((value) => {
+          this.assertRexUILayout();
+          return value;
+        });
+      }
+      this.assertRexUILayout();
+      return result;
+    };
+  }
+  /**
+   * 保证业务 create 开始前已经拥有可用的 `this.rexUI`。
+   * 注册由 devkit 统一负责，避免应用配置被修改后出现“类型存在、运行时未注入”。
+   */
+  ensureRexUIPlugin() {
+    const scene = this;
+    if (scene.rexUI?.add) {
+      return;
+    }
+    this.plugins.installScenePlugin("rexUI", RexUIPlugin, "rexUI", this, true);
+    if (!scene.rexUI?.add) {
+      throw new Error(
+        `[UI_INITIALIZATION_FAILED] ${this.sys.settings.key || this.constructor.name} \u754C\u9762\u521D\u59CB\u5316\u5931\u8D25\u3002`
+      );
+    }
+  }
+  /**
+   * 记录业务通过 `this.rexUI.add.*` 创建的 Sizer。
+   * 这一步用于区分“插件可用”和“业务确实采用 RexUI 组织界面”，同时不改变工厂返回值。
+   */
+  instrumentRexUIFactory() {
+    const rexUI = this.rexUI;
+    if (!rexUI?.add) {
+      return;
+    }
+    const factory = rexUI.add;
+    if (this.instrumentedFactories.has(factory)) {
+      return;
+    }
+    const wrappedMethods = /* @__PURE__ */ new Map();
+    const instrumentedFactory = new Proxy(factory, {
+      get: (target, property, receiver) => {
+        const value = Reflect.get(target, property, receiver);
+        if (typeof value !== "function") {
+          return value;
+        }
+        let wrapped = wrappedMethods.get(property);
+        if (!wrapped) {
+          wrapped = (...args) => {
+            const result = Reflect.apply(value, target, args);
+            this.instrumentSizer(result);
+            return result;
+          };
+          wrappedMethods.set(property, wrapped);
+        }
+        return wrapped;
+      }
+    });
+    rexUI.add = instrumentedFactory;
+    this.instrumentedFactories.add(instrumentedFactory);
+  }
+  /**
+   * 为单个 Sizer 采集可靠的布局完成证据。
+   * RexUI 没有公开持久的“layout 已调用”状态，因此必须在原始 layout 成功返回后记录；
+   * 该证据能发现组件已经创建但仍因漏调 layout() 而重叠的页面。
+   */
+  instrumentSizer(candidate) {
+    if (!candidate?.isRexSizer || typeof candidate.layout !== "function" || candidate[REXUI_LAYOUT_INSTRUMENTED]) {
+      return;
+    }
+    const originalLayout = candidate.layout;
+    candidate.layout = (...args) => {
+      const result = Reflect.apply(originalLayout, candidate, args);
+      this.rexUILayoutRoots.add(candidate);
+      return result;
+    };
+    candidate[REXUI_LAYOUT_INSTRUMENTED] = true;
+  }
+  /**
+   * 在业务 create 完成后验证 RexUI 使用情况。
+   * 合格布局必须属于当前 Scene、调用过 layout()，并且自身不是另一 Sizer 的子级。
+   */
+  assertRexUILayout() {
+    const sceneKey = this.sys.settings.key || this.constructor.name;
+    const hasLaidOutRoot = [...this.rexUILayoutRoots].some((sizer) => {
+      const parent = sizer.getParentSizer?.();
+      return !parent && sizer.scene === this;
+    });
+    if (hasLaidOutRoot) {
+      return;
+    }
+    throw new Error(
+      `[REXUI_LAYOUT_REQUIRED] ${sceneKey} \u6CA1\u6709\u5B8C\u6210 RexUI \u6839\u5E03\u5C40\u3002
+\u8BF7\u4F7F\u7528 this.rexUI.add.sizer\u3001gridSizer\u3001scrollablePanel \u6216\u5176\u4ED6\u5408\u9002\u7684 RexUI \u5BB9\u5668\u521B\u5EFA UI \u6839\u5E03\u5C40\uFF0C\u628A HUD\u3001\u83DC\u5355\u3001\u9762\u677F\u548C\u6309\u94AE\u52A0\u5165\u8BE5\u5E03\u5C40\uFF0C\u5E76\u5728\u7EC4\u5408\u6216\u5C3A\u5BF8\u53D8\u5316\u540E\u8C03\u7528 .layout()\u3002
+\u4E0D\u8981\u4F7F\u7528 container + rectangle + text \u6216 this.add.text(...).setInteractive() \u624B\u5DE5\u62FC\u88C5 Canvas UI\u3002`
+    );
+  }
+};
+
+// src/phaser/phaser-facade.js
+export * from "phaser";
+var PhaserFacade = Object.freeze({
+  ...PhaserNamespace,
+  Scene: RexUIScene
+});
+var phaser_facade_default = PhaserFacade;
+export {
+  RexUIScene as Scene,
+  phaser_facade_default as default
+};

package/dist/react/index.d.mts

@@ -0,0 +1,13 @@
+export { G as GameClock, a as GameFrameCallback, b as browserGameClock } from '../game-clock-suUidZdT.mjs';
+
+interface DisposableGameSession {
+    destroy(): void;
+}
+/**
+ * 创建由当前组件拥有的 Session，并在真实卸载后销毁。
+ * 微任务检查避免 React Strict Mode 的 effect 探测误销毁仍在使用的 Session。
+ * createSession 必须只创建内存状态；监听器、定时器等外部资源应在订阅或操作时启用。
+ */
+declare function useOwnedGameSession<TSession extends DisposableGameSession>(createSession: () => TSession): TSession;
+
+export { type DisposableGameSession, useOwnedGameSession };

package/dist/react/index.d.ts

@@ -0,0 +1,13 @@
+export { G as GameClock, a as GameFrameCallback, b as browserGameClock } from '../game-clock-suUidZdT.js';
+
+interface DisposableGameSession {
+    destroy(): void;
+}
+/**
+ * 创建由当前组件拥有的 Session，并在真实卸载后销毁。
+ * 微任务检查避免 React Strict Mode 的 effect 探测误销毁仍在使用的 Session。
+ * createSession 必须只创建内存状态；监听器、定时器等外部资源应在订阅或操作时启用。
+ */
+declare function useOwnedGameSession<TSession extends DisposableGameSession>(createSession: () => TSession): TSession;
+
+export { type DisposableGameSession, useOwnedGameSession };