feat: migrate to Tailwind CSS v4 (#7614)

* chore: update deps

* feat: use jsonc/x language

* chore: update eslint 10.0

* fix: no-useless-assignment

* feat: add CLAUDE.md

* chore: ignore

* feat: claude

* fix: lint

* chore: suppot eslint v10

* fix: lint

* fix: lint

* fix: type check

* fix: unit test

* fix: Suggested fix

* fix: unit test

* chore: update stylelint v17

* chore: update all major deps

* fix:  echarts console warn

* chore: update vitest v4

* feat: add skills ignores

* chore: update deps

* chore: update deps

* fix: cspell

* chore: update deps

* chore: update tailwindcss v4

* chore: remove postcss config

* fix: no use catalog

* chore: tailwind v4 config

* fix: tailwindcss v4 sort

* feat: use eslint-plugin-better-tailwindcss

* fix: Interference between enforce-consistent-line-wrapping, jsx-curly-brace-presence and Prettier

* fix: Interference between enforce-consistent-line-wrapping, jsx-curly-brace-presence and Prettier

* fix(lint): resolve prettier and better-tailwindcss formatting conflicts

* fix(tailwind): update theme references and lint sources

* style(format): normalize apps docs and playground vue files

* style(format): normalize core ui-kit components

* style(format): normalize effects ui and layout components

packages/@core/base/design/package.json

@@ -25,6 +25,9 @@
       "development": "./src/scss-bem/bem.scss",
       "default": "./dist/bem.scss"
     },
+    "./theme": {
+      "default": "./src/css/global.css"
+    },
     ".": {
       "types": "./src/index.ts",
       "development": "./src/index.ts",
@@ -37,5 +40,11 @@
         "default": "./dist/index.mjs"
       }
     }
+  },
+  "dependencies": {
+    "@iconify/json": "catalog:",
+    "@iconify/tailwind4": "catalog:",
+    "@tailwindcss/typography": "catalog:",
+    "tw-animate-css": "catalog:"
   }
 }

packages/@core/base/design/src/css/global.css

@@ -1,12 +1,294 @@
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
+@import 'tailwindcss';
+@import 'tw-animate-css';
 
+@plugin '@tailwindcss/typography';
+@plugin '@iconify/tailwind4';
+
+/* Monorepo source detection: scan all packages and apps for utility classes */
+@source '../../../../../../packages/';
+@source '../../../../../../apps/';
+@source '../../../../../../docs/';
+@source '../../../../../../playground/';
+
+/* Dark mode uses .dark class selector, not prefers-color-scheme */
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  /* Font */
+  --font-sans: var(--font-family);
+
+  /* Border Radius */
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+
+  /* Box Shadow */
+  --shadow-float:
+    0 6px 16px 0 rgb(0 0 0 / 8%), 0 3px 6px -4px rgb(0 0 0 / 12%),
+    0 9px 28px 8px rgb(0 0 0 / 5%);
+
+  /* Animations */
+  --animate-accordion-down: accordion-down 0.2s ease-out;
+  --animate-accordion-up: accordion-up 0.2s ease-out;
+  --animate-collapsible-down: collapsible-down 0.2s ease-in-out;
+  --animate-collapsible-up: collapsible-up 0.2s ease-in-out;
+  --animate-float: float 5s linear 0ms infinite;
+
+  /* ===== Semantic Colors (shadcn-ui) ===== */
+
+  --color-background: hsl(var(--background));
+  --color-background-deep: hsl(var(--background-deep));
+  --color-foreground: hsl(var(--foreground));
+  --color-card: hsl(var(--card));
+  --color-card-foreground: hsl(var(--card-foreground));
+  --color-popover: hsl(var(--popover));
+  --color-popover-foreground: hsl(var(--popover-foreground));
+  --color-muted: hsl(var(--muted));
+  --color-muted-foreground: hsl(var(--muted-foreground));
+  --color-accent: hsl(var(--accent));
+  --color-accent-foreground: hsl(var(--accent-foreground));
+  --color-accent-hover: hsl(var(--accent-hover));
+  --color-accent-lighter: hsl(var(--accent-lighter));
+  --color-border: hsl(var(--border));
+  --color-input: hsl(var(--input));
+  --color-input-background: hsl(var(--input-background));
+  --color-ring: hsl(var(--ring));
+  --color-secondary: hsl(var(--secondary));
+  --color-secondary-desc: hsl(var(--secondary-desc));
+  --color-secondary-foreground: hsl(var(--secondary-foreground));
+
+  /* ===== Custom Semantic Colors ===== */
+
+  --color-header: hsl(var(--header));
+  --color-heavy: hsl(var(--heavy));
+  --color-heavy-foreground: hsl(var(--heavy-foreground));
+  --color-main: hsl(var(--main));
+  --color-overlay: hsl(var(--overlay));
+  --color-overlay-content: hsl(var(--overlay-content));
+  --color-sidebar: hsl(var(--sidebar));
+  --color-sidebar-deep: hsl(var(--sidebar-deep));
+
+  /* ===== Primary Palette ===== */
+
+  --color-primary: hsl(var(--primary));
+  --color-primary-foreground: hsl(var(--primary-foreground));
+  --color-primary-50: hsl(var(--primary-50));
+  --color-primary-100: hsl(var(--primary-100));
+  --color-primary-200: hsl(var(--primary-200));
+  --color-primary-300: hsl(var(--primary-300));
+  --color-primary-400: hsl(var(--primary-400));
+  --color-primary-500: hsl(var(--primary-500));
+  --color-primary-600: hsl(var(--primary-600));
+  --color-primary-700: hsl(var(--primary-700));
+  --color-primary-active: hsl(var(--primary-700));
+  --color-primary-background-light: hsl(var(--primary-200));
+  --color-primary-background-lighter: hsl(var(--primary-100));
+  --color-primary-background-lightest: hsl(var(--primary-50));
+  --color-primary-border: hsl(var(--primary-400));
+  --color-primary-border-light: hsl(var(--primary-300));
+  --color-primary-hover: hsl(var(--primary-600));
+  --color-primary-text: hsl(var(--primary-500));
+  --color-primary-text-active: hsl(var(--primary-700));
+  --color-primary-text-hover: hsl(var(--primary-600));
+
+  /* ===== Destructive Palette ===== */
+
+  --color-destructive: hsl(var(--destructive));
+  --color-destructive-foreground: hsl(var(--destructive-foreground));
+  --color-destructive-50: hsl(var(--destructive-50));
+  --color-destructive-100: hsl(var(--destructive-100));
+  --color-destructive-200: hsl(var(--destructive-200));
+  --color-destructive-300: hsl(var(--destructive-300));
+  --color-destructive-400: hsl(var(--destructive-400));
+  --color-destructive-500: hsl(var(--destructive-500));
+  --color-destructive-600: hsl(var(--destructive-600));
+  --color-destructive-700: hsl(var(--destructive-700));
+  --color-destructive-active: hsl(var(--destructive-700));
+  --color-destructive-background-light: hsl(var(--destructive-200));
+  --color-destructive-background-lighter: hsl(var(--destructive-100));
+  --color-destructive-background-lightest: hsl(var(--destructive-50));
+  --color-destructive-border: hsl(var(--destructive-400));
+  --color-destructive-border-light: hsl(var(--destructive-300));
+  --color-destructive-hover: hsl(var(--destructive-600));
+  --color-destructive-text: hsl(var(--destructive-500));
+  --color-destructive-text-active: hsl(var(--destructive-700));
+  --color-destructive-text-hover: hsl(var(--destructive-600));
+
+  /* ===== Success Palette ===== */
+
+  --color-success: hsl(var(--success));
+  --color-success-foreground: hsl(var(--success-foreground));
+  --color-success-50: hsl(var(--success-50));
+  --color-success-100: hsl(var(--success-100));
+  --color-success-200: hsl(var(--success-200));
+  --color-success-300: hsl(var(--success-300));
+  --color-success-400: hsl(var(--success-400));
+  --color-success-500: hsl(var(--success-500));
+  --color-success-600: hsl(var(--success-600));
+  --color-success-700: hsl(var(--success-700));
+  --color-success-active: hsl(var(--success-700));
+  --color-success-background-light: hsl(var(--success-200));
+  --color-success-background-lighter: hsl(var(--success-100));
+  --color-success-background-lightest: hsl(var(--success-50));
+  --color-success-border: hsl(var(--success-400));
+  --color-success-border-light: hsl(var(--success-300));
+  --color-success-hover: hsl(var(--success-600));
+  --color-success-text: hsl(var(--success-500));
+  --color-success-text-active: hsl(var(--success-700));
+  --color-success-text-hover: hsl(var(--success-600));
+
+  /* ===== Warning Palette ===== */
+
+  --color-warning: hsl(var(--warning));
+  --color-warning-foreground: hsl(var(--warning-foreground));
+  --color-warning-50: hsl(var(--warning-50));
+  --color-warning-100: hsl(var(--warning-100));
+  --color-warning-200: hsl(var(--warning-200));
+  --color-warning-300: hsl(var(--warning-300));
+  --color-warning-400: hsl(var(--warning-400));
+  --color-warning-500: hsl(var(--warning-500));
+  --color-warning-600: hsl(var(--warning-600));
+  --color-warning-700: hsl(var(--warning-700));
+  --color-warning-active: hsl(var(--warning-700));
+  --color-warning-background-light: hsl(var(--warning-200));
+  --color-warning-background-lighter: hsl(var(--warning-100));
+  --color-warning-background-lightest: hsl(var(--warning-50));
+  --color-warning-border: hsl(var(--warning-400));
+  --color-warning-border-light: hsl(var(--warning-300));
+  --color-warning-hover: hsl(var(--warning-600));
+  --color-warning-text: hsl(var(--warning-500));
+  --color-warning-text-active: hsl(var(--warning-700));
+  --color-warning-text-hover: hsl(var(--warning-600));
+
+  /* ===== Green Palette (alias for success shades) ===== */
+
+  --color-green-50: hsl(var(--green-50));
+  --color-green-100: hsl(var(--green-100));
+  --color-green-200: hsl(var(--green-200));
+  --color-green-300: hsl(var(--green-300));
+  --color-green-400: hsl(var(--green-400));
+  --color-green-500: hsl(var(--green-500));
+  --color-green-600: hsl(var(--green-600));
+  --color-green-700: hsl(var(--green-700));
+  --color-green-active: hsl(var(--green-700));
+  --color-green-background-light: hsl(var(--green-200));
+  --color-green-background-lighter: hsl(var(--green-100));
+  --color-green-background-lightest: hsl(var(--green-50));
+  --color-green-border: hsl(var(--green-400));
+  --color-green-border-light: hsl(var(--green-300));
+  --color-green-foreground: hsl(var(--success-foreground));
+  --color-green-hover: hsl(var(--green-600));
+  --color-green-text: hsl(var(--green-500));
+  --color-green-text-active: hsl(var(--green-700));
+  --color-green-text-hover: hsl(var(--green-600));
+
+  /* ===== Red Palette (alias for destructive shades) ===== */
+
+  --color-red-50: hsl(var(--red-50));
+  --color-red-100: hsl(var(--red-100));
+  --color-red-200: hsl(var(--red-200));
+  --color-red-300: hsl(var(--red-300));
+  --color-red-400: hsl(var(--red-400));
+  --color-red-500: hsl(var(--red-500));
+  --color-red-600: hsl(var(--red-600));
+  --color-red-700: hsl(var(--red-700));
+  --color-red-active: hsl(var(--red-700));
+  --color-red-background-light: hsl(var(--red-200));
+  --color-red-background-lighter: hsl(var(--red-100));
+  --color-red-background-lightest: hsl(var(--red-50));
+  --color-red-border: hsl(var(--red-400));
+  --color-red-border-light: hsl(var(--red-300));
+  --color-red-foreground: hsl(var(--destructive-foreground));
+  --color-red-hover: hsl(var(--red-600));
+  --color-red-text: hsl(var(--red-500));
+  --color-red-text-active: hsl(var(--red-700));
+  --color-red-text-hover: hsl(var(--red-600));
+
+  /* ===== Yellow Palette (alias for warning shades) ===== */
+
+  --color-yellow-50: hsl(var(--yellow-50));
+  --color-yellow-100: hsl(var(--yellow-100));
+  --color-yellow-200: hsl(var(--yellow-200));
+  --color-yellow-300: hsl(var(--yellow-300));
+  --color-yellow-400: hsl(var(--yellow-400));
+  --color-yellow-500: hsl(var(--yellow-500));
+  --color-yellow-600: hsl(var(--yellow-600));
+  --color-yellow-700: hsl(var(--yellow-700));
+  --color-yellow-active: hsl(var(--yellow-700));
+  --color-yellow-background-light: hsl(var(--yellow-200));
+  --color-yellow-background-lighter: hsl(var(--yellow-100));
+  --color-yellow-background-lightest: hsl(var(--yellow-50));
+  --color-yellow-border: hsl(var(--yellow-400));
+  --color-yellow-border-light: hsl(var(--yellow-300));
+  --color-yellow-foreground: hsl(var(--warning-foreground));
+  --color-yellow-hover: hsl(var(--yellow-600));
+  --color-yellow-text: hsl(var(--yellow-500));
+  --color-yellow-text-active: hsl(var(--yellow-700));
+  --color-yellow-text-hover: hsl(var(--yellow-600));
+}
+
+/* Keyframes */
+@keyframes accordion-down {
+  from {
+    height: 0;
+  }
+
+  to {
+    height: var(--reka-accordion-content-height);
+  }
+}
+
+@keyframes accordion-up {
+  from {
+    height: var(--reka-accordion-content-height);
+  }
+
+  to {
+    height: 0;
+  }
+}
+
+@keyframes collapsible-down {
+  from {
+    height: 0;
+  }
+
+  to {
+    height: var(--reka-collapsible-content-height);
+  }
+}
+
+@keyframes collapsible-up {
+  from {
+    height: var(--reka-collapsible-content-height);
+  }
+
+  to {
+    height: 0;
+  }
+}
+
+@keyframes float {
+  0% {
+    transform: translateY(0);
+  }
+
+  50% {
+    transform: translateY(-20px);
+  }
+
+  100% {
+    transform: translateY(0);
+  }
+}
+
+/* Base styles */
 @layer base {
   *,
   ::after,
   ::before {
-    @apply border-border;
+    @apply border-border outline-ring/50;
 
     box-sizing: border-box;
     border-style: solid;
@@ -24,29 +306,16 @@
     text-rendering: optimizelegibility;
     text-size-adjust: 100%;
     -webkit-tap-highlight-color: transparent;
-
-    /* -webkit-font-smoothing: antialiased;
-    -moz-osx-font-smoothing: grayscale; */
   }
 
   #app,
   body,
   html {
     @apply size-full;
-
-    /* scrollbar-gutter: stable; */
   }
 
   body {
     min-height: 100vh;
-
-    /* pointer-events: auto !important; */
-
-    /* overflow: overlay; */
-
-    /* -webkit-font-smoothing: antialiased; */
-
-    /* -moz-osx-font-smoothing: grayscale; */
   }
 
   a,
@@ -63,19 +332,19 @@
   }
 
   ::view-transition-old(root) {
-    @apply z-[1];
+    @apply z-1;
   }
 
   ::view-transition-new(root) {
-    @apply z-[2147483646];
+    @apply z-2147483646;
   }
 
   html.dark::view-transition-old(root) {
-    @apply z-[2147483646];
+    @apply z-2147483646;
   }
 
   html.dark::view-transition-new(root) {
-    @apply z-[1];
+    @apply z-1;
   }
 
   input::placeholder,
@@ -83,18 +352,12 @@
     @apply opacity-100;
   }
 
-  /* input:-webkit-autofill {
-    @apply border-none;
-
-    box-shadow: 0 0 0 1000px transparent inset;
-  } */
-
   input[type='number']::-webkit-inner-spin-button,
   input[type='number']::-webkit-outer-spin-button {
     @apply m-0 appearance-none;
   }
 
-  /* 只有非mac下才进行调整，mac下使用默认滚动条 */
+  /* Only adjust scrollbar for non-macOS */
   html:not([data-platform='macOs']) {
     ::-webkit-scrollbar {
       @apply h-[10px] w-[10px];
@@ -114,44 +377,184 @@
   }
 }
 
-@layer components {
-  .flex-center {
-    @apply flex items-center justify-center;
-  }
+/* Custom utilities (v4 @utility syntax) */
+@utility flex-center {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
 
-  .flex-col-center {
-    @apply flex flex-col items-center justify-center;
-  }
+@utility flex-col-center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+}
 
-  .outline-box {
-    @apply outline-border relative cursor-pointer rounded-md p-1 outline outline-1;
-  }
+/* Component styles (complex selectors, not convertible to @utility) */
+.outline-box {
+  @apply outline-border relative cursor-pointer rounded-md p-1 outline-1;
+}
 
-  .outline-box::after {
-    @apply absolute left-1/2 top-1/2 z-20 h-0 w-[1px] rounded-sm opacity-0 outline outline-2 outline-transparent transition-all duration-300 content-[""];
-  }
+.outline-box::after {
+  @apply absolute top-1/2 left-1/2 z-20 h-0 w-px rounded-sm opacity-0 outline-2 outline-transparent transition-all duration-300 content-[""];
+}
 
-  .outline-box.outline-box-active {
-    @apply outline-primary outline outline-2;
-  }
+.outline-box.outline-box-active {
+  @apply outline-primary outline-2;
+}
 
-  .outline-box.outline-box-active::after {
-    display: none;
-  }
+.outline-box.outline-box-active::after {
+  display: none;
+}
 
-  .outline-box:not(.outline-box-active):hover::after {
-    @apply outline-primary left-0 top-0 h-full w-full p-1 opacity-100;
-  }
+.outline-box:not(.outline-box-active):hover::after {
+  @apply outline-primary top-0 left-0 h-full w-full p-1 opacity-100;
+}
 
-  .vben-link {
-    @apply text-primary hover:text-primary-hover active:text-primary-active cursor-pointer;
-  }
+.vben-link {
+  @apply text-primary hover:text-primary-hover active:text-primary-active cursor-pointer;
+}
 
-  .card-box {
-    @apply bg-card text-card-foreground border-border rounded-xl border;
+.card-box {
+  @apply bg-card text-card-foreground border-border rounded-xl border;
+}
+
+/* Enter animations (converted from enterAnimationPlugin) */
+@keyframes enter-x-animation {
+  to {
+    opacity: 1;
+    transform: translateX(0);
   }
 }
 
+@keyframes enter-y-animation {
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.enter-x:nth-child(1) {
+  opacity: 0;
+  transform: translateX(50px);
+  animation: enter-x-animation 0.3s ease-in-out 0.1s forwards;
+}
+
+.enter-x:nth-child(2) {
+  opacity: 0;
+  transform: translateX(50px);
+  animation: enter-x-animation 0.3s ease-in-out 0.2s forwards;
+}
+
+.enter-x:nth-child(3) {
+  opacity: 0;
+  transform: translateX(50px);
+  animation: enter-x-animation 0.3s ease-in-out 0.3s forwards;
+}
+
+.enter-x:nth-child(4) {
+  opacity: 0;
+  transform: translateX(50px);
+  animation: enter-x-animation 0.3s ease-in-out 0.4s forwards;
+}
+
+.enter-x:nth-child(5) {
+  opacity: 0;
+  transform: translateX(50px);
+  animation: enter-x-animation 0.3s ease-in-out 0.5s forwards;
+}
+
+.enter-y:nth-child(1) {
+  opacity: 0;
+  transform: translateY(50px);
+  animation: enter-y-animation 0.3s ease-in-out 0.1s forwards;
+}
+
+.enter-y:nth-child(2) {
+  opacity: 0;
+  transform: translateY(50px);
+  animation: enter-y-animation 0.3s ease-in-out 0.2s forwards;
+}
+
+.enter-y:nth-child(3) {
+  opacity: 0;
+  transform: translateY(50px);
+  animation: enter-y-animation 0.3s ease-in-out 0.3s forwards;
+}
+
+.enter-y:nth-child(4) {
+  opacity: 0;
+  transform: translateY(50px);
+  animation: enter-y-animation 0.3s ease-in-out 0.4s forwards;
+}
+
+.enter-y:nth-child(5) {
+  opacity: 0;
+  transform: translateY(50px);
+  animation: enter-y-animation 0.3s ease-in-out 0.5s forwards;
+}
+
+.-enter-x:nth-child(1) {
+  opacity: 0;
+  transform: translateX(-50px);
+  animation: enter-x-animation 0.3s ease-in-out 0.1s forwards;
+}
+
+.-enter-x:nth-child(2) {
+  opacity: 0;
+  transform: translateX(-50px);
+  animation: enter-x-animation 0.3s ease-in-out 0.2s forwards;
+}
+
+.-enter-x:nth-child(3) {
+  opacity: 0;
+  transform: translateX(-50px);
+  animation: enter-x-animation 0.3s ease-in-out 0.3s forwards;
+}
+
+.-enter-x:nth-child(4) {
+  opacity: 0;
+  transform: translateX(-50px);
+  animation: enter-x-animation 0.3s ease-in-out 0.4s forwards;
+}
+
+.-enter-x:nth-child(5) {
+  opacity: 0;
+  transform: translateX(-50px);
+  animation: enter-x-animation 0.3s ease-in-out 0.5s forwards;
+}
+
+.-enter-y:nth-child(1) {
+  opacity: 0;
+  transform: translateY(-50px);
+  animation: enter-y-animation 0.3s ease-in-out 0.1s forwards;
+}
+
+.-enter-y:nth-child(2) {
+  opacity: 0;
+  transform: translateY(-50px);
+  animation: enter-y-animation 0.3s ease-in-out 0.2s forwards;
+}
+
+.-enter-y:nth-child(3) {
+  opacity: 0;
+  transform: translateY(-50px);
+  animation: enter-y-animation 0.3s ease-in-out 0.3s forwards;
+}
+
+.-enter-y:nth-child(4) {
+  opacity: 0;
+  transform: translateY(-50px);
+  animation: enter-y-animation 0.3s ease-in-out 0.4s forwards;
+}
+
+.-enter-y:nth-child(5) {
+  opacity: 0;
+  transform: translateY(-50px);
+  animation: enter-y-animation 0.3s ease-in-out 0.5s forwards;
+}
+
 html.invert-mode {
   @apply invert;
 }

packages/@core/base/design/src/css/nprogress.css

@@ -1,10 +1,12 @@
+@reference "./global.css";
+
 /* Make clicks pass-through */
 #nprogress {
   @apply pointer-events-none;
 }
 
 #nprogress .bar {
-  @apply bg-primary fixed left-0 top-0 z-[1031] h-[2px] w-full;
+  @apply bg-primary fixed top-0 left-0 z-1031 h-[2px] w-full;
 }
 
 /* Fancy blur effect */
@@ -20,11 +22,11 @@
 
 /* Remove these to get rid of the spinner */
 #nprogress .spinner {
-  @apply fixed right-4 top-4 z-[1031] block;
+  @apply fixed top-4 right-4 z-1031 block;
 }
 
 #nprogress .spinner-icon {
-  @apply border-t-primary border-l-primary size-4 rounded-full border-[2px] border-solid border-transparent;
+  @apply border-t-primary border-l-primary size-4 rounded-full border-2 border-solid border-transparent;
 
   animation: nprogress-spinner 400ms linear infinite;
 }

packages/@core/base/shared/src/utils/__tests__/resources.test.ts

@@ -1,10 +1,7 @@
-import { beforeEach, describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { loadScript } from '../resources';
 
-const testJsPath =
-  'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.min.js';
-
 describe('loadScript', () => {
   beforeEach(() => {
     // 每个测试前清空 head，保证环境干净
@@ -12,18 +9,14 @@ describe('loadScript', () => {
   });
 
   it('should resolve when the script loads successfully', async () => {
-    const promise = loadScript(testJsPath);
+    // happy-dom v20+ auto-fires 'load' via handleDisabledFileLoadingAsSuccess
+    const promise = loadScript('/test-script.js');
 
-    // 此时脚本元素已被创建并插入
     const script = document.querySelector(
-      `script[src="${testJsPath}"]`,
+      'script[src="/test-script.js"]',
     ) as HTMLScriptElement;
     expect(script).toBeTruthy();
 
-    // 模拟加载成功
-    script.dispatchEvent(new Event('load'));
-
-    // 等待 promise resolve
     await expect(promise).resolves.toBeUndefined();
   });
 
@@ -45,37 +38,42 @@ describe('loadScript', () => {
   });
 
   it('should reject when the script fails to load', async () => {
+    let capturedScript: HTMLScriptElement | null = null;
+
+    // 拦截 append，捕获 script 元素但不插入 DOM，
+    // 防止 happy-dom v20+ 自动触发 load 事件
+    const appendSpy = vi
+      .spyOn(document.head, 'append')
+      .mockImplementation((...nodes) => {
+        for (const node of nodes) {
+          if (node instanceof HTMLScriptElement) {
+            capturedScript = node;
+          }
+        }
+      });
+
     const promise = loadScript('error.js');
 
-    const script = document.querySelector(
-      'script[src="error.js"]',
-    ) as HTMLScriptElement;
-    expect(script).toBeTruthy();
+    appendSpy.mockRestore();
 
-    // 模拟加载失败
-    script.dispatchEvent(new Event('error'));
+    expect(capturedScript).toBeTruthy();
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    capturedScript!.dispatchEvent(new Event('error'));
 
     await expect(promise).rejects.toThrow('Failed to load script: error.js');
   });
 
   it('should handle multiple concurrent calls and only insert one script tag', async () => {
-    const p1 = loadScript(testJsPath);
-    const p2 = loadScript(testJsPath);
-
-    const script = document.querySelector(
-      `script[src="${testJsPath}"]`,
-    ) as HTMLScriptElement;
-    expect(script).toBeTruthy();
-
-    // 触发一次 load，两个 promise 都应该 resolve
-    script.dispatchEvent(new Event('load'));
+    const p1 = loadScript('/test-script.js');
+    const p2 = loadScript('/test-script.js');
 
+    // happy-dom v20+ auto-fires 'load'，两个 promise 都应该 resolve
     await expect(p1).resolves.toBeUndefined();
     await expect(p2).resolves.toBeUndefined();
 
     // 只插入一次
     const scripts = document.head.querySelectorAll(
-      `script[src="${testJsPath}"]`,
+      'script[src="/test-script.js"]',
     );
     expect(scripts).toHaveLength(1);
   });