@emulsify/core 4.3.2 → 4.5.0

package/config/vite/plugins/twig/twig-module.js

@@ -11,7 +11,7 @@
 
 import fs from 'fs';
 import { readFile, stat } from 'fs/promises';
-import { basename, dirname, isAbsolute, relative, resolve } from 'path';
+import { basename, dirname, relative, resolve } from 'path';
 import Twig from 'twig';
 
 import {
@@ -27,6 +27,12 @@ import {
 import { firstExistingPath, safeExists } from '../../utils/fs-safe.js';
 import { createLruCache } from '../../utils/lru.js';
 import { toPosixPath } from '../../utils/paths.js';
+import {
+  buildTemplateFileCandidates,
+  isWithinRoot,
+  parseTwigNamespaceReference,
+  resolveComponentReference,
+} from '../../utils/twig-component-resolver.js';
 import { unique } from '../../../../src/extensions/shared/lists.js';
 
 /** Twig token types that can reference another template file. */
@@ -338,29 +344,6 @@ const collectStaticSourceReferences = (tokens = []) => [
   ),
 ];
 
-/**
- * Build likely filesystem candidates for a Twig template reference.
- *
- * @param {string} baseDir - Directory used as the resolution root.
- * @param {string} templatePath - Template path from Twig source.
- * @returns {string[]} Candidate absolute paths.
- */
-const buildTemplateFileCandidates = (baseDir, templatePath) => {
-  const normalizedTemplatePath = toPosixPath(templatePath);
-  const withoutTwigExt = normalizedTemplatePath.replace(/\.twig$/i, '');
-  const stem = basename(withoutTwigExt);
-
-  return unique(
-    [
-      resolve(baseDir, normalizedTemplatePath),
-      resolve(baseDir, `${normalizedTemplatePath}.twig`),
-      resolve(baseDir, `${normalizedTemplatePath}.html.twig`),
-      resolve(baseDir, withoutTwigExt, `${stem}.twig`),
-      resolve(baseDir, withoutTwigExt, `${stem}.html.twig`),
-    ].filter(Boolean),
-  );
-};
-
 /**
  * Return the first candidate that exists as a file.
  *
@@ -376,60 +359,6 @@ const findExistingTemplateFile = (paths) =>
     }
   });
 
-/**
- * Determine whether a file path is equal to or below a candidate root.
- *
- * @param {string} root - Absolute root path.
- * @param {string} filePath - Absolute file path.
- * @returns {boolean} TRUE when the file belongs to the root.
- */
-const isWithinRoot = (root, filePath) => {
-  const rootRelativePath = relative(root, filePath);
-  return (
-    rootRelativePath === '' ||
-    (!!rootRelativePath &&
-      !rootRelativePath.startsWith('..') &&
-      !isAbsolute(rootRelativePath))
-  );
-};
-
-/**
- * Return the first component template candidate contained by its configured root.
- *
- * Both lexical and real paths are checked so `..` segments and symlinks cannot
- * escape the component root.
- *
- * @param {string[]} paths - Candidate absolute paths.
- * @param {string} componentRoot - Absolute component root path.
- * @returns {string|undefined} Existing component template path.
- */
-const findExistingComponentTemplateFile = (paths, componentRoot) => {
-  const absoluteRoot = resolve(componentRoot);
-  let realRoot;
-
-  try {
-    realRoot = fs.realpathSync(absoluteRoot);
-  } catch {
-    return undefined;
-  }
-
-  return paths.filter(Boolean).find((filePath) => {
-    const absoluteFilePath = resolve(filePath);
-    if (!isWithinRoot(absoluteRoot, absoluteFilePath)) {
-      return false;
-    }
-
-    try {
-      return (
-        fs.statSync(absoluteFilePath).isFile() &&
-        isWithinRoot(realRoot, fs.realpathSync(absoluteFilePath))
-      );
-    } catch {
-      return false;
-    }
-  });
-};
-
 /**
  * Find the most specific configured Twig root for a template file.
  *
@@ -548,161 +477,6 @@ const rewriteTemplateReferencesToIds = (tokens = [], fromFilePath, options) =>
     return nextToken;
   });
 
-/**
- * Resolve Twig namespace syntax to a namespace root and relative path.
- *
- * @param {string} templatePath - Template reference from Twig source.
- * @param {Record<string, string>} [namespaces={}] - Namespace root map.
- * @returns {{ namespace: string, root: string, path: string }|null}
- *   Namespace lookup result.
- */
-const parseTwigNamespaceReference = (templatePath, namespaces = {}) => {
-  const namespaceNames = Object.keys(namespaces);
-  const atNamespace = templatePath.match(/^@([^/]+)\/(.+)$/);
-  if (atNamespace && namespaces[atNamespace[1]]) {
-    return {
-      namespace: atNamespace[1],
-      root: namespaces[atNamespace[1]],
-      path: atNamespace[2],
-    };
-  }
-
-  const doubleColon = templatePath.match(/^([^:]+)::(.+)$/);
-  if (doubleColon && namespaces[doubleColon[1]]) {
-    return {
-      namespace: doubleColon[1],
-      root: namespaces[doubleColon[1]],
-      path: doubleColon[2],
-    };
-  }
-
-  const singleColon = templatePath.match(/^([^:/.]+):(.+)$/);
-  if (singleColon && namespaces[singleColon[1]]) {
-    return {
-      namespace: singleColon[1],
-      root: namespaces[singleColon[1]],
-      path: singleColon[2],
-    };
-  }
-
-  const slashNamespace = namespaceNames.find((namespace) =>
-    templatePath.startsWith(`${namespace}/`),
-  );
-  if (slashNamespace) {
-    return {
-      namespace: slashNamespace,
-      // Namespace names come from the normalized Twig namespace map.
-      root: namespaces[slashNamespace],
-      path: templatePath.slice(slashNamespace.length + 1),
-    };
-  }
-
-  return null;
-};
-
-/**
- * Return grouping directories below the configured component root.
- *
- * Breadth-first traversal preserves direct and one-level behavior before
- * searching deeper groups. Siblings use code-point order so duplicate
- * shorthand names resolve consistently across filesystems.
- *
- * @param {string} componentRoot - Absolute component root path.
- * @returns {string[]} Absolute grouping directory paths.
- */
-const componentGroupRoots = (componentRoot) => {
-  if (!componentRoot) return [];
-
-  const absoluteRoot = resolve(componentRoot);
-  if (componentGroupRootsCache.has(absoluteRoot)) {
-    return componentGroupRootsCache.get(absoluteRoot);
-  }
-
-  const groupRoots = [];
-  const pendingDirectories = [absoluteRoot];
-
-  for (let index = 0; index < pendingDirectories.length; index += 1) {
-    const directory = pendingDirectories[index];
-    let entries;
-
-    try {
-      entries = fs.readdirSync(directory, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-
-    const childDirectories = entries
-      .filter((entry) => entry.isDirectory())
-      .sort(({ name: left }, { name: right }) =>
-        left === right ? 0 : left < right ? -1 : 1,
-      )
-      .map((entry) => resolve(directory, entry.name))
-      .filter((childDirectory) => isWithinRoot(absoluteRoot, childDirectory));
-
-    groupRoots.push(...childDirectories);
-    pendingDirectories.push(...childDirectories);
-  }
-
-  componentGroupRootsCache.set(absoluteRoot, groupRoots);
-  return groupRoots;
-};
-
-/**
- * Resolve a component reference through recursively grouped directories.
- *
- * Project-scoped component IDs can use the component name (`project:button`)
- * even when projects organize components under grouping paths such as
- * `atoms/text`.
- *
- * @param {string} templatePath - Component-relative template reference.
- * @param {string} componentRoot - Absolute component root path.
- * @returns {string|null} Existing template path when found.
- */
-const resolveGroupedComponentTemplate = (templatePath, componentRoot) =>
-  findExistingComponentTemplateFile(
-    componentGroupRoots(componentRoot).flatMap((groupRoot) =>
-      buildTemplateFileCandidates(groupRoot, templatePath),
-    ),
-    componentRoot,
-  ) || null;
-
-/**
- * Resolve shorthand component references against the components namespace.
- *
- * @param {string} templatePath - Template reference from Twig source.
- * @param {string} componentRoot - Absolute component root path.
- * @returns {string|null} Existing template path when found.
- */
-const resolveComponentShorthandReference = (templatePath, componentRoot) => {
-  if (!componentRoot || templatePath.startsWith('.')) return null;
-
-  const shorthandPath =
-    templatePath.startsWith('@') && !templatePath.includes('/')
-      ? templatePath.slice(1)
-      : templatePath;
-  const directComponentPath = findExistingComponentTemplateFile(
-    buildTemplateFileCandidates(componentRoot, shorthandPath),
-    componentRoot,
-  );
-  if (directComponentPath) {
-    return directComponentPath;
-  }
-
-  const genericNamespace = templatePath.match(/^@?[^/:]+[:/](.+)$/);
-  if (!genericNamespace) {
-    return null;
-  }
-
-  const genericComponentPath = genericNamespace[1];
-
-  return (
-    findExistingComponentTemplateFile(
-      buildTemplateFileCandidates(componentRoot, genericComponentPath),
-      componentRoot,
-    ) || resolveGroupedComponentTemplate(genericComponentPath, componentRoot)
-  );
-};
-
 /**
  * Build a stable key segment for include resolution cache entries.
  *
@@ -734,27 +508,19 @@ const resolveTwigTemplateWithoutCache = (templatePath, fromDir, options) => {
     options.namespaces,
   );
   if (namespaced) {
-    const namespacedTemplate =
-      namespaced.namespace === 'components'
-        ? findExistingComponentTemplateFile(
-            buildTemplateFileCandidates(namespaced.root, namespaced.path),
-            namespaced.root,
-          )
-        : findExistingTemplateFile(
-            buildTemplateFileCandidates(namespaced.root, namespaced.path),
-          );
-    if (namespacedTemplate) {
-      return namespacedTemplate;
-    }
-
     if (namespaced.namespace === 'components') {
-      return resolveGroupedComponentTemplate(
-        namespaced.path,
-        options.namespaces?.components,
+      return resolveComponentReference(
+        templatePath,
+        options.namespaces,
+        componentGroupRootsCache,
       );
     }
 
-    return null;
+    return (
+      findExistingTemplateFile(
+        buildTemplateFileCandidates(namespaced.root, namespaced.path),
+      ) || null
+    );
   }
 
   const relativeTemplate = findExistingTemplateFile([
@@ -764,9 +530,10 @@ const resolveTwigTemplateWithoutCache = (templatePath, fromDir, options) => {
 
   return (
     relativeTemplate ||
-    resolveComponentShorthandReference(
+    resolveComponentReference(
       templatePath,
-      options.namespaces?.components,
+      options.namespaces,
+      componentGroupRootsCache,
     )
   );
 };
@@ -996,7 +763,7 @@ export function makeTwigPluginOptions(env) {
     namespaces: makeTwigNamespaces(env),
     functions: getTwigFunctionMap(),
     registerDrupalTwigFilters: shouldRegisterDrupalTwigFilters(env),
-    // Twig updates are handled by emulsifyTwigModulePlugin.handleHotUpdate.
+    // Twig updates are handled by emulsifyTwigModulePlugin.hotUpdate.
     // Vituum's full reload would defeat HMR by reloading the whole iframe on
     // every Twig save before module graph invalidation can update the story.
     reload: () => false,
@@ -1403,7 +1170,7 @@ export function emulsifyTwigModulePlugin(options) {
         };
       }
     },
-    handleHotUpdate({ file, server }) {
+    hotUpdate({ type, file, modules: changedModules = [] }) {
       const filePath = resolve(file);
       const componentRoot = options.namespaces?.components
         ? resolve(options.namespaces.components)
@@ -1442,7 +1209,11 @@ export function emulsifyTwigModulePlugin(options) {
         !!projectRoot &&
         isWithinRoot(resolve(projectRoot), filePath) &&
         fileExists !== knownFile;
-      const structuralChange = componentDirectoryChanged || projectPathChanged;
+      const structuralChange =
+        type === 'create' ||
+        type === 'delete' ||
+        componentDirectoryChanged ||
+        projectPathChanged;
 
       if (file.endsWith('.twig')) {
         compileCache.delete(filePath);
@@ -1459,7 +1230,7 @@ export function emulsifyTwigModulePlugin(options) {
          * directory invalidated. New or deleted files can change previous
          * resolution misses, so those events clear the full resolution cache.
          */
-        if (fileExists && knownFile) {
+        if (type === 'update' && fileExists && knownFile) {
           invalidateKnownResolutionCacheEntries(filePath);
         } else {
           resolutionCache.clear();
@@ -1475,6 +1246,9 @@ export function emulsifyTwigModulePlugin(options) {
       }
 
       if (structuralChange) {
+        // Every environment receives the event, including after shared known-
+        // file state was cleared. Namespace roots can also be outside a project.
+        resolutionCache.clear();
         compileCache.clear();
       }
 
@@ -1489,12 +1263,15 @@ export function emulsifyTwigModulePlugin(options) {
         return undefined;
       }
 
-      const moduleGraph = server?.moduleGraph;
+      const moduleGraph = this.environment?.moduleGraph;
       if (!moduleGraph?.getModulesByFile) {
         return undefined;
       }
 
-      const modules = new Set(moduleGraph.getModulesByFile(filePath) || []);
+      const modules = new Set([
+        ...changedModules,
+        ...(moduleGraph.getModulesByFile(filePath) || []),
+      ]);
       const dependencyModule = moduleGraph.getModuleById?.(dependencyModuleId);
       if (dependencyModule) {
         moduleGraph.invalidateModule?.(dependencyModule);

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

@@ -8,6 +8,11 @@
 import { readFileSync, readdirSync } from 'fs';
 import { relative, resolve } from 'path';
 import { fileURLToPath } from 'url';
+import {
+  resolveAssetRoots,
+  toAbsoluteAssetRoot,
+} from '../../utils/asset-roots.js';
+import { isStorybookOutput } from '../assets/storybook-output.js';
 import { safeExists } from '../../utils/fs-safe.js';
 import { toPosixPath } from '../../utils/paths.js';
 import { unique } from '../../../../src/extensions/shared/lists.js';
@@ -27,43 +32,15 @@ const ASSET_SOURCE_RUNTIME_URL = new 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'];
+// Keys stay Vite root-relative because the runtime looks asset sources up by
+// root-relative key. The values are the public URLs Storybook fetches, and they
+// stay relative to the preview document so a static build works at a domain
+// root and under any deployment subpath.
 const PUBLIC_ASSET_ROOTS = new Map([
-  ['/assets', '/assets'],
-  ['/dist/assets', '/assets'],
+  ['/assets', './assets'],
+  ['/dist/assets', './assets'],
 ]);
 
-/**
- * Resolve a configured asset root to an absolute filesystem path.
- *
- * @param {string} projectDir - Absolute project root.
- * @param {string} assetRoot - Absolute, project-relative, or Vite root-relative asset root.
- * @returns {string} Absolute filesystem path.
- */
-function toAbsoluteAssetRoot(projectDir, assetRoot) {
-  const normalizedProjectDir = toPosixPath(projectDir || '').replace(
-    /\/+$/,
-    '',
-  );
-  const normalizedRoot = toPosixPath(assetRoot || '').replace(/\/+$/, '');
-
-  if (!normalizedRoot) return '';
-  if (
-    normalizedProjectDir &&
-    (normalizedRoot === normalizedProjectDir ||
-      normalizedRoot.startsWith(`${normalizedProjectDir}/`))
-  ) {
-    return normalizedRoot;
-  }
-  if (normalizedRoot.startsWith('/') && normalizedProjectDir) {
-    if (safeExists(normalizedRoot)) {
-      return normalizedRoot;
-    }
-    return `${normalizedProjectDir}${normalizedRoot}`;
-  }
-
-  return toPosixPath(resolve(projectDir || '.', normalizedRoot));
-}
-
 /**
  * Resolve existing project asset roots for Storybook source() text imports.
  *
@@ -71,17 +48,8 @@ function toAbsoluteAssetRoot(projectDir, assetRoot) {
  * @returns {string[]} Existing Vite root-relative asset root paths.
  */
 export function assetSourceRoots(env) {
-  const configuredRoots =
-    Array.isArray(env?.projectStructure?.assetRoots) &&
-    env.projectStructure.assetRoots.length
-      ? env.projectStructure.assetRoots
-      : [];
-  const fallbackRoots = ['/assets', '/src/assets'];
-
   return unique(
-    [...configuredRoots, ...fallbackRoots]
-      .map((root) => toAbsoluteAssetRoot(env?.projectDir, root))
-      .filter((root) => root && safeExists(root))
+    resolveAssetRoots(env)
       .map((root) => toRootRelativePath(env?.projectDir, root))
       .filter(Boolean),
   );
@@ -116,20 +84,33 @@ function generatedAssetRootPrefixes() {
 /**
  * Build Vite glob patterns from text asset roots.
  *
+ * Project roots stay recursive. Generated roots contain build output, so only
+ * the aliases Twig can resolve from those roots belong in the source map.
+ *
  * @param {{ projectDir?: string, projectStructure?: { assetRoots?: string[] } }} env - Emulsify environment.
  * @returns {string[]} Root-relative text asset glob patterns.
  */
 export function assetSourceGlobPatterns(env) {
   const extensions = Array.from(INLINE_ASSET_EXTS).join(',');
-
-  return [...assetSourceRoots(env), ...generatedAssetSourceRoots(env)].map(
+  const projectPatterns = assetSourceRoots(env).map(
     (root) => `${root === '/' ? '' : root}/**/*.{${extensions}}`,
   );
+  const generatedPatterns = generatedAssetSourceRoots(env).flatMap((root) =>
+    Array.from(
+      GENERATED_ASSET_ALIASES,
+      (alias) => `${root === '/' ? '' : root}/${alias}`,
+    ),
+  );
+
+  return unique([...projectPatterns, ...generatedPatterns]);
 }
 
 /**
  * Return a public URL base for asset roots served by Storybook staticDirs.
  *
+ * The base is relative to Storybook's preview document rather than the domain
+ * root, so generated fetch URLs resolve under any deployment subpath.
+ *
  * @param {string} root - Vite root-relative asset source root.
  * @returns {string} Public URL base, or an empty string for non-public roots.
  */
@@ -226,9 +207,13 @@ export function publicAssetSourceEntries(env) {
  * Generate the virtual module source for lazy text asset maps.
  *
  * @param {{ projectDir?: string, projectStructure?: { assetRoots?: string[] } }} env - Emulsify environment.
+ * @param {{ inlineTextAssets?: boolean }} [options={}] - Generation options.
  * @returns {string} JavaScript module source.
  */
-export function generateVirtualTwigAssetSourcesModule(env) {
+export function generateVirtualTwigAssetSourcesModule(
+  env,
+  { inlineTextAssets = true } = {},
+) {
   const rootPrefixes = assetSourceRoots(env).map((root) =>
     `${root === '/' ? '' : root}/`.replace(/\/{2,}/g, '/'),
   );
@@ -239,7 +224,12 @@ export function generateVirtualTwigAssetSourcesModule(env) {
     ...generatedRootPrefixes,
     ...generatedAssetRootPrefixes(),
   ]);
-  const patterns = assetSourceGlobPatterns(env);
+  // Each glob entry becomes a lazy chunk carrying one asset's bytes as a
+  // JavaScript string. Storybook needs them so source('@assets/...') can inline
+  // an SVG synchronously; a theme build does not, and emitting them there just
+  // copies the asset tree into dist/ in another form. The fetch entries below
+  // keep source() working at runtime without bundling anything.
+  const patterns = inlineTextAssets ? assetSourceGlobPatterns(env) : [];
   const globEntries = patterns.length
     ? patterns
         .map(
@@ -304,8 +294,15 @@ export const getAssetText = assetSourceRuntime.getAssetText;
  * @returns {import('vite').PluginOption} Virtual module plugin.
  */
 export function virtualTwigAssetSourcesPlugin(env) {
+  let inlineTextAssets = true;
+
   return {
     name: 'emulsify-virtual-twig-asset-sources',
+
+    configResolved(config) {
+      inlineTextAssets = isStorybookOutput(config);
+    },
+
     resolveId(id) {
       if (id === VIRTUAL_TWIG_ASSET_SOURCES_ID) {
         return RESOLVED_VIRTUAL_TWIG_ASSET_SOURCES_ID;
@@ -318,7 +315,9 @@ export function virtualTwigAssetSourcesPlugin(env) {
     },
     load(id) {
       if (id === RESOLVED_VIRTUAL_TWIG_ASSET_SOURCES_ID) {
-        return generateVirtualTwigAssetSourcesModule(env);
+        return generateVirtualTwigAssetSourcesModule(env, {
+          inlineTextAssets,
+        });
       }
       if (id === RESOLVED_VIRTUAL_TWIG_ASSET_SOURCE_RUNTIME_ID) {
         this.addWatchFile(ASSET_SOURCE_RUNTIME_PATH);