@emulsify/core 4.2.1 → 4.3.1

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

@@ -5,16 +5,26 @@
  * resident unless a Twig template calls `source('@assets/...')`.
  */
 
-import { readdirSync } from 'fs';
+import { readFileSync, readdirSync } from 'fs';
 import { relative, resolve } from 'path';
-import { safeExists } from '../utils/fs-safe.js';
-import { toPosixPath } from '../utils/paths.js';
-import { unique } from '../utils/unique.js';
-import { INLINE_ASSET_EXTS } from '../../../src/storybook/twig/source-extensions.js';
+import { fileURLToPath } from 'url';
+import { safeExists } from '../../utils/fs-safe.js';
+import { toPosixPath } from '../../utils/paths.js';
+import { unique } from '../../../../src/extensions/shared/lists.js';
+import { toRootRelativePath } from '../../../../src/extensions/shared/root-relative.js';
+import { INLINE_ASSET_EXTS } from '../../../../src/storybook/twig/constants.js';
 
 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 VIRTUAL_TWIG_ASSET_SOURCE_RUNTIME_ID =
+  'virtual:emulsify-twig-asset-source-runtime';
+const RESOLVED_VIRTUAL_TWIG_ASSET_SOURCE_RUNTIME_ID = `\0${VIRTUAL_TWIG_ASSET_SOURCE_RUNTIME_ID}`;
+const ASSET_SOURCE_RUNTIME_URL = new URL(
+  '../../../../src/storybook/twig/asset-source-runtime.js',
+  import.meta.url,
+);
+const ASSET_SOURCE_RUNTIME_PATH = fileURLToPath(ASSET_SOURCE_RUNTIME_URL);
 const GENERATED_ASSET_ALIASES = new Set(['icons.svg']);
 const GENERATED_ASSET_ROOTS = ['/dist/assets'];
 const PUBLIC_ASSET_ROOTS = new Map([
@@ -22,35 +32,6 @@ const PUBLIC_ASSET_ROOTS = new Map([
   ['/dist/assets', '/assets'],
 ]);
 
-/**
- * Convert an absolute project path to a Vite root-relative glob base.
- *
- * @param {string} projectDir - Absolute project root.
- * @param {string} absolutePath - Absolute asset root path.
- * @returns {string} Vite root-relative path.
- */
-function toRootRelativePath(projectDir, absolutePath) {
-  if (!absolutePath) return '';
-
-  const normalizedProjectDir = toPosixPath(projectDir || '').replace(
-    /\/+$/,
-    '',
-  );
-  const normalizedPath = toPosixPath(absolutePath).replace(/\/+$/, '');
-
-  if (
-    normalizedProjectDir &&
-    normalizedPath.startsWith(`${normalizedProjectDir}/`)
-  ) {
-    return `/${normalizedPath.slice(normalizedProjectDir.length + 1)}`.replace(
-      /\/{2,}/g,
-      '/',
-    );
-  }
-
-  return `/${normalizedPath.replace(/^\/+/, '')}`.replace(/\/{2,}/g, '/');
-}
-
 /**
  * Resolve a configured asset root to an absolute filesystem path.
  *
@@ -275,11 +256,13 @@ export function generateVirtualTwigAssetSourcesModule(env) {
     .join(',\n');
 
   return `/**
- * Virtual module generated by config/vite/plugins/virtual-twig-asset-sources.js.
+ * Virtual module generated by config/vite/plugins/twig/virtual-twig-asset-sources.js.
  *
  * Raw text assets stay lazy and load only when Twig source() requests them.
  */
 
+import { createAssetSourceRuntime } from '${VIRTUAL_TWIG_ASSET_SOURCE_RUNTIME_ID}';
+
 export const assetRootPrefixes = ${JSON.stringify(rootPrefixes)};
 export const generatedAssetRootPrefixes = ${JSON.stringify(allGeneratedRootPrefixes)};
 export const generatedAssetAliases = ${JSON.stringify(
@@ -299,107 +282,18 @@ ${globEntries}
 ${fetchEntries ? `${globEntries ? ',\n' : ''}{\n${fetchEntries}\n}` : ''}
 ]);
 
-const sourceTextCache = new Map();
-const sourceLoadPromises = new Map();
-
-const unique = (values) => Array.from(new Set(values.filter(Boolean)));
-
-const normalizeAssetPath = (assetPath) =>
-  String(assetPath || '')
-    .replace(/^@assets\\//, '')
-    .replace(/^\\/?assets\\//, '')
-    .replace(/^\\/+/, '');
-
-const candidateKeysForAssetPath = (assetPath) => {
-  const rawPath = String(assetPath || '');
-  const normalized = normalizeAssetPath(rawPath);
-  const directPath = rawPath.startsWith('/') ? rawPath : \`/\${rawPath}\`;
-  const generatedCandidates = generatedAssetAliases.includes(normalized)
-    ? generatedAssetRootPrefixes.map((root) =>
-        \`\${root.replace(/\\/+$/, '')}/\${normalized}\`,
-      )
-    : [];
-
-  return unique([
-    rawPath,
-    directPath,
-    normalized ? \`/\${normalized}\` : '',
-    ...generatedCandidates,
-    ...assetRootPrefixes.map((root) =>
-      \`\${root.replace(/\\/+$/, '')}/\${normalized}\`,
-    ),
-  ]);
-};
-
-const findAssetKey = (assetPath) =>
-  candidateKeysForAssetPath(assetPath).find((key) =>
-    Object.hasOwnProperty.call(assets, key),
-  );
-
-const normalizeSourceText = (value) => {
-  const source = value?.default ?? value;
-  return typeof source === 'string' ? source : undefined;
-};
-
-export const coversAssetPath = (assetPath) =>
-  (assetRootPrefixes.length > 0 || generatedAssetRootPrefixes.length > 0) &&
-  normalizeAssetPath(assetPath).length > 0;
-
-export const hasAssetText = (assetPath) => Boolean(findAssetKey(assetPath));
-
-export const isAssetTextLoading = (assetPath) => {
-  const key = findAssetKey(assetPath);
-  return Boolean(key && sourceLoadPromises.has(key));
-};
-
-export const whenAssetTextLoaded = (assetPath) => {
-  const key = findAssetKey(assetPath);
-  return key ? sourceLoadPromises.get(key) : undefined;
-};
-
-export const getAssetText = (assetPath) => {
-  const key = findAssetKey(assetPath);
-  if (!key) return undefined;
-  if (sourceTextCache.has(key)) {
-    return sourceTextCache.get(key);
-  }
-
-  const loader = assets[key];
-  const sourceText = normalizeSourceText(loader);
-  if (typeof sourceText === 'string') {
-    sourceTextCache.set(key, sourceText);
-    return sourceText;
-  }
-
-  if (typeof loader === 'function' && !sourceLoadPromises.has(key)) {
-    let loadedSource;
-    try {
-      loadedSource = loader();
-    } catch (error) {
-      loadedSource = Promise.reject(error);
-    }
-
-    const sourceLoad = Promise.resolve(loadedSource)
-      .then((loaded) => {
-        const loadedText = normalizeSourceText(loaded);
-        if (typeof loadedText === 'string') {
-          sourceTextCache.set(key, loadedText);
-        }
-        return loadedText;
-      })
-      .catch((error) => {
-        console.error(\`source(): failed to load asset \${key}\`, error);
-        return undefined;
-      })
-      .finally(() => {
-        sourceLoadPromises.delete(key);
-      });
-
-    sourceLoadPromises.set(key, sourceLoad);
-  }
-
-  return undefined;
-};
+const assetSourceRuntime = createAssetSourceRuntime({
+  assets,
+  assetRootPrefixes,
+  generatedAssetRootPrefixes,
+  generatedAssetAliases,
+});
+
+export const coversAssetPath = assetSourceRuntime.coversAssetPath;
+export const hasAssetText = assetSourceRuntime.hasAssetText;
+export const isAssetTextLoading = assetSourceRuntime.isAssetTextLoading;
+export const whenAssetTextLoaded = assetSourceRuntime.whenAssetTextLoaded;
+export const getAssetText = assetSourceRuntime.getAssetText;
 `;
 }
 
@@ -416,6 +310,9 @@ export function virtualTwigAssetSourcesPlugin(env) {
       if (id === VIRTUAL_TWIG_ASSET_SOURCES_ID) {
         return RESOLVED_VIRTUAL_TWIG_ASSET_SOURCES_ID;
       }
+      if (id === VIRTUAL_TWIG_ASSET_SOURCE_RUNTIME_ID) {
+        return RESOLVED_VIRTUAL_TWIG_ASSET_SOURCE_RUNTIME_ID;
+      }
 
       return null;
     },
@@ -423,6 +320,10 @@ export function virtualTwigAssetSourcesPlugin(env) {
       if (id === RESOLVED_VIRTUAL_TWIG_ASSET_SOURCES_ID) {
         return generateVirtualTwigAssetSourcesModule(env);
       }
+      if (id === RESOLVED_VIRTUAL_TWIG_ASSET_SOURCE_RUNTIME_ID) {
+        this.addWatchFile(ASSET_SOURCE_RUNTIME_PATH);
+        return readFileSync(ASSET_SOURCE_RUNTIME_PATH, 'utf8');
+      }
 
       return null;
     },

package/config/vite/plugins/{virtual-twig-globs.js → twig/virtual-twig-globs.js}

@@ -5,8 +5,8 @@
  * virtual module instead of replacing placeholder strings in resolver source.
  */
 
-import { toPosixPath } from '../utils/paths.js';
-import { unique } from '../utils/unique.js';
+import { unique } from '../../../../src/extensions/shared/lists.js';
+import { toRootRelativePath } from '../../../../src/extensions/shared/root-relative.js';
 
 export const VIRTUAL_TWIG_GLOBS_ID = 'virtual:emulsify-twig-globs';
 const RESOLVED_VIRTUAL_TWIG_GLOBS_ID = `\0${VIRTUAL_TWIG_GLOBS_ID}`;
@@ -17,35 +17,6 @@ const RESOLVED_VIRTUAL_TWIG_GLOBS_ID = `\0${VIRTUAL_TWIG_GLOBS_ID}`;
  * @property {Record<string, Function>} sources - Lazy raw Twig source loaders.
  */
 
-/**
- * Convert an absolute project path to a Vite root-relative glob base.
- *
- * @param {string} projectDir - Absolute project root.
- * @param {string} absolutePath - Absolute Twig root path.
- * @returns {string} Vite root-relative path.
- */
-function toRootRelativePath(projectDir, absolutePath) {
-  if (!absolutePath) return '';
-
-  const normalizedProjectDir = toPosixPath(projectDir || '').replace(
-    /\/+$/,
-    '',
-  );
-  const normalizedPath = toPosixPath(absolutePath).replace(/\/+$/, '');
-
-  if (
-    normalizedProjectDir &&
-    normalizedPath.startsWith(`${normalizedProjectDir}/`)
-  ) {
-    return `/${normalizedPath.slice(normalizedProjectDir.length + 1)}`.replace(
-      /\/{2,}/g,
-      '/',
-    );
-  }
-
-  return `/${normalizedPath.replace(/^\/+/, '')}`.replace(/\/{2,}/g, '/');
-}
-
 /**
  * Build Vite glob patterns from a resolved Emulsify environment.
  *
@@ -85,7 +56,7 @@ export function generateVirtualTwigGlobsModule(env) {
     : '';
 
   return `/**
- * Virtual module generated by config/vite/plugins/virtual-twig-globs.js.
+ * Virtual module generated by config/vite/plugins/twig/virtual-twig-globs.js.
  *
  * Compiled Twig modules stay eager for synchronous story rendering. Raw source
  * entries stay lazy and load only when Twig source() requests a template.

package/config/vite/plugins/{vituum-patch.js → twig/vituum-patch.js}

@@ -8,9 +8,9 @@
 import twig from '@vituum/vite-plugin-twig';
 import Twig from 'twig';
 
-import { registerTwigExtensions } from '../../../src/extensions/twig/index.js';
+import { registerTwigExtensions } from '../../../../src/extensions/twig/index.js';
 import { makeTwigPluginOptions } from './twig-module.js';
-import { registerConfiguredTwigExtensions } from '../twig-extensions.js';
+import { installProjectTwigExtensions } from './extensions.js';
 
 const EXPECTED_PLUGIN_NAMES = [
   '@vituum/vite-plugin-core:bundle',
@@ -140,7 +140,7 @@ function stripExpectedHooks(pluginOption) {
  */
 export function makeTwigPlugins(env, options = makeTwigPluginOptions(env)) {
   registerTwigExtensions(Twig);
-  registerConfiguredTwigExtensions(Twig, options);
+  installProjectTwigExtensions(Twig, options);
 
   const twigPlugins = twig(options);
   const normalizedPlugins = Array.isArray(twigPlugins)

package/config/vite/plugins.js

@@ -9,4 +9,4 @@ export { makePlugins } from './plugins/index.js';
 export {
   makeTwigNamespaces,
   makeTwigPluginOptions,
-} from './plugins/twig-module.js';
+} from './plugins/twig/twig-module.js';

package/config/vite/project-config.js

@@ -11,7 +11,7 @@ import { normalize, resolve, sep } from 'path';
 import { getPlatformAdapter, normalizePlatformName } from './platforms.js';
 import { resolveProjectStructure } from './project-structure.js';
 import { safeExists, safeReadJson } from './utils/fs-safe.js';
-import { unique } from './utils/unique.js';
+import { unique } from '../../src/extensions/shared/lists.js';
 
 /**
  * Cache normalized project config by project root and relevant env signature.

package/config/vite/project-structure.js

@@ -10,7 +10,7 @@
 import { basename, normalize, relative, resolve, sep } from 'path';
 import { safeExists } from './utils/fs-safe.js';
 import { replaceLastSlash, toPosixPath } from './utils/paths.js';
-import { unique } from './utils/unique.js';
+import { unique } from '../../src/extensions/shared/lists.js';
 
 export { replaceLastSlash, toPosixPath };
 

package/config/vite/utils/lru.js

@@ -0,0 +1,77 @@
+/**
+ * @file Tiny Map-like LRU cache helper.
+ */
+
+/**
+ * Create a bounded insertion-order LRU cache.
+ *
+ * @template K,V
+ * @param {number} maxEntries - Maximum number of entries to retain.
+ * @returns {{
+ *   readonly size: number,
+ *   has(key: K): boolean,
+ *   get(key: K): V|undefined,
+ *   set(key: K, value: V): object,
+ *   delete(key: K): boolean,
+ *   clear(): void,
+ *   entries(): IterableIterator<[K, V]>,
+ *   keys(): IterableIterator<K>,
+ *   values(): IterableIterator<V>,
+ *   [Symbol.iterator](): IterableIterator<[K, V]>
+ * }} Map-like LRU cache.
+ */
+export function createLruCache(maxEntries) {
+  if (!Number.isInteger(maxEntries) || maxEntries < 1) {
+    throw new RangeError('LRU cache size must be a positive integer.');
+  }
+
+  const entries = new Map();
+  const cache = {
+    get size() {
+      return entries.size;
+    },
+    has(key) {
+      return entries.has(key);
+    },
+    get(key) {
+      if (!entries.has(key)) return undefined;
+
+      const value = entries.get(key);
+      entries.delete(key);
+      entries.set(key, value);
+      return value;
+    },
+    set(key, value) {
+      if (entries.has(key)) {
+        entries.delete(key);
+      }
+      entries.set(key, value);
+
+      while (entries.size > maxEntries) {
+        entries.delete(entries.keys().next().value);
+      }
+
+      return cache;
+    },
+    delete(key) {
+      return entries.delete(key);
+    },
+    clear() {
+      entries.clear();
+    },
+    entries() {
+      return entries.entries();
+    },
+    keys() {
+      return entries.keys();
+    },
+    values() {
+      return entries.values();
+    },
+    [Symbol.iterator]() {
+      return entries[Symbol.iterator]();
+    },
+  };
+
+  return cache;
+}

package/config/vite/utils/package-version.js

@@ -0,0 +1,42 @@
+/**
+ * @file Emulsify Core package version resolution.
+ *
+ * Shared by the component mirror plugin, which stamps the version into its
+ * state marker, and the develop reporter, which prints it in the banner.
+ */
+
+import { join } from 'path';
+
+import { safeReadJson } from './fs-safe.js';
+
+/**
+ * Resolve the installed Core package version.
+ *
+ * `import.meta.url` is deliberately avoided so Jest's CommonJS transform can
+ * load callers of this module without extra plumbing. Candidates are ordered
+ * from most to least specific: the consuming project's installed copy, the
+ * current working directory's installed copy, then the working directory
+ * itself for the case where Core is building its own source tree.
+ *
+ * @param {string} [projectDir] - Project directory running the build.
+ * @returns {string} Emulsify Core package version, or `0.0.0` when unknown.
+ */
+export function resolvePackageVersion(projectDir) {
+  const candidates = [
+    projectDir && join(projectDir, 'node_modules/@emulsify/core/package.json'),
+    join(process.cwd(), 'node_modules/@emulsify/core/package.json'),
+    join(process.cwd(), 'package.json'),
+  ].filter(Boolean);
+
+  for (const candidate of candidates) {
+    const candidatePackage = safeReadJson(candidate).data;
+    if (
+      candidatePackage?.name === '@emulsify/core' &&
+      candidatePackage.version
+    ) {
+      return candidatePackage.version;
+    }
+  }
+
+  return '0.0.0';
+}

package/config/vite/utils/paths.js

@@ -14,18 +14,10 @@ import { sep } from 'path';
  * @param {string} filePath - Filesystem path.
  * @returns {string} Path using forward slashes.
  */
-export function toPosix(filePath) {
+export function toPosixPath(filePath) {
   return filePath.split(sep).join('/').replace(/\\/g, '/');
 }
 
-/**
- * Normalize a filesystem path to POSIX separators.
- *
- * @param {string} filePath - Filesystem path.
- * @returns {string} Path using forward slashes.
- */
-export const toPosixPath = toPosix;
-
 /**
  * Replace the final slash in a POSIX path with a custom segment.
  *

package/config/vite/utils/react-singleton.js

@@ -2,7 +2,7 @@
  * @file React singleton helpers for Storybook and Vite config.
  */
 
-import { unique } from './unique.js';
+import { unique } from '../../../src/extensions/shared/lists.js';
 
 /**
  * React modules that must resolve from the consumer project root.

package/config/vite/vite.config.js

@@ -13,17 +13,35 @@
  *     parts of it by returning a patch object from `extendConfig(...)`.
  *
  * Notes:
- * - CSS & JS sourcemaps are enabled.
+ * - JS sourcemaps come from `build.sourcemap`. Extracted CSS gets no map from
+ *   `vite build`: `vite:css-post` emits CSS through
+ *   `this.emitFile({ type: 'asset' })`, Rollup/Rolldown assets carry no map,
+ *   and `finalizeCss()` -> `minifyCSS()` returns code only. To trace a rule
+ *   back to its `.scss` partial, let Vite compile the SCSS in Storybook: set
+ *   `parameters.emulsify.loadAllCSS = false` in
+ *   `config/emulsify-core/storybook/preview.js` and import the SCSS entry
+ *   there, so `css.devSourcemap` can chain the map to source. Loading the
+ *   compiled CSS instead yields an identity map whose only source is the
+ *   compiled `.css` file.
+ * - CSS is left unminified during `vite build --watch` so the develop loop
+ *   stays readable; one-shot builds keep minification.
  * - CSS assets keep their path and drop the internal `__style` suffix if present.
  */
 
-import { defineConfig, mergeConfig } from 'vite';
+import { createLogger, defineConfig, mergeConfig } from 'vite';
 import path from 'node:path';
 
 import { resolveEnvironment } from './environment.js';
 import { makePlugins } from './plugins.js';
 import { buildInputs } from './entries.js';
-import { createSourceFileIndex } from './plugins/source-file-index.js';
+import { createSourceFileIndex } from './plugins/assets/source-file-index.js';
+import { createDiagnosticsCollector } from './plugins/reporter/diagnostics.js';
+import { createSassOptions } from './plugins/reporter/sass-logger.js';
+import {
+  createReporterLogger,
+  isVerbose,
+} from './plugins/reporter/vite-logger.js';
+import { isWatchInvocation } from './plugins/reporter/watch-mode.js';
 import { loadProjectExtensions } from './project-extensions.js';
 import { mergeReactSingletonResolve } from './utils/react-singleton.js';
 
@@ -44,7 +62,14 @@ export default defineConfig(async () => {
   /** @type {EmulsifyEnv} */
   const env = resolveEnvironment();
   const sourceFileIndex = createSourceFileIndex(env.projectStructure);
-  const envWithSourceFileIndex = { ...env, sourceFileIndex };
+
+  // The develop reporter takes over output only for `vite build --watch`, the
+  // watcher `npm run develop` runs. One-shot builds, Storybook, and the release
+  // fixture verifications keep their existing output untouched, so no warning
+  // is ever collected without also being reported.
+  const watching = isWatchInvocation();
+  const diagnostics = watching ? createDiagnosticsCollector() : undefined;
+  const envWithSourceFileIndex = { ...env, sourceFileIndex, diagnostics };
 
   // Build the Rollup/Vite entry map: keys encode output paths, values source files.
   /** @type {Record<string, string>} */
@@ -79,12 +104,66 @@ export default defineConfig(async () => {
     // Core plugin set + project-provided plugins (if any).
     plugins: [...makePlugins(envWithSourceFileIndex), ...projectPlugins],
 
+    // Quieting `develop` takes two independent switches, because the output has
+    // two independent sources.
+    //
+    // 1. `logLevel` gates Vite's build reporter, which is a native Rolldown
+    //    plugin. Vite reads `config.logLevel` directly when constructing it and
+    //    passes a `logInfo` callback only when the level admits info. Rolldown's
+    //    Rust side registers its Transform, BuildStart, BuildEnd, RenderChunk,
+    //    WriteBundle, and GenerateBundle hooks only when that callback exists,
+    //    so raising the level does not merely hide the report — it stops
+    //    Rolldown instrumenting transforms and computing gzip sizes at all.
+    //    That removes the `transforming (N)` progress line, `N modules
+    //    transformed.`, `rendering chunks...`, `computing gzip size...`, and the
+    //    per-file asset table, and makes every rebuild cheaper.
+    //
+    //    The progress line is the one that matters most for legibility: Rolldown
+    //    writes it from Rust with a `\x1b[2K\r` prefix and no trailing newline,
+    //    which is what collides with Storybook's output when `concurrently`
+    //    merges both streams onto one pipe. Nothing on the JavaScript side can
+    //    intercept it, so `logLevel` is the only lever that removes it.
+    //
+    // 2. `customLogger` gates Vite's own JavaScript chatter — `building client
+    //    environment...`, `build started...`, `watching for file changes...`,
+    //    and `built in Nms.` — and routes unresolved CSS asset URLs into the
+    //    diagnostics collector so they are summarized rather than printed
+    //    mid-build. The reporter writes straight to stdout rather than through
+    //    this logger, so its own output survives the higher level, and warnings
+    //    and errors still come through.
+    //
+    // Neither switch substitutes for the other: `createLogger` returns a
+    // supplied `customLogger` verbatim and never consults the level, while the
+    // build reporter consults the level and never consults the logger.
+    // `build.reportCompressedSize` is deliberately left alone; it suppresses
+    // only the gzip column, and the table it belongs to is already gone.
+    ...(diagnostics
+      ? {
+          logLevel: isVerbose() ? 'info' : 'warn',
+          customLogger: createReporterLogger(
+            diagnostics,
+            createLogger(isVerbose() ? 'info' : 'warn'),
+          ),
+        }
+      : {}),
+
     // Keep React-based story helpers on the consumer project's React singleton.
     resolve: mergeReactSingletonResolve(),
 
     // Generate CSS sourcemaps in dev; JS sourcemaps are set in `build.sourcemap`.
+    // These map only what Vite itself compiles. A preview that imports
+    // already-compiled CSS gets an identity map pointing at that `.css` file,
+    // so import SCSS entries when styles need to resolve to their partials.
     css: {
       devSourcemap: true,
+
+      // During a watch build, route Sass warnings into the diagnostics
+      // collector instead of letting Dart Sass print a formatted block per
+      // occurrence. The reporter prints one deduplicated tally per cycle, so
+      // the deprecation debt stays visible without the repetition.
+      ...(diagnostics
+        ? { preprocessorOptions: { scss: createSassOptions(diagnostics) } }
+        : {}),
     },
 
     build: {
@@ -94,9 +173,16 @@ export default defineConfig(async () => {
       // All outputs are written into ./dist/
       outDir: 'dist/',
 
-      // Emit production sourcemaps as well.
+      // Emit JS sourcemaps. Extracted CSS is not covered; see the file header.
       sourcemap: true,
 
+      // Vite cannot map extracted CSS, so during `vite build --watch` the
+      // readable stylesheet is the debugging aid: keep it unminified so
+      // devtools shows one declaration per line instead of a single long line.
+      // One-shot `vite build`, `storybook build`, and the release fixture
+      // verifications still minify, so nothing a platform ships changes.
+      cssMinify: !watching,
+
       rollupOptions: {
         // Multi-entry input map constructed above.
         input: entries,