miaoda-game-devkit 0.2.12 → 0.2.14

package/README.md

@@ -8,11 +8,17 @@
   Vitest 配置和自动收集运行错误的 Testing Library setup，分别从 `miaoda-game-devkit/react`、
   `miaoda-game-devkit/react/testing` 和 `miaoda-game-devkit/react/vitest-config` 导入；
 
+- React Vitest 在项目声明 Phaser 3 时使用其 browser bundle，并提供仅供模块能力探测的
+  最小 Canvas 2D 边界，使 Phaser 3 代码不会阻断普通 JSDOM 测试；Storage 使用 JSDOM
+  按 origin 提供的原生实现，Node 25+ worker 会关闭冲突的 Node Web Storage，
+  并在每个用例后清理；该 Canvas 适配不执行真实绘制，
+  也不提供 Canvas/WebGL 像素证明；
+
 - 支持 DOM 鼠标、键盘和触摸输入的确定性 Phaser 无头测试宿主；
 - 不依赖渲染器的运行时、交互区域和文字健康检查；
-- 由模板平台维护的通用 Vitest 契约测试；
-- 统一的 `miaoda-game-lint` 命令，聚合 TypeScript、Biome、Tailwind、
-  Oxlint 和 Phaser 通用契约检查。
+- 只在 devkit 自身 CI 中运行、不会发布到业务项目的通用 Vitest 契约测试；
+- 显式隔离的 `miaoda-react-game-lint` 与 `miaoda-phaser-game-lint` 命令，
+  共享 TypeScript、Biome、Tailwind 和 Oxlint 检查，同时分别校验 React 与 Phaser 4 配置边界。
 - 统一的 `defineGameVitestConfig` 配置工厂，固定 Phaser 无头测试依赖的基础配置，
   同时允许每个游戏声明 Scene 审计范围，并配置额外 alias、setup 文件和超时。
 - 与 Vite `defineConfig` 同签名的 `defineGameViteConfig` 配置工厂，统一维护生产 Scene
@@ -42,21 +48,25 @@ HEADLESS host，并在 `onTestFinished` 校验 Ledger。`vitest.config.ts` 默
 基线、失败、证据不足、Scene 未访问和 registry 不一致。旧项目仍可提供显式
 `gameplayAudit.contracts` 清单，但新游戏通常不需要。
 
-模板直接调用开发工具包提供的命令行程序：
+两套模板直接调用各自的命令行程序：
 
 ```json
 {
   "scripts": {
-    "lint": "miaoda-game-lint"
+    "lint": "miaoda-react-game-lint"
   }
 }
 ```
 
+Phaser 4 模板对应使用 `miaoda-phaser-game-lint`。命令类型不通过依赖猜测，因此 React
+模板即使预装 Phaser 3 及相关插件，也不会解析 Phaser 或运行 Phaser 4 检查。旧的
+`miaoda-game-lint` 不再发布，避免在同时包含 React 与 Phaser 依赖的项目中产生歧义。
+
 开发工具包自行维护工具版本，并从自身依赖中解析可执行文件，使用方不需要重复声明
 Biome、Oxlint 或 tsgo。仓库中保留稳定的命令入口，因此 `dist/` 尚未生成时，pnpm
 也能正确建立命令链接；工作区开发状态下由 Nx 在模板检查前构建开发工具包，发布包则
-直接携带运行时 `dist/`。开发工具包内部的 `*.test.*` 测试不会进入 npm 包；随包运行的
-通用契约测试以 `*.contract.mjs` 形式发布。
+直接携带运行时 `dist/`。开发工具包内部的 `*.test.*` 与构建后的 `*.contract.mjs` 都不会
+进入 npm 包；这些契约只由 devkit 自己的测试目标执行。
 
 monorepo 中的模板可以放置只包含 `extends: ["miaoda-game-devkit/biome"]` 的薄配置，
 用于让 Biome 从模板 package.json 判断依赖声明。规则本身仍由本开发工具包维护；生成后的
@@ -64,7 +74,7 @@ monorepo 中的模板可以放置只包含 `extends: ["miaoda-game-devkit/biome"
 
 模板的 `tsconfig.json` 应继承 `miaoda-game-devkit/tsconfig-base`，只保留源码范围和路径
 别名等项目差异。TypeScript 严格模式、bundler 模块解析和无输出检查等平台基线由开发
-工具包集中维护，`miaoda-game-lint` 会直接检查模板的这个配置。
+工具包集中维护，两套模板专用 lint CLI 会直接检查模板的这个配置。
 
 Phaser4 模板的 `vite.config.ts` 应从 `miaoda-game-devkit/vite` 导入 `defineGameViteConfig`，调用方式
 与 Vite 的 `defineConfig` 相同，支持配置对象、Promise、同步配置函数和异步配置函数：

package/bin/miaoda-phaser-game-lint.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../dist/cli/phaser-lint.js');

package/bin/miaoda-react-game-lint.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../dist/cli/react-lint.js');

package/dist/cli/phaser-lint.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/cli/lint.ts
+var import_node_child_process = require("child_process");
+var import_node_fs = require("fs");
+var import_node_module = require("module");
+var import_node_os = require("os");
+var import_node_path = require("path");
+var devkitRoot = (0, import_node_path.resolve)(__dirname, "../..");
+var projectRoot = process.cwd();
+var requireFromDevkit = (0, import_node_module.createRequire)((0, import_node_path.join)(devkitRoot, "package.json"));
+var projectBiomeConfig = (0, import_node_path.join)(projectRoot, "biome.json");
+var biomeConfig = (0, import_node_fs.existsSync)(projectBiomeConfig) ? projectBiomeConfig : (0, import_node_path.join)(devkitRoot, "biome-config.json");
+function resolveBin(packageName, binName) {
+  const packageJsonPath = requireFromDevkit.resolve(`${packageName}/package.json`);
+  const packageJson = JSON.parse((0, import_node_fs.readFileSync)(packageJsonPath, "utf8"));
+  const relativeBin = typeof packageJson.bin === "string" ? packageJson.bin : packageJson.bin?.[binName];
+  if (!relativeBin) {
+    throw new Error(`${packageName} does not expose the ${binName} executable`);
+  }
+  return (0, import_node_path.resolve)((0, import_node_path.dirname)(packageJsonPath), relativeBin);
+}
+function run(name, packageName, binName, args) {
+  return new Promise((resolveResult) => {
+    const child = (0, import_node_child_process.spawn)(process.execPath, [resolveBin(packageName, binName), ...args], {
+      cwd: projectRoot,
+      env: process.env,
+      stdio: "inherit"
+    });
+    child.once("error", (error) => {
+      console.error(`[${name}] ${error.message}`);
+      resolveResult({ name, ok: false });
+    });
+    child.once("close", (code, signal) => {
+      if (signal) {
+        console.error(`[${name}] terminated by ${signal}`);
+      }
+      resolveResult({ name, ok: code === 0 && signal === null });
+    });
+  });
+}
+function readProjectSource(path, checkName) {
+  const absolutePath = (0, import_node_path.join)(projectRoot, path);
+  if (!(0, import_node_fs.existsSync)(absolutePath)) {
+    console.error(`[${checkName}] \u7F3A\u5C11\u6A21\u677F\u5FC5\u9700\u7684 ${path}\u3002\u8BF7\u6062\u590D\u6A21\u677F\u539F\u6587\u4EF6\u540E\u91CD\u65B0\u8FD0\u884C pnpm lint\u3002`);
+    return void 0;
+  }
+  return (0, import_node_fs.readFileSync)(absolutePath, "utf8");
+}
+function readProjectManifest() {
+  const manifestPath = (0, import_node_path.join)(projectRoot, "package.json");
+  if (!(0, import_node_fs.existsSync)(manifestPath)) {
+    console.error("[phaser-version] \u7F3A\u5C11\u9879\u76EE package.json\u3002");
+    return void 0;
+  }
+  try {
+    return JSON.parse((0, import_node_fs.readFileSync)(manifestPath, "utf8"));
+  } catch (error) {
+    console.error(`[phaser-version] \u65E0\u6CD5\u89E3\u6790 package.json\uFF1A${String(error)}`);
+    return void 0;
+  }
+}
+function checkPhaser4Dependency() {
+  const name = "phaser-version";
+  const manifest = readProjectManifest();
+  const version = manifest?.dependencies?.phaser ?? manifest?.devDependencies?.phaser;
+  const declaresPhaser4 = typeof version === "string" && /(?:^|[\s<>=~^|])4(?:\.|\s|$)/.test(version);
+  if (!declaresPhaser4) {
+    console.error(
+      `[${name}] Phaser \u6A21\u677F\u5FC5\u987B\u663E\u5F0F\u58F0\u660E Phaser 4\uFF1B\u5F53\u524D\u58F0\u660E\u4E3A ${JSON.stringify(version ?? null)}\u3002`
+    );
+    return { name, ok: false };
+  }
+  return { name, ok: true };
+}
+function checkPhaserViteConfig() {
+  const name = "phaser-vite-config";
+  const source = readProjectSource("vite.config.ts", name);
+  if (!source) return { name, ok: false };
+  const hasDevkitImport = /from\s+["']miaoda-game-devkit\/vite["']/.test(source);
+  const hasConfigCall = /defineGameViteConfig\s*\(/.test(source);
+  if (!hasDevkitImport || !hasConfigCall) {
+    console.error(
+      `[${name}] vite.config.ts \u672A\u4F7F\u7528 Phaser \u6A21\u677F\u89C4\u5B9A\u7684\u914D\u7F6E\u5165\u53E3\u3002
+\u8BF7\u4ECE miaoda-game-devkit/vite \u5BFC\u5165 defineGameViteConfig\uFF0C\u5E76\u7528 defineGameViteConfig({ ... }) \u5305\u4F4F\u5F53\u524D\u7684\u914D\u7F6E\u5BF9\u8C61\u3002
+\u53EA\u66FF\u6362\u914D\u7F6E\u51FD\u6570\uFF0C\u4FDD\u7559\u73B0\u6709 plugins\u3001resolve \u7B49\u5BF9\u8C61\u5185\u5BB9\u4E0D\u53D8\u3002`
+    );
+    return { name, ok: false };
+  }
+  return { name, ok: true };
+}
+function checkVitestConfig(target) {
+  const name = `${target}-vitest-config`;
+  const source = readProjectSource("vitest.config.ts", name);
+  if (!source) return { name, ok: false };
+  const expected = target === "react" ? {
+    entry: "miaoda-game-devkit/react/vitest-config",
+    factory: "defineReactGameVitestConfig"
+  } : {
+    entry: "miaoda-game-devkit/vitest-config",
+    factory: "defineGameVitestConfig"
+  };
+  const hasDevkitImport = new RegExp(
+    `from\\s+["']${expected.entry.replaceAll("/", "\\/")}["']`
+  ).test(source);
+  const hasConfigCall = new RegExp(`${expected.factory}\\s*\\(`).test(source);
+  if (!hasDevkitImport || !hasConfigCall) {
+    console.error(
+      `[${name}] vitest.config.ts \u5FC5\u987B\u4ECE ${expected.entry} \u5BFC\u5165\u5E76\u8C03\u7528 ${expected.factory}\u3002`
+    );
+    return { name, ok: false };
+  }
+  return { name, ok: true };
+}
+async function runAllChecks(target) {
+  const targetChecks = target === "react" ? [checkVitestConfig("react")] : [checkPhaser4Dependency(), checkPhaserViteConfig(), checkVitestConfig("phaser")];
+  const [tsgo, biome] = await Promise.all([
+    run("tsgo", "@typescript/native-preview", "tsgo", ["-p", "tsconfig.json"]),
+    run("biome", "@biomejs/biome", "biome", [
+      "lint",
+      "--config-path",
+      biomeConfig,
+      "src"
+    ])
+  ]);
+  const tailwindOutput = (0, import_node_path.join)((0, import_node_os.tmpdir)(), `miaoda-game-devkit-${process.pid}.css`);
+  const tailwind = await run("tailwind", "tailwindcss", "tailwindcss", [
+    "-i",
+    (0, import_node_path.join)(projectRoot, "src/index.css"),
+    "-o",
+    tailwindOutput
+  ]);
+  (0, import_node_fs.rmSync)(tailwindOutput, { force: true });
+  const oxlint = await run("oxlint", "oxlint", "oxlint", [
+    "-c",
+    (0, import_node_path.join)(devkitRoot, "oxlint-config.json"),
+    "src"
+  ]);
+  return [...targetChecks, tsgo, biome, tailwind, oxlint];
+}
+async function runLintCli(target) {
+  try {
+    const results = await runAllChecks(target);
+    const failed = results.filter((result) => !result.ok);
+    console.log("");
+    if (failed.length === 0) {
+      console.log("RESULT: ALL CHECKS PASSED - Finished with 0 errors. Found no issues.");
+      return;
+    }
+    console.error(
+      `RESULT: FAILED - Found errors in: ${failed.map(({ name }) => name).join(", ")}`
+    );
+    console.error("Fix all lint errors, then re-run 'pnpm lint'.");
+    process.exitCode = 1;
+  } catch (error) {
+    console.error(error);
+    process.exitCode = 1;
+  }
+}
+
+// src/cli/phaser-lint.ts
+void runLintCli("phaser");

package/dist/cli/react-lint.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/cli/lint.ts
+var import_node_child_process = require("child_process");
+var import_node_fs = require("fs");
+var import_node_module = require("module");
+var import_node_os = require("os");
+var import_node_path = require("path");
+var devkitRoot = (0, import_node_path.resolve)(__dirname, "../..");
+var projectRoot = process.cwd();
+var requireFromDevkit = (0, import_node_module.createRequire)((0, import_node_path.join)(devkitRoot, "package.json"));
+var projectBiomeConfig = (0, import_node_path.join)(projectRoot, "biome.json");
+var biomeConfig = (0, import_node_fs.existsSync)(projectBiomeConfig) ? projectBiomeConfig : (0, import_node_path.join)(devkitRoot, "biome-config.json");
+function resolveBin(packageName, binName) {
+  const packageJsonPath = requireFromDevkit.resolve(`${packageName}/package.json`);
+  const packageJson = JSON.parse((0, import_node_fs.readFileSync)(packageJsonPath, "utf8"));
+  const relativeBin = typeof packageJson.bin === "string" ? packageJson.bin : packageJson.bin?.[binName];
+  if (!relativeBin) {
+    throw new Error(`${packageName} does not expose the ${binName} executable`);
+  }
+  return (0, import_node_path.resolve)((0, import_node_path.dirname)(packageJsonPath), relativeBin);
+}
+function run(name, packageName, binName, args) {
+  return new Promise((resolveResult) => {
+    const child = (0, import_node_child_process.spawn)(process.execPath, [resolveBin(packageName, binName), ...args], {
+      cwd: projectRoot,
+      env: process.env,
+      stdio: "inherit"
+    });
+    child.once("error", (error) => {
+      console.error(`[${name}] ${error.message}`);
+      resolveResult({ name, ok: false });
+    });
+    child.once("close", (code, signal) => {
+      if (signal) {
+        console.error(`[${name}] terminated by ${signal}`);
+      }
+      resolveResult({ name, ok: code === 0 && signal === null });
+    });
+  });
+}
+function readProjectSource(path, checkName) {
+  const absolutePath = (0, import_node_path.join)(projectRoot, path);
+  if (!(0, import_node_fs.existsSync)(absolutePath)) {
+    console.error(`[${checkName}] \u7F3A\u5C11\u6A21\u677F\u5FC5\u9700\u7684 ${path}\u3002\u8BF7\u6062\u590D\u6A21\u677F\u539F\u6587\u4EF6\u540E\u91CD\u65B0\u8FD0\u884C pnpm lint\u3002`);
+    return void 0;
+  }
+  return (0, import_node_fs.readFileSync)(absolutePath, "utf8");
+}
+function readProjectManifest() {
+  const manifestPath = (0, import_node_path.join)(projectRoot, "package.json");
+  if (!(0, import_node_fs.existsSync)(manifestPath)) {
+    console.error("[phaser-version] \u7F3A\u5C11\u9879\u76EE package.json\u3002");
+    return void 0;
+  }
+  try {
+    return JSON.parse((0, import_node_fs.readFileSync)(manifestPath, "utf8"));
+  } catch (error) {
+    console.error(`[phaser-version] \u65E0\u6CD5\u89E3\u6790 package.json\uFF1A${String(error)}`);
+    return void 0;
+  }
+}
+function checkPhaser4Dependency() {
+  const name = "phaser-version";
+  const manifest = readProjectManifest();
+  const version = manifest?.dependencies?.phaser ?? manifest?.devDependencies?.phaser;
+  const declaresPhaser4 = typeof version === "string" && /(?:^|[\s<>=~^|])4(?:\.|\s|$)/.test(version);
+  if (!declaresPhaser4) {
+    console.error(
+      `[${name}] Phaser \u6A21\u677F\u5FC5\u987B\u663E\u5F0F\u58F0\u660E Phaser 4\uFF1B\u5F53\u524D\u58F0\u660E\u4E3A ${JSON.stringify(version ?? null)}\u3002`
+    );
+    return { name, ok: false };
+  }
+  return { name, ok: true };
+}
+function checkPhaserViteConfig() {
+  const name = "phaser-vite-config";
+  const source = readProjectSource("vite.config.ts", name);
+  if (!source) return { name, ok: false };
+  const hasDevkitImport = /from\s+["']miaoda-game-devkit\/vite["']/.test(source);
+  const hasConfigCall = /defineGameViteConfig\s*\(/.test(source);
+  if (!hasDevkitImport || !hasConfigCall) {
+    console.error(
+      `[${name}] vite.config.ts \u672A\u4F7F\u7528 Phaser \u6A21\u677F\u89C4\u5B9A\u7684\u914D\u7F6E\u5165\u53E3\u3002
+\u8BF7\u4ECE miaoda-game-devkit/vite \u5BFC\u5165 defineGameViteConfig\uFF0C\u5E76\u7528 defineGameViteConfig({ ... }) \u5305\u4F4F\u5F53\u524D\u7684\u914D\u7F6E\u5BF9\u8C61\u3002
+\u53EA\u66FF\u6362\u914D\u7F6E\u51FD\u6570\uFF0C\u4FDD\u7559\u73B0\u6709 plugins\u3001resolve \u7B49\u5BF9\u8C61\u5185\u5BB9\u4E0D\u53D8\u3002`
+    );
+    return { name, ok: false };
+  }
+  return { name, ok: true };
+}
+function checkVitestConfig(target) {
+  const name = `${target}-vitest-config`;
+  const source = readProjectSource("vitest.config.ts", name);
+  if (!source) return { name, ok: false };
+  const expected = target === "react" ? {
+    entry: "miaoda-game-devkit/react/vitest-config",
+    factory: "defineReactGameVitestConfig"
+  } : {
+    entry: "miaoda-game-devkit/vitest-config",
+    factory: "defineGameVitestConfig"
+  };
+  const hasDevkitImport = new RegExp(
+    `from\\s+["']${expected.entry.replaceAll("/", "\\/")}["']`
+  ).test(source);
+  const hasConfigCall = new RegExp(`${expected.factory}\\s*\\(`).test(source);
+  if (!hasDevkitImport || !hasConfigCall) {
+    console.error(
+      `[${name}] vitest.config.ts \u5FC5\u987B\u4ECE ${expected.entry} \u5BFC\u5165\u5E76\u8C03\u7528 ${expected.factory}\u3002`
+    );
+    return { name, ok: false };
+  }
+  return { name, ok: true };
+}
+async function runAllChecks(target) {
+  const targetChecks = target === "react" ? [checkVitestConfig("react")] : [checkPhaser4Dependency(), checkPhaserViteConfig(), checkVitestConfig("phaser")];
+  const [tsgo, biome] = await Promise.all([
+    run("tsgo", "@typescript/native-preview", "tsgo", ["-p", "tsconfig.json"]),
+    run("biome", "@biomejs/biome", "biome", [
+      "lint",
+      "--config-path",
+      biomeConfig,
+      "src"
+    ])
+  ]);
+  const tailwindOutput = (0, import_node_path.join)((0, import_node_os.tmpdir)(), `miaoda-game-devkit-${process.pid}.css`);
+  const tailwind = await run("tailwind", "tailwindcss", "tailwindcss", [
+    "-i",
+    (0, import_node_path.join)(projectRoot, "src/index.css"),
+    "-o",
+    tailwindOutput
+  ]);
+  (0, import_node_fs.rmSync)(tailwindOutput, { force: true });
+  const oxlint = await run("oxlint", "oxlint", "oxlint", [
+    "-c",
+    (0, import_node_path.join)(devkitRoot, "oxlint-config.json"),
+    "src"
+  ]);
+  return [...targetChecks, tsgo, biome, tailwind, oxlint];
+}
+async function runLintCli(target) {
+  try {
+    const results = await runAllChecks(target);
+    const failed = results.filter((result) => !result.ok);
+    console.log("");
+    if (failed.length === 0) {
+      console.log("RESULT: ALL CHECKS PASSED - Finished with 0 errors. Found no issues.");
+      return;
+    }
+    console.error(
+      `RESULT: FAILED - Found errors in: ${failed.map(({ name }) => name).join(", ")}`
+    );
+    console.error("Fix all lint errors, then re-run 'pnpm lint'.");
+    process.exitCode = 1;
+  } catch (error) {
+    console.error(error);
+    process.exitCode = 1;
+  }
+}
+
+// src/cli/react-lint.ts
+void runLintCli("react");

package/dist/lint/setup.mjs

@@ -1,5 +1,7 @@
 // src/lint/setup.ts
 import { afterEach } from "vitest";
+
+// src/testing/jsdom-canvas.ts
 var contexts = /* @__PURE__ */ new WeakMap();
 function createCanvasContext(canvas) {
   const imageData = (width = 1, height = 1) => ({
@@ -14,9 +16,7 @@ function createCanvasContext(canvas) {
   };
   const context = new Proxy(state, {
     get(target, property) {
-      if (property in target) {
-        return target[property];
-      }
+      if (property in target) return target[property];
       if (property === "createImageData" || property === "getImageData") {
         return (...args) => imageData(args.at(-2), args.at(-1));
       }
@@ -48,18 +48,25 @@ function createCanvasContext(canvas) {
   });
   return context;
 }
-HTMLCanvasElement.prototype.getContext = function getContext(contextId) {
-  if (contextId !== "2d") {
-    return null;
-  }
-  const existing = contexts.get(this);
-  if (existing) {
-    return existing;
-  }
-  const context = createCanvasContext(this);
-  contexts.set(this, context);
-  return context;
-};
+function installJSDOMCanvasContext() {
+  HTMLCanvasElement.prototype.getContext = function getContext(contextId) {
+    if (contextId !== "2d") return null;
+    const existing = contexts.get(this);
+    if (existing) return existing;
+    const context = createCanvasContext(this);
+    contexts.set(this, context);
+    return context;
+  };
+}
+
+// src/testing/jsdom-storage.ts
+function clearJSDOMStorage() {
+  window.localStorage.clear();
+  window.sessionStorage.clear();
+}
+
+// src/lint/setup.ts
+installJSDOMCanvasContext();
 var HeadlessImage = class {
   onerror = null;
   onload = null;
@@ -91,32 +98,7 @@ var HeadlessImage = class {
   }
 };
 globalThis.Image = HeadlessImage;
-var storageValues = /* @__PURE__ */ new Map();
-var headlessStorage = {
-  get length() {
-    return storageValues.size;
-  },
-  clear() {
-    storageValues.clear();
-  },
-  getItem(key) {
-    return storageValues.get(key) ?? null;
-  },
-  key(index) {
-    return [...storageValues.keys()][index] ?? null;
-  },
-  removeItem(key) {
-    storageValues.delete(key);
-  },
-  setItem(key, value) {
-    storageValues.set(key, value);
-  }
-};
-Object.defineProperty(globalThis, "localStorage", {
-  configurable: true,
-  value: headlessStorage
-});
 afterEach(() => {
   document.body.replaceChildren();
-  headlessStorage.clear();
+  clearJSDOMStorage();
 });

package/dist/react/vitest-config.js

@@ -23,18 +23,51 @@ __export(react_vitest_config_exports, {
   defineReactGameVitestConfig: () => defineReactGameVitestConfig
 });
 module.exports = __toCommonJS(react_vitest_config_exports);
+var import_node_fs = require("fs");
 var import_node_path = require("path");
 var import_config = require("vitest/config");
+
+// src/testing/vitest-node-args.ts
+function getJSDOMWorkerExecArgv() {
+  const nodeMajor = Number.parseInt(process.versions.node, 10);
+  return nodeMajor >= 25 ? ["--no-experimental-webstorage"] : [];
+}
+
+// src/react-vitest-config.ts
+function resolvePhaser3BrowserEntry(projectRoot) {
+  const manifestPath = (0, import_node_path.resolve)(projectRoot, "node_modules/phaser/package.json");
+  if (!(0, import_node_fs.existsSync)(manifestPath)) return void 0;
+  try {
+    const manifest = JSON.parse((0, import_node_fs.readFileSync)(manifestPath, "utf8"));
+    if (!manifest.version?.startsWith("3.")) return void 0;
+    const browserEntry = (0, import_node_path.resolve)(
+      (0, import_node_path.dirname)(manifestPath),
+      manifest.browser ?? "dist/phaser.js"
+    );
+    return (0, import_node_fs.existsSync)(browserEntry) ? browserEntry : void 0;
+  } catch {
+    return void 0;
+  }
+}
 function defineReactGameVitestConfig(options) {
+  const phaser3BrowserEntry = resolvePhaser3BrowserEntry(options.projectRoot);
   return (0, import_config.defineConfig)({
     resolve: {
-      alias: { ...options.aliases, "@": (0, import_node_path.resolve)(options.projectRoot, "src") }
+      alias: {
+        ...phaser3BrowserEntry ? { phaser: phaser3BrowserEntry } : {},
+        ...options.aliases,
+        "@": (0, import_node_path.resolve)(options.projectRoot, "src")
+      }
     },
     test: {
+      env: {
+        NODE_ENV: "test"
+      },
       include: [
         "src/**/*.{test,spec}.{ts,tsx}",
         "tests/**/*.{test,spec}.{ts,tsx}"
       ],
+      execArgv: getJSDOMWorkerExecArgv(),
       environment: "jsdom",
       environmentOptions: {
         jsdom: { url: "http://localhost/", pretendToBeVisual: true }
@@ -43,6 +76,9 @@ function defineReactGameVitestConfig(options) {
         "miaoda-game-devkit/react/vitest-setup",
         ...options.additionalSetupFiles ?? []
       ],
+      sequence: {
+        setupFiles: "list"
+      },
       reporters: ["minimal"],
       restoreMocks: true,
       clearMocks: true,

package/dist/react/vitest-config.mjs

@@ -1,16 +1,49 @@
 // src/react-vitest-config.ts
-import { resolve } from "path";
+import { existsSync, readFileSync } from "fs";
+import { dirname, resolve } from "path";
 import { defineConfig } from "vitest/config";
+
+// src/testing/vitest-node-args.ts
+function getJSDOMWorkerExecArgv() {
+  const nodeMajor = Number.parseInt(process.versions.node, 10);
+  return nodeMajor >= 25 ? ["--no-experimental-webstorage"] : [];
+}
+
+// src/react-vitest-config.ts
+function resolvePhaser3BrowserEntry(projectRoot) {
+  const manifestPath = resolve(projectRoot, "node_modules/phaser/package.json");
+  if (!existsSync(manifestPath)) return void 0;
+  try {
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    if (!manifest.version?.startsWith("3.")) return void 0;
+    const browserEntry = resolve(
+      dirname(manifestPath),
+      manifest.browser ?? "dist/phaser.js"
+    );
+    return existsSync(browserEntry) ? browserEntry : void 0;
+  } catch {
+    return void 0;
+  }
+}
 function defineReactGameVitestConfig(options) {
+  const phaser3BrowserEntry = resolvePhaser3BrowserEntry(options.projectRoot);
   return defineConfig({
     resolve: {
-      alias: { ...options.aliases, "@": resolve(options.projectRoot, "src") }
+      alias: {
+        ...phaser3BrowserEntry ? { phaser: phaser3BrowserEntry } : {},
+        ...options.aliases,
+        "@": resolve(options.projectRoot, "src")
+      }
     },
     test: {
+      env: {
+        NODE_ENV: "test"
+      },
       include: [
         "src/**/*.{test,spec}.{ts,tsx}",
         "tests/**/*.{test,spec}.{ts,tsx}"
       ],
+      execArgv: getJSDOMWorkerExecArgv(),
       environment: "jsdom",
       environmentOptions: {
         jsdom: { url: "http://localhost/", pretendToBeVisual: true }
@@ -19,6 +52,9 @@ function defineReactGameVitestConfig(options) {
         "miaoda-game-devkit/react/vitest-setup",
         ...options.additionalSetupFiles ?? []
       ],
+      sequence: {
+        setupFiles: "list"
+      },
       reporters: ["minimal"],
       restoreMocks: true,
       clearMocks: true,