@emulsify/core 4.0.3 → 4.1.0

package/.storybook/main.js

@@ -120,12 +120,58 @@ function readOptionalHtmlFragment(relativePath) {
  * @returns {Array<string|{from: string, to: string}>} Existing static directory entries.
  */
 function existingStaticDirs(staticDirs) {
-  return staticDirs.filter((staticDir) => {
+  const seen = new Set();
+  const existing = [];
+
+  for (const staticDir of staticDirs) {
     const directory =
       typeof staticDir === 'string' ? staticDir : staticDir.from;
 
-    return directory && fs.existsSync(directory);
-  });
+    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',
+    },
+  ]);
 }
 
 /**
@@ -265,22 +311,7 @@ const baseConfig = {
    *
    * @type {Array<string|{from: string, to: string}>}
    */
-  staticDirs: [
-    ...existingStaticDirs([
-      {
-        from: path.resolve(projectRoot, 'assets'),
-        to: '/assets',
-      },
-      {
-        from: path.resolve(projectRoot, 'dist/assets'),
-        to: '/assets',
-      },
-      {
-        from: path.resolve(projectRoot, 'dist'),
-        to: '/dist',
-      },
-    ]),
-  ],
+  staticDirs: buildAssetStaticDirs(resolvedStorybookEnv),
 
   /**
    * Enable the default addon set used by Emulsify.

package/.storybook/preview.js

@@ -3,7 +3,6 @@
  */
 
 import { getRules } from 'axe-core';
-import React from 'react';
 import { defaultDecorateStory, useEffect } from 'storybook/preview-api';
 import Twig from 'twig';
 import { twigExtensionInstallers } from 'virtual:emulsify-twig-extension-installers';
@@ -12,9 +11,9 @@ import {
   normalizePreviewOverrideModule,
 } from '../src/storybook/preview-parameters.js';
 import {
-  renderHtmlStoryResult,
-  withLegacyStoryToString,
-} from '../src/storybook/render-twig.js';
+  applyStoryDecorators,
+  renderPreviewStory,
+} from '../src/storybook/preview-decorator.js';
 import {
   attachStorybookBehaviors,
   fetchCSSFiles,
@@ -93,13 +92,7 @@ const AxeRules = enableRulesByTag([
  * @returns {Function} Decorated story function.
  */
 export const applyDecorators = (storyFn, decorators) =>
-  defaultDecorateStory(
-    (context) =>
-      withLegacyStoryToString(React.createElement(storyFn, context), () =>
-        storyFn(context),
-      ),
-    decorators,
-  );
+  applyStoryDecorators(defaultDecorateStory, storyFn, decorators);
 
 /**
  * Storybook decorators to apply platform-specific behavior after each story render.
@@ -115,7 +108,9 @@ export const decorators = [
    * @param {object} context Story context including args.
    * @returns {*} Rendered story.
    */
-  (Story, { args }) => {
+  (Story, context) => {
+    const { args } = context;
+
     useEffect(() => {
       void attachStorybookBehaviors({
         adapter: platformAdapter,
@@ -123,7 +118,7 @@ export const decorators = [
       });
     }, [args]);
 
-    return renderHtmlStoryResult(Story({ args }), {
+    return renderPreviewStory(Story, context, {
       platformAdapter,
     });
   },

package/README.md

@@ -34,7 +34,7 @@ See [Version Evolution](docs/version-evolution.md) for more release history.
 
 Twig and React are equally valid ways to build component libraries with Emulsify Core. The right authoring model depends on the consuming project:
 
-- Use Twig for CMS themes and server-rendered template systems. Drupal has a dedicated adapter today; Craft CMS and WordPress + Timber can use the `none` adapter unless a project adds platform-specific behavior.
+- Use Twig for CMS themes and server-rendered template systems. Drupal has a dedicated adapter today. WordPress and Timber projects should currently use `platform: "none"` unless a project adds its own platform-specific behavior.
 - Use React for standalone UI libraries, application components, or projects that already use React.
 - Use mixed Twig and React when a design system needs to document both CMS-rendered and JavaScript-rendered components in the same Storybook instance.
 
@@ -56,10 +56,18 @@ Every project should provide a `project.emulsify.json` file at the project root:
     "platform": "none",
     "name": "example",
     "machineName": "example"
+  },
+  "assets": {
+    "roots": ["./design/assets"]
   }
 }
 ```
 
+Asset files are discovered from the default asset roots and any additional
+roots configured in `project.emulsify.json`. Use asset roots when a project
+stores fonts, images, icons, or other static files outside the default
+locations.
+
 Common project scripts call the shared Emulsify Core Vite and Storybook config:
 
 - `storybook`: starts Storybook development.
@@ -86,7 +94,7 @@ The documentation is split by task:
 
 ## Known Limitations
 
-- Implemented platform adapters are currently `none` and `drupal`. WordPress + Timber and Craft CMS are supported as Twig-oriented use cases through the `none` adapter today. Dedicated adapters are future opportunities. See [Platform Adapters](docs/platform-adapters.md).
+- Implemented platform adapters are currently `none` and `drupal`. WordPress and Timber projects should currently use `platform: "none"`. This keeps Emulsify Core in platform-neutral mode while still supporting Twig-oriented component development. A dedicated WordPress adapter may be added later when WordPress-specific behavior is introduced. See [Platform Adapters](docs/platform-adapters.md).
 - Storybook's Twig resolver eagerly imports Twig modules and raw Twig source. This is reliable for `include()` and `source()`, but large Twig libraries should keep Storybook source roots intentional. See [Performance](docs/performance.md).
 - Production sourcemaps are enabled by default unless a project overrides Vite config through `config/emulsify-core/vite/plugins.*`. See [Performance](docs/performance.md).
 - Project extensions use the public `config/emulsify-core` directory: `config/emulsify-core/vite/plugins.*` for Vite, `config/emulsify-core/storybook/...` for Storybook, and `config/emulsify-core/a11y.config.js` for a11y. See [Extension Points](docs/extension-points.md).
@@ -103,7 +111,7 @@ Release-readiness coverage validates:
 - Projects using multiple `variant.structureImplementations`.
 - Mixed Twig + React Storybook projects.
 
-WordPress + Timber and Craft CMS are Twig-based project use cases that can use the `none` adapter today. Dedicated adapters for those platforms are future opportunities. The implemented adapters in this package are currently `none` and `drupal`.
+WordPress and Timber projects should currently use `platform: "none"`. This keeps Emulsify Core in platform-neutral mode while still supporting Twig-oriented component development. A dedicated WordPress adapter may be added later when WordPress-specific behavior is introduced. The implemented adapters in this package are currently `none` and `drupal`.
 
 ## Public Imports
 

package/config/a11y.config.js

@@ -7,6 +7,7 @@
 
 export default {
   storybookBuildDir: '../../../../.out',
+  discoverStories: true,
   pa11y: {
     includeNotices: false,
     includeWarnings: false,
@@ -17,7 +18,7 @@ export default {
     codes: ['landmark-one-main', 'page-has-heading-one'],
     descriptions: ['Ensures all page content is contained by landmarks'],
   },
-  // List of storybook component IDs defined and used in this project.
+  // Manual Storybook IDs merged with IDs discovered from built Storybook output.
   components: [
     'base-colors--palettes',
     'base-motion--usage',

package/config/vite/environment.js

@@ -9,6 +9,7 @@
  *  - `SDC`: boolean from project.emulsify.json `project.singleDirectoryComponents`.
  *  - `structureOverrides`: true when safe `variant.structureImplementations` exist.
  *  - `structureRoots`: array of directories from `variant.structureImplementations`.
+ *  - `assetRoots`: array of directories from safe `assets.roots` config.
  *  - `platformAdapter`: active adapter for platform-specific behavior.
  */
 
@@ -26,6 +27,7 @@ import { resolveProjectConfig } from './project-config.js';
  *   structureOverrides: boolean,
  *   structureRoots: string[],
  *   structureImplementations: Array<{name: string, directory: string}>,
+ *   assetRoots: string[],
  *   componentRoots: string[],
  *   globalRoots: string[],
  *   namespaceRoots: Record<string, string>,

package/config/vite/project-config.js

@@ -11,6 +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';
 
 /**
  * Cache normalized project config by project root and relevant env signature.
@@ -94,6 +95,65 @@ function normalizeStructureImplementations(projectDir, implementations = []) {
     .filter(Boolean);
 }
 
+/**
+ * Read public asset root configuration from supported project config paths.
+ *
+ * `assets.roots` is the documented public path.
+ * `projectStructure.assetRoots` and `project.assetRoots` remain supported for
+ * compatibility with earlier follow-up work and local project experiments.
+ *
+ * @param {object} rawConfig - Parsed project.emulsify.json contents.
+ * @returns {Array} Raw configured asset roots.
+ */
+function rawAssetRoots(rawConfig = {}) {
+  return [
+    ...(Array.isArray(rawConfig?.assets?.roots) ? rawConfig.assets.roots : []),
+    ...(Array.isArray(rawConfig?.projectStructure?.assetRoots)
+      ? rawConfig.projectStructure.assetRoots
+      : []),
+    ...(Array.isArray(rawConfig?.project?.assetRoots)
+      ? rawConfig.project.assetRoots
+      : []),
+  ];
+}
+
+/**
+ * Normalize public asset root declarations.
+ *
+ * Paths must resolve inside the project root. Invalid entries are retained as
+ * diagnostics so the audit command can report them without making Storybook or
+ * Vite builds fail for existing projects.
+ *
+ * @param {string} projectDir - Absolute project root.
+ * @param {Array} roots - Raw configured asset root entries.
+ * @returns {{roots: string[], ignored: string[]}} Normalized asset root state.
+ */
+function normalizeAssetRoots(projectDir, roots = []) {
+  if (!Array.isArray(roots)) return { roots: [], ignored: [] };
+
+  const normalizedRoots = [];
+  const ignored = [];
+
+  for (const item of roots) {
+    if (typeof item !== 'string' || !item.trim()) {
+      continue;
+    }
+
+    const directory = coerceToProjectPath(projectDir, item);
+    if (!directory) {
+      ignored.push(item);
+      continue;
+    }
+
+    normalizedRoots.push(normalize(directory));
+  }
+
+  return {
+    roots: unique(normalizedRoots),
+    ignored: unique(ignored),
+  };
+}
+
 /**
  * Normalize project config for current tooling consumers.
  *
@@ -140,6 +200,7 @@ export function resolveProjectConfig(
     root,
     rawStructureImplementations,
   );
+  const assetRoots = normalizeAssetRoots(root, rawAssetRoots(rawConfig));
   const structureRoots = structureImplementations.map(
     (implementation) => implementation.directory,
   );
@@ -149,6 +210,8 @@ export function resolveProjectConfig(
     srcExists,
     SDC: singleDirectoryComponents,
     structureImplementations,
+    assetRoots: assetRoots.roots,
+    ignoredAssetRoots: assetRoots.ignored,
     platformAdapter,
   });
 
@@ -166,6 +229,8 @@ export function resolveProjectConfig(
     structureOverrides: projectStructure.structureOverrides,
     structureImplementations,
     structureRoots,
+    assetRoots: projectStructure.assetRoots,
+    ignoredAssetRoots: projectStructure.ignoredAssetRoots,
     componentRoots: projectStructure.componentRoots,
     globalRoots: projectStructure.globalRoots,
     namespaceRoots: projectStructure.namespaceRoots,

package/config/vite/project-structure.js

@@ -7,7 +7,7 @@
  * process.
  */
 
-import { basename, relative, resolve, sep } from 'path';
+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';
@@ -181,6 +181,33 @@ function fallbackNamespaceRoots({
   return namespaceRoots;
 }
 
+/**
+ * Normalize project-scoped asset roots.
+ *
+ * @param {string} projectDir - Absolute project root.
+ * @param {string[]} assetRoots - Raw asset root paths.
+ * @returns {string[]} Safe absolute asset root paths.
+ */
+function normalizeAssetRoots(projectDir, assetRoots = []) {
+  if (!Array.isArray(assetRoots)) return [];
+
+  const projectRoot = resolve(projectDir);
+
+  return unique(
+    assetRoots
+      .map((root) =>
+        typeof root === 'string' && root.trim()
+          ? normalize(resolve(projectRoot, root))
+          : '',
+      )
+      .filter(
+        (root) =>
+          root &&
+          (root === projectRoot || root.startsWith(`${projectRoot}${sep}`)),
+      ),
+  );
+}
+
 /**
  * Resolve the serializable project structure model.
  *
@@ -190,6 +217,8 @@ function fallbackNamespaceRoots({
  *   srcExists?: boolean,
  *   SDC?: boolean,
  *   structureImplementations?: {name: string, directory: string}[],
+ *   assetRoots?: string[],
+ *   ignoredAssetRoots?: string[],
  *   platformAdapter?: object
  * }} [env] - Normalized project environment.
  * @returns {object} Project structure model.
@@ -214,6 +243,8 @@ export function resolveProjectStructure(env) {
     srcDir = defaultSrcDir,
     srcExists = safeExists(defaultSrcDir),
     SDC = false,
+    assetRoots: rawAssetRoots = [],
+    ignoredAssetRoots = [],
     platformAdapter = {},
   } = resolvedEnv;
   const structureImplementations =
@@ -244,6 +275,7 @@ export function resolveProjectStructure(env) {
       });
   const componentRoots = componentRootRecords.map((root) => root.directory);
   const globalRoots = globalRootRecords.map((root) => root.directory);
+  const assetRoots = normalizeAssetRoots(projectDir, rawAssetRoots);
   const namespaceRootValues = Object.values(namespaceRoots);
   const sourceRoots = unique(
     [...componentRoots, ...globalRoots].filter(Boolean),
@@ -278,7 +310,9 @@ export function resolveProjectStructure(env) {
     globalRootRecords,
     componentRoots,
     globalRoots,
+    assetRoots,
     sourceRoots,
+    ignoredAssetRoots: unique(ignoredAssetRoots),
     sourceRootRecords,
     storyRoots,
     twigRoots,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emulsify/core",
-  "version": "4.0.3",
+  "version": "4.1.0",
   "description": "Bundled tooling for Storybook development + Vite Build",
   "keywords": [
     "component library",
@@ -98,6 +98,7 @@
     "src/storybook/index.js",
     "src/storybook/main-config.js",
     "src/storybook/platform-behaviors.js",
+    "src/storybook/preview-decorator.js",
     "src/storybook/preview-parameters.js",
     "src/storybook/render-twig.js",
     "src/storybook/twig/include-function.js",
@@ -157,7 +158,7 @@
     "twatch": "npm run check-node-version && jest --no-coverage --watch --verbose"
   },
   "dependencies": {
-    "@babel/core": "^7.28.4",
+    "@babel/core": "^7.29.7",
     "@babel/eslint-parser": "^7.28.6",
     "@babel/preset-env": "^7.28.3",
     "@emulsify/cli": "^1.11.4",
@@ -171,7 +172,7 @@
     "autoprefixer": "^10.4.21",
     "axe-core": "^4.11.4",
     "babel-preset-minify": "^0.5.2",
-    "concurrently": "^9.2.1",
+    "concurrently": "^9.2.3",
     "eslint": "^9.39.4",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
@@ -200,7 +201,7 @@
     "stylelint-selector-bem-pattern": "^5.0.0",
     "twig": "^3.0.0",
     "twig-drupal-filters": "^3.2.0",
-    "vite": "^7.3.3",
+    "vite": "^7.3.5",
     "vite-plugin-sass-glob-import": "^6.0.0",
     "vite-plugin-static-copy": "^4.1.0",
     "vite-plugin-svg-sprite": "^0.7.0",

package/scripts/a11y.js

@@ -5,7 +5,7 @@
  * and reports issues.
  */
 
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import path from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
 import * as R from 'ramda';
@@ -16,15 +16,15 @@ import a11yConfig from '../config/a11y.config.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-const { storybookBuildDir, pa11y: pa11yConfig } = a11yConfig;
-
 // Project-specific configuration.
-let { ignore = {}, components = [] } = a11yConfig;
+let {
+  ignore = {},
+  components = [],
+  discoverStories = true,
+  storybookBuildDir,
+  pa11y: pa11yConfig = {},
+} = a11yConfig;
 
-/** Absolute path to Storybook build directory. */
-const STORYBOOK_BUILD_DIR = path.resolve(__dirname, '../', storybookBuildDir);
-/** Absolute path to Storybook iframe file used for per-story rendering. */
-const STORYBOOK_IFRAME = path.join(STORYBOOK_BUILD_DIR, 'iframe.html');
 /** Project-specific accessibility config path used by generated themes. */
 const PROJECT_A11Y_CONFIG = path.resolve(
   __dirname,
@@ -48,12 +48,26 @@ const loadProjectA11yConfig = async () => {
 /**
  * Apply project-specific a11y config values over shared defaults.
  *
- * @param {{ignore?: object, components?: string[]}} config - Project config.
+ * @param {{ignore?: object, components?: string[], discoverStories?: boolean, storybookBuildDir?: string, pa11y?: object}} config - Project config.
  * @returns {void}
  */
 const applyProjectA11yConfig = (config = {}) => {
   ignore = config.ignore || ignore;
-  components = config.components || components;
+  components = Array.isArray(config.components)
+    ? config.components
+    : components;
+  discoverStories =
+    typeof config.discoverStories === 'boolean'
+      ? config.discoverStories
+      : discoverStories;
+  storybookBuildDir =
+    typeof config.storybookBuildDir === 'string' && config.storybookBuildDir
+      ? config.storybookBuildDir
+      : storybookBuildDir;
+  pa11yConfig =
+    config.pa11y && typeof config.pa11y === 'object'
+      ? { ...pa11yConfig, ...config.pa11y }
+      : pa11yConfig;
 };
 
 /**
@@ -67,12 +81,128 @@ const printHelp = () => {
       'Usage: node scripts/a11y.js [options]',
       '',
       'Options:',
-      '  -r           Run pa11y against configured Storybook component IDs.',
+      '  -r           Run pa11y against discovered and configured Storybook story IDs.',
       '  -h, --help   Print this help text.',
     ].join('\n'),
   );
 };
 
+/**
+ * Resolve the configured Storybook build directory.
+ *
+ * @param {string} [buildDir=storybookBuildDir] - Configured build directory.
+ * @returns {string} Absolute Storybook build directory.
+ */
+const resolveStorybookBuildDir = (buildDir = storybookBuildDir) =>
+  path.resolve(__dirname, '../', buildDir);
+
+/**
+ * Resolve Storybook's iframe file used for per-story rendering.
+ *
+ * @param {string} [buildDir=storybookBuildDir] - Configured build directory.
+ * @returns {string} Absolute iframe.html path.
+ */
+const resolveStorybookIframe = (buildDir = storybookBuildDir) =>
+  path.join(resolveStorybookBuildDir(buildDir), 'iframe.html');
+
+/**
+ * Return unique non-empty Storybook IDs in first-seen order.
+ *
+ * @param {Array} values - Candidate story IDs.
+ * @returns {string[]} Unique story IDs.
+ */
+const normalizeStoryIds = (values = []) =>
+  Array.from(
+    new Set(
+      values
+        .filter((value) => typeof value === 'string')
+        .map((value) => value.trim())
+        .filter(Boolean),
+    ),
+  );
+
+/**
+ * Extract runnable story IDs from a Storybook index object.
+ *
+ * @param {object} index - Parsed Storybook index.json or stories.json.
+ * @returns {string[]} Story IDs.
+ */
+const storyIdsFromStorybookIndex = (index = {}) => {
+  const entries =
+    index?.entries && typeof index.entries === 'object'
+      ? index.entries
+      : index?.stories && typeof index.stories === 'object'
+        ? index.stories
+        : {};
+
+  return normalizeStoryIds(
+    Object.entries(entries)
+      .filter(([, entry]) => !entry?.type || entry.type === 'story')
+      .map(([id, entry]) =>
+        typeof entry?.id === 'string' && entry.id ? entry.id : id,
+      ),
+  );
+};
+
+/**
+ * Discover runnable Storybook story IDs from built Storybook output.
+ *
+ * @param {string} [buildDir=storybookBuildDir] - Configured Storybook build directory.
+ * @param {{warn?: Function}} [options] - Reporting options.
+ * @returns {string[]} Story IDs discovered from Storybook's generated index.
+ */
+const discoverStoryIds = (
+  buildDir = storybookBuildDir,
+  { warn = console.warn } = {},
+) => {
+  const indexPath = path.join(resolveStorybookBuildDir(buildDir), 'index.json');
+
+  if (!existsSync(indexPath)) {
+    warn(
+      `Storybook index not found at ${indexPath}; falling back to configured Pa11y story IDs.`,
+    );
+    return [];
+  }
+
+  try {
+    return storyIdsFromStorybookIndex(
+      JSON.parse(readFileSync(indexPath, 'utf8')),
+    );
+  } catch (error) {
+    warn(
+      `Unable to read Storybook index at ${indexPath}: ${
+        error.message || error
+      }; falling back to configured Pa11y story IDs.`,
+    );
+    return [];
+  }
+};
+
+/**
+ * Resolve the final Pa11y story ID list.
+ *
+ * @param {object} [options={}] - Resolution options.
+ * @param {string[]} [options.manualIds=components] - Manually configured IDs.
+ * @param {boolean} [options.discover=discoverStories] - Whether discovery is enabled.
+ * @param {string} [options.buildDir=storybookBuildDir] - Storybook build directory.
+ * @param {Function} [options.warn=console.warn] - Warning sink.
+ * @returns {string[]} Story IDs to lint.
+ */
+const resolvePa11yStoryIds = ({
+  manualIds = components,
+  discover = discoverStories,
+  buildDir = storybookBuildDir,
+  warn = console.warn,
+} = {}) => {
+  const manual = normalizeStoryIds(manualIds);
+  if (discover === false) return manual;
+
+  return normalizeStoryIds([
+    ...manual,
+    ...discoverStoryIds(buildDir, { warn }),
+  ]);
+};
+
 /**
  * Map pa11y/axe severity to a label (historically a color name).
  * Retained for backward compatibility, but not used for styling anymore.
@@ -155,7 +285,7 @@ const logReport = ({ issues, pageUrl }) => {
  * @returns {Promise<{ issues: Pa11yIssue[], pageUrl: string }>} Pa11y result.
  */
 const lintComponent = async (name) =>
-  pa11y(`${STORYBOOK_IFRAME}?id=${name}`, {
+  pa11y(`${resolveStorybookIframe()}?id=${name}`, {
     includeNotices: true,
     includeWarnings: true,
     runners: ['axe'],
@@ -188,15 +318,22 @@ if (R.includes(process.argv[2], ['-h', '--help'])) {
 } else if (R.pathEq(['argv', 2], '-r')(process)) {
   loadProjectA11yConfig().then((projectConfig) => {
     applyProjectA11yConfig(projectConfig);
-    return lintReportAndExit(components);
+    return lintReportAndExit(resolvePa11yStoryIds());
   });
 }
 
 export {
   severityToColor,
+  applyProjectA11yConfig,
+  discoverStoryIds,
   issueIsValid,
   logIssue,
   logReport,
   lintComponent,
   lintReportAndExit,
+  normalizeStoryIds,
+  resolvePa11yStoryIds,
+  resolveStorybookBuildDir,
+  resolveStorybookIframe,
+  storyIdsFromStorybookIndex,
 };

package/scripts/audit.js

@@ -5,7 +5,14 @@
  */
 
 import { lstatSync, readdirSync, statSync } from 'node:fs';
-import { basename, dirname, relative, resolve, sep } from 'node:path';
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  relative,
+  resolve,
+  sep,
+} from 'node:path';
 import { globSync } from 'glob';
 import { resolveProjectConfig } from '../config/vite/project-config.js';
 import {
@@ -68,6 +75,7 @@ const RECOMMENDED_PACKAGE_OVERRIDES = [
 ];
 const GENERATED_PACKAGE_SCRIPT_DOCS =
   'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/migration-4x.md#manual-packagejson-updates';
+const GENERATED_ASSET_ALIASES = new Set(['icons.svg']);
 
 /**
  * Cache source file reads for one top-level audit run.
@@ -388,6 +396,18 @@ function auditProjectConfig(context) {
     }
   }
 
+  for (const root of env.ignoredAssetRoots || []) {
+    findings.push(
+      makeFinding({
+        id: 'invalid-asset-root',
+        severity: 'warn',
+        filePath: resolve(projectDir, 'project.emulsify.json'),
+        message: `Configured asset root "${root}" was ignored because it resolves outside the project root.`,
+        docs: 'https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/project-structure.md#asset-roots',
+      }),
+    );
+  }
+
   return findings;
 }
 
@@ -726,6 +746,74 @@ function candidateKeysToFiles(keys, env) {
   );
 }
 
+/**
+ * Resolve an audit asset root using Storybook's root-relative convention.
+ *
+ * @param {string} projectDir - Absolute project root.
+ * @param {string} assetRoot - Configured, absolute, or project-relative root.
+ * @returns {string} Absolute filesystem path, or an empty string.
+ */
+function resolveAuditAssetRoot(projectDir, assetRoot) {
+  if (typeof assetRoot !== 'string' || !assetRoot.trim()) return '';
+
+  const normalizedProjectDir = resolve(projectDir || process.cwd());
+  const normalizedRoot = assetRoot.trim();
+
+  if (isAbsolute(normalizedRoot)) {
+    const absoluteRoot = resolve(normalizedRoot);
+
+    return safeExists(absoluteRoot)
+      ? absoluteRoot
+      : resolve(normalizedProjectDir, `.${normalizedRoot}`);
+  }
+
+  return resolve(normalizedProjectDir, normalizedRoot);
+}
+
+/**
+ * Return filesystem roots that Storybook can use for @assets source() calls.
+ *
+ * @param {object} env - Normalized environment.
+ * @param {object} [options={}] - Asset root options.
+ * @param {boolean} [options.includeGenerated=false] - Include generated roots.
+ * @returns {string[]} Absolute asset roots.
+ */
+function auditAssetRoots(env = {}, { includeGenerated = false } = {}) {
+  const projectDir = env.projectDir || process.cwd();
+  const configuredRoots = Array.isArray(env?.projectStructure?.assetRoots)
+    ? env.projectStructure.assetRoots
+    : [];
+  const fallbackRoots = ['assets', 'src/assets'];
+  const generatedRoots = includeGenerated ? ['dist/assets'] : [];
+
+  return Array.from(
+    new Set(
+      [...fallbackRoots, ...configuredRoots, ...generatedRoots]
+        .map((root) => resolveAuditAssetRoot(projectDir, root))
+        .filter(Boolean),
+    ),
+  );
+}
+
+/**
+ * Determine whether an @assets reference resolves through Storybook asset roots.
+ *
+ * @param {string} reference - Twig @assets reference.
+ * @param {object} env - Normalized environment.
+ * @returns {boolean} TRUE when a candidate exists.
+ */
+function resolvesAssetReference(reference, env) {
+  const relAsset = reference.replace(/^@assets\//, '');
+  if (!relAsset) return false;
+  const includeGenerated = GENERATED_ASSET_ALIASES.has(relAsset);
+
+  return auditAssetRoots(env, { includeGenerated }).some((root) => {
+    const candidate = resolve(root, relAsset);
+
+    return isSameOrInside(candidate, root) && safeExists(candidate);
+  });
+}
+
 /**
  * Determine whether a Twig include/source reference resolves.
  *
@@ -738,8 +826,7 @@ export function resolvesTwigReference(reference, filePath, env) {
   if (!reference || /^https?:\/\//i.test(reference)) return true;
 
   if (reference.startsWith('@assets/')) {
-    const relAsset = reference.replace(/^@assets\//, '');
-    return safeExists(resolve(env.projectDir, 'assets', relAsset));
+    return resolvesAssetReference(reference, env);
   }
 
   const candidates =
@@ -971,7 +1058,7 @@ function styleRuntimeDirectories(filePath, env, projectDir) {
 function auditCssAssetReferences(context) {
   const { env, projectDir, styleFiles } = context;
   const findings = [];
-  const projectAssetsDir = resolve(projectDir, 'assets');
+  const projectAssetRoots = auditAssetRoots(env).filter(safeIsDirectory);
   const styleSourceRoots = env.projectStructure?.sourceRoots || [];
 
   for (const filePath of styleFiles) {
@@ -1017,7 +1104,7 @@ function auditCssAssetReferences(context) {
       }
 
       if (
-        isSameOrInside(resolvedAsset, projectAssetsDir) &&
+        projectAssetRoots.some((root) => isSameOrInside(resolvedAsset, root)) &&
         (!sourceAsset || runtimeAsset || assetPath.startsWith('..'))
       ) {
         findings.push(

package/src/storybook/preview-decorator.js

@@ -0,0 +1,45 @@
+/**
+ * @file Shared helpers for Storybook preview decorator wiring.
+ */
+
+import React from 'react';
+import {
+  renderHtmlStoryResult,
+  withLegacyStoryToString,
+} from './render-twig.js';
+
+/**
+ * Render a Storybook story function as a React element with full context props.
+ *
+ * @param {Function} storyFn - Storybook story function.
+ * @param {object} context - Full Storybook story context.
+ * @returns {React.ReactElement} React story element.
+ */
+export function createStoryElement(storyFn, context) {
+  return withLegacyStoryToString(React.createElement(storyFn, context), () =>
+    storyFn(context),
+  );
+}
+
+/**
+ * Apply Storybook decorators while preserving full story context.
+ *
+ * @param {Function} decorateStory - Storybook decorator applier.
+ * @param {Function} storyFn - Storybook story function.
+ * @param {Function[]} decorators - Storybook decorators.
+ * @returns {Function} Decorated story function.
+ */
+export const applyStoryDecorators = (decorateStory, storyFn, decorators) =>
+  decorateStory((context) => createStoryElement(storyFn, context), decorators);
+
+/**
+ * Render a preview Story callback through Emulsify's HTML compatibility layer.
+ *
+ * @param {Function} Story - Decorated Storybook story callback.
+ * @param {object} context - Full Storybook story context.
+ * @param {object} [options={}] - Render options.
+ * @returns {*} Rendered Storybook story result.
+ */
+export function renderPreviewStory(Story, context, options = {}) {
+  return renderHtmlStoryResult(Story(context), options);
+}