@emulsify/core 4.2.1 → 4.3.0

package/.storybook/main-vite.js

@@ -1,16 +1,17 @@
 import path from 'path';
 import viteConfig from '../config/vite/vite.config.js';
-import { twigExtensionModuleSpecifiers } from '../config/vite/twig-extensions.js';
+import { twigExtensionModuleSpecifiers } from '../config/vite/plugins/twig/extensions.js';
 import {
   mergeReactSingletonOptimizeDeps,
   mergeReactSingletonResolve,
 } from '../config/vite/utils/react-singleton.js';
 import { makeGeneratedDistFilesPlugin } from './main-static-assets.js';
 
-// Twig glob maps are provided by config/vite/plugins/virtual-twig-globs.js.
+// Twig glob maps are provided by config/vite/plugins/twig/virtual-twig-globs.js.
 const twigVirtualModuleIds = [
   'virtual:emulsify-twig-globs',
   'virtual:emulsify-twig-asset-sources',
+  'virtual:emulsify-twig-asset-source-runtime',
   'virtual:emulsify-twig-extension-installers',
 ];
 
@@ -52,22 +53,64 @@ function mergeTwigRuntimeOptimizeDepsExcludes(...excludeLists) {
   );
 }
 
+/**
+ * Drop Vite's legacy `rollupOptions` alias from an `optimizeDeps` object.
+ *
+ * Vite 8 installs a compat shim on resolved `optimizeDeps` that defines
+ * `rollupOptions` as an *enumerable accessor* forwarding to `rolldownOptions`.
+ * Spreading such an object — which is how Storybook's config is merged here —
+ * copies the alias out as an ordinary data property. Vite then sees an
+ * `optimizeDeps` carrying two distinct objects and logs:
+ *
+ *   `optimizeDeps.rollupOptions` / `ssr.optimizeDeps.rollupOptions` is
+ *   deprecated. Use `optimizeDeps.rolldownOptions` instead.
+ *
+ * `ssr.optimizeDeps` inherits from `optimizeDeps`, so clearing the alias here
+ * settles both. Anything the alias was carrying is folded into
+ * `rolldownOptions` rather than discarded, so behavior is unchanged.
+ *
+ * That deprecation is emitted with `console.warn` rather than through Vite's
+ * logger, so it cannot be intercepted downstream — it has to be prevented.
+ *
+ * @param {object} [optimizeDeps] - Resolved or partial optimizeDeps config.
+ * @returns {object} Copy with the alias resolved into `rolldownOptions`.
+ */
+export function stripRollupOptionsAlias(optimizeDeps) {
+  if (!optimizeDeps) return {};
+
+  const { rollupOptions, rolldownOptions, ...rest } = optimizeDeps;
+  const resolved = rolldownOptions || rollupOptions;
+
+  return resolved ? { ...rest, rolldownOptions: resolved } : rest;
+}
+
+/**
+ * Virtual module IDs that must stay external during dependency optimization.
+ *
+ * @type {RegExp}
+ */
+const TWIG_VIRTUAL_MODULE_PATTERN =
+  /^virtual:emulsify-twig-(?:globs|asset-sources|asset-source-runtime)$/;
+
 /**
  * Keep Emulsify Twig virtual imports out of Storybook dependency prebundles.
  *
- * @returns {import('esbuild').Plugin} Esbuild plugin for optimizeDeps.
+ * Vite 8 optimizes dependencies with Rolldown rather than esbuild, so this is a
+ * Rolldown plugin using the Rollup-compatible `resolveId` hook. It replaces the
+ * previous esbuild `onResolve` plugin, which reached Vite through the
+ * deprecated `optimizeDeps.esbuildOptions` escape hatch.
+ *
+ * @returns {import('rolldown').Plugin} Rolldown plugin for optimizeDeps.
  */
 function makeTwigVirtualModuleOptimizerPlugin() {
   return {
     name: 'emulsify-twig-virtual-modules',
-    setup(build) {
-      build.onResolve(
-        { filter: /^virtual:emulsify-twig-(?:globs|asset-sources)$/ },
-        (args) => ({
-          path: args.path,
-          external: true,
-        }),
-      );
+    resolveId(source) {
+      if (!TWIG_VIRTUAL_MODULE_PATTERN.test(source)) return null;
+
+      // Marking these external leaves them in the module graph for Emulsify's
+      // virtual plugins to resolve during the normal Vite pipeline.
+      return { id: source, external: true };
     },
   };
 }
@@ -125,9 +168,16 @@ export function createViteFinal(resolvedStorybookEnv) {
         '**/*.twig',
       ]),
     );
+    // Clear Vite's legacy `rollupOptions` alias before either object is
+    // spread, so the merged result never carries both it and `rolldownOptions`.
+    const baseOptimizeDeps = stripRollupOptionsAlias(
+      baseViteConfig?.optimizeDeps,
+    );
+    const storybookOptimizeDeps = stripRollupOptionsAlias(config?.optimizeDeps);
+
     const optimizeDepsInclude = mergeReactSingletonOptimizeDeps(
-      baseViteConfig?.optimizeDeps?.include,
-      config?.optimizeDeps?.include,
+      baseOptimizeDeps.include,
+      storybookOptimizeDeps.include,
       [
         'twig',
         '@emulsify/core/extensions/twig',
@@ -166,32 +216,37 @@ export function createViteFinal(resolvedStorybookEnv) {
         exclude: [],
       },
       optimizeDeps: {
-        ...(baseViteConfig?.optimizeDeps || {}),
-        ...(config?.optimizeDeps || {}),
+        ...baseOptimizeDeps,
+        ...storybookOptimizeDeps,
         include: optimizeDepsInclude,
         exclude: mergeTwigRuntimeOptimizeDepsExcludes(
-          baseViteConfig?.optimizeDeps?.exclude,
-          config?.optimizeDeps?.exclude,
+          baseOptimizeDeps.exclude,
+          storybookOptimizeDeps.exclude,
         ),
-        esbuildOptions: {
-          ...(baseViteConfig?.optimizeDeps?.esbuildOptions || {}),
-          ...(config?.optimizeDeps?.esbuildOptions || {}),
+        rolldownOptions: {
+          ...(baseOptimizeDeps.rolldownOptions || {}),
+          ...(storybookOptimizeDeps.rolldownOptions || {}),
           plugins: [
-            ...(baseViteConfig?.optimizeDeps?.esbuildOptions?.plugins || []),
-            ...(config?.optimizeDeps?.esbuildOptions?.plugins || []),
+            ...(baseOptimizeDeps.rolldownOptions?.plugins || []),
+            ...(storybookOptimizeDeps.rolldownOptions?.plugins || []),
             makeTwigVirtualModuleOptimizerPlugin(),
           ],
-          loader: {
-            ...(baseViteConfig?.optimizeDeps?.esbuildOptions?.loader || {}),
-            ...(config?.optimizeDeps?.esbuildOptions?.loader || {}),
-            // Pre-bundle `.js` dependencies with the JSX loader for packages
-            // that ship JSX without a `.jsx` extension.
+          moduleTypes: {
+            ...(baseOptimizeDeps.rolldownOptions?.moduleTypes || {}),
+            ...(storybookOptimizeDeps.rolldownOptions?.moduleTypes || {}),
+            // Pre-bundle `.js` dependencies as JSX for packages that ship JSX
+            // without a `.jsx` extension. Rolldown's `moduleTypes` is the
+            // successor to esbuild's `loader` map.
             '.js': 'jsx',
           },
         },
       },
     });
 
+    const mergedOptimizeDeps = stripRollupOptionsAlias(
+      mergedConfig.optimizeDeps,
+    );
+
     return {
       ...mergedConfig,
       build: {
@@ -204,17 +259,17 @@ export function createViteFinal(resolvedStorybookEnv) {
       },
       resolve: mergeReactSingletonResolve(mergedConfig),
       optimizeDeps: {
-        ...(mergedConfig.optimizeDeps || {}),
-        include: mergeReactSingletonOptimizeDeps(
-          mergedConfig.optimizeDeps?.include,
-        ),
+        // `mergeConfig` walks enumerable keys, so the alias can reappear on the
+        // merged result even though both inputs were cleaned above.
+        ...mergedOptimizeDeps,
+        include: mergeReactSingletonOptimizeDeps(mergedOptimizeDeps.include),
         exclude: mergeTwigRuntimeOptimizeDepsExcludes(
-          mergedConfig.optimizeDeps?.exclude,
+          mergedOptimizeDeps.exclude,
         ),
-        esbuildOptions: {
-          ...(mergedConfig.optimizeDeps?.esbuildOptions || {}),
-          loader: {
-            ...(mergedConfig.optimizeDeps?.esbuildOptions?.loader || {}),
+        rolldownOptions: {
+          ...(mergedOptimizeDeps.rolldownOptions || {}),
+          moduleTypes: {
+            ...(mergedOptimizeDeps.rolldownOptions?.moduleTypes || {}),
             '.js': 'jsx',
           },
         },

package/README.md

@@ -2,47 +2,85 @@
 
 # Emulsify Core
 
-An open-source toolset for creating and implementing design systems.
+An open-source foundation for building design systems across component
+libraries, CMS themes, Storybook, and the handoff between design and
+development.
 
-**Emulsify Core** provides shared [Vite](https://vite.dev/) build configuration and a [Storybook](https://storybook.js.org/) component library setup for component-driven development. Twig-based components and React components are both supported authoring models. A project can be Twig-first, React-first, or intentionally mixed.
+**Emulsify Core** provides shared [Vite](https://vite.dev/) build configuration
+and a [Storybook](https://storybook.js.org/) workspace for component-driven
+development with Twig, React, and autonomous custom elements.
 
 ## How Emulsify Core Works
 
-- Vite builds project JavaScript, Sass/CSS, Twig templates, component metadata, and static component assets.
-- Storybook uses the React/Vite framework.
-- Twig files can render in React-based Storybook through `renderTwig()`.
-- React components render through Storybook's React/Vite support.
-- Twig and React stories can coexist in the same Storybook instance.
-- `project.emulsify.json` is the source of truth for platform and structure configuration.
-- Platform-specific behavior is controlled by adapters instead of being assumed globally.
-- Node.js 24 or later is required.
+Emulsify Core is the shared frontend layer for Emulsify projects. It gives teams
+one place to build, document, and test components while leaving platform-specific
+implementation details where they belong.
+
+- Vite builds project JavaScript, Sass/CSS, Twig templates, component metadata,
+  and static component assets.
+- Storybook runs on the React/Vite framework.
+- Twig files render in React-based Storybook through `renderTwig()`.
+- React components render through Storybook's standard React support.
+- Autonomous custom elements render in Storybook through
+  `renderWebComponent()`.
+- Twig, React, and custom element stories can live together in one Storybook
+  workspace.
+- `project.emulsify.json` is the source of truth for platform and structure
+  configuration.
+- Platform adapters control CMS-specific behavior instead of assuming it
+  globally.
+
+## Node.js Runtime Policy
+
+- Consumers are supported on Node.js 24.13.0 or later. The strictest published
+  toolchain dependency, `stylelint-selector-bem-pattern` 5, requires that patch.
+- Contributors should use Node.js 24.18.0, the exact version pinned in `.nvmrc`.
+- CI also uses Node.js 24.18.0 by reading `.nvmrc`, so local development and
+  automated checks share the same recommended runtime.
 
 ## Project Evolution
 
-Emulsify Core has grown through each major release while keeping the same practical goal: make component-library tooling easier to share across real projects.
+Emulsify Core began as shared Webpack and Storybook tooling, adopted ESM in
+3.x, and moved to Vite and React/Vite Storybook in 4.x. The current project
+model supports CMS themes, standalone component libraries, and mixed Twig,
+React, and custom element Storybook workspaces.
 
-- `1.x` established Emulsify Core as a reusable package for Storybook, Webpack, linting, a11y checks, project overrides, and asset handling.
-- `2.x` expanded component structure support, improved Drupal SDC compatibility, upgraded Storybook, and made more project files configurable from consuming projects.
-- `3.x` modernized the runtime around ESM and Node 24, continued Storybook and dependency upgrades, improved component asset copying, and strengthened compatibility for existing Drupal-oriented builds.
-- The current release moves the build system to Vite, runs Storybook on React/Vite, supports Twig and React stories side by side, and normalizes platform and project-structure behavior through `project.emulsify.json`.
+See [Version Evolution](docs/version-evolution.md) for major-version history
+and the [4.3.0 release notes](docs/releases/4.3.0.md) for the compatibility
+changes and additions in that release.
 
-The latest version is the next evolution of that work: faster builds, clearer public APIs, less global Drupal assumption, and a broader foundation for CMS themes, standalone UI libraries, and mixed component systems.
+## Authoring Models
 
-See [Version Evolution](docs/version-evolution.md) for more release history.
+Emulsify Core supports Twig and React authoring workflows plus a focused
+Storybook adapter for web components built with autonomous custom elements. The
+right choice depends on how the design system will be used.
 
-## Authoring Models
+- 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 web components built with autonomous custom elements for
+  framework-neutral browser components that fit the adapter's documented
+  property, attribute, default-slot, and native event boundaries.
+- Use mixed authoring when a design system needs to document CMS-rendered,
+  framework-rendered, and framework-neutral components in the same Storybook
+  instance.
 
-Twig and React are equally valid ways to build component libraries with Emulsify Core. The right authoring model depends on the consuming project:
+See [Component Authoring](docs/component-authoring.md) for Twig, React, custom
+element, mixed Storybook, and shared Sass examples.
 
-- 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.
+## Installation And Project Setup
 
-See [Component Authoring](docs/component-authoring.md) for Twig, React, mixed Storybook, and shared Sass examples.
+Emulsify Core can enter a project in two common ways. Both are supported and both
+are valid. The right setup path depends on whether you are wiring Core into a
+project yourself or starting from an Emulsify starter.
 
-## Basic Usage
+### Manual Setup With npm
 
-Installation and project scripts are usually provided by a starter or platform integration. Manual setup starts with:
+Use npm when you want to add Emulsify Core to an existing project, a custom
+starter, or a project that owns its own setup decisions.
 
 ```sh
 npm install @emulsify/core
@@ -63,74 +101,163 @@ Every project should provide a `project.emulsify.json` file at the project root:
 }
 ```
 
-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.
+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.
 - `storybook-build`: builds static Storybook output.
-- `build`: runs the Vite build for JS, CSS, copied Twig templates, component metadata, and static component assets.
+- `build`: runs the Vite build for JS, CSS, copied Twig templates, component
+  metadata, and static component assets.
 - `lint`: lints maintained project source.
 
+### Streamlined Setup With Emulsify CLI
+
+Use the [Emulsify CLI](https://github.com/emulsify-ds/emulsify-cli) when you
+want a starter-driven setup with project scaffolding, starter hooks, system
+installation, and component generation.
+
+Install the CLI globally:
+
+```sh
+npm install -g @emulsify/cli
+```
+
+Then initialize a project from a starter:
+
+```sh
+emulsify init "My Project" ./path/to/projects --platform none
+```
+
+Global or direct CLI installation is still the supported way to run
+`emulsify init` before a project exists. For Core 4.x compatibility, projects
+that install `@emulsify/core` also receive a project-local `emulsify` binary
+through Core's `@emulsify/cli` dependency. That local binary can be invoked with
+`npx --no-install emulsify --help`; it is a compatibility bridge for existing
+Core consumers, not a replacement for choosing an explicit CLI installation
+when scaffolding a new project.
+
+The CLI supports built-in `drupal`, `wordpress`, and `none` platforms. It can
+create starter projects, install component systems, list available components,
+install system components, and generate local components. The starter owns the
+project structure and scripts; Emulsify Core still provides the shared build and
+Storybook foundation underneath.
+
 ## Documentation
 
 The documentation is split by task:
 
-| Topic                                                     | Use This When                                                                                                         |
-| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| [Version Evolution](docs/version-evolution.md)            | Understanding how Emulsify Core has evolved across major releases.                                                    |
-| [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`, `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.                                    |
-| [Release Verification](docs/release.md)                   | Running 4.x release checks, tarball smoke tests, and semantic-release dry runs before publishing.                     |
-| [Migration](docs/migration-4x.md)                         | Upgrading from earlier versions while preserving existing structures.                                                 |
+| Topic                                                     | Use This When                                                                                                     |
+| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| [Version Evolution](docs/version-evolution.md)            | Understanding how Emulsify Core has evolved across major releases.                                                |
+| [Component Authoring](docs/component-authoring.md)        | Choosing Twig, React, custom element, or mixed Storybook authoring and comparing component examples.              |
+| [Storybook](docs/storybook.md)                            | Rendering Twig and custom element stories, using Storybook helpers, and mixing authoring models.                  |
+| [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`, `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.                      |
+| [Dependency Contract](docs/dependency-contract.md)        | Understanding why generated themes rely on Core runtime dependencies and npm hoisting.                            |
+| [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.                                |
+| [Component Inspector](docs/component-inspector.md)        | Listing recognized Twig component templates, exact references, shorthand collisions, and expected output paths.   |
+| [Project Audit](docs/audit.md)                            | Running human or versioned JSON project audits and configuring CI failure thresholds.                             |
+| [Release Verification](docs/release.md)                   | Running 4.x release checks, tarball smoke tests, and semantic-release dry runs before publishing.                 |
+| [Release Pull Request Review](docs/release-review.md)     | Reviewing large release pull requests by independent API, runtime, consumer, accessibility, and release risks.    |
+| [Migration To 4.x](docs/migration-4x.md)                  | Upgrading a pre-4.x/Webpack project while preserving existing structures.                                         |
+| [4.3.0 Release Notes](docs/releases/4.3.0.md)             | Reviewing the 4.3.0 scope, compatibility changes, public APIs, limitations, and verification evidence.            |
 
 ## Known Limitations
 
-- 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` and `wordpress` projects should expect output to remain in `dist/`. See [Platform Adapters](docs/platform-adapters.md).
+Emulsify Core is intentionally focused on the shared build and Storybook layer.
+Some integration work still belongs to the project, starter, theme, or platform
+package using it.
+
+- 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 eagerly imports compiled Twig modules for synchronous rendering,
+  while raw Twig and text asset sources load lazily when `source()` requests
+  them. Large Twig libraries should still 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` and `wordpress` projects should expect output to remain in
+  `dist/`. See [Platform Adapters](docs/platform-adapters.md).
+- Generated themes that depend only on `@emulsify/core` assume npm's flat
+  `node_modules` hoisting for script binaries and shared config packages. pnpm's
+  isolated linker and Yarn Plug'n'Play are unsupported for that one-dependency
+  generated-theme pattern unless the consuming project declares each tool
+  package itself. See [Dependency Contract](docs/dependency-contract.md).
+- The Storybook renderer for custom elements supports autonomous custom elements,
+  light DOM children for an unnamed default slot, and explicitly mapped native
+  events. It does not provide a named-slot composition API or support
+  customized built-in elements. See
+  [Storybook](docs/storybook.md#known-limitations).
 
 ## Supported Project Shapes
 
-Core supports these project shapes:
+Emulsify Core is designed to meet projects where they are. These project shapes
+are supported:
 
 - 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.
+- Mixed Storybook projects with Twig, React, and custom elements.
 
-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`.
+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
 
-Emulsify Core exposes stable public package paths:
+Emulsify Core exposes stable public package paths so consuming projects do not
+need to reach into internal files:
 
 ```js
 import { renderTwig } from '@emulsify/core/storybook';
+import {
+  defineCustomElement,
+  renderWebComponent,
+} from '@emulsify/core/storybook';
 import { registerTwigExtensions } from '@emulsify/core/extensions/twig';
 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).
+`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`, public
+Vite plugin helpers from `@emulsify/core/vite/plugins`, and platform adapter
+helpers from `@emulsify/core/vite/platforms`.
 
-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`.
+`defineCustomElement()` and `renderWebComponent()` use the existing
+`@emulsify/core/storybook` entry point; they do not require a dedicated package
+subpath. The generated Twig asset-source runtime is internal and is not a
+public package export.
 
 ## Contributing
 
-Maintained JavaScript source, config, scripts, and tests should use consistent comments:
+Contributions should keep the codebase clear for the next person working in it.
+Maintained JavaScript source, config, scripts, and tests should use consistent
+comments:
 
 - Start each maintained JS file with a short JSDoc file block that explains the file's responsibility.
 - Use JSDoc blocks for exported functions, complex helpers, and public contracts.
@@ -138,7 +265,9 @@ Maintained JavaScript source, config, scripts, and tests should use consistent c
 - Keep comments concise and factual. Prefer explaining why behavior exists instead of restating the code.
 - Use YAML or shell comments in workflow, hook, and fixture files where the format supports comments.
 
-Do not add comments to JSON files, lockfiles, binary assets, generated output, legal documents, or dependency files. Those formats either do not support comments or should remain exact artifacts.
+Do not add comments to JSON files, lockfiles, binary assets, generated output,
+legal documents, or dependency files. Those formats either do not support
+comments or should remain exact artifacts.
 
 Please also follow the issue template and pull request templates provided. See below for the correct places to post issues:
 

package/config/a11y.config.js

@@ -6,9 +6,10 @@
  */
 
 export default {
-  storybookBuildDir: '../../../../.out',
+  storybookBuildDir: '.out',
   discoverStories: true,
   pa11y: {
+    actions: ['wait for element #storybook-root > * to be visible'],
     includeNotices: false,
     includeWarnings: false,
     runners: ['axe'],

package/config/vite/entries.js

@@ -24,10 +24,10 @@ import {
   resolveProjectStructure,
   storybookStyleOutputPath,
 } from './project-structure.js';
-import { createSourceFileIndex } from './plugins/source-file-index.js';
-import { replaceLastSlash, toPosix } from './utils/paths.js';
+import { createSourceFileIndex } from './plugins/assets/source-file-index.js';
+import { replaceLastSlash, toPosixPath } from './utils/paths.js';
 
-export { replaceLastSlash, toPosix };
+export { replaceLastSlash, toPosixPath };
 
 /** Remove characters that would confuse Rollup naming or file systems. */
 export const sanitizePath = (s) => s.replace(/[^a-zA-Z0-9/_-]/g, '');
@@ -123,7 +123,7 @@ export function buildInputs(ctx) {
    */
   const add = (key, abs) => {
     if (!key) return;
-    const clean = sanitizePath(toPosix(key)).replace(/^\/+/, '');
+    const clean = sanitizePath(toPosixPath(key)).replace(/^\/+/, '');
     if (!clean) return;
     safeSetKey(inputs, clean, abs);
   };

package/config/vite/plugins/{copy-src-assets.js → assets/copy-src-assets.js}

@@ -12,7 +12,7 @@ import {
   copiedComponentOutputPath,
   copiedGlobalOutputPath,
   findSourceRoot,
-} from '../project-structure.js';
+} from '../../project-structure.js';
 import {
   createSourceFileIndex,
   isStaticSourceAsset,

package/config/vite/plugins/{copy-twig-files.js → assets/copy-twig-files.js}

@@ -11,7 +11,7 @@ import { dirname, join } from 'path';
 import {
   copiedComponentOutputPath,
   copiedGlobalOutputPath,
-} from '../project-structure.js';
+} from '../../project-structure.js';
 import {
   createSourceFileIndex,
   isComponentMetadataFile,

package/config/vite/plugins/{css-asset-relativizer.js → assets/css-asset-relativizer.js}

@@ -3,6 +3,13 @@
  *
  * Rewrites emitted CSS references to root assets so nested CSS files can keep
  * resolving copied assets correctly from their final output directories.
+ *
+ * Sourcemap warning: this rewrites emitted CSS in `generateBundle` without
+ * adjusting positions, and every replacement changes the length of the line it
+ * sits on. Vite does not emit sourcemaps for extracted CSS today, so there is
+ * nothing to invalidate. If CSS sourcemaps are ever added, this plugin has to
+ * shift mappings as it rewrites (for example via MagicString) or each mapping
+ * after the first rewritten `url()` will silently resolve to the wrong column.
  */
 
 import { posix as pathPosix } from 'path';
@@ -26,6 +33,8 @@ export function cssAssetUrlRelativizer({ assetsRoot = 'assets' } = {}) {
 
         const fromDir = pathPosix.dirname(fileName);
 
+        // Length-changing rewrite: read the sourcemap warning in the file
+        // header before pairing this plugin with CSS sourcemaps.
         chunk.source = chunk.source.replace(
           /url\((['"]?)\/?assets\/([^)'"]+)\1\)/g,
           (match, quote = '', rest) => {

package/config/vite/plugins/{mirror-components.js → assets/mirror-components.js}

@@ -22,39 +22,13 @@ import {
 } from 'fs';
 import { basename, dirname, join, resolve } from 'path';
 
-import { safeExists, safeReadJson } from '../utils/fs-safe.js';
+import { safeExists, safeReadJson } from '../../utils/fs-safe.js';
+import { resolvePackageVersion } from '../../utils/package-version.js';
 import { walkFiles } from './source-file-index.js';
 
 const MIRROR_STATE_FILE = '.emulsify-mirror-state.json';
 const FILE_COMPARE_CHUNK_SIZE = 64 * 1024;
 
-/**
- * Resolve the installed Core package version without relying on import.meta so
- * Jest's CommonJS transform can load this Vite plugin module.
- *
- * @param {string} projectDir - Project directory running the build.
- * @returns {string} Emulsify Core package version.
- */
-const resolvePackageVersion = (projectDir) => {
-  const candidates = [
-    join(projectDir, 'node_modules/@emulsify/core/package.json'),
-    join(process.cwd(), 'node_modules/@emulsify/core/package.json'),
-    join(process.cwd(), 'package.json'),
-  ];
-
-  for (const candidate of candidates) {
-    const candidatePackage = safeReadJson(candidate).data;
-    if (
-      candidatePackage?.name === '@emulsify/core' &&
-      candidatePackage.version
-    ) {
-      return candidatePackage.version;
-    }
-  }
-
-  return '0.0.0';
-};
-
 /**
  * Remove empty parent directories from a start directory up to, but not including,
  * a stopping boundary directory.