@emulsify/core 4.1.1 → 4.2.1

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. WordPress and Timber projects should currently use `platform: "none"` unless a project adds its own platform-specific behavior.
+- Use Twig for CMS themes and server-rendered template systems. Drupal has a Drupal-specific adapter, and WordPress/Timber projects can use the intentionally neutral `wordpress` adapter. WordPress runtime integration belongs in `emulsify-wordpress-theme`.
 - 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.
 
@@ -85,7 +85,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 `none`, `drupal`, platform resolution order, and Drupal SDC behavior.                                   |
+| [Platform Adapters](docs/platform-adapters.md)            | Understanding `none`, `wordpress`, `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.                                    |
@@ -94,24 +94,25 @@ The documentation is split by task:
 
 ## Known Limitations
 
-- 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).
+- Implemented platform adapters are `none`, `wordpress`, and `drupal`. The `wordpress` adapter is intentionally neutral: it supports Core Twig authoring, Storybook, Vite, `bem()`, `add_attributes()`, `include()`, and `source()`, but it does not emulate WordPress or Timber PHP runtime behavior. Runtime integration belongs in `emulsify-wordpress-theme`. 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. `none` 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` and `wordpress` projects should expect output to remain in `dist/`. See [Platform Adapters](docs/platform-adapters.md).
 
 ## Supported Project Shapes
 
-Release-readiness coverage validates:
+Core supports these project shapes:
 
 - Drupal SDC projects using `src/components`.
 - `none` platform Twig projects using `src/components`.
+- `wordpress` platform Twig projects using `src/components`.
 - Root `./components` projects.
 - Projects using multiple `variant.structureImplementations`.
 - Mixed Twig + React Storybook projects.
 
-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`.
+WordPress and Timber projects should use `platform: "wordpress"` when they want Core's neutral WordPress adapter. The adapter keeps output in `dist/`, loads Storybook CSS from `dist/**/*.css`, and leaves WordPress runtime behavior to `emulsify-wordpress-theme`.
 
 ## Public Imports
 
@@ -125,7 +126,7 @@ import { defineReactExtension } from '@emulsify/core/extensions/react';
 
 `defineReactExtension` is reserved for future React extension support. It currently returns the input unchanged. Adopting the import path is safe; the runtime is intentionally a no-op until the registry lands. See [Extension Points](docs/extension-points.md#public-imports).
 
-Vite consumers can import the shared config from `@emulsify/core/vite` and public Vite plugin helpers from `@emulsify/core/vite/plugins`.
+Vite consumers can import the shared config from `@emulsify/core/vite`, public Vite plugin helpers from `@emulsify/core/vite/plugins`, and platform adapter helpers from `@emulsify/core/vite/platforms`.
 
 ## Contributing
 

package/config/vite/platforms.js

@@ -5,7 +5,21 @@
  * decisions can be used by Node-side Vite config and Storybook browser code.
  */
 
-const noneAdapter = {
+/**
+ * Freeze adapter definition data while preserving cloneable plain objects.
+ *
+ * @param {object} adapter - Adapter definition.
+ * @returns {object} Frozen adapter definition.
+ */
+function freezeAdapter(adapter) {
+  return Object.freeze({
+    ...adapter,
+    storybook: Object.freeze({ ...adapter.storybook }),
+    build: Object.freeze({ ...adapter.build }),
+  });
+}
+
+const noneAdapter = freezeAdapter({
   name: 'none',
   outputStrategy: 'dist',
   storybook: {
@@ -18,9 +32,9 @@ const noneAdapter = {
   build: {
     mirrorDistComponentsToRoot: false,
   },
-};
+});
 
-const drupalAdapter = {
+const drupalAdapter = freezeAdapter({
   name: 'drupal',
   outputStrategy: 'drupal-sdc',
   storybook: {
@@ -33,13 +47,29 @@ const drupalAdapter = {
   build: {
     mirrorDistComponentsToRoot: true,
   },
-};
+});
 
-const adapters = {
+const wordpressAdapter = freezeAdapter({
+  name: 'wordpress',
+  outputStrategy: 'dist',
+  storybook: {
+    loadDrupalBehaviorShim: false,
+    attachDrupalBehaviors: false,
+    registerDrupalTwigFilters: false,
+    loadMirroredComponentCss: false,
+    allowSyncXhrSource: false,
+  },
+  build: {
+    mirrorDistComponentsToRoot: false,
+  },
+});
+
+const adapters = Object.freeze({
   none: noneAdapter,
   generic: noneAdapter,
   drupal: drupalAdapter,
-};
+  wordpress: wordpressAdapter,
+});
 
 /**
  * Deep-clone an adapter so callers can safely serialize or extend it.
@@ -80,10 +110,7 @@ export function normalizePlatformName(platform = 'none') {
  */
 export function getPlatformAdapter(platform = 'none') {
   const key = normalizePlatformName(platform);
-  if (key === 'drupal') {
-    return cloneAdapter(drupalAdapter);
-  }
-  return cloneAdapter(noneAdapter);
+  return cloneAdapter(adapters[key] || noneAdapter);
 }
 
 export { adapters };

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

@@ -74,6 +74,13 @@ const compileCache = new Map();
  */
 const resolutionCache = new Map();
 
+/**
+ * Cache recursively discovered component grouping directories by root.
+ *
+ * @type {Map<string, string[]>}
+ */
+const componentGroupRootsCache = new Map();
+
 /**
  * Track Twig files that have been seen during this build/session.
  *
@@ -355,6 +362,43 @@ const isWithinRoot = (root, filePath) => {
   );
 };
 
+/**
+ * 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.
  *
@@ -511,7 +555,11 @@ const parseTwigNamespaceReference = (templatePath, namespaces = {}) => {
 };
 
 /**
- * Return immediate directory roots that may group component folders.
+ * 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.
@@ -519,33 +567,57 @@ const parseTwigNamespaceReference = (templatePath, namespaces = {}) => {
 const componentGroupRoots = (componentRoot) => {
   if (!componentRoot) return [];
 
-  try {
-    // Component group roots come from a configured project directory.
-    return fs
-      .readdirSync(componentRoot, { withFileTypes: true })
+  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())
-      .map((entry) => resolve(componentRoot, entry.name));
-  } catch {
-    return [];
+      .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 one grouping directory level.
+ * 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 directories such as
- * `ui`.
+ * 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) =>
-  findExistingTemplateFile(
+  findExistingComponentTemplateFile(
     componentGroupRoots(componentRoot).flatMap((groupRoot) =>
       buildTemplateFileCandidates(groupRoot, templatePath),
     ),
+    componentRoot,
   ) || null;
 
 /**
@@ -562,8 +634,9 @@ const resolveComponentShorthandReference = (templatePath, componentRoot) => {
     templatePath.startsWith('@') && !templatePath.includes('/')
       ? templatePath.slice(1)
       : templatePath;
-  const directComponentPath = findExistingTemplateFile(
+  const directComponentPath = findExistingComponentTemplateFile(
     buildTemplateFileCandidates(componentRoot, shorthandPath),
+    componentRoot,
   );
   if (directComponentPath) {
     return directComponentPath;
@@ -577,8 +650,9 @@ const resolveComponentShorthandReference = (templatePath, componentRoot) => {
   const genericComponentPath = genericNamespace[1];
 
   return (
-    findExistingTemplateFile(
+    findExistingComponentTemplateFile(
       buildTemplateFileCandidates(componentRoot, genericComponentPath),
+      componentRoot,
     ) || resolveGroupedComponentTemplate(genericComponentPath, componentRoot)
   );
 };
@@ -614,9 +688,15 @@ const resolveTwigTemplateWithoutCache = (templatePath, fromDir, options) => {
     options.namespaces,
   );
   if (namespaced) {
-    const namespacedTemplate = findExistingTemplateFile(
-      buildTemplateFileCandidates(namespaced.root, namespaced.path),
-    );
+    const namespacedTemplate =
+      namespaced.namespace === 'components'
+        ? findExistingComponentTemplateFile(
+            buildTemplateFileCandidates(namespaced.root, namespaced.path),
+            namespaced.root,
+          )
+        : findExistingTemplateFile(
+            buildTemplateFileCandidates(namespaced.root, namespaced.path),
+          );
     if (namespacedTemplate) {
       return namespacedTemplate;
     }
@@ -914,6 +994,16 @@ export function emulsifyTwigModulePlugin(options) {
    */
   const dependencyImporters = new Map();
 
+  /**
+   * Twig entry modules transformed by this plugin instance.
+   *
+   * Structural component changes invalidate these modules because a new or
+   * removed directory can change the target of a shorthand reference.
+   *
+   * @type {Set<string>}
+   */
+  const transformedTwigModules = new Set();
+
   /**
    * Remember that one imported Twig module depends on another Twig file.
    *
@@ -948,7 +1038,9 @@ export function emulsifyTwigModulePlugin(options) {
     buildStart() {
       compileCache.clear();
       resolutionCache.clear();
+      componentGroupRootsCache.clear();
       knownTwigFiles.clear();
+      transformedTwigModules.clear();
     },
     transform(...args) {
       const [, id] = args;
@@ -958,6 +1050,7 @@ export function emulsifyTwigModulePlugin(options) {
 
       const filePath = stripRequestQuery(id);
       const sourceFilePath = resolve(filePath);
+      transformedTwigModules.add(sourceFilePath);
       /** @type {Map<string, ReturnType<typeof compileTwigTemplate>>} */
       const compiledDependencyTemplates = new Map();
       /** @type {Map<string, Set<string>>} */
@@ -1106,6 +1199,7 @@ export function emulsifyTwigModulePlugin(options) {
                 compiledDependency.templateId,
                 compiledDependency.templateParams,
               )};
+              ${variableName}.method = 'emulsify';
             `,
           )
           .join('\n');
@@ -1153,9 +1247,21 @@ export function emulsifyTwigModulePlugin(options) {
           const Twig = factory();
           registerTwigExtensions(Twig);
           registerConfiguredTwigExtensions(Twig);
+          Twig.extend((TwigCore) => {
+            TwigCore.Templates.registerLoader(
+              'emulsify',
+              (location, params = {}) => {
+                const templateName = params.path || params.id || location;
+                throw new TwigCore.Error(
+                  'Unable to find template ' + templateName + '.',
+                );
+              },
+            );
+          });
 
           ${dependencyTemplateCode}
           const __emulsifyTemplate = ${compiled.code};
+          __emulsifyTemplate.method = 'emulsify';
           const __emulsifyIncludeTemplates = new Map();
           const __emulsifySourceTemplates = new Map();
           ${includeTemplateRegistrations}
@@ -1192,21 +1298,54 @@ export function emulsifyTwigModulePlugin(options) {
       }
     },
     handleHotUpdate({ file, server }) {
-      if (!file.endsWith('.twig')) {
+      const filePath = resolve(file);
+      const componentRoot = options.namespaces?.components
+        ? resolve(options.namespaces.components)
+        : null;
+      const cachedComponentRoots = componentRoot
+        ? componentGroupRootsCache.get(componentRoot)
+        : undefined;
+      let fileIsDirectory = false;
+
+      try {
+        fileIsDirectory = fs.statSync(filePath).isDirectory();
+      } catch {
+        // Removed paths cannot be inspected.
+      }
+
+      const componentDirectoryChanged =
+        !!componentRoot &&
+        isWithinRoot(componentRoot, filePath) &&
+        (fileIsDirectory || cachedComponentRoots?.includes(filePath));
+      if (componentDirectoryChanged) {
+        componentGroupRootsCache.delete(componentRoot);
+        resolutionCache.clear();
+        compileCache.clear();
+      }
+
+      if (!file.endsWith('.twig') && !componentDirectoryChanged) {
         return undefined;
       }
 
-      const filePath = resolve(file);
       const fileExists = safeExists(filePath);
       const knownFile = knownTwigFiles.has(filePath);
-      compileCache.delete(filePath);
       const importers = dependencyImporters.get(filePath);
-      if (!fileExists) {
+      const projectRoot = options.projectDir || options.root;
+      const projectPathChanged =
+        !!projectRoot &&
+        isWithinRoot(resolve(projectRoot), filePath) &&
+        fileExists !== knownFile;
+      const structuralChange = componentDirectoryChanged || projectPathChanged;
+
+      if (file.endsWith('.twig')) {
+        compileCache.delete(filePath);
+      }
+      if (!fileExists && file.endsWith('.twig')) {
         dependencyImporters.delete(filePath);
         knownTwigFiles.delete(filePath);
+        transformedTwigModules.delete(filePath);
       }
 
-      const projectRoot = options.projectDir || options.root;
       if (projectRoot && isWithinRoot(resolve(projectRoot), filePath)) {
         /**
          * Existing files only need entries for their own path and source
@@ -1220,26 +1359,47 @@ export function emulsifyTwigModulePlugin(options) {
         }
       }
 
-      if (!importers?.size) {
+      if (
+        componentRoot &&
+        isWithinRoot(componentRoot, filePath) &&
+        structuralChange
+      ) {
+        componentGroupRootsCache.delete(componentRoot);
+      }
+
+      if (structuralChange) {
+        compileCache.clear();
+      }
+
+      const affectedImporters = new Set(importers || []);
+      if (structuralChange) {
+        for (const transformedModule of transformedTwigModules) {
+          affectedImporters.add(transformedModule);
+        }
+      }
+
+      if (!affectedImporters.size) {
         return undefined;
       }
 
-      const modules = new Set(
-        server.moduleGraph.getModulesByFile(filePath) || [],
-      );
-      for (const importer of importers) {
+      const moduleGraph = server?.moduleGraph;
+      if (!moduleGraph?.getModulesByFile) {
+        return undefined;
+      }
+
+      const modules = new Set(moduleGraph.getModulesByFile(filePath) || []);
+      for (const importer of affectedImporters) {
         compileCache.delete(importer);
 
-        const importerModules =
-          server.moduleGraph.getModulesByFile(importer) || [];
+        const importerModules = moduleGraph.getModulesByFile(importer) || [];
 
         for (const module of importerModules) {
-          server.moduleGraph.invalidateModule(module);
+          moduleGraph.invalidateModule?.(module);
           modules.add(module);
         }
       }
 
-      return Array.from(modules);
+      return modules.size ? Array.from(modules) : undefined;
     },
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emulsify/core",
-  "version": "4.1.1",
+  "version": "4.2.1",
   "description": "Bundled tooling for Storybook development + Vite Build",
   "keywords": [
     "component library",
@@ -127,6 +127,7 @@
     "./storybook/twig/source": "./src/storybook/twig/source.js",
     "./vite": "./config/vite/vite.config.js",
     "./vite/plugins": "./config/vite/plugins.js",
+    "./vite/platforms": "./config/vite/platforms.js",
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -153,6 +154,7 @@
     "prettier": "npm run check-node-version && prettier --check --config config/.prettierrc.json --ignore-unknown \"**/*.{js,mjs,cjs,jsx,json,yml,yaml,scss,md,twig}\"",
     "prettier-fix": "npm run check-node-version && prettier --config config/.prettierrc.json --write --ignore-unknown \"**/*.{js,mjs,cjs,jsx,json,yml,yaml,scss,md,twig}\"",
     "semantic-release": "npm run check-node-version && semantic-release --config ./release.config.cjs",
+    "smoke:pack": "npm run check-node-version && node scripts/smoke-pack.js",
     "version:develop": "npm run check-node-version && node scripts/bump-version-from-commits.js",
     "storybook": "npm run check-node-version && NODE_OPTIONS=--no-deprecation storybook dev -p 6006 --no-open --exact-port",
     "storybook-build": "npm run check-node-version && storybook build -o .out",
@@ -164,7 +166,7 @@
     "@babel/core": "^7.29.7",
     "@babel/eslint-parser": "^7.28.6",
     "@babel/preset-env": "^7.28.3",
-    "@emulsify/cli": "^1.11.4",
+    "@emulsify/cli": "^2.2.0",
     "@eslint/js": "^9.39.4",
     "@storybook/addon-a11y": "^10.1.4",
     "@storybook/addon-links": "^10.1.4",
@@ -172,31 +174,27 @@
     "@storybook/react": "^10.1.4",
     "@storybook/react-vite": "^10.1.4",
     "@vituum/vite-plugin-twig": "^1.1.0",
-    "autoprefixer": "^10.4.21",
+    "autoprefixer": "^10.5.2",
     "axe-core": "^4.11.4",
     "babel-preset-minify": "^0.5.2",
     "concurrently": "^9.2.3",
     "eslint": "^9.39.4",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-jest": "^29.0.1",
+    "eslint-plugin-jest": "^29.15.4",
     "eslint-plugin-prettier": "^5.5.4",
-    "eslint-plugin-security": "^4.0.0",
-    "eslint-plugin-storybook": "^10.1.4",
-    "fs-extra": "^11.3.1",
+    "eslint-plugin-security": "^4.0.1",
+    "eslint-plugin-storybook": "^10.4.6",
     "glob": "^13.0.6",
-    "graceful-fs": "^4.2.11",
     "jest": "^30.2.0",
     "jest-environment-jsdom": "^30.2.0",
     "js-yaml": "^4.1.0",
     "normalize.css": "^8.0.1",
     "open-cli": "^9.0.0",
     "pa11y": "^9.0.1",
-    "postcss": "^8.5.4",
+    "postcss": "^8.5.16",
     "postcss-scss": "^4.0.9",
-    "ramda": "^0.32.0",
-    "regenerator-runtime": "^0.14.1",
-    "sass": "^1.93.2",
+    "sass": "^1.101.0",
     "storybook": "^10.1.4",
     "stylelint": "^17.12.0",
     "stylelint-config-standard-scss": "^17.0.0",
@@ -211,18 +209,18 @@
     "yaml": "^2.8.1"
   },
   "devDependencies": {
-    "@commitlint/cli": "^21.0.1",
-    "@commitlint/config-conventional": "^21.0.1",
+    "@commitlint/cli": "^21.2.0",
+    "@commitlint/config-conventional": "^21.2.0",
     "@semantic-release/changelog": "^6.0.2",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^12.0.8",
+    "@semantic-release/github": "^12.0.9",
     "@semantic-release/npm": "^13.1.5",
     "@semantic-release/release-notes-generator": "^14.1.0",
     "husky": "^9.1.7",
-    "lint-staged": "^17.0.5",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
+    "lint-staged": "^17.0.8",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
     "semantic-release": "^25.0.3"
   },
   "peerDependencies": {

package/scripts/a11y.js

@@ -8,7 +8,6 @@
 import { existsSync, readFileSync } from 'fs';
 import path from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
-import * as R from 'ramda';
 import pa11y from 'pa11y';
 
 import a11yConfig from '../config/a11y.config.js';
@@ -210,11 +209,12 @@ const resolvePa11yStoryIds = ({
  * @param {'error'|'warning'|'notice'} severity
  * @returns {'red'|'yellow'|'blue'|undefined}
  */
-const severityToColor = R.cond([
-  [R.equals('error'), R.always('red')],
-  [R.equals('warning'), R.always('yellow')],
-  [R.equals('notice'), R.always('blue')],
-]);
+const severityToColor = (severity) =>
+  ({
+    error: 'red',
+    warning: 'yellow',
+    notice: 'blue',
+  })[severity];
 
 /**
  * @typedef {Object} Pa11yIssue
@@ -297,25 +297,20 @@ const lintComponent = async (name) =>
  * @param {string[]} names - List of Storybook story IDs.
  * @returns {Promise<void>}
  */
-const lintReportAndExit = R.pipe(
-  /** @param {string[]} list */
-  (list) => list.map(lintComponent),
-  (promises) => Promise.all(promises),
-  R.andThen(
-    R.pipe(
-      /** @param {Array<{issues: Pa11yIssue[], pageUrl: string}>} results */
-      (results) => results.map(logReport),
-      R.reject(R.equals(false)),
-      R.unless(R.isEmpty, () => process.exit(1)),
-    ),
-  ),
-);
+const lintReportAndExit = async (names) => {
+  const results = await Promise.all(names.map(lintComponent));
+  const hasIssues = results.map(logReport).some(Boolean);
+
+  if (hasIssues) {
+    process.exit(1);
+  }
+};
 
 // Only perform linting/reporting when instructed via "-r".
 /* istanbul ignore next */
-if (R.includes(process.argv[2], ['-h', '--help'])) {
+if (['-h', '--help'].includes(process.argv[2])) {
   printHelp();
-} else if (R.pathEq(['argv', 2], '-r')(process)) {
+} else if (process.argv[2] === '-r') {
   loadProjectA11yConfig().then((projectConfig) => {
     applyProjectA11yConfig(projectConfig);
     return lintReportAndExit(resolvePa11yStoryIds());

package/src/storybook/twig/resolver.js

@@ -91,9 +91,26 @@ function findGroupedComponentEntry(map, candidates, env) {
 
   for (const { rootRel, suffix } of groupedComponentSuffixes(candidates, env)) {
     const rootPrefix = `${rootRel}/`;
-    const match = entries.find(
-      ([key]) => key.startsWith(rootPrefix) && key.endsWith(suffix),
-    );
+    const matches = entries
+      .filter(([key]) => key.startsWith(rootPrefix) && key.endsWith(suffix))
+      .sort(([leftKey], [rightKey]) => {
+        const leftGroupingPath = leftKey.slice(
+          rootPrefix.length,
+          -suffix.length,
+        );
+        const rightGroupingPath = rightKey.slice(
+          rootPrefix.length,
+          -suffix.length,
+        );
+        const leftDepth = leftGroupingPath.split('/').filter(Boolean).length;
+        const rightDepth = rightGroupingPath.split('/').filter(Boolean).length;
+
+        if (leftDepth !== rightDepth) {
+          return leftDepth - rightDepth;
+        }
+        return leftKey === rightKey ? 0 : leftKey < rightKey ? -1 : 1;
+      });
+    const match = matches[0];
     if (match) {
       return { key: match[0], value: match[1] };
     }

package/src/storybook/twig/source-function.js

@@ -84,7 +84,7 @@ function warnTextAssetSource(relPath, reason) {
 
   warnedAssetSources.add(relPath);
   console.warn(
-    `source(): ${reason} for @assets/${relPath}. Synchronous XHR fallback is disabled by default because it blocks Storybook rendering. Move the asset under a configured asset root such as src/assets or assets, or temporarily enable platformAdapter.storybook.allowSyncXhrSource. The sync-XHR fallback is deprecated and will be removed in 4.2.`,
+    `source(): ${reason} for @assets/${relPath}. Synchronous XHR fallback is disabled by default because it blocks Storybook rendering. Move the asset under a configured asset root such as src/assets or assets, or temporarily enable platformAdapter.storybook.allowSyncXhrSource. The sync-XHR fallback is deprecated and scheduled for removal in a future major release.`,
   );
 }