miaoda-game-devkit 0.2.8 → 0.2.10

package/dist/vitest-config.js

@@ -23,7 +23,7 @@ __export(vitest_config_exports, {
   defineGameVitestConfig: () => defineGameVitestConfig
 });
 module.exports = __toCommonJS(vitest_config_exports);
-var import_node_path3 = require("path");
+var import_node_path4 = require("path");
 var import_config = require("vitest/config");
 
 // src/gameplay-audit.ts
@@ -70,6 +70,7 @@ function createGameplayContractMetadata(contract) {
 }
 function validateGameplayAuditOptions(options, projectRoot) {
   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") {
@@ -91,7 +92,7 @@ function validateGameplayAuditOptions(options, projectRoot) {
   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");
@@ -117,7 +118,6 @@ function validateGameplayAuditOptions(options, projectRoot) {
       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`);
     }
@@ -125,7 +125,6 @@ function validateGameplayAuditOptions(options, projectRoot) {
       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`);
@@ -147,32 +146,25 @@ function validateGameplayAuditOptions(options, projectRoot) {
       `\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'
+        "\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"
       );
     }
-    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)
-      );
-      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 = projectRoot ? containsProductionRestart(projectRoot) : false;
     if (restartSignal && options.flows?.restart !== true) {
       issues.push("\u68C0\u6D4B\u5230\u751F\u4EA7 Scene \u4F7F\u7528 scene.restart()\uFF1B\u5FC5\u987B\u58F0\u660E flows.restart: true \u5E76\u63D0\u4F9B kind: recovery contract\u3002");
@@ -233,11 +225,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) {
@@ -310,7 +312,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
     );
@@ -353,7 +373,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`
       );
@@ -548,7 +568,7 @@ var GameplayAuditReporter = class {
         (specification) => normalizePath((0, import_node_path2.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(
@@ -592,7 +612,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"
@@ -607,6 +627,49 @@ GAMEPLAY_AUDIT: ALL CONTRACTS PASSED (${this.options.contracts.length} contracts
   }
 };
 
+// src/vite.ts
+var import_node_fs2 = require("fs");
+var import_node_module = require("module");
+var import_node_path3 = require("path");
+var PHASER_MODULE_ID = "phaser";
+function resolvePhaserFacade(projectRoot) {
+  const requireFromProject = (0, import_node_module.createRequire)((0, import_node_path3.join)(projectRoot, "package.json"));
+  const viteEntry = requireFromProject.resolve("miaoda-game-devkit/vite");
+  const facade = (0, import_node_path3.join)((0, import_node_path3.dirname)(viteEntry), "phaser-facade.mjs");
+  if (!(0, import_node_fs2.existsSync)(facade)) {
+    throw new Error(
+      `miaoda-game-devkit \u7F3A\u5C11 Phaser facade\uFF1A${facade}`
+    );
+  }
+  return facade;
+}
+function isInsideDirectory(filePath, directory) {
+  const normalizedFile = (0, import_node_path3.normalize)(filePath);
+  const normalizedDirectory = `${(0, import_node_path3.normalize)(directory)}${import_node_path3.sep}`;
+  return normalizedFile.startsWith(normalizedDirectory);
+}
+function phaserRexUIScenePlugin(projectRoot) {
+  let scenesRoot = projectRoot ? (0, import_node_path3.resolve)(projectRoot, "src/scenes") : void 0;
+  let phaserFacade = projectRoot ? resolvePhaserFacade(projectRoot) : void 0;
+  return {
+    name: "miaoda-phaser-rexui-scene",
+    enforce: "pre",
+    configResolved(config) {
+      const resolvedProjectRoot = projectRoot ?? config.root;
+      scenesRoot ??= (0, import_node_path3.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;
+    }
+  };
+}
+
 // src/vitest-config.ts
 function defineGameVitestConfig(options) {
   const auditIssues = validateGameplayAuditOptions(options.gameplayAudit, options.projectRoot);
@@ -617,10 +680,11 @@ function defineGameVitestConfig(options) {
     );
   }
   return (0, import_config.defineConfig)({
+    plugins: [phaserRexUIScenePlugin(options.projectRoot)],
     resolve: {
       alias: {
         ...options.aliases,
-        "@": (0, import_node_path3.resolve)(options.projectRoot, "src")
+        "@": (0, import_node_path4.resolve)(options.projectRoot, "src")
       }
     },
     // devkit 作为 external ESM 加载时，应用测试也必须 externalize Phaser，

package/dist/vitest-config.mjs

@@ -1,5 +1,5 @@
 // src/vitest-config.ts
-import { resolve } from "path";
+import { resolve as resolve2 } from "path";
 import { defineConfig } from "vitest/config";
 
 // src/gameplay-audit.ts
@@ -46,6 +46,7 @@ function createGameplayContractMetadata(contract) {
 }
 function validateGameplayAuditOptions(options, projectRoot) {
   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") {
@@ -67,7 +68,7 @@ function validateGameplayAuditOptions(options, projectRoot) {
   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");
@@ -93,7 +94,6 @@ function validateGameplayAuditOptions(options, projectRoot) {
       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`);
     }
@@ -101,7 +101,6 @@ function validateGameplayAuditOptions(options, projectRoot) {
       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`);
@@ -123,31 +122,24 @@ function validateGameplayAuditOptions(options, projectRoot) {
       `\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 = projectRoot ? containsProductionRestart(projectRoot) : false;
     if (restartSignal && options.flows?.restart !== true) {
@@ -209,11 +201,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) {
@@ -286,7 +288,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
     );
@@ -329,7 +349,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`
       );
@@ -524,7 +544,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(
@@ -568,7 +588,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"
@@ -583,6 +603,49 @@ GAMEPLAY_AUDIT: ALL CONTRACTS PASSED (${this.options.contracts.length} contracts
   }
 };
 
+// src/vite.ts
+import { existsSync } from "fs";
+import { createRequire } from "module";
+import { dirname, join as join2, normalize, resolve, sep } from "path";
+var PHASER_MODULE_ID = "phaser";
+function resolvePhaserFacade(projectRoot) {
+  const requireFromProject = createRequire(join2(projectRoot, "package.json"));
+  const viteEntry = requireFromProject.resolve("miaoda-game-devkit/vite");
+  const facade = join2(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(projectRoot) {
+  let scenesRoot = projectRoot ? resolve(projectRoot, "src/scenes") : void 0;
+  let phaserFacade = projectRoot ? resolvePhaserFacade(projectRoot) : void 0;
+  return {
+    name: "miaoda-phaser-rexui-scene",
+    enforce: "pre",
+    configResolved(config) {
+      const resolvedProjectRoot = projectRoot ?? 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;
+    }
+  };
+}
+
 // src/vitest-config.ts
 function defineGameVitestConfig(options) {
   const auditIssues = validateGameplayAuditOptions(options.gameplayAudit, options.projectRoot);
@@ -593,10 +656,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，

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miaoda-game-devkit",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Shared lint and deterministic Phaser HEADLESS testing tools for Miaoda games",
   "license": "MIT",
   "main": "./dist/index.js",
@@ -30,7 +30,48 @@
         "default": "./dist/vitest-config.js"
       }
     },
+    "./vite": {
+      "import": {
+        "types": "./dist/vite.d.mts",
+        "default": "./dist/vite.mjs"
+      },
+      "require": {
+        "types": "./dist/vite.d.ts",
+        "default": "./dist/vite.js"
+      }
+    },
     "./vitest-setup": "./dist/lint/setup.mjs",
+    "./react": {
+      "import": {
+        "types": "./dist/react/index.d.mts",
+        "default": "./dist/react/index.mjs"
+      },
+      "require": {
+        "types": "./dist/react/index.d.ts",
+        "default": "./dist/react/index.js"
+      }
+    },
+    "./react/testing": {
+      "import": {
+        "types": "./dist/react/testing.d.mts",
+        "default": "./dist/react/testing.mjs"
+      },
+      "require": {
+        "types": "./dist/react/testing.d.ts",
+        "default": "./dist/react/testing.js"
+      }
+    },
+    "./react/vitest-config": {
+      "import": {
+        "types": "./dist/react/vitest-config.d.mts",
+        "default": "./dist/react/vitest-config.mjs"
+      },
+      "require": {
+        "types": "./dist/react/vitest-config.d.ts",
+        "default": "./dist/react/vitest-config.js"
+      }
+    },
+    "./react/vitest-setup": "./dist/react/vitest-setup.mjs",
     "./biome": "./biome-config.json",
     "./tsconfig-base": "./tsconfig-base.json"
   },
@@ -80,7 +121,36 @@
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
-    "phaser": ">=4.0.0 <5"
+    "@testing-library/jest-dom": ">=6 <8",
+    "@testing-library/react": ">=16 <17",
+    "phaser": ">=4.0.0 <5",
+    "phaser4-rex-plugins": ">=4.0.0 <5",
+    "react": ">=19 <20",
+    "react-dom": ">=19 <20",
+    "vite": ">=6 <9"
+  },
+  "peerDependenciesMeta": {
+    "@testing-library/jest-dom": {
+      "optional": true
+    },
+    "@testing-library/react": {
+      "optional": true
+    },
+    "phaser": {
+      "optional": true
+    },
+    "phaser4-rex-plugins": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",