@emulsify/core 4.3.1 → 4.4.0

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);

package/config/vite/project-config.js

@@ -7,7 +7,7 @@
  * per project directory and relevant environment signature for one process.
  */
 
-import { normalize, resolve, sep } from 'path';
+import { normalize, posix, resolve, sep, win32 } from 'path';
 import { getPlatformAdapter, normalizePlatformName } from './platforms.js';
 import { resolveProjectStructure } from './project-structure.js';
 import { safeExists, safeReadJson } from './utils/fs-safe.js';
@@ -47,6 +47,51 @@ function normalizeIdentifier(value) {
   return (value || '').toString().toLowerCase().trim();
 }
 
+/** Match Unicode characters in the General_Category=Control class. */
+const CONTROL_CHARACTER_RE = /\p{Cc}/u;
+
+/**
+ * Normalize a structure implementation name without allowing path semantics.
+ *
+ * Names become output-directory segments and Twig namespace keys. Rejecting
+ * path-like values is safer than stripping them: two distinct configured
+ * names must never silently collapse onto the same output directory.
+ *
+ * @param {*} value - Candidate implementation name.
+ * @param {number} index - Implementation index for fallback and diagnostics.
+ * @returns {string} Safe normalized name.
+ * @throws {Error} When an explicit name is not a control-free path segment.
+ */
+function normalizeStructureImplementationName(value, index) {
+  if (typeof value !== 'string') {
+    return `structure-${index + 1}`;
+  }
+
+  if (CONTROL_CHARACTER_RE.test(value)) {
+    throw new Error(
+      `Invalid variant.structureImplementations[${index}].name ${JSON.stringify(value)}: expected a single path segment without control characters.`,
+    );
+  }
+
+  if (!value.trim()) {
+    return `structure-${index + 1}`;
+  }
+
+  const name = normalizeIdentifier(value);
+  if (
+    name === '.' ||
+    name === '..' ||
+    posix.basename(name) !== name ||
+    win32.basename(name) !== name
+  ) {
+    throw new Error(
+      `Invalid variant.structureImplementations[${index}].name ${JSON.stringify(value)}: expected a single path segment.`,
+    );
+  }
+
+  return name;
+}
+
 /**
  * Build the environment signature for config values that affect resolution.
  *
@@ -60,39 +105,88 @@ function projectConfigEnvSignature(env = {}) {
     EMULSIFY_PLATFORM: platformOverride
       ? normalizePlatformName(platformOverride)
       : '',
+    EMULSIFY_ASSET_REBASE: normalizeIdentifier(env.EMULSIFY_ASSET_REBASE),
+    EMULSIFY_SELF_CONTAINED_OUTPUT: normalizeIdentifier(
+      env.EMULSIFY_SELF_CONTAINED_OUTPUT,
+    ),
   });
 }
 
+/**
+ * Resolve whether the build may repair unresolvable CSS asset URLs.
+ *
+ * On by default: the URLs it repairs are already broken in every output shape
+ * except mirrored Drupal SDC, so an opt-in would leave the defect in place for
+ * anyone who does not read a changelog. The env override is the bisect tool —
+ * a consumer can turn the repair off for one build without editing config.
+ *
+ * @param {object} rawConfig - Parsed project.emulsify.json contents.
+ * @param {NodeJS.ProcessEnv|Record<string,string>} env - Environment values.
+ * @returns {boolean} TRUE when the rebase is enabled.
+ */
+function resolveAssetRebase(rawConfig = {}, env = {}) {
+  const override = normalizeIdentifier(env.EMULSIFY_ASSET_REBASE);
+  if (override) return !['0', 'false', 'off', 'no'].includes(override);
+
+  return rawConfig?.assets?.rebase !== false;
+}
+
+/**
+ * Resolve whether project assets remain inside the build output.
+ *
+ * Self-contained output preserves the existing deployment contract by default.
+ * Projects that deploy the complete theme directory may opt into leaner output
+ * through project config or a one-build environment override.
+ *
+ * @param {object} rawConfig - Parsed project.emulsify.json contents.
+ * @param {NodeJS.ProcessEnv|Record<string,string>} env - Environment values.
+ * @returns {boolean} TRUE when project assets remain in the output directory.
+ */
+function resolveSelfContainedOutput(rawConfig = {}, env = {}) {
+  const override = normalizeIdentifier(env.EMULSIFY_SELF_CONTAINED_OUTPUT);
+  if (override) return !['0', 'false', 'off', 'no'].includes(override);
+
+  return rawConfig?.assets?.selfContainedOutput !== false;
+}
+
 /**
  * Normalize variant structure implementation declarations.
  *
  * @param {string} projectDir - Absolute project root.
  * @param {Array} implementations - Raw implementation entries.
  * @returns {{name: string, directory: string}[]} Safe implementation entries.
+ * @throws {Error} When valid entries normalize to the same name.
  */
 function normalizeStructureImplementations(projectDir, implementations = []) {
   if (!Array.isArray(implementations)) return [];
 
-  return implementations
-    .map((item, index) => {
-      const rawDirectory =
-        typeof item?.directory === 'string' ? item.directory : null;
-      const directory = rawDirectory
-        ? coerceToProjectPath(projectDir, rawDirectory)
-        : null;
-      if (!directory) return null;
-
-      const name =
-        typeof item?.name === 'string' && item.name.trim()
-          ? normalizeIdentifier(item.name)
-          : `structure-${index + 1}`;
-
-      return {
-        name,
-        directory: normalize(directory),
-      };
-    })
-    .filter(Boolean);
+  const normalized = [];
+  const nameIndexes = new Map();
+
+  for (const [index, item] of implementations.entries()) {
+    const name = normalizeStructureImplementationName(item?.name, index);
+    const rawDirectory =
+      typeof item?.directory === 'string' ? item.directory : null;
+    const directory = rawDirectory
+      ? coerceToProjectPath(projectDir, rawDirectory)
+      : null;
+    if (!directory) continue;
+
+    const previousIndex = nameIndexes.get(name);
+    if (previousIndex !== undefined) {
+      throw new Error(
+        `Invalid variant.structureImplementations[${index}].name ${JSON.stringify(item?.name)}: normalized name ${JSON.stringify(name)} duplicates variant.structureImplementations[${previousIndex}].name.`,
+      );
+    }
+
+    nameIndexes.set(name, index);
+    normalized.push({
+      name,
+      directory: normalize(directory),
+    });
+  }
+
+  return normalized;
 }
 
 /**
@@ -201,6 +295,8 @@ export function resolveProjectConfig(
     rawStructureImplementations,
   );
   const assetRoots = normalizeAssetRoots(root, rawAssetRoots(rawConfig));
+  const assetRebase = resolveAssetRebase(rawConfig, env);
+  const selfContainedOutput = resolveSelfContainedOutput(rawConfig, env);
   const structureRoots = structureImplementations.map(
     (implementation) => implementation.directory,
   );
@@ -212,6 +308,8 @@ export function resolveProjectConfig(
     structureImplementations,
     assetRoots: assetRoots.roots,
     ignoredAssetRoots: assetRoots.ignored,
+    assetRebase,
+    selfContainedOutput,
     platformAdapter,
   });
 
@@ -231,6 +329,8 @@ export function resolveProjectConfig(
     structureRoots,
     assetRoots: projectStructure.assetRoots,
     ignoredAssetRoots: projectStructure.ignoredAssetRoots,
+    assetRebase: projectStructure.assetRebase,
+    selfContainedOutput: projectStructure.selfContainedOutput,
     componentRoots: projectStructure.componentRoots,
     globalRoots: projectStructure.globalRoots,
     namespaceRoots: projectStructure.namespaceRoots,

package/config/vite/project-structure.js

@@ -219,6 +219,8 @@ function normalizeAssetRoots(projectDir, assetRoots = []) {
  *   structureImplementations?: {name: string, directory: string}[],
  *   assetRoots?: string[],
  *   ignoredAssetRoots?: string[],
+ *   assetRebase?: boolean,
+ *   selfContainedOutput?: boolean,
  *   platformAdapter?: object
  * }} [env] - Normalized project environment.
  * @returns {object} Project structure model.
@@ -245,6 +247,8 @@ export function resolveProjectStructure(env) {
     SDC = false,
     assetRoots: rawAssetRoots = [],
     ignoredAssetRoots = [],
+    assetRebase = true,
+    selfContainedOutput = true,
     platformAdapter = {},
   } = resolvedEnv;
   const structureImplementations =
@@ -311,6 +315,8 @@ export function resolveProjectStructure(env) {
     componentRoots,
     globalRoots,
     assetRoots,
+    assetRebase: assetRebase !== false,
+    selfContainedOutput: selfContainedOutput !== false,
     sourceRoots,
     ignoredAssetRoots: unique(ignoredAssetRoots),
     sourceRootRecords,

package/config/vite/utils/asset-roots.js

@@ -0,0 +1,205 @@
+/**
+ * @file Shared project asset root resolution.
+ *
+ * Three places used to keep their own copy of "where does `/assets/...` come
+ * from": the audit (`scripts/audit/lib/twig.js`), the Twig source() virtual
+ * module (`config/vite/plugins/twig/virtual-twig-asset-sources.js`), and
+ * Storybook's static mounts (`.storybook/main-static-assets.js`). They
+ * disagreed on precedence, so the audit could name a root that Storybook
+ * shadowed. This module is the single list; every caller delegates here.
+ *
+ * Precedence is configured `assets.roots` first, then root `assets/`, then
+ * `src/assets/` — the order Storybook actually serves at `/assets`, which is
+ * what an author's `url('/assets/...')` resolves against at review time.
+ */
+
+import { statSync } from 'fs';
+import { isAbsolute, relative, resolve, sep, win32 } from 'path';
+
+import { safeExists, safeRealPath } from './fs-safe.js';
+import { toPosixPath } from './paths.js';
+import { unique } from '../../../src/extensions/shared/lists.js';
+
+/**
+ * Asset roots every project gets, whether or not `assets.roots` is configured.
+ *
+ * @type {string[]}
+ */
+export const DEFAULT_ASSET_ROOTS = ['assets', 'src/assets'];
+
+/**
+ * Build output roots, opt-in because a build that resolved through its own
+ * previous output would not be reproducible from a clean tree.
+ *
+ * @type {string[]}
+ */
+export const GENERATED_ASSET_ROOTS = ['dist/assets'];
+
+/**
+ * Determine whether a path is the same as a directory or inside it.
+ *
+ * @param {string} candidate - Absolute candidate path.
+ * @param {string} directory - Absolute directory path.
+ * @returns {boolean} TRUE when the candidate cannot escape the directory.
+ */
+function isSameOrInside(candidate, directory) {
+  if (candidate === directory) return true;
+  const rel = relative(directory, candidate);
+
+  // On Windows, `relative()` returns the target unchanged when it sits on
+  // another volume — `relative('C:\\p\\assets', 'D:\\out\\x.svg')` is
+  // `'D:\\out\\x.svg'`, and a UNC share behaves the same way. Neither result
+  // begins with `..`, so the checks below would read an escape as containment.
+  if (isAbsolute(rel)) return false;
+
+  return Boolean(rel) && !rel.startsWith('..') && !rel.includes(`..${sep}`);
+}
+
+/**
+ * Determine whether an asset tail names a volume instead of a relative path.
+ *
+ * A tail is everything after the `assets/` prefix in an authored URL, so it is
+ * relative by construction. A drive-qualified (`D:/x.svg`), drive-relative
+ * (`D:x.svg`), or UNC (`\\server\share\x.svg`) tail is therefore malformed,
+ * and on Windows `resolve()` would switch away from the asset root. That also
+ * rejects a POSIX-legal first segment such as `x:y.png`: it is syntactically
+ * indistinguishable from a Windows drive-relative path. Windows semantics are
+ * checked on every platform so the API remains portable and testable in CI.
+ *
+ * @param {string} tail - Asset path relative to an asset root.
+ * @returns {boolean} TRUE when the tail escapes any root it is resolved from.
+ */
+function isVolumeQualified(tail) {
+  return isAbsolute(tail) || Boolean(win32.parse(tail).root);
+}
+
+/**
+ * Determine whether an asset candidate is a regular file.
+ *
+ * @param {string} candidate - Absolute candidate path.
+ * @returns {boolean} TRUE when the candidate is a file.
+ */
+function isFile(candidate) {
+  try {
+    return statSync(candidate).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve an asset root declaration to an absolute filesystem path.
+ *
+ * Accepts the three forms consumers write: an absolute filesystem path, a
+ * project-relative path (`./design-system/assets`), and Vite's root-relative
+ * form (`/assets`), which is what `project.emulsify.json` and Storybook use.
+ * An absolute-looking root that neither sits inside the project nor exists on
+ * disk is reinterpreted as root-relative, matching the behavior both previous
+ * copies had.
+ *
+ * @param {string} projectDir - Absolute project root.
+ * @param {string} assetRoot - Absolute, project-relative, or root-relative root.
+ * @returns {string} Absolute filesystem path, or an empty string.
+ */
+export function toAbsoluteAssetRoot(projectDir, assetRoot) {
+  if (typeof assetRoot !== 'string') return '';
+
+  const trimmed = assetRoot.trim().replace(/[/\\]+$/, '');
+  if (!trimmed) return '';
+
+  const base = resolve(projectDir || process.cwd());
+
+  if (isAbsolute(trimmed)) {
+    const absolute = resolve(trimmed);
+    if (isSameOrInside(absolute, base) || safeExists(absolute)) {
+      return absolute;
+    }
+
+    // Vite root-relative: "/assets" means "<projectDir>/assets".
+    return resolve(base, `.${toPosixPath(trimmed)}`);
+  }
+
+  return resolve(base, trimmed);
+}
+
+/**
+ * Resolve the ordered asset roots for a project.
+ *
+ * @param {{projectDir?: string, projectStructure?: {assetRoots?: string[]}}} [env={}] - Emulsify environment.
+ * @param {object} [options={}] - Resolution options.
+ * @param {boolean} [options.includeGenerated=false] - Append `dist/assets`.
+ * @param {boolean} [options.existingOnly=true] - Drop roots absent from disk.
+ * @returns {string[]} Absolute asset roots, in precedence order.
+ */
+export function resolveAssetRoots(
+  env = {},
+  { includeGenerated = false, existingOnly = true } = {},
+) {
+  const projectDir = env?.projectDir || process.cwd();
+  const configured = Array.isArray(env?.projectStructure?.assetRoots)
+    ? env.projectStructure.assetRoots
+    : [];
+
+  const roots = unique(
+    [
+      ...configured,
+      ...DEFAULT_ASSET_ROOTS,
+      ...(includeGenerated ? GENERATED_ASSET_ROOTS : []),
+    ]
+      .map((root) => toAbsoluteAssetRoot(projectDir, root))
+      .filter(Boolean),
+  );
+
+  return existingOnly ? roots.filter((root) => safeExists(root)) : roots;
+}
+
+/**
+ * Resolve a published asset path (the part after `/assets/`) against the roots.
+ * The tail must already be relative and portable across POSIX and Windows;
+ * leading separators and Windows volume syntax are rejected as malformed.
+ *
+ * Overlapping roots are normal — a project can declare `./assets` explicitly
+ * and still pick up the implicit root — so candidates are collapsed by their
+ * canonical path before ambiguity is decided. A genuine ambiguity means two
+ * different files answer to one URL, which no caller may guess at.
+ *
+ * @param {string} tail - Asset path relative to an asset root.
+ * @param {string[]} [roots=[]] - Absolute asset roots, in precedence order.
+ * @returns {{status: 'resolved'|'ambiguous'|'missing', file?: string, root?: string, candidates: string[]}} Resolution.
+ */
+export function resolveAssetTail(tail, roots = []) {
+  const cleaned = String(tail || '').trim();
+  if (!cleaned || isVolumeQualified(cleaned)) {
+    return { status: 'missing', candidates: [] };
+  }
+
+  const seen = new Set();
+  /** @type {{file: string, root: string}[]} */
+  const matches = [];
+
+  for (const root of roots) {
+    const candidate = resolve(root, cleaned);
+
+    // A tail such as `../../etc/passwd` must not escape its root.
+    if (!isSameOrInside(candidate, root)) continue;
+    if (!isFile(candidate)) continue;
+
+    const key = safeRealPath(candidate);
+    if (seen.has(key)) continue;
+
+    seen.add(key);
+    matches.push({ file: candidate, root });
+  }
+
+  if (!matches.length) return { status: 'missing', candidates: [] };
+
+  const candidates = matches.map((match) => match.file);
+  if (matches.length > 1) return { status: 'ambiguous', candidates };
+
+  return {
+    status: 'resolved',
+    file: matches[0].file,
+    root: matches[0].root,
+    candidates,
+  };
+}