@emulsify/core 4.3.0 → 4.3.2

package/.storybook/main-vite.js

@@ -5,6 +5,7 @@ import {
   mergeReactSingletonOptimizeDeps,
   mergeReactSingletonResolve,
 } from '../config/vite/utils/react-singleton.js';
+import { createDevServerLogger } from '../config/vite/plugins/reporter/vite-logger.js';
 import { makeGeneratedDistFilesPlugin } from './main-static-assets.js';
 
 // Twig glob maps are provided by config/vite/plugins/twig/virtual-twig-globs.js.
@@ -123,7 +124,7 @@ function makeTwigVirtualModuleOptimizerPlugin() {
  */
 export function createViteFinal(resolvedStorybookEnv) {
   return async function viteFinal(config) {
-    const { mergeConfig } = await import('vite');
+    const { createLogger, mergeConfig } = await import('vite');
     const env = resolvedStorybookEnv;
     const storybookBuildConfig = config?.build || {};
 
@@ -249,6 +250,15 @@ export function createViteFinal(resolvedStorybookEnv) {
 
     return {
       ...mergedConfig,
+
+      // Assigned after the merge rather than inside it, because `mergeConfig`
+      // deep-merges plain objects and a logger is an object of functions — merging
+      // Storybook's with ours would produce a hybrid belonging to neither. Spread
+      // last, it simply wins, and it delegates to whatever was already configured
+      // so Storybook keeps its prefixes for every message it is allowed to print.
+      customLogger: createDevServerLogger({
+        baseLogger: mergedConfig.customLogger || createLogger(),
+      }),
       build: {
         ...(mergedConfig.build || {}),
         ...(storybookBuildConfig.outDir

package/.storybook/main.js

@@ -21,6 +21,10 @@ import {
 } from '../src/storybook/main-config.js';
 import { buildAssetStaticDirs } from './main-static-assets.js';
 import { createViteFinal } from './main-vite.js';
+import {
+  installReadyReporter,
+  requestedPortFromArgv,
+} from './ready-reporter.js';
 
 /**
  * Minimal subset of the resolved Emulsify environment used by this file.
@@ -143,6 +147,22 @@ const safeConfigOverrides = await loadConfigOverrides();
  */
 const resolvedStorybookEnv = resolveEnvironment();
 
+/**
+ * Render Storybook's startup announcement in the Emulsify reporter's voice.
+ *
+ * Installed here because this module is itself a Storybook preset: `loadAllPresets`
+ * imports it, so a top-level await runs well before the dev server announces
+ * itself. Only the ready box is affected, and only when the internal logger is
+ * reachable — see `.storybook/ready-reporter.js` for why this is interception
+ * rather than `--quiet`.
+ *
+ * Restricted to `storybook dev`. A static `storybook build` prints no ready box,
+ * and the develop reporter deliberately leaves one-shot builds alone.
+ */
+if (process.argv.includes('dev')) {
+  await installReadyReporter({ requestedPort: requestedPortFromArgv() });
+}
+
 /**
  * Primary Storybook configuration object.
  * @type {StorybookConfig}

package/.storybook/ready-reporter.js

@@ -0,0 +1,230 @@
+/**
+ * @file Route Storybook's startup announcement through the Emulsify reporter.
+ *
+ * `npm run develop` runs Vite and Storybook side by side under `concurrently`.
+ * Once the reporter quiets Vite and Rolldown, Storybook's rounded box is the
+ * only remaining block drawn in another tool's visual language, which makes one
+ * command look like two.
+ *
+ * ## Why interception rather than `--quiet`
+ *
+ * Storybook has a switch for this: `outputStartupInformation()` is called behind
+ * `options.quiet ||`, so `storybook dev --quiet` removes the box outright. It was
+ * not used, for two reasons.
+ *
+ * The first is distribution. The `storybook` script lives in each consuming
+ * project's `package.json`, so `--quiet` would make a cosmetic improvement
+ * depend on every consumer editing a script — and a project that did not would
+ * get no improvement at all. Interception ships with the package.
+ *
+ * The second is that the box carries information nothing else does. Consumers
+ * run `storybook dev --ci`, and `--ci` makes Storybook fall forward to the next
+ * free port without prompting. The resolved port only appears in the box. A
+ * developer whose previous session is still holding 6006 would otherwise open
+ * the requested port and see a stale instance, with nothing anywhere saying so.
+ * Parsing the box is what makes {@link renderReady}'s port drift warning
+ * possible.
+ *
+ * ## Failure behavior
+ *
+ * Everything here is best-effort. `storybook/internal/node-logger` is an
+ * internal subpath and the box payload is a formatted string, so both can change
+ * between Storybook releases. Every failure path leaves Storybook's own logger
+ * untouched, which means the worst outcome is the box that prints today.
+ */
+
+import {
+  createStyler,
+  supportsColor,
+  supportsUnicode,
+} from '../config/vite/plugins/reporter/format.js';
+import { renderReady } from '../config/vite/plugins/reporter/render.js';
+
+/**
+ * Matches the URL rows inside Storybook's startup box.
+ *
+ * The box lists `- Local:`, `- On your network:`, and optionally
+ * `- Other allowed hosts:`, each followed by whitespace and a URL. Matching the
+ * label rather than the position keeps the parse working if a row is added or
+ * reordered.
+ *
+ * @type {RegExp}
+ */
+const URL_ROW_PATTERN = /^\s*-\s*(Local|On your network):\s*(\S+)/gim;
+
+/**
+ * Identifies the startup box among every other boxed message Storybook draws.
+ *
+ * @type {RegExp}
+ */
+const READY_PATTERN = /Storybook\s+ready/i;
+
+/**
+ * Remove ANSI escape sequences so pattern matching sees plain text.
+ *
+ * @param {string} value - Possibly styled text.
+ * @returns {string} Plain text.
+ */
+const stripAnsi = (value) =>
+  // eslint-disable-next-line no-control-regex
+  String(value).replace(/\[[0-9;]*m/g, '');
+
+/**
+ * Extract the local and network URLs from a startup box payload.
+ *
+ * @param {string} message - Box contents.
+ * @returns {{local?: string, network?: string}} Parsed URLs.
+ */
+export function parseReadyUrls(message) {
+  const urls = {};
+  if (typeof message !== 'string') return urls;
+
+  const plain = stripAnsi(message);
+  URL_ROW_PATTERN.lastIndex = 0;
+
+  let match = URL_ROW_PATTERN.exec(plain);
+  while (match) {
+    const [, label, url] = match;
+    urls[label.toLowerCase() === 'local' ? 'local' : 'network'] = url;
+    match = URL_ROW_PATTERN.exec(plain);
+  }
+
+  return urls;
+}
+
+/**
+ * Read the port out of a URL.
+ *
+ * @param {string|undefined} url - URL to inspect.
+ * @returns {string|undefined} Port, when present.
+ */
+export function portFromUrl(url) {
+  if (!url) return undefined;
+
+  try {
+    const { port } = new URL(url);
+    return port || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Determine whether a boxed message is Storybook's startup announcement.
+ *
+ * @param {string} message - Box contents.
+ * @returns {boolean} TRUE when the message is the ready box.
+ */
+export function isReadyBox(message) {
+  return typeof message === 'string' && READY_PATTERN.test(stripAnsi(message));
+}
+
+/**
+ * Replace Storybook's startup box with the Emulsify ready panel.
+ *
+ * Only the ready box is intercepted. Every other boxed message — and there are
+ * several, including migration notices and error summaries — passes through to
+ * Storybook untouched, because this exists to unify one visual element rather
+ * than to take over Storybook's output.
+ *
+ * @param {{
+ *   logger?: {logBox?: Function, log?: Function},
+ *   requestedPort?: string|number,
+ *   write?: (line: string) => void,
+ *   colorEnabled?: boolean,
+ *   unicodeEnabled?: boolean
+ * }} [options] - Interception options.
+ * @returns {boolean} TRUE when the logger was wrapped.
+ */
+export function interceptReadyBox({
+  logger,
+  requestedPort,
+  write = (line) => process.stdout.write(`${line}\n`),
+  colorEnabled,
+  unicodeEnabled,
+} = {}) {
+  if (typeof logger?.logBox !== 'function') return false;
+
+  const styler = createStyler(
+    colorEnabled === undefined ? supportsColor() : colorEnabled,
+  );
+  const unicode =
+    unicodeEnabled === undefined ? supportsUnicode() : unicodeEnabled;
+
+  const originalLogBox = logger.logBox.bind(logger);
+
+  logger.logBox = (message, boxOptions) => {
+    if (!isReadyBox(message)) return originalLogBox(message, boxOptions);
+
+    try {
+      const urls = parseReadyUrls(message);
+      const actual = portFromUrl(urls.local);
+
+      const lines = renderReady({
+        service: 'storybook',
+        urls,
+        portDrift:
+          requestedPort && actual
+            ? { requested: requestedPort, actual }
+            : undefined,
+        unicode,
+        styler,
+      });
+
+      lines.forEach((line) => write(line));
+      return undefined;
+    } catch {
+      // A parse failure must not cost the developer the URLs they need.
+      return originalLogBox(message, boxOptions);
+    }
+  };
+
+  return true;
+}
+
+/**
+ * Install the interception against Storybook's real node logger.
+ *
+ * Called for its side effect during preset evaluation, which happens well before
+ * the server announces itself.
+ *
+ * @param {{requestedPort?: string|number}} [options] - Interception options.
+ * @returns {Promise<boolean>} TRUE when interception was installed.
+ */
+export async function installReadyReporter({ requestedPort } = {}) {
+  try {
+    const { logger } = await import('storybook/internal/node-logger');
+    return interceptReadyBox({ logger, requestedPort });
+  } catch {
+    // Storybook changed the subpath or the export. Its own box still prints.
+    return false;
+  }
+}
+
+/**
+ * Read the port requested on the command line.
+ *
+ * Storybook resolves `-p` / `--port` itself, but by the time the box is drawn the
+ * value has been replaced by whatever port was actually free. The request has to
+ * be captured from argv to have anything to compare against.
+ *
+ * @param {string[]} [argv] - Process arguments.
+ * @returns {string|undefined} Requested port.
+ */
+export function requestedPortFromArgv(argv = process.argv) {
+  if (!Array.isArray(argv)) return undefined;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '-p' || arg === '--port') {
+      const value = argv[index + 1];
+      return value && /^\d+$/.test(value) ? value : undefined;
+    }
+
+    const inline = /^--port=(\d+)$/.exec(arg);
+    if (inline) return inline[1];
+  }
+
+  return undefined;
+}

package/README.md

@@ -166,6 +166,7 @@ The documentation is split by task:
 | [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
 

package/config/vite/plugins/assets/copy-src-assets.js

@@ -29,16 +29,45 @@ export function copyAllSrcAssetsPlugin({
   sourceFileIndex = createSourceFileIndex(structure),
 }) {
   let outDir = 'dist';
+  let watching = false;
+  /** @type {Array<{absPath: string, relDest: string}>|undefined} */
+  let plan;
 
-  const copyToOutDir = (absPath, relDest) => {
-    if (!relDest) return;
-    const destPath = join(outDir, relDest);
-    mkdirSync(dirname(destPath), { recursive: true });
-    try {
-      copyFileSync(absPath, destPath);
-    } catch {
-      /* noop */
+  /**
+   * 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 {
@@ -49,28 +78,43 @@ export function copyAllSrcAssetsPlugin({
     /** 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 file of sourceFileIndex.componentFiles()) {
-        if (!isStaticSourceAsset(file.absPath)) continue;
-        copyToOutDir(
-          file.absPath,
-          copiedComponentOutputPath(file.absPath, structure),
-        );
-      }
-
-      for (const file of sourceFileIndex.globalFiles()) {
-        if (!isStaticSourceAsset(file.absPath)) continue;
-        if (findSourceRoot(file.absPath, structure.componentRootRecords)) {
-          continue;
-        }
-        copyToOutDir(
-          file.absPath,
-          copiedGlobalOutputPath(file.absPath, structure),
-        );
+      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

@@ -17,10 +17,6 @@ import {
   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/`.
  *
@@ -32,16 +28,54 @@ export function copyTwigFilesPlugin({
   sourceFileIndex = createSourceFileIndex(structure),
 }) {
   let outDir = 'dist';
+  let watching = false;
+  /** @type {Array<{absPath: string, relDest: string}>|undefined} */
+  let plan;
 
-  const copyToOutDir = (absPath, relDest) => {
-    if (!relDest) return;
-    const destPath = join(outDir, relDest);
-    mkdirSync(dirname(destPath), { recursive: true });
-    try {
-      copyFileSync(absPath, destPath);
-    } catch {
-      /* noop */
+  /**
+   * 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 = [];
+
+    // A leading underscore excludes a stylesheet from compilation, because a Sass
+    // partial is inlined into whatever imports it and has no output of its own.
+    // Twig has no equivalent: `{% include %}` and `{% embed %}` resolve at render
+    // time against the emitted tree, so an underscored template is a file the site
+    // still has to find. Skipping those left the include unresolvable at runtime.
+    for (const file of sourceFileIndex.componentFiles()) {
+      if (
+        !file.absPath.endsWith('.twig') &&
+        !isComponentMetadataFile(file.absPath)
+      ) {
+        continue;
+      }
+
+      plan.push({
+        absPath: file.absPath,
+        relDest: copiedComponentOutputPath(file.absPath, structure),
+      });
+    }
+
+    for (const file of sourceFileIndex.globalFiles()) {
+      if (!file.absPath.endsWith('.twig')) continue;
+
+      plan.push({
+        absPath: file.absPath,
+        relDest: copiedGlobalOutputPath(file.absPath, structure),
+      });
     }
+
+    return plan;
   };
 
   return {
@@ -52,33 +86,47 @@ export function copyTwigFilesPlugin({
     /** 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 file of sourceFileIndex.componentFiles()) {
-        if (file.absPath.endsWith('.twig')) {
-          if (isPartial(file.relPath)) continue;
-          copyToOutDir(
-            file.absPath,
-            copiedComponentOutputPath(file.absPath, structure),
-          );
-        } else if (isComponentMetadataFile(file.absPath)) {
-          copyToOutDir(
-            file.absPath,
-            copiedComponentOutputPath(file.absPath, structure),
-          );
-        }
-      }
-
-      for (const file of sourceFileIndex.globalFiles()) {
-        if (!file.absPath.endsWith('.twig')) continue;
-        if (isPartial(file.relPath)) continue;
-        copyToOutDir(
-          file.absPath,
-          copiedGlobalOutputPath(file.absPath, structure),
-        );
+      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/reporter/diagnostics.js

@@ -148,6 +148,7 @@ const groupDeprecationsByFile = (deprecationList) => {
  *     deprecationsByFile: Array<{file: string, occurrences: number, entries: Array<{id: string, count: number, lines: number[]}>}>,
  *     unresolvedAssets: Array<{url: string, importer: string|undefined, count: number}>,
  *     importErrors: Array<{file: string|undefined, line: number|undefined, specifier: string, count: number}>,
+ *     syntaxErrors: Array<{minifier: string|undefined, message: string, declaration: string|undefined, count: number}>,
  *     warnings: Array<{message: string|undefined, file: string|undefined, line: number|undefined, count: number}>,
  *     errors: Array<{message: string|undefined, file: string|undefined, line: number|undefined, count: number}>,
  *     deprecationTotal: number,

package/config/vite/plugins/reporter/format.js

@@ -136,6 +136,47 @@ export function formatDuration(milliseconds) {
   return `${(milliseconds / 1000).toFixed(2)}s`;
 }
 
+/**
+ * Format a byte count for display.
+ *
+ * Rolldown's discarded asset table reported kilobytes to two decimals per file.
+ * The reporter states one total and one largest file instead, so it rounds to
+ * whole kilobytes and one decimal megabyte — enough to notice a bundle doubling,
+ * without implying a precision that matters at this scale.
+ *
+ * @param {number} bytes - Byte count.
+ * @returns {string} Formatted size.
+ */
+export function formatBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes < 0) return '0 B';
+  if (bytes < 1024) return `${Math.round(bytes)} B`;
+
+  const kilobytes = bytes / 1024;
+  if (kilobytes < 1024) return `${Math.round(kilobytes)} kB`;
+
+  return `${(kilobytes / 1024).toFixed(1)} MB`;
+}
+
+/**
+ * Format a byte count for a column of sizes.
+ *
+ * {@link formatBytes} rounds hard, which is right for a one-line total but wrong
+ * for a table: rounding turns 5,660 and 3,010 bytes into `6 kB` and `3 kB`, and a
+ * table whose whole purpose is comparison should not round away the difference.
+ * A single unit keeps the column directly comparable down its length rather than
+ * making the reader convert between B, kB, and MB row to row.
+ *
+ * Two decimals of kilobytes is the convention Rolldown's discarded asset table
+ * used, so the numbers are recognizable to anyone who has read that output.
+ *
+ * @param {number} bytes - Byte count.
+ * @returns {string} Formatted size in kilobytes.
+ */
+export function formatPreciseBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes < 0) return '0.00 kB';
+  return `${(bytes / 1024).toFixed(2)} kB`;
+}
+
 /**
  * Format a wall-clock timestamp for rebuild lines.
  *