@emulsify/core 4.1.0 → 4.1.1

package/.storybook/css-components.js

@@ -6,7 +6,10 @@
  * dist/components so the mirrored component CSS is not loaded twice.
  */
 
+// Load mirrored component output first so Drupal adapter stories match theme roots.
 import.meta.glob('../../../../components/**/*.css', { eager: true });
+
+// Keep shared dist CSS while avoiding duplicate generated component CSS.
 import.meta.glob(
   ['../../../../dist/**/*.css', '!../../../../dist/components/**/*.css'],
   { eager: true },

package/.storybook/css-dist.js

@@ -2,4 +2,5 @@
  * @file Storybook compiled dist CSS side-effect loader.
  */
 
+// Import matching CSS for Vite side effects so CSS HMR stays on the native path.
 import.meta.glob('../../../../dist/**/*.css', { eager: true });

package/.storybook/main-static-assets.js

@@ -0,0 +1,217 @@
+import fs from 'fs';
+import path from 'path';
+
+const projectRoot = process.cwd();
+
+/**
+ * Keeps Storybook static directory config aligned to the consuming project.
+ *
+ * @param {Array<string|{from: string, to: string}>} staticDirs - Static directory entries.
+ * @returns {Array<string|{from: string, to: string}>} Existing static directory entries.
+ */
+function existingStaticDirs(staticDirs) {
+  const seen = new Set();
+  const existing = [];
+
+  for (const staticDir of staticDirs) {
+    const directory =
+      typeof staticDir === 'string' ? staticDir : staticDir.from;
+
+    if (!directory || !fs.existsSync(directory)) continue;
+
+    const key =
+      typeof staticDir === 'string'
+        ? staticDir
+        : `${staticDir.from || ''}\0${staticDir.to || ''}`;
+    if (seen.has(key)) continue;
+
+    seen.add(key);
+    existing.push(staticDir);
+  }
+
+  return existing;
+}
+
+/**
+ * Build static directory mounts for normalized project asset roots.
+ *
+ * @param {object} env - Resolved project paths used by Storybook.
+ * @returns {Array<string|{from: string, to: string}>} Static directory entries.
+ */
+export function buildAssetStaticDirs(env) {
+  const configuredAssetRoots = Array.isArray(env.projectStructure?.assetRoots)
+    ? env.projectStructure.assetRoots
+    : [];
+  const assetRoots = [
+    ...configuredAssetRoots,
+    path.resolve(projectRoot, 'assets'),
+    path.resolve(projectRoot, 'src/assets'),
+  ];
+
+  return existingStaticDirs([
+    ...assetRoots.map((root) => ({
+      from: root,
+      to: '/assets',
+    })),
+    {
+      from: path.resolve(projectRoot, 'dist/assets'),
+      to: '/assets',
+    },
+    {
+      from: path.resolve(projectRoot, 'dist/assets'),
+      to: '/',
+    },
+  ]);
+}
+
+/**
+ * Checks whether a resolved file path stays inside an expected directory.
+ *
+ * @param {string} filePath - Resolved candidate file path.
+ * @param {string} directory - Resolved directory that must contain the file.
+ * @returns {boolean} Whether the file path is inside the directory.
+ */
+function isWithinDirectory(filePath, directory) {
+  // `path.relative()` exposes traversal attempts as `..` or absolute paths.
+  const relativePath = path.relative(directory, filePath);
+  return Boolean(
+    relativePath &&
+    !relativePath.startsWith('..') &&
+    !path.isAbsolute(relativePath),
+  );
+}
+
+/**
+ * Returns a browser content type for generated files served by Storybook.
+ *
+ * @param {string} filePath - Resolved file path being served.
+ * @returns {string} HTTP content type header value.
+ */
+function contentTypeForFile(filePath) {
+  const extension = path.extname(filePath).toLowerCase();
+  // Keep this map small; unknown generated files can still download as binary.
+  const types = {
+    '.css': 'text/css; charset=utf-8',
+    '.gif': 'image/gif',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.js': 'text/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml; charset=utf-8',
+    '.webp': 'image/webp',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+  };
+
+  return types[extension] || 'application/octet-stream';
+}
+
+/**
+ * Serves generated dist files that may not exist when `staticDirs` is built.
+ *
+ * Storybook validates static directories during config load, but Emulsify
+ * projects often generate `dist` after Storybook starts. This middleware keeps
+ * those generated asset URLs available without replacing Vite's CSS HMR.
+ *
+ * @param {import('http').IncomingMessage} req - Vite dev server request.
+ * @param {import('http').ServerResponse} res - Vite dev server response.
+ * @param {Function} next - Next middleware callback.
+ * @returns {void}
+ */
+function serveGeneratedDistFile(req, res, next) {
+  const method = req.method || 'GET';
+  if (method !== 'GET' && method !== 'HEAD') {
+    next();
+    return;
+  }
+
+  let pathname = '';
+  try {
+    // Malformed URLs should fall through to Storybook's normal Vite server.
+    pathname = decodeURIComponent(
+      new URL(req.url || '/', 'http://localhost').pathname,
+    );
+  } catch {
+    next();
+    return;
+  }
+
+  // These URL shapes match Emulsify's compiled CSS and sprite references.
+  const routes = [
+    {
+      pathname: '/icons.svg',
+      file: path.resolve(projectRoot, 'dist/assets/icons.svg'),
+    },
+    {
+      prefix: '/assets/',
+      directory: path.resolve(projectRoot, 'dist/assets'),
+    },
+    {
+      prefix: '/dist/',
+      directory: path.resolve(projectRoot, 'dist'),
+    },
+  ];
+  const route = routes.find(({ prefix, pathname: routePathname }) =>
+    routePathname ? pathname === routePathname : pathname.startsWith(prefix),
+  );
+  if (!route) {
+    next();
+    return;
+  }
+
+  const filePath = route.file
+    ? route.file
+    : path.resolve(route.directory, pathname.slice(route.prefix.length));
+  // Resolve from known roots only, then reject traversal before reading.
+  if (route.directory && !isWithinDirectory(filePath, route.directory)) {
+    next();
+    return;
+  }
+
+  try {
+    const stats = fs.statSync(filePath);
+    if (!stats.isFile()) {
+      next();
+      return;
+    }
+    if (path.extname(filePath).toLowerCase() === '.css') {
+      next();
+      return;
+    }
+
+    res.statusCode = 200;
+    res.setHeader('Content-Type', contentTypeForFile(filePath));
+    res.setHeader('Content-Length', stats.size);
+    if (method === 'HEAD') {
+      res.end();
+      return;
+    }
+    res.end(fs.readFileSync(filePath));
+  } catch {
+    next();
+  }
+}
+
+/**
+ * Adds Vite dev-server access to generated dist files.
+ *
+ * CSS itself is still imported through native `import.meta.glob()` calls in the
+ * preview runtime; this plugin only fills the static-file gap for late-created
+ * dist assets.
+ *
+ * @returns {import('vite').Plugin} Vite middleware plugin.
+ */
+export function makeGeneratedDistFilesPlugin() {
+  return {
+    name: 'emulsify-generated-dist-files',
+    configureServer(server) {
+      server.middlewares.use(serveGeneratedDistFile);
+      // Watch generated assets so Vite notices files created after startup.
+      server.watcher.add([
+        path.join(projectRoot, 'dist/**/*.css'),
+        path.join(projectRoot, 'dist/assets/**/*'),
+      ]);
+    },
+  };
+}

package/.storybook/main-vite.js

@@ -0,0 +1,224 @@
+import path from 'path';
+import viteConfig from '../config/vite/vite.config.js';
+import { twigExtensionModuleSpecifiers } from '../config/vite/twig-extensions.js';
+import {
+  mergeReactSingletonOptimizeDeps,
+  mergeReactSingletonResolve,
+} from '../config/vite/utils/react-singleton.js';
+import { makeGeneratedDistFilesPlugin } from './main-static-assets.js';
+
+// Twig glob maps are provided by config/vite/plugins/virtual-twig-globs.js.
+const twigVirtualModuleIds = [
+  'virtual:emulsify-twig-globs',
+  'virtual:emulsify-twig-asset-sources',
+  'virtual:emulsify-twig-extension-installers',
+];
+
+const twigRuntimeOptimizeDepsExclude = [
+  ...twigVirtualModuleIds,
+  '@emulsify/core/storybook/twig/source-function',
+  '@emulsify/core/storybook/twig/source',
+  '@emulsify/core/storybook/twig/resolver',
+];
+
+/**
+ * Vite-generated Storybook chunks should not share `/assets` with project
+ * static files. Storybook copies staticDirs while the preview build runs, so
+ * keeping generated chunks in a separate folder avoids concurrent writers in
+ * `.out/assets`.
+ *
+ * @type {string}
+ */
+const storybookViteAssetsDir = 'storybook-assets';
+
+/**
+ * Merge Storybook and project optimizeDeps excludes with Core Twig runtime IDs.
+ *
+ * Storybook's dependency optimizer runs before normal Vite virtual module
+ * resolution. Core Twig runtime modules import virtual IDs that must stay in
+ * the Vite module graph so Emulsify's virtual plugins can resolve them.
+ *
+ * @param {...string[]} excludeLists - Existing optimizeDeps exclude arrays.
+ * @returns {string[]} Merged exclude list.
+ */
+function mergeTwigRuntimeOptimizeDepsExcludes(...excludeLists) {
+  return Array.from(
+    new Set([
+      ...excludeLists.flatMap((excludeList) =>
+        Array.isArray(excludeList) ? excludeList : [],
+      ),
+      ...twigRuntimeOptimizeDepsExclude,
+    ]),
+  );
+}
+
+/**
+ * Keep Emulsify Twig virtual imports out of Storybook dependency prebundles.
+ *
+ * @returns {import('esbuild').Plugin} Esbuild plugin for optimizeDeps.
+ */
+function makeTwigVirtualModuleOptimizerPlugin() {
+  return {
+    name: 'emulsify-twig-virtual-modules',
+    setup(build) {
+      build.onResolve(
+        { filter: /^virtual:emulsify-twig-(?:globs|asset-sources)$/ },
+        (args) => ({
+          path: args.path,
+          external: true,
+        }),
+      );
+    },
+  };
+}
+
+/**
+ * Builds the Storybook Vite config merger.
+ *
+ * @param {object} resolvedStorybookEnv - Resolved project paths used by Storybook.
+ * @returns {Function} Storybook `viteFinal` callback.
+ */
+export function createViteFinal(resolvedStorybookEnv) {
+  return async function viteFinal(config) {
+    const { mergeConfig } = await import('vite');
+    const env = resolvedStorybookEnv;
+    const storybookBuildConfig = config?.build || {};
+
+    // Keep using the `serve` branch of the shared Vite config here. Storybook
+    // has historically consumed that branch, while `mode` still reflects
+    // whether Storybook is running in development or production.
+    const mode = config?.mode || 'development';
+    const baseViteConfig =
+      typeof viteConfig === 'function'
+        ? await viteConfig({ command: 'serve', mode })
+        : viteConfig;
+    const existingDefine = (config && config.define) || {};
+    const viteDefine = (baseViteConfig && baseViteConfig.define) || {};
+
+    // Allow Storybook's dev server to read component sources from the project
+    // root and any structure override paths used by Emulsify consumers.
+    const allowList = new Set([
+      ...(config?.server?.fs?.allow || []),
+      env.projectDir,
+      path.resolve(env.projectDir, 'src'),
+      path.resolve(env.projectDir, 'components'),
+      path.resolve(env.projectDir, 'dist'),
+      ...(Array.isArray(env.projectStructure?.sourceRoots)
+        ? env.projectStructure.sourceRoots
+        : []),
+      ...(Array.isArray(env.componentRoots) ? env.componentRoots : []),
+      ...(Array.isArray(env.structureRoots) ? env.structureRoots : []),
+      ...(env.namespaceRoots && typeof env.namespaceRoots === 'object'
+        ? Object.values(env.namespaceRoots)
+        : []),
+      ...(Array.isArray(env.projectStructure?.assetRoots)
+        ? env.projectStructure.assetRoots
+        : []),
+    ]);
+
+    // Twig files are loaded through custom resolvers/plugins, so they need to
+    // be treated as importable assets by Storybook's Vite pipeline.
+    const assetsInclude = Array.from(
+      new Set([
+        ...(config.assetsInclude || []),
+        ...(baseViteConfig.assetsInclude || []),
+        '**/*.twig',
+      ]),
+    );
+    const optimizeDepsInclude = mergeReactSingletonOptimizeDeps(
+      baseViteConfig?.optimizeDeps?.include,
+      config?.optimizeDeps?.include,
+      [
+        'twig',
+        '@emulsify/core/extensions/twig',
+        ...twigExtensionModuleSpecifiers(env),
+      ],
+    );
+
+    const mergedConfig = mergeConfig(config, {
+      ...baseViteConfig,
+      resolve: mergeReactSingletonResolve(baseViteConfig, config),
+      define: {
+        // Preserve shared and Storybook-provided constants, then publish the
+        // resolved Emulsify environment to client-side code.
+        ...viteDefine,
+        ...existingDefine,
+        __EMULSIFY_ENV__: JSON.stringify(env),
+        'globalThis.__EMULSIFY_ENV__': JSON.stringify(env),
+      },
+      server: {
+        ...(baseViteConfig?.server || {}),
+        fs: {
+          allow: Array.from(allowList),
+        },
+      },
+      assetsInclude,
+      plugins: [
+        ...(baseViteConfig?.plugins || []),
+        makeGeneratedDistFilesPlugin(),
+      ],
+      esbuild: {
+        // Some downstream code is authored as `.js` files containing JSX, so
+        // keep Storybook's esbuild settings aligned with the shared Vite config.
+        jsx: 'automatic',
+        loader: 'jsx',
+        include: /.*\.jsx?$/,
+        exclude: [],
+      },
+      optimizeDeps: {
+        ...(baseViteConfig?.optimizeDeps || {}),
+        ...(config?.optimizeDeps || {}),
+        include: optimizeDepsInclude,
+        exclude: mergeTwigRuntimeOptimizeDepsExcludes(
+          baseViteConfig?.optimizeDeps?.exclude,
+          config?.optimizeDeps?.exclude,
+        ),
+        esbuildOptions: {
+          ...(baseViteConfig?.optimizeDeps?.esbuildOptions || {}),
+          ...(config?.optimizeDeps?.esbuildOptions || {}),
+          plugins: [
+            ...(baseViteConfig?.optimizeDeps?.esbuildOptions?.plugins || []),
+            ...(config?.optimizeDeps?.esbuildOptions?.plugins || []),
+            makeTwigVirtualModuleOptimizerPlugin(),
+          ],
+          loader: {
+            ...(baseViteConfig?.optimizeDeps?.esbuildOptions?.loader || {}),
+            ...(config?.optimizeDeps?.esbuildOptions?.loader || {}),
+            // Pre-bundle `.js` dependencies with the JSX loader for packages
+            // that ship JSX without a `.jsx` extension.
+            '.js': 'jsx',
+          },
+        },
+      },
+    });
+
+    return {
+      ...mergedConfig,
+      build: {
+        ...(mergedConfig.build || {}),
+        ...(storybookBuildConfig.outDir
+          ? { outDir: storybookBuildConfig.outDir }
+          : {}),
+        assetsDir: storybookViteAssetsDir,
+        emptyOutDir: false,
+      },
+      resolve: mergeReactSingletonResolve(mergedConfig),
+      optimizeDeps: {
+        ...(mergedConfig.optimizeDeps || {}),
+        include: mergeReactSingletonOptimizeDeps(
+          mergedConfig.optimizeDeps?.include,
+        ),
+        exclude: mergeTwigRuntimeOptimizeDepsExcludes(
+          mergedConfig.optimizeDeps?.exclude,
+        ),
+        esbuildOptions: {
+          ...(mergedConfig.optimizeDeps?.esbuildOptions || {}),
+          loader: {
+            ...(mergedConfig.optimizeDeps?.esbuildOptions?.loader || {}),
+            '.js': 'jsx',
+          },
+        },
+      },
+    };
+  };
+}

package/.storybook/main.js

@@ -14,32 +14,13 @@
 import fs from 'fs';
 import path, { resolve } from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
-import viteConfig from '../config/vite/vite.config.js';
 import { resolveEnvironment } from '../config/vite/environment.js';
-import {
-  mergeReactSingletonOptimizeDeps,
-  mergeReactSingletonResolve,
-} from '../config/vite/utils/react-singleton.js';
-import { twigExtensionModuleSpecifiers } from '../config/vite/twig-extensions.js';
 import {
   applyStorybookConfigOverrides,
   normalizeStorybookConfigOverrideModule,
 } from '../src/storybook/main-config.js';
-
-// Twig glob maps are provided by config/vite/plugins/virtual-twig-globs.js.
-
-const twigVirtualModuleIds = [
-  'virtual:emulsify-twig-globs',
-  'virtual:emulsify-twig-asset-sources',
-  'virtual:emulsify-twig-extension-installers',
-];
-
-const twigRuntimeOptimizeDepsExclude = [
-  ...twigVirtualModuleIds,
-  '@emulsify/core/storybook/twig/source-function',
-  '@emulsify/core/storybook/twig/source',
-  '@emulsify/core/storybook/twig/resolver',
-];
+import { buildAssetStaticDirs } from './main-static-assets.js';
+import { createViteFinal } from './main-vite.js';
 
 /**
  * Minimal subset of the resolved Emulsify environment used by this file.
@@ -70,27 +51,6 @@ const _filename = fileURLToPath(import.meta.url);
  */
 const _dirname = path.dirname(_filename);
 
-/**
- * The consuming project root for Storybook static mounts.
- *
- * Storybook loads this package config from different physical locations
- * depending on whether Core is linked locally or installed in node_modules, so
- * static paths must be rooted at the process cwd rather than this file.
- *
- * @type {string}
- */
-const projectRoot = process.cwd();
-
-/**
- * Vite-generated Storybook chunks should not share `/assets` with project
- * static files. Storybook copies staticDirs while the preview build runs, so
- * keeping generated chunks in a separate folder avoids concurrent writers in
- * `.out/assets`.
- *
- * @type {string}
- */
-const storybookViteAssetsDir = 'storybook-assets';
-
 /**
  * Reads an optional HTML fragment relative to this config file.
  *
@@ -110,111 +70,6 @@ function readOptionalHtmlFragment(relativePath) {
   return fs.readFileSync(fragmentPath, 'utf8');
 }
 
-/**
- * Keeps Storybook static directory config aligned to the consuming project.
- *
- * Storybook errors when a declared static directory is absent, so only expose
- * project asset directories that exist in the current workspace.
- *
- * @param {Array<string|{from: string, to: string}>} staticDirs - Static directory entries.
- * @returns {Array<string|{from: string, to: string}>} Existing static directory entries.
- */
-function existingStaticDirs(staticDirs) {
-  const seen = new Set();
-  const existing = [];
-
-  for (const staticDir of staticDirs) {
-    const directory =
-      typeof staticDir === 'string' ? staticDir : staticDir.from;
-
-    if (!directory || !fs.existsSync(directory)) continue;
-
-    const key =
-      typeof staticDir === 'string'
-        ? staticDir
-        : `${staticDir.from || ''}\0${staticDir.to || ''}`;
-    if (seen.has(key)) continue;
-
-    seen.add(key);
-    existing.push(staticDir);
-  }
-
-  return existing;
-}
-
-/**
- * Build static directory mounts for normalized project asset roots.
- *
- * @param {StorybookEnvironment} env - Resolved project paths used by Storybook.
- * @returns {Array<string|{from: string, to: string}>} Static directory entries.
- */
-function buildAssetStaticDirs(env) {
-  const configuredAssetRoots = Array.isArray(env.projectStructure?.assetRoots)
-    ? env.projectStructure.assetRoots
-    : [];
-  const assetRoots = [
-    ...configuredAssetRoots,
-    path.resolve(projectRoot, 'assets'),
-    path.resolve(projectRoot, 'src/assets'),
-  ];
-
-  return existingStaticDirs([
-    ...assetRoots.map((root) => ({
-      from: root,
-      to: '/assets',
-    })),
-    {
-      from: path.resolve(projectRoot, 'dist/assets'),
-      to: '/assets',
-    },
-    {
-      from: path.resolve(projectRoot, 'dist'),
-      to: '/dist',
-    },
-  ]);
-}
-
-/**
- * Merge Storybook and project optimizeDeps excludes with Core Twig runtime IDs.
- *
- * Storybook's dependency optimizer runs before normal Vite virtual module
- * resolution. Core Twig runtime modules import virtual IDs that must stay in
- * the Vite module graph so Emulsify's virtual plugins can resolve them.
- *
- * @param {...string[]} excludeLists - Existing optimizeDeps exclude arrays.
- * @returns {string[]} Merged exclude list.
- */
-function mergeTwigRuntimeOptimizeDepsExcludes(...excludeLists) {
-  return Array.from(
-    new Set([
-      ...excludeLists.flatMap((excludeList) =>
-        Array.isArray(excludeList) ? excludeList : [],
-      ),
-      ...twigRuntimeOptimizeDepsExclude,
-    ]),
-  );
-}
-
-/**
- * Keep Emulsify Twig virtual imports out of Storybook dependency prebundles.
- *
- * @returns {import('esbuild').Plugin} Esbuild plugin for optimizeDeps.
- */
-function makeTwigVirtualModuleOptimizerPlugin() {
-  return {
-    name: 'emulsify-twig-virtual-modules',
-    setup(build) {
-      build.onResolve(
-        { filter: /^virtual:emulsify-twig-(?:globs|asset-sources)$/ },
-        (args) => ({
-          path: args.path,
-          external: true,
-        }),
-      );
-    },
-  };
-}
-
 /**
  * Reads optional project-level Storybook overrides.
  *
@@ -367,109 +222,12 @@ const baseConfig = {
    * @returns {string} Manager head markup with Emulsify additions appended.
    */
   managerHead: (head) => {
-    // Keep the manager styling inline so consumers inherit the branded UI
-    // without having to maintain a separate manager-only stylesheet.
-    const inlineStyles = `
-      <style>
-      :root {
-        --colors-emulsify-blue-100: #e6f5fc;
-        --colors-emulsify-blue-200: #CCECFA;
-        --colors-emulsify-blue-300: #99D9F4;
-        --colors-emulsify-blue-400: #66c5ef;
-        --colors-emulsify-blue-500: #33b2e9;
-        --colors-emulsify-blue-600: #009fe4;
-        --colors-emulsify-blue-700: #007FB6;
-        --colors-emulsify-blue-800: #005f89;
-        --colors-emulsify-blue-900: #00405b;
-        --colors-emulsify-blue-1000: #00202e;
-        --colors-purple: #8B1E7E;
-      }
-      .sidebar-container {
-        background-color: var(--colors-emulsify-blue-900);
-      }
-      .sidebar-container .sidebar-subheading {
-        color: var(--colors-emulsify-blue-200);
-        font-size: 13px;
-        letter-spacing: 0.15em;
-      }
-      .sidebar-container .sidebar-subheading button:focus {
-        color: var(--colors-emulsify-blue-300);
-      }
-      /* Triangle icon. */
-      .sidebar-container .sidebar-subheading button span {
-        color: var(--colors-emulsify-blue-300);
-      }
-      .sidebar-container .search-field input {
-        border-color: var(--colors-emulsify-blue-700);
-      }
-      .sidebar-container .search-field input:active {
-        border-color: var(--colors-emulsify-blue-700);
-      }
-      .sidebar-container .search-result-recentlyOpened,
-      .sidebar-container .search-result-back,
-      .sidebar-container .search-result-clearHistory {
-        color: var(--colors-emulsify-blue-300) !important;
-        letter-spacing: 0.15em;
-      }
-      .sidebar-container .search-result-back span,
-      .sidebar-container .search-result-back svg,
-      .sidebar-container .search-result-clearHistory span,
-      .sidebar-container .search-result-clearHistory svg {
-        letter-spacing: normal;
-        color: white;
-      }
-      .sidebar-container .sidebar-item svg {
-        margin-top: 1px;
-      }
-      .sidebar-container .sidebar-item span {
-        margin-top: 4px;
-      }
-      .sidebar-container .sidebar-subheading-action svg {
-        color: var(--colors-emulsify-blue-400);
-      }
-      .sidebar-container .sidebar-subheading-action:hover svg {
-        color: var(--colors-emulsify-blue-300);
-      }
-      .sidebar-header button[title="Shortcuts"] {
-        box-shadow: none;
-        border: 1px solid var(--colors-emulsify-blue-700);
-      }
-      .sidebar-header button[title="Shortcuts"]:active {
-        border: 1px solid var(--colors-emulsify-blue-500);
-      }
-      .sidebar-header button[title="Shortcuts"]:focus {
-        background: transparent;
-      }
-      #shortcuts {
-        border-bottom-color: var(--colors-emulsify-blue-900) !important;
-      }
-      [role="main"]:not(:nth-child(3)) {
-        top: 1rem !important;
-        height: calc(100vh - 2rem) !important;
-      }
-      [role="main"] .os-host .os-content button:hover {
-        background: var(--colors-emulsify-blue-100);
-      }
-      [role="main"] .os-host .os-content button:hover svg {
-        color: var(--colors-emulsify-blue-900);
-      }
-      #panel-tab-content,
-      #panel-tab-content>* {
-        color: var(--colors-emulsify-blue-100) !important;
-      }
-      #panel-tab-content a,
-      #panel-tab-content a span,
-      #panel-tab-content a span svg {
-        color: var(--colors-emulsify-blue-800);
-      }
-      #panel-tab-content>div>div>div>div>div>div {
-        background: transparent;
-      }
-      #panel-tab-content>div>div>div>div>div>div>div {
-        color: var(--colors-emulsify-blue-1000) !important;
-      }
-    </style>
-    `;
+    const managerStyles = readOptionalHtmlFragment('./manager-head.css');
+    const inlineStyles = managerStyles
+      ? `<style>
+${managerStyles}
+</style>`
+      : '';
     const externalManagerHtml = readOptionalHtmlFragment(
       '../../../../config/emulsify-core/storybook/manager-head.html',
     );
@@ -497,156 +255,7 @@ const baseConfig = {
       ${externalHtml}`;
   },
 
-  /**
-   * Merges Storybook's generated Vite config with Emulsify's shared Vite config.
-   *
-   * Storybook supplies a baseline config, but Emulsify still needs to expose
-   * the resolved environment, expand filesystem access, and expose the Twig
-   * virtual glob module used by the runtime resolver.
-   *
-   * @param {import('vite').UserConfig} config - Storybook's generated Vite config.
-   * @returns {Promise<import('vite').UserConfig>} Final Vite config used by Storybook.
-   */
-  async viteFinal(config) {
-    const { mergeConfig } = await import('vite');
-    /** @type {StorybookEnvironment} */
-    const env = resolvedStorybookEnv;
-    const storybookBuildConfig = config?.build || {};
-
-    // Keep using the `serve` branch of the shared Vite config here. Storybook
-    // has historically consumed that branch, while `mode` still reflects
-    // whether Storybook is running in development or production.
-    const mode = config?.mode || 'development';
-    const baseViteConfig =
-      typeof viteConfig === 'function'
-        ? await viteConfig({ command: 'serve', mode })
-        : viteConfig;
-    const existingDefine = (config && config.define) || {};
-    const viteDefine = (baseViteConfig && baseViteConfig.define) || {};
-
-    // Allow Storybook's dev server to read component sources from the project
-    // root and any structure override paths used by Emulsify consumers.
-    const allowList = new Set([
-      ...(config?.server?.fs?.allow || []),
-      env.projectDir,
-      path.resolve(env.projectDir, 'src'),
-      path.resolve(env.projectDir, 'components'),
-      path.resolve(env.projectDir, 'dist'),
-      ...(Array.isArray(env.projectStructure?.sourceRoots)
-        ? env.projectStructure.sourceRoots
-        : []),
-      ...(Array.isArray(env.componentRoots) ? env.componentRoots : []),
-      ...(Array.isArray(env.structureRoots) ? env.structureRoots : []),
-      ...(env.namespaceRoots && typeof env.namespaceRoots === 'object'
-        ? Object.values(env.namespaceRoots)
-        : []),
-      ...(Array.isArray(env.projectStructure?.assetRoots)
-        ? env.projectStructure.assetRoots
-        : []),
-    ]);
-
-    // Twig files are loaded through custom resolvers/plugins, so they need to
-    // be treated as importable assets by Storybook's Vite pipeline.
-    const assetsInclude = Array.from(
-      new Set([
-        ...(config.assetsInclude || []),
-        ...(baseViteConfig.assetsInclude || []),
-        '**/*.twig',
-      ]),
-    );
-    const optimizeDepsInclude = mergeReactSingletonOptimizeDeps(
-      baseViteConfig?.optimizeDeps?.include,
-      config?.optimizeDeps?.include,
-      [
-        'twig',
-        '@emulsify/core/extensions/twig',
-        ...twigExtensionModuleSpecifiers(env),
-      ],
-    );
-
-    const mergedConfig = mergeConfig(config, {
-      ...baseViteConfig,
-      resolve: mergeReactSingletonResolve(baseViteConfig, config),
-      define: {
-        // Preserve shared and Storybook-provided constants, then publish the
-        // resolved Emulsify environment to client-side code.
-        ...viteDefine,
-        ...existingDefine,
-        __EMULSIFY_ENV__: JSON.stringify(env),
-        'globalThis.__EMULSIFY_ENV__': JSON.stringify(env),
-      },
-      server: {
-        ...(baseViteConfig?.server || {}),
-        fs: {
-          allow: Array.from(allowList),
-        },
-      },
-      assetsInclude,
-      plugins: [...(baseViteConfig?.plugins || [])],
-      esbuild: {
-        // Some downstream code is authored as `.js` files containing JSX, so
-        // keep Storybook's esbuild settings aligned with the shared Vite config.
-        jsx: 'automatic',
-        loader: 'jsx',
-        include: /.*\.jsx?$/,
-        exclude: [],
-      },
-      optimizeDeps: {
-        ...(baseViteConfig?.optimizeDeps || {}),
-        ...(config?.optimizeDeps || {}),
-        include: optimizeDepsInclude,
-        exclude: mergeTwigRuntimeOptimizeDepsExcludes(
-          baseViteConfig?.optimizeDeps?.exclude,
-          config?.optimizeDeps?.exclude,
-        ),
-        esbuildOptions: {
-          ...(baseViteConfig?.optimizeDeps?.esbuildOptions || {}),
-          ...(config?.optimizeDeps?.esbuildOptions || {}),
-          plugins: [
-            ...(baseViteConfig?.optimizeDeps?.esbuildOptions?.plugins || []),
-            ...(config?.optimizeDeps?.esbuildOptions?.plugins || []),
-            makeTwigVirtualModuleOptimizerPlugin(),
-          ],
-          loader: {
-            ...(baseViteConfig?.optimizeDeps?.esbuildOptions?.loader || {}),
-            ...(config?.optimizeDeps?.esbuildOptions?.loader || {}),
-            // Pre-bundle `.js` dependencies with the JSX loader for packages
-            // that ship JSX without a `.jsx` extension.
-            '.js': 'jsx',
-          },
-        },
-      },
-    });
-
-    return {
-      ...mergedConfig,
-      build: {
-        ...(mergedConfig.build || {}),
-        ...(storybookBuildConfig.outDir
-          ? { outDir: storybookBuildConfig.outDir }
-          : {}),
-        assetsDir: storybookViteAssetsDir,
-        emptyOutDir: false,
-      },
-      resolve: mergeReactSingletonResolve(mergedConfig),
-      optimizeDeps: {
-        ...(mergedConfig.optimizeDeps || {}),
-        include: mergeReactSingletonOptimizeDeps(
-          mergedConfig.optimizeDeps?.include,
-        ),
-        exclude: mergeTwigRuntimeOptimizeDepsExcludes(
-          mergedConfig.optimizeDeps?.exclude,
-        ),
-        esbuildOptions: {
-          ...(mergedConfig.optimizeDeps?.esbuildOptions || {}),
-          loader: {
-            ...(mergedConfig.optimizeDeps?.esbuildOptions?.loader || {}),
-            '.js': 'jsx',
-          },
-        },
-      },
-    };
-  },
+  viteFinal: createViteFinal(resolvedStorybookEnv),
 };
 
 /**

package/.storybook/manager-head.css

@@ -0,0 +1,120 @@
+:root {
+  --colors-emulsify-blue-100: #e6f5fc;
+  --colors-emulsify-blue-200: #ccecfa;
+  --colors-emulsify-blue-300: #99d9f4;
+  --colors-emulsify-blue-400: #66c5ef;
+  --colors-emulsify-blue-500: #33b2e9;
+  --colors-emulsify-blue-600: #009fe4;
+  --colors-emulsify-blue-700: #007fb6;
+  --colors-emulsify-blue-800: #005f89;
+  --colors-emulsify-blue-900: #00405b;
+  --colors-emulsify-blue-1000: #00202e;
+  --colors-purple: #8b1e7e;
+}
+
+.sidebar-container {
+  background-color: var(--colors-emulsify-blue-900);
+}
+
+.sidebar-container .sidebar-subheading {
+  color: var(--colors-emulsify-blue-200);
+  font-size: 13px;
+  letter-spacing: 0.15em;
+}
+
+.sidebar-container .sidebar-subheading button:focus {
+  color: var(--colors-emulsify-blue-300);
+}
+
+/* Triangle icon. */
+.sidebar-container .sidebar-subheading button span {
+  color: var(--colors-emulsify-blue-300);
+}
+
+.sidebar-container .search-field input {
+  border-color: var(--colors-emulsify-blue-700);
+}
+
+.sidebar-container .search-field input:active {
+  border-color: var(--colors-emulsify-blue-700);
+}
+
+.sidebar-container .search-result-recentlyOpened,
+.sidebar-container .search-result-back,
+.sidebar-container .search-result-clearHistory {
+  color: var(--colors-emulsify-blue-300) !important;
+  letter-spacing: 0.15em;
+}
+
+.sidebar-container .search-result-back span,
+.sidebar-container .search-result-back svg,
+.sidebar-container .search-result-clearHistory span,
+.sidebar-container .search-result-clearHistory svg {
+  letter-spacing: normal;
+  color: white;
+}
+
+.sidebar-container .sidebar-item svg {
+  margin-top: 1px;
+}
+
+.sidebar-container .sidebar-item span {
+  margin-top: 4px;
+}
+
+.sidebar-container .sidebar-subheading-action svg {
+  color: var(--colors-emulsify-blue-400);
+}
+
+.sidebar-container .sidebar-subheading-action:hover svg {
+  color: var(--colors-emulsify-blue-300);
+}
+
+.sidebar-header button[title='Shortcuts'] {
+  box-shadow: none;
+  border: 1px solid var(--colors-emulsify-blue-700);
+}
+
+.sidebar-header button[title='Shortcuts']:active {
+  border: 1px solid var(--colors-emulsify-blue-500);
+}
+
+.sidebar-header button[title='Shortcuts']:focus {
+  background: transparent;
+}
+
+#shortcuts {
+  border-bottom-color: var(--colors-emulsify-blue-900) !important;
+}
+
+[role='main']:not(:nth-child(3)) {
+  top: 1rem !important;
+  height: calc(100vh - 2rem) !important;
+}
+
+[role='main'] .os-host .os-content button:hover {
+  background: var(--colors-emulsify-blue-100);
+}
+
+[role='main'] .os-host .os-content button:hover svg {
+  color: var(--colors-emulsify-blue-900);
+}
+
+#panel-tab-content,
+#panel-tab-content > * {
+  color: var(--colors-emulsify-blue-100) !important;
+}
+
+#panel-tab-content a,
+#panel-tab-content a span,
+#panel-tab-content a span svg {
+  color: var(--colors-emulsify-blue-800);
+}
+
+#panel-tab-content > div > div > div > div > div > div {
+  background: transparent;
+}
+
+#panel-tab-content > div > div > div > div > div > div > div {
+  color: var(--colors-emulsify-blue-1000) !important;
+}

package/.storybook/preview.js

@@ -14,12 +14,9 @@ import {
   applyStoryDecorators,
   renderPreviewStory,
 } from '../src/storybook/preview-decorator.js';
-import {
-  attachStorybookBehaviors,
-  fetchCSSFiles,
-  getStorybookPlatformAdapter,
-  setupTwig,
-} from './utils.js';
+import { attachStorybookBehaviors } from '../src/storybook/platform-behaviors.js';
+import { setupTwig } from '../src/storybook/twig/setup.js';
+import { fetchCSSFiles, getStorybookPlatformAdapter } from './utils.js';
 
 const previewOverrideModules = import.meta.glob(
   [

package/.storybook/utils.js

@@ -89,7 +89,7 @@ export function getProjectMachineName() {
     : undefined;
 }
 
-// Keep these named exports stable for preview.js and downstream overrides.
+// Keep these compatibility exports for downstream preview overrides.
 export {
   attachStorybookBehaviors,
   fetchCSSFiles,

package/config/vite/plugins/virtual-twig-asset-sources.js

@@ -16,6 +16,7 @@ export const VIRTUAL_TWIG_ASSET_SOURCES_ID =
   'virtual:emulsify-twig-asset-sources';
 const RESOLVED_VIRTUAL_TWIG_ASSET_SOURCES_ID = `\0${VIRTUAL_TWIG_ASSET_SOURCES_ID}`;
 const GENERATED_ASSET_ALIASES = new Set(['icons.svg']);
+const GENERATED_ASSET_ROOTS = ['/dist/assets'];
 const PUBLIC_ASSET_ROOTS = new Map([
   ['/assets', '/assets'],
   ['/dist/assets', '/assets'],
@@ -116,14 +117,21 @@ export function assetSourceRoots(env) {
  */
 export function generatedAssetSourceRoots(env) {
   return unique(
-    ['/dist/assets']
-      .map((root) => toAbsoluteAssetRoot(env?.projectDir, root))
+    GENERATED_ASSET_ROOTS.map((root) =>
+      toAbsoluteAssetRoot(env?.projectDir, root),
+    )
       .filter((root) => root && safeExists(root))
       .map((root) => toRootRelativePath(env?.projectDir, root))
       .filter(Boolean),
   );
 }
 
+function generatedAssetRootPrefixes() {
+  return GENERATED_ASSET_ROOTS.map((root) =>
+    `${root}/`.replace(/\/{2,}/g, '/'),
+  );
+}
+
 /**
  * Build Vite glob patterns from text asset roots.
  *
@@ -216,6 +224,20 @@ export function publicAssetSourceEntries(env) {
     }
   }
 
+  for (const root of generatedAssetRootPrefixes()) {
+    const publicBase = publicAssetBaseForRoot(root);
+    if (!publicBase) continue;
+
+    for (const alias of GENERATED_ASSET_ALIASES) {
+      const key = `${root.replace(/\/+$/, '')}/${alias}`.replace(
+        /\/{2,}/g,
+        '/',
+      );
+      const url = `${publicBase}${alias}`.replace(/\/{2,}/g, '/');
+      entries.set(key, { key, url });
+    }
+  }
+
   return Array.from(entries.values());
 }
 
@@ -232,6 +254,10 @@ export function generateVirtualTwigAssetSourcesModule(env) {
   const generatedRootPrefixes = generatedAssetSourceRoots(env).map((root) =>
     `${root === '/' ? '' : root}/`.replace(/\/{2,}/g, '/'),
   );
+  const allGeneratedRootPrefixes = unique([
+    ...generatedRootPrefixes,
+    ...generatedAssetRootPrefixes(),
+  ]);
   const patterns = assetSourceGlobPatterns(env);
   const globEntries = patterns.length
     ? patterns
@@ -255,7 +281,7 @@ export function generateVirtualTwigAssetSourcesModule(env) {
  */
 
 export const assetRootPrefixes = ${JSON.stringify(rootPrefixes)};
-export const generatedAssetRootPrefixes = ${JSON.stringify(generatedRootPrefixes)};
+export const generatedAssetRootPrefixes = ${JSON.stringify(allGeneratedRootPrefixes)};
 export const generatedAssetAliases = ${JSON.stringify(
     Array.from(GENERATED_ASSET_ALIASES),
   )};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emulsify/core",
-  "version": "4.1.0",
+  "version": "4.1.1",
   "description": "Bundled tooling for Storybook development + Vite Build",
   "keywords": [
     "component library",
@@ -38,7 +38,10 @@
     ".storybook/css-components.js",
     ".storybook/css-dist.js",
     ".storybook/emulsifyTheme.js",
+    ".storybook/main-static-assets.js",
+    ".storybook/main-vite.js",
     ".storybook/main.js",
+    ".storybook/manager-head.css",
     ".storybook/manager.js",
     ".storybook/preview.js",
     ".storybook/utils.js",