From 5b95ff07040944baa4988f4faa00cb410d22c6fb Mon Sep 17 00:00:00 2001
From: cylewaitforit <cyle@cylewaitfor.it>
Date: Fri, 10 Apr 2026 16:37:08 -0500
Subject: [PATCH 1/4] docs(ui): add stories for Brand page

---
 .storybook/main.ts         | 112 +++++++++++++++++++++++++++++++------
 app/pages/brand.stories.ts |  16 ++++++
 2 files changed, 110 insertions(+), 18 deletions(-)
 create mode 100644 app/pages/brand.stories.ts

diff --git a/.storybook/main.ts b/.storybook/main.ts
index 31dc739ca8..bd5ece12fd 100644
--- a/.storybook/main.ts
+++ b/.storybook/main.ts
@@ -1,4 +1,6 @@
 import type { StorybookConfig } from '@storybook-vue/nuxt'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
 
 const config = {
   stories: [
@@ -21,29 +23,98 @@ const config = {
   async viteFinal(newConfig) {
     newConfig.plugins ??= []
 
+    // Fix: nuxt:components:imports-alias relies on internal Nuxt state that is
+    // cleaned up after nuxt.close() in @storybook-vue/nuxt's loadNuxtViteConfig.
+    // When that state is gone, `import X from '#components'` is left unresolved
+    // and Vite 8 falls through to package-subpath resolution, which fails with
+    // "Missing '#components' specifier in 'nuxt' package".
+    // This plugin intercepts #components first and serves a virtual module built
+    // from the components.d.ts written during the same Nuxt boot.
+    // Resolve the Nuxt build dir from Vite's alias map, which can be either a
+    // plain-object (Record<string, string>) or Vite's resolved array form
+    // (readonly Alias[] where find is string | RegExp). We must handle both
+    // without casting to Record<string, string>, which would be unsound for the
+    // array form.
+    const aliases = newConfig.resolve?.alias
+    const buildDir = (() => {
+      if (!aliases) return undefined
+      if (Array.isArray(aliases)) {
+        const entry = aliases.find(a => a.find === '#build')
+        return typeof entry?.replacement === 'string' ? entry.replacement : undefined
+      }
+      const value = (aliases as Record<string, unknown>)['#build']
+      return typeof value === 'string' ? value : undefined
+    })()
+    newConfig.plugins.unshift({
+      name: 'storybook-nuxt-components',
+      enforce: 'pre',
+      resolveId(id) {
+        if (id === '#components') return '\0virtual:#components'
+        return null
+      },
+      load(id) {
+        if (id !== '\0virtual:#components') return
+        if (!buildDir) return 'export {}'
+        const dtsPath = resolve(buildDir, 'components.d.ts')
+        // Wire the generated declaration file into Vite's file-watch graph so
+        // that the virtual module is invalidated when Nuxt regenerates it.
+        this.addWatchFile(dtsPath)
+        try {
+          const dts = readFileSync(dtsPath, 'utf-8')
+          const lines: string[] = []
+          // Match only the direct `typeof import("…").default` form.
+          // Lazy/island wrappers (LazyComponent<T>, IslandComponent<T>) are
+          // excluded intentionally — Storybook only needs the concrete type.
+          // The format has been stable across all Nuxt 3 releases; if it ever
+          // changes, the exports array will simply be empty and Storybook will
+          // fall back to direct imports from `~/components`.
+          const re = /^export const (\w+): typeof import\("([^"]+)"\)\.default$/gm
+          let match: RegExpExecArray | null
+          while ((match = re.exec(dts)) !== null) {
+            const [, name, rel] = match
+            if (!name || !rel) continue
+            const abs = resolve(buildDir, rel)
+            lines.push(`export { default as ${name} } from ${JSON.stringify(abs)}`)
+          }
+          return lines.join('\n') || 'export {}'
+        } catch (err) {
+          // oxlint-disable-next-line no-console -- Log and swallow errors to avoid breaking the Storybook build when components.d.ts is missing or malformed.
+          console.warn(
+            '[storybook-nuxt-components] Failed to build #components virtual module:',
+            err,
+          )
+          return 'export {}'
+        }
+      },
+    })
+
     // Bridge compatibility between Storybook v10 core and v9 @storybook-vue/nuxt
     // v10 expects module federation globals that v9 doesn't provide
     newConfig.plugins.push({
       name: 'storybook-v10-compat',
       transformIndexHtml: {
         order: 'pre',
-        handler(html) {
-          const script = `
-<script>
-  // Minimal shims for Storybook v10 module federation system
-  // These will be replaced when Storybook runtime loads
-  window.__STORYBOOK_MODULE_GLOBAL__ = { global: window };
-  window.__STORYBOOK_MODULE_CLIENT_LOGGER__ = {
-    deprecate: console.warn.bind(console, '[deprecated]'),
-    once: console.log.bind(console),
-    logger: console
-  };
-  window.__STORYBOOK_MODULE_CHANNELS__ = {
-    Channel: class { on() {} off() {} emit() {} once() {} },
-    createBrowserChannel: () => new window.__STORYBOOK_MODULE_CHANNELS__.Channel()
-  };
-</script>`
-          return html.replace(/<script>/, script + '<script>')
+        handler() {
+          return [
+            {
+              tag: 'script',
+              injectTo: 'head-prepend' as const,
+              children: [
+                '// Minimal shims for Storybook v10 module federation system',
+                '// These will be replaced when Storybook runtime loads',
+                'window.__STORYBOOK_MODULE_GLOBAL__ = { global: window };',
+                'window.__STORYBOOK_MODULE_CLIENT_LOGGER__ = {',
+                "  deprecate: console.warn.bind(console, '[deprecated]'),",
+                '  once: console.log.bind(console),',
+                '  logger: console',
+                '};',
+                'window.__STORYBOOK_MODULE_CHANNELS__ = {',
+                '  Channel: class { on() {} off() {} emit() {} once() {} },',
+                '  createBrowserChannel: () => new window.__STORYBOOK_MODULE_CHANNELS__.Channel()',
+                '};',
+              ].join('\n'),
+            },
+          ]
         },
       },
     })
@@ -73,7 +144,12 @@ const config = {
         const wrapped = async function (this: unknown, ...args: unknown[]) {
           try {
             return await originalFn.apply(this, args)
-          } catch {
+          } catch (err) {
+            // oxlint-disable-next-line no-console -- Log and swallow errors to avoid breaking the Storybook build when vue-docgen-api encounters an unparseable component.
+            console.warn(
+              '[storybook:vue-docgen-plugin] Suppressed docgen error (component docs may be missing):',
+              err,
+            )
             return undefined
           }
         }
diff --git a/app/pages/brand.stories.ts b/app/pages/brand.stories.ts
new file mode 100644
index 0000000000..3eeef66c4d
--- /dev/null
+++ b/app/pages/brand.stories.ts
@@ -0,0 +1,16 @@
+import Brand from './brand.vue'
+import type { Meta, StoryObj } from '@storybook-vue/nuxt'
+import { pageDecorator } from '../../.storybook/decorators'
+
+const meta = {
+  component: Brand,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  decorators: [pageDecorator],
+} satisfies Meta<typeof Brand>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {}

From 11651c85b9eb2cb6cdf1e4fda1238c3b6143a2b2 Mon Sep 17 00:00:00 2001
From: cylewaitforit <cyle@cylewaitfor.it>
Date: Fri, 10 Apr 2026 17:07:00 -0500
Subject: [PATCH 2/4] fix: normalize path

---
 .storybook/main.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.storybook/main.ts b/.storybook/main.ts
index bd5ece12fd..9e078e3467 100644
--- a/.storybook/main.ts
+++ b/.storybook/main.ts
@@ -73,7 +73,7 @@ const config = {
           while ((match = re.exec(dts)) !== null) {
             const [, name, rel] = match
             if (!name || !rel) continue
-            const abs = resolve(buildDir, rel)
+            const abs = resolve(buildDir, rel).replaceAll('\\', '/')
             lines.push(`export { default as ${name} } from ${JSON.stringify(abs)}`)
           }
           return lines.join('\n') || 'export {}'

From 8df8629a02f17424066f1e7826ea0a0954e15536 Mon Sep 17 00:00:00 2001
From: cylewaitforit <cyle@cylewaitfor.it>
Date: Fri, 10 Apr 2026 17:32:03 -0500
Subject: [PATCH 3/4] fix: throw if no #build

---
 .storybook/main.ts | 46 +++++++++++++++++++++-------------------------
 1 file changed, 21 insertions(+), 25 deletions(-)

diff --git a/.storybook/main.ts b/.storybook/main.ts
index 9e078e3467..fb45644c9c 100644
--- a/.storybook/main.ts
+++ b/.storybook/main.ts
@@ -54,37 +54,33 @@ const config = {
       },
       load(id) {
         if (id !== '\0virtual:#components') return
-        if (!buildDir) return 'export {}'
+        if (!buildDir) {
+          throw new Error('[storybook-nuxt-components] Could not resolve the `#build` alias.')
+        }
         const dtsPath = resolve(buildDir, 'components.d.ts')
         // Wire the generated declaration file into Vite's file-watch graph so
         // that the virtual module is invalidated when Nuxt regenerates it.
         this.addWatchFile(dtsPath)
-        try {
-          const dts = readFileSync(dtsPath, 'utf-8')
-          const lines: string[] = []
-          // Match only the direct `typeof import("…").default` form.
-          // Lazy/island wrappers (LazyComponent<T>, IslandComponent<T>) are
-          // excluded intentionally — Storybook only needs the concrete type.
-          // The format has been stable across all Nuxt 3 releases; if it ever
-          // changes, the exports array will simply be empty and Storybook will
-          // fall back to direct imports from `~/components`.
-          const re = /^export const (\w+): typeof import\("([^"]+)"\)\.default$/gm
-          let match: RegExpExecArray | null
-          while ((match = re.exec(dts)) !== null) {
-            const [, name, rel] = match
-            if (!name || !rel) continue
-            const abs = resolve(buildDir, rel).replaceAll('\\', '/')
-            lines.push(`export { default as ${name} } from ${JSON.stringify(abs)}`)
-          }
-          return lines.join('\n') || 'export {}'
-        } catch (err) {
-          // oxlint-disable-next-line no-console -- Log and swallow errors to avoid breaking the Storybook build when components.d.ts is missing or malformed.
-          console.warn(
-            '[storybook-nuxt-components] Failed to build #components virtual module:',
-            err,
+        const dts = readFileSync(dtsPath, 'utf-8')
+        const lines: string[] = []
+        // Match only the direct `typeof import("…").default` form.
+        // Lazy/island wrappers (LazyComponent<T>, IslandComponent<T>) are
+        // excluded intentionally — Storybook only needs the concrete type.
+        // The format has been stable across all Nuxt 3 releases.
+        const re = /^export const (\w+): typeof import\("([^"]+)"\)\.default$/gm
+        let match: RegExpExecArray | null
+        while ((match = re.exec(dts)) !== null) {
+          const [, name, rel] = match
+          if (!name || !rel) continue
+          const abs = resolve(buildDir, rel).replaceAll('\\', '/')
+          lines.push(`export { default as ${name} } from ${JSON.stringify(abs)}`)
+        }
+        if (lines.length === 0) {
+          throw new Error(
+            `[storybook-nuxt-components] No component exports were found in ${dtsPath}.`,
           )
-          return 'export {}'
         }
+        return lines.join('\n')
       },
     })
 

From 0979d00ac959d798fe2339509c86725cd8d2b1c2 Mon Sep 17 00:00:00 2001
From: cylewaitforit <cyle@cylewaitfor.it>
Date: Fri, 10 Apr 2026 17:45:12 -0500
Subject: [PATCH 4/4] Update .storybook/main.ts

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
---
 .storybook/main.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.storybook/main.ts b/.storybook/main.ts
index fb45644c9c..8e14495eb5 100644
--- a/.storybook/main.ts
+++ b/.storybook/main.ts
@@ -67,7 +67,8 @@ const config = {
         // Lazy/island wrappers (LazyComponent<T>, IslandComponent<T>) are
         // excluded intentionally — Storybook only needs the concrete type.
         // The format has been stable across all Nuxt 3 releases.
-        const re = /^export const (\w+): typeof import\("([^"]+)"\)\.default$/gm
+        const re =
+          /^export const (\w+): typeof import\("([^"]+)"\)(?:\.default|\[['"]default['"]\])\s*;?$/gm
         let match: RegExpExecArray | null
         while ((match = re.exec(dts)) !== null) {
           const [, name, rel] = match