@emulsify/core 4.2.1 → 4.3.1

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,164 @@ 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.            |
+| [4.3.1 Release Notes](docs/releases/4.3.1.md)             | Reviewing the 4.3.1 develop reporter changes, verbosity controls, and scope limits.                               |
 
 ## 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 +266,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/assets/copy-src-assets.js

@@ -0,0 +1,120 @@
+/**
+ * @file Static source asset copy plugin.
+ *
+ * Copies non-code source assets beside the JS/CSS/Twig output that references
+ * them, preserving component and global routing semantics.
+ */
+
+import { copyFileSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+
+import {
+  copiedComponentOutputPath,
+  copiedGlobalOutputPath,
+  findSourceRoot,
+} from '../../project-structure.js';
+import {
+  createSourceFileIndex,
+  isStaticSourceAsset,
+} from './source-file-index.js';
+
+/**
+ * Copy non-code assets from source roots to `dist/`.
+ *
+ * @param {{ structure: object, sourceFileIndex?: object }} opts - Plugin options.
+ * @returns {import('vite').PluginOption} Copy plugin.
+ */
+export function copyAllSrcAssetsPlugin({
+  structure,
+  sourceFileIndex = createSourceFileIndex(structure),
+}) {
+  let outDir = 'dist';
+  let watching = false;
+  /** @type {Array<{absPath: string, relDest: string}>|undefined} */
+  let plan;
+
+  /**
+   * Resolve every asset this plugin copies, paired with where it lands.
+   *
+   * Shared by both hooks for the same reason as the Twig copier: watching and
+   * copying have to be driven by one list, or a file can end up copied on a full
+   * build and ignored on a save.
+   *
+   * @returns {Array<{absPath: string, relDest: string}>} Copy plan.
+   */
+  const copyPlan = () => {
+    if (plan) return plan;
+
+    plan = [];
+
+    for (const file of sourceFileIndex.componentFiles()) {
+      if (!isStaticSourceAsset(file.absPath)) continue;
+
+      plan.push({
+        absPath: file.absPath,
+        relDest: copiedComponentOutputPath(file.absPath, structure),
+      });
+    }
+
+    for (const file of sourceFileIndex.globalFiles()) {
+      if (!isStaticSourceAsset(file.absPath)) continue;
+      if (findSourceRoot(file.absPath, structure.componentRootRecords))
+        continue;
+
+      plan.push({
+        absPath: file.absPath,
+        relDest: copiedGlobalOutputPath(file.absPath, structure),
+      });
+    }
+
+    return plan;
+  };
+
+  return {
+    name: 'emulsify-copy-all-src-assets',
+    apply: 'build',
+    enforce: 'post',
+
+    /** Capture outDir. */
+    configResolved(cfg) {
+      outDir = cfg.build?.outDir || 'dist';
+      watching = Boolean(cfg.build?.watch);
+    },
+
+    // Static assets are copied rather than compiled, so like Twig they are absent
+    // from Rollup's module graph and a save would otherwise go unnoticed. Swapping
+    // an SVG or a font left the old bytes in `dist/` until an unrelated rebuild.
+    buildStart() {
+      if (!watching) return;
+      for (const { absPath } of copyPlan()) this.addWatchFile(absPath);
+    },
+
+    /** Copy before the mirror plugin moves dist/components to the project root. */
+    writeBundle() {
+      for (const { absPath, relDest } of copyPlan()) {
+        copyToOutDir(absPath, relDest);
+      }
+    },
+  };
+
+  /**
+   * Copy one file into the output directory.
+   *
+   * @param {string} absPath - Absolute source path.
+   * @param {string} relDest - Destination relative to `outDir`.
+   * @returns {void}
+   */
+  function copyToOutDir(absPath, relDest) {
+    if (!relDest) return;
+
+    // Copied unconditionally; see the note in copy-twig-files.js — `emptyOutDir`
+    // clears the destination on every cycle, so nothing is ever up to date.
+    const destPath = join(outDir, relDest);
+    mkdirSync(dirname(destPath), { recursive: true });
+    try {
+      copyFileSync(absPath, destPath);
+    } catch {
+      /* noop */
+    }
+  }
+}

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

@@ -0,0 +1,130 @@
+/**
+ * @file Twig template and component metadata copy plugin.
+ *
+ * Copies canonical source Twig files and component metadata to the emitted dist
+ * structure using the same routing rules as compiled JS and CSS entries.
+ */
+
+import { copyFileSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+
+import {
+  copiedComponentOutputPath,
+  copiedGlobalOutputPath,
+} from '../../project-structure.js';
+import {
+  createSourceFileIndex,
+  isComponentMetadataFile,
+} from './source-file-index.js';
+
+/** Determine whether a Twig file is a partial (filename starts with `_`). */
+const isPartial = (filePath) =>
+  (filePath.split('/')?.pop() || '').trim().startsWith('_');
+
+/**
+ * Copy Twig templates and component metadata to `dist/`.
+ *
+ * @param {{ structure: object, sourceFileIndex?: object }} opts - Plugin options.
+ * @returns {import('vite').PluginOption} Copy plugin.
+ */
+export function copyTwigFilesPlugin({
+  structure,
+  sourceFileIndex = createSourceFileIndex(structure),
+}) {
+  let outDir = 'dist';
+  let watching = false;
+  /** @type {Array<{absPath: string, relDest: string}>|undefined} */
+  let plan;
+
+  /**
+   * Resolve every file this plugin copies, paired with where it lands.
+   *
+   * Built once and reused, because the source index is resolved at config time
+   * and does not change across watch cycles. Both hooks below read this same
+   * list, which is what keeps "gets copied to dist" and "a save triggers the
+   * copy" from drifting apart — a file cannot be added to one without the other.
+   *
+   * @returns {Array<{absPath: string, relDest: string}>} Copy plan.
+   */
+  const copyPlan = () => {
+    if (plan) return plan;
+
+    plan = [];
+
+    for (const file of sourceFileIndex.componentFiles()) {
+      const isTwig = file.absPath.endsWith('.twig');
+
+      if (!isTwig && !isComponentMetadataFile(file.absPath)) continue;
+      if (isTwig && isPartial(file.relPath)) continue;
+
+      plan.push({
+        absPath: file.absPath,
+        relDest: copiedComponentOutputPath(file.absPath, structure),
+      });
+    }
+
+    for (const file of sourceFileIndex.globalFiles()) {
+      if (!file.absPath.endsWith('.twig')) continue;
+      if (isPartial(file.relPath)) continue;
+
+      plan.push({
+        absPath: file.absPath,
+        relDest: copiedGlobalOutputPath(file.absPath, structure),
+      });
+    }
+
+    return plan;
+  };
+
+  return {
+    name: 'emulsify-copy-twig-files',
+    apply: 'build',
+    enforce: 'post',
+
+    /** Capture the final outDir. */
+    configResolved(cfg) {
+      outDir = cfg.build?.outDir || 'dist';
+      watching = Boolean(cfg.build?.watch);
+    },
+
+    // Twig is copied rather than compiled, so none of it reaches Rollup's module
+    // graph, and Rollup only watches what is in that graph. Without this, saving
+    // a template produced no rebuild at all: `dist/` kept the previous version
+    // until some unrelated stylesheet happened to change. Storybook renders Twig
+    // through its own pipeline and looked correct throughout, so the stale copy
+    // was only visible to whatever consumes `dist/` — which on Drupal is the site.
+    buildStart() {
+      if (!watching) return;
+      for (const { absPath } of copyPlan()) this.addWatchFile(absPath);
+    },
+
+    /** Copy before the mirror plugin moves dist/components to the project root. */
+    writeBundle() {
+      for (const { absPath, relDest } of copyPlan()) {
+        copyToOutDir(absPath, relDest);
+      }
+    },
+  };
+
+  /**
+   * Copy one file into the output directory.
+   *
+   * @param {string} absPath - Absolute source path.
+   * @param {string} relDest - Destination relative to `outDir`.
+   * @returns {void}
+   */
+  function copyToOutDir(absPath, relDest) {
+    if (!relDest) return;
+
+    // Copied unconditionally, because `build.emptyOutDir` clears the output
+    // directory on every watch cycle and not just the first — a freshness check
+    // against the destination can never find anything to skip.
+    const destPath = join(outDir, relDest);
+    mkdirSync(dirname(destPath), { recursive: true });
+    try {
+      copyFileSync(absPath, destPath);
+    } catch {
+      /* noop */
+    }
+  }
+}

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) => {