miaoda-game-devkit 0.2.8 → 0.2.10

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;
@@ -50,6 +114,7 @@ function createGameplayContractMetadata(contract) {
 }
 function validateGameplayAuditOptions(options, projectRoot2) {
   const issues = [];
+  const contracts = options.contracts;
   const scenes = [...new Set(options.scenes.map((scene) => scene.trim()).filter(Boolean))];
   const mode = options.mode ?? "interactive";
   if (mode === "non-interactive") {
@@ -71,7 +136,7 @@ function validateGameplayAuditOptions(options, projectRoot2) {
   const coveredScenes = /* @__PURE__ */ new Set();
   const kinds = /* @__PURE__ */ new Map();
   const invalidKindContracts = [];
-  for (const contract of options.contracts) {
+  for (const contract of contracts ?? []) {
     const id = contract.id.trim();
     if (!id) {
       issues.push("gameplayAudit.contracts \u4E2D\u5B58\u5728\u7A7A contract id\u3002");
@@ -97,7 +162,6 @@ function validateGameplayAuditOptions(options, projectRoot2) {
       kinds.set(contract.kind, list);
     }
     if (contract.kind === "playthrough") {
-      if (!contract.requireInput) issues.push(`playthrough contract "${id}" \u5FC5\u987B requireInput: true\u3002`);
       if (!contract.requireFrameAdvance) issues.push(`playthrough contract "${id}" \u5FC5\u987B requireFrameAdvance: true\u3002`);
       if (normalizeList(contract.requireCheckpoint).length === 0) issues.push(`playthrough contract "${id}" \u5FC5\u987B\u58F0\u660E requireCheckpoint\u3002`);
     }
@@ -105,7 +169,6 @@ function validateGameplayAuditOptions(options, projectRoot2) {
       issues.push(`transition contract "${id}" \u5FC5\u987B\u58F0\u660E requireTransition\u3002`);
     }
     if (contract.kind === "recovery") {
-      if (!contract.requireInput) issues.push(`recovery contract "${id}" \u5FC5\u987B requireInput: true\u3002`);
       if (!contract.requireFrameAdvance) issues.push(`recovery contract "${id}" \u5FC5\u987B requireFrameAdvance: true\u3002`);
       if (normalizeList(contract.requireRestart).length === 0) issues.push(`recovery contract "${id}" \u5FC5\u987B\u58F0\u660E requireRestart\u3002`);
       if (normalizeList(contract.requireCheckpoint).length < 2) issues.push(`recovery contract "${id}" \u81F3\u5C11\u9700\u8981\u4E24\u4E2A checkpoint\uFF08\u91CD\u7F6E\u524D\u540E\uFF09\u3002`);
@@ -127,31 +190,24 @@ function validateGameplayAuditOptions(options, projectRoot2) {
       `\u4EE5\u4E0B contract \u7F3A\u5C11\u6709\u6548 kind\uFF1A${invalidKindContracts.map((id) => `"${id}"`).join("\u3001")}\u3002\u8BF7\u4E3A\u6BCF\u4E2A contract \u8BBE\u7F6E kind: "boot"\u3001"playthrough"\u3001"transition" \u6216 "recovery"\u3002`
     );
   }
-  for (const scene of scenes) {
-    if (!coveredScenes.has(scene)) {
-      issues.push(`Scene "${scene}" \u6CA1\u6709\u4EFB\u4F55 gameplay contract \u8D1F\u8D23\u9A8C\u8BC1\u3002`);
+  if (contracts) {
+    for (const scene of scenes) {
+      if (!coveredScenes.has(scene)) {
+        issues.push(`Scene "${scene}" \u6CA1\u6709\u4EFB\u4F55 gameplay contract \u8D1F\u8D23\u9A8C\u8BC1\u3002`);
+      }
     }
+    if (contracts.length === 0)
+      issues.push("gameplayAudit.contracts \u5B58\u5728\u65F6\u4E0D\u80FD\u4E3A\u7A7A\uFF1B\u4E0D\u4F7F\u7528\u663E\u5F0F\u6E05\u5355\u8BF7\u7701\u7565\u8BE5\u5B57\u6BB5\u3002");
   }
-  if (options.contracts.length === 0)
-    issues.push("gameplayAudit.contracts \u4E0D\u80FD\u4E3A\u7A7A\u3002");
-  if (mode === "interactive") {
-    const hasPlaythrough = (kinds.get("playthrough") ?? []).length > 0;
-    const hasInput = options.contracts.some((contract) => contract.requireInput);
-    const hasCheckpoint = options.contracts.some((contract) => normalizeList(contract.requireCheckpoint).length > 0);
-    if (!hasPlaythrough || !hasInput || !hasCheckpoint) {
+  if (mode === "interactive" && contracts) {
+    const hasPlaythrough = (kinds.get("playthrough") ?? []).some(
+      (contract) => Boolean(contract.requireFrameAdvance) && normalizeList(contract.requireCheckpoint).length > 0
+    );
+    const hasInput = contracts.some((contract) => contract.requireInput);
+    if (!hasPlaythrough || !hasInput) {
       issues.push(
-        '\u4EA4\u4E92\u9879\u76EE\u7F3A\u5C11\u6700\u4F4E\u73A9\u6CD5\u57FA\u7EBF\uFF1A\u81F3\u5C11\u4E00\u4E2A kind: "playthrough" contract \u5FC5\u987B\u540C\u65F6\u58F0\u660E requireInput: true\u3001requireFrameAdvance: true \u548C requireCheckpoint: ["progress"]\u3002'
-      );
-    }
-    const entryScene = scenes[0];
-    for (const scene of scenes.slice(1)) {
-      const transitioned = options.contracts.some(
-        (contract) => (contract.kind === "transition" || contract.kind === "playthrough") && normalizeList(contract.requireTransition).includes(scene)
+        "\u4EA4\u4E92\u9879\u76EE\u7F3A\u5C11\u6700\u4F4E\u73A9\u6CD5\u57FA\u7EBF\uFF1A\u81F3\u5C11\u4E00\u4E2A playthrough contract \u5FC5\u987B\u58F0\u660E requireFrameAdvance \u548C checkpoint\uFF0C\u4E14\u81F3\u5C11\u4E00\u4E2A contract \u5FC5\u987B\u58F0\u660E requireInput: true\u3002"
       );
-      if (!transitioned) issues.push(`\u975E\u5165\u53E3 Scene "${scene}" \u5FC5\u987B\u7531 transition/playthrough contract \u901A\u8FC7\u751F\u4EA7\u8F6C\u573A\u8986\u76D6\u3002`);
-    }
-    if (entryScene && scenes.length > 1 && (kinds.get("transition") ?? []).length === 0 && (kinds.get("playthrough") ?? []).length === 0 && invalidKindContracts.length === 0) {
-      issues.push(`\u4EA4\u4E92\u9879\u76EE\u5165\u53E3 Scene "${entryScene}" \u7F3A\u5C11 transition/playthrough flow\u3002`);
     }
     const restartSignal = projectRoot2 ? containsProductionRestart(projectRoot2) : false;
     if (restartSignal && options.flows?.restart !== true) {
@@ -165,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 {
@@ -174,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);
@@ -213,11 +269,21 @@ function getDefinitionIssues(expected, actual) {
 }
 function auditGameplayCollection(options, file, tests) {
   const normalizedFile = file.replaceAll("\\", "/");
-  const expected = options.contracts.filter(
+  const expected = (options.contracts ?? []).filter(
     (contract) => contract.testFile.replaceAll("\\", "/") === normalizedFile
   );
   const actual = tests.filter((test) => test.metadata);
   const issues = [];
+  if (!options.contracts) {
+    const actualIds = /* @__PURE__ */ new Set();
+    for (const test of actual) {
+      const id = test.metadata?.id;
+      if (!id) continue;
+      if (actualIds.has(id)) issues.push(`contract "${id}" \u5728 ${normalizedFile} \u4E2D\u91CD\u590D\u5B9A\u4E49\u3002`);
+      actualIds.add(id);
+    }
+    return { passed: issues.length === 0, issues };
+  }
   for (const contract of expected) {
     const matches = actual.filter((test) => test.metadata?.id === contract.id);
     if (matches.length === 0) {
@@ -290,7 +356,25 @@ function auditGameplayRun(options, tests) {
   const issues = [];
   const actualContracts = tests.filter((test) => test.metadata);
   const observedEvidence = [];
-  for (const expected of options.contracts) {
+  const discoveredContracts = actualContracts.flatMap((test) => {
+    const metadata = test.metadata;
+    if (!metadata) return [];
+    return [{
+      id: metadata.id,
+      kind: metadata.kind,
+      testFile: test.file,
+      scenes: metadata.scenes,
+      ...metadata.requirements
+    }];
+  });
+  const expectedContracts = options.contracts ?? discoveredContracts;
+  if (!options.contracts) {
+    const discoveredIssues = validateGameplayAuditOptions(
+      { ...options, contracts: discoveredContracts }
+    );
+    issues.push(...discoveredIssues);
+  }
+  for (const expected of expectedContracts) {
     const matches = actualContracts.filter(
       (test2) => test2.metadata?.id === expected.id
     );
@@ -333,7 +417,7 @@ function auditGameplayRun(options, tests) {
   }
   for (const test of actualContracts) {
     const id = test.metadata?.id;
-    if (id && !options.contracts.some((contract) => contract.id === id)) {
+    if (id && options.contracts && !options.contracts.some((contract) => contract.id === id)) {
       issues.push(
         `\u53D1\u73B0\u672A\u5217\u5165 gameplayAudit \u6E05\u5355\u7684 contract "${id}"\uFF08${test.file}\uFF09\u3002`
       );
@@ -528,7 +612,7 @@ var GameplayAuditReporter = class {
         (specification) => normalizePath(relative(this.projectRoot, specification.moduleId))
       )
     );
-    for (const contract of this.options.contracts) {
+    for (const contract of this.options.contracts ?? []) {
       const testFile = normalizePath(contract.testFile);
       if (!scheduledFiles.has(testFile)) {
         this.reportPreflightIssue(
@@ -572,7 +656,7 @@ var GameplayAuditReporter = class {
     } else {
       console.log(
         `
-GAMEPLAY_AUDIT: ALL CONTRACTS PASSED (${this.options.contracts.length} contracts, ${this.options.scenes.length} scenes)`
+GAMEPLAY_AUDIT: ALL CONTRACTS PASSED (${tests.filter((test) => test.metadata).length} contracts, ${this.options.scenes.length} scenes)`
       );
       console.log(
         "GAMEPLAY_AUDIT_NOTE: \u73A9\u6CD5\u68C0\u67E5\u5DF2\u901A\u8FC7\uFF1B\u4ECD\u9700\u4EE5\u6700\u540E\u7684 TEST_RESULT \u5224\u65AD\u6574\u4F53\u6210\u529F\u3002"
@@ -597,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，
@@ -660,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",
@@ -677,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({
@@ -755,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 };

package/dist/react/index.js

@@ -0,0 +1,57 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/react/index.ts
+var react_exports = {};
+__export(react_exports, {
+  browserGameClock: () => browserGameClock,
+  useOwnedGameSession: () => useOwnedGameSession
+});
+module.exports = __toCommonJS(react_exports);
+
+// src/react/game-clock.ts
+var browserGameClock = {
+  now: () => performance.now(),
+  requestFrame: (callback) => requestAnimationFrame(callback),
+  cancelFrame: (id) => cancelAnimationFrame(id),
+  setTimeout: (callback, delayMs) => window.setTimeout(callback, delayMs),
+  clearTimeout: (id) => window.clearTimeout(id)
+};
+
+// src/react/use-owned-game-session.ts
+var import_react = require("react");
+function useOwnedGameSession(createSession) {
+  const [session] = (0, import_react.useState)(createSession);
+  const mounted = (0, import_react.useRef)(false);
+  (0, import_react.useEffect)(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+      queueMicrotask(() => {
+        if (!mounted.current) session.destroy();
+      });
+    };
+  }, [session]);
+  return session;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  browserGameClock,
+  useOwnedGameSession
+});