chore(web): migrate the Storybook family to 10.x (Closes #425)

.github/dependabot.yml

@@ -23,6 +23,26 @@ updates:
       interval: "weekly"
     open-pull-requests-limit: 5
     groups:
+      # THE ONE GROUP THAT INCLUDES MAJORS. Storybook refuses to run unless every
+      # one of its packages sits on the same major, so a per-package PR is
+      # structurally unmergeable: #413 moved `@storybook/react-vite` to 10 and died
+      # on `No matching export ... "Tag"` against core 9, while #414 moved core
+      # only and made bun resolve a NESTED storybook@9 under every `@storybook/*`
+      # package (two cores in one install). Neither could ever go green alone.
+      #
+      # This does NOT contradict the #398 decision below to ungroup majors — that
+      # rationale is "one migration per PR", and the Storybook family IS one
+      # migration whose packages must move in lockstep. Without this group, every
+      # future Storybook major arrives as N individually-unmergeable PRs that a
+      # human has to hand-merge into one branch (see #425).
+      #
+      # Listed FIRST on purpose: Dependabot assigns a dependency to the first
+      # group it matches, so this keeps the family together for minor/patch too
+      # (same lockstep requirement, same failure if it splits).
+      storybook:
+        patterns:
+          - "storybook"
+          - "@storybook/*"
       # Minor/patch only. Majors are deliberately EXCLUDED from the group so each
       # arrives as its own PR: the grouped major PR (#396) bundled ESLint 9→10,
       # TypeScript 5→7, Vitest 3→4, Vite 8 and Storybook 9→10 into one branch and

apps/web/.storybook/main.ts

@@ -22,7 +22,7 @@ const config: StorybookConfig = {
         'storybook/test',
         'storybook/actions',
         'react-dom/client',
-        // @storybook/react-dom-shim (dist/react-18.mjs) is the module Storybook's
+        // @storybook/react-dom-shim (dist/react-18.js) is the module Storybook's
         // React renderer dynamically imports to mount a story. Pre-bundle it for the
         // same reason as react-dom/client: a mid-run re-optimize 404s the in-flight
         // page as `.../sb-vitest/deps/react-18-*.js` (the F3 false-red documented in

apps/web/.storybook/vitest.setup.ts

@@ -14,6 +14,15 @@ MotionGlobalConfig.skipAnimations = true;
 // Apply the preview-level annotations (decorators, parameters) to every story
 // when they run as Vitest tests via the Storybook plugin. Required by the
 // portable-stories API the addon-vitest uses internally.
+//
+// KEEP THIS despite the Storybook 10 nudge. addon-vitest ≥10.3 prints an INFO
+// box saying it now applies preview annotations automatically and this call can
+// be deleted — that is true ONLY for the `storybook` Vitest project, the one
+// carrying the `storybookTest` plugin. The `unit` project (vitest.config.ts)
+// shares this same setup file and has NO Storybook plugin, so deleting the call
+// would silently strip the preview decorators (MotionProvider + the cosmic-dark
+// theme) from every composed-story unit test. When the addon finds this call it
+// skips its own provisioning, so nothing is applied twice.
 const project = setProjectAnnotations([previewAnnotations]);
 
 beforeAll(project.beforeAll);

apps/web/package.json

@@ -40,17 +40,17 @@
     "shiki": "^4.3.0"
   },
   "devDependencies": {
-    "@storybook/addon-a11y": "^9.1.20",
-    "@storybook/addon-vitest": "^9.1.20",
-    "@storybook/react-vite": "^9.1.20",
+    "@storybook/addon-a11y": "^10.5.5",
+    "@storybook/addon-vitest": "^10.5.5",
+    "@storybook/react-vite": "^10.5.5",
     "@tailwindcss/vite": "^4.1.0",
     "@types/react": "^19.2.0",
     "@types/react-dom": "^19.2.0",
     "@vitejs/plugin-react": "^5.0.0",
     "@vitest/browser": "^3.2.7",
     "@vitest/coverage-istanbul": "^3.2.7",
     "playwright": "^1.61.0",
-    "storybook": "^9.1.20",
+    "storybook": "^10.5.5",
     "tailwindcss": "^4.1.0",
     "typescript": "^5.6.0",
     "vite": "^7.0.0",

apps/web/vitest.config.ts

@@ -80,7 +80,7 @@ export default defineConfig({
           include: [
             'react-dom/client',
             // Storybook's React renderer dynamically imports @storybook/react-dom-shim,
-            // whose main entry is dist/react-18.mjs (createRoot path, used for React 18+).
+            // whose main entry is dist/react-18.js (createRoot path, used for React 18+).
             // If Vite discovers it mid-run under the addon-vitest gate, the
             // "optimized dependencies changed" reload 404s the in-flight page as
             // `.../sb-vitest/deps/react-18-*.js` — the confirmed CI false-red (F3 in
@@ -130,7 +130,7 @@ export default defineConfig({
             'react-dom/client',
             // Same F3 guard as the storybook project: the composed-story render
             // path (setProjectAnnotations + vitest-browser-react) pulls in
-            // @storybook/react-dom-shim (dist/react-18.mjs). Pre-bundle it so it is
+            // @storybook/react-dom-shim (dist/react-18.js). Pre-bundle it so it is
             // never re-optimized mid-run. See docs/research/2026-07-11-ci-performance.md.
             '@storybook/react-dom-shim',
             'motion/react',