@emulsify/core 4.0.2 → 4.0.4

package/.storybook/preview.js

@@ -115,7 +115,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 +125,7 @@ export const decorators = [
       });
     }, [args]);
 
-    return renderHtmlStoryResult(Story({ args }), {
+    return renderHtmlStoryResult(Story(context), {
       platformAdapter,
     });
   },

package/.storybook/utils.js

@@ -5,6 +5,7 @@
 import {
   attachStorybookBehaviors,
   genericStorybookAdapter,
+  noneStorybookAdapter,
   normalizeStorybookPlatformAdapter,
 } from '../src/storybook/platform-behaviors.js';
 import { setupTwig } from '../src/storybook/twig/setup.js';
@@ -93,6 +94,7 @@ export {
   attachStorybookBehaviors,
   fetchCSSFiles,
   genericStorybookAdapter,
+  noneStorybookAdapter,
   normalizeStorybookPlatformAdapter,
   setupTwig,
 };

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 generic adapter unless a project adds platform-specific behavior.
+- 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 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.
 
@@ -53,7 +53,7 @@ Every project should provide a `project.emulsify.json` file at the project root:
 ```json
 {
   "project": {
-    "platform": "generic",
+    "platform": "none",
     "name": "example",
     "machineName": "example"
   }
@@ -77,7 +77,7 @@ The documentation is split by task:
 | [Component Authoring](docs/component-authoring.md)        | Choosing Twig, React, or mixed Storybook authoring and comparing component examples.                                  |
 | [Storybook](docs/storybook.md)                            | Rendering Twig stories, using `renderTwig()`, understanding Twig runtime helpers, and mixing Twig with React stories. |
 | [Project Structure And Output](docs/project-structure.md) | Configuring `src/components`, root `./components`, `variant.structureImplementations`, and expected output paths.     |
-| [Platform Adapters](docs/platform-adapters.md)            | Understanding `generic`, `drupal`, platform resolution order, and Drupal SDC behavior.                                |
+| [Platform Adapters](docs/platform-adapters.md)            | Understanding `none`, `drupal`, platform resolution order, and Drupal SDC behavior.                                   |
 | [Extension Points](docs/extension-points.md)              | Adding Vite plugins, Tailwind CSS, Storybook preview overrides, and other framework tooling.                          |
 | [Performance](docs/performance.md)                        | Understanding sourcemaps, eager Twig imports, Tailwind scanning, copied files, and fixture validation.                |
 | [Native Twig Extensions](docs/native-twig-extensions.md)  | Using `bem()`, `add_attributes()`, and `switch/case/default/endswitch` in Twig.js.                                    |
@@ -86,24 +86,24 @@ The documentation is split by task:
 
 ## Known Limitations
 
-- Implemented platform adapters are currently `generic` and `drupal`. WordPress + Timber and Craft CMS are supported as Twig-oriented use cases through the generic adapter today; dedicated adapters are future opportunities. See [Platform Adapters](docs/platform-adapters.md).
+- 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).
 - 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).
 - Webpack-specific customizations must be migrated manually to Vite plugins or `extendConfig()`. See [Migration](docs/migration-4x.md).
-- Drupal SDC mirroring only applies when the Drupal adapter and SDC settings are enabled. Generic projects should expect output to remain in `dist/`. See [Platform Adapters](docs/platform-adapters.md).
+- Drupal SDC mirroring only applies when the Drupal adapter and SDC settings are enabled. `none` projects should expect output to remain in `dist/`. See [Platform Adapters](docs/platform-adapters.md).
 
 ## Supported Project Shapes
 
 Release-readiness coverage validates:
 
 - Drupal SDC projects using `src/components`.
-- Generic Twig projects using `src/components`.
+- `none` platform Twig projects using `src/components`.
 - Root `./components` projects.
 - 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 `generic` adapter today. Dedicated adapters for those platforms are future opportunities. The implemented adapters in this package are currently `generic` and `drupal`.
+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`.
 
 ## Public Imports
 

package/config/vite/environment.js

@@ -5,7 +5,7 @@
  * entries, plugins, and the Vite config.
  *
  * Highlights:
- *  - `platform`: from env var or project.emulsify.json (default "generic").
+ *  - `platform`: from env var or project.emulsify.json (default "none").
  *  - `SDC`: boolean from project.emulsify.json `project.singleDirectoryComponents`.
  *  - `structureOverrides`: true when safe `variant.structureImplementations` exist.
  *  - `structureRoots`: array of directories from `variant.structureImplementations`.
@@ -21,7 +21,7 @@ import { resolveProjectConfig } from './project-config.js';
  *   projectDir: string,
  *   srcDir: string,
  *   srcExists: boolean,
- *   platform: 'drupal' | 'generic' | string,
+ *   platform: 'drupal' | 'none' | string,
  *   SDC: boolean,
  *   structureOverrides: boolean,
  *   structureRoots: string[],

package/config/vite/platforms.js

@@ -5,8 +5,8 @@
  * decisions can be used by Node-side Vite config and Storybook browser code.
  */
 
-const genericAdapter = {
-  name: 'generic',
+const noneAdapter = {
+  name: 'none',
   outputStrategy: 'dist',
   storybook: {
     loadDrupalBehaviorShim: false,
@@ -36,7 +36,8 @@ const drupalAdapter = {
 };
 
 const adapters = {
-  generic: genericAdapter,
+  none: noneAdapter,
+  generic: noneAdapter,
   drupal: drupalAdapter,
 };
 
@@ -50,21 +51,39 @@ function cloneAdapter(adapter) {
   return JSON.parse(JSON.stringify(adapter));
 }
 
+/**
+ * Normalize configured platform names to canonical identifiers.
+ *
+ * `generic` is retained as a legacy alias for existing projects, but new
+ * configuration should use `none` for projects without platform-specific
+ * behavior.
+ *
+ * @param {*} platform - Candidate platform name.
+ * @returns {string} Canonical platform name.
+ */
+export function normalizePlatformName(platform = 'none') {
+  const key = (platform || '').toString().toLowerCase().trim();
+  if (!key || key === 'generic') {
+    return 'none';
+  }
+  return key;
+}
+
 /**
  * Resolve the platform adapter for a normalized platform name.
  *
- * Unknown platforms intentionally use generic behavior while preserving the
+ * Unknown platforms intentionally use `none` behavior while preserving the
  * resolved `platform` string separately on the environment object.
  *
- * @param {string} [platform='generic'] - Normalized platform name.
+ * @param {string} [platform='none'] - Normalized platform name.
  * @returns {object} Serializable platform adapter.
  */
-export function getPlatformAdapter(platform = 'generic') {
-  const key = (platform || 'generic').toString().toLowerCase().trim();
+export function getPlatformAdapter(platform = 'none') {
+  const key = normalizePlatformName(platform);
   if (key === 'drupal') {
     return cloneAdapter(drupalAdapter);
   }
-  return cloneAdapter(genericAdapter);
+  return cloneAdapter(noneAdapter);
 }
 
 export { adapters };

package/config/vite/project-config.js

@@ -8,7 +8,7 @@
  */
 
 import { normalize, resolve, sep } from 'path';
-import { getPlatformAdapter } from './platforms.js';
+import { getPlatformAdapter, normalizePlatformName } from './platforms.js';
 import { resolveProjectStructure } from './project-structure.js';
 import { safeExists, safeReadJson } from './utils/fs-safe.js';
 
@@ -53,8 +53,12 @@ function normalizeIdentifier(value) {
  * @returns {string} Stable cache-key segment.
  */
 function projectConfigEnvSignature(env = {}) {
+  const platformOverride = normalizeIdentifier(env.EMULSIFY_PLATFORM);
+
   return JSON.stringify({
-    EMULSIFY_PLATFORM: normalizeIdentifier(env.EMULSIFY_PLATFORM),
+    EMULSIFY_PLATFORM: platformOverride
+      ? normalizePlatformName(platformOverride)
+      : '',
   });
 }
 
@@ -119,11 +123,12 @@ export function resolveProjectConfig(
   const srcExists = safeExists(srcCandidate);
   const srcDir = srcExists ? srcCandidate : resolve(root, 'components');
 
-  const platform =
+  const resolvedPlatform =
     normalizeIdentifier(env.EMULSIFY_PLATFORM) ||
     normalizeIdentifier(rawConfig?.project?.platform) ||
     normalizeIdentifier(rawConfig?.variant?.platform) ||
-    'generic';
+    'none';
+  const platform = normalizePlatformName(resolvedPlatform);
   const platformAdapter = getPlatformAdapter(platform);
 
   const singleDirectoryComponents = Boolean(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emulsify/core",
-  "version": "4.0.2",
+  "version": "4.0.4",
   "description": "Bundled tooling for Storybook development + Vite Build",
   "keywords": [
     "component library",
@@ -157,7 +157,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 +171,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 +200,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/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.
@@ -329,7 +337,7 @@ function resolveAuditEnvironment(projectDir) {
     return {
       env: {
         projectDir,
-        platform: 'generic',
+        platform: 'none',
         namespaceRoots: {},
         projectStructure: {},
       },
@@ -726,6 +734,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 +814,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 =

package/src/storybook/platform-behaviors.js

@@ -2,7 +2,7 @@
  * @file Platform-specific Storybook behavior helpers.
  */
 
-export const genericStorybookAdapter = {
+export const noneStorybookAdapter = {
   loadDrupalBehaviorShim: false,
   attachDrupalBehaviors: false,
   registerDrupalTwigFilters: false,
@@ -10,15 +10,17 @@ export const genericStorybookAdapter = {
   allowSyncXhrSource: false,
 };
 
+export const genericStorybookAdapter = noneStorybookAdapter;
+
 /**
  * Normalize optional platform adapter flags into the full Storybook shape.
  *
  * @param {object} [adapter] - Candidate Storybook adapter flags.
- * @returns {object} Storybook adapter flags with generic defaults.
+ * @returns {object} Storybook adapter flags with non-platform defaults.
  */
 export function normalizeStorybookPlatformAdapter(adapter = {}) {
   return {
-    ...genericStorybookAdapter,
+    ...noneStorybookAdapter,
     ...(adapter || {}),
   };
 }
@@ -27,7 +29,7 @@ export function normalizeStorybookPlatformAdapter(adapter = {}) {
  * Attach platform-specific behaviors after a Storybook render.
  *
  * Drupal behavior attachment is opt-in through the active platform adapter.
- * Generic and unknown platforms return without creating Drupal globals.
+ * `none` and unknown platforms return without creating Drupal globals.
  *
  * @param {object} [options={}] - Attachment options.
  * @param {object} [options.adapter] - Active Storybook platform adapter.