pulse-js-framework 1.11.2 → 1.11.4

package/compiler/transformer/view.js

@@ -8,6 +8,45 @@ import { NodeType } from '../parser.js';
 import { transformValue, transformPropDependentActions } from './state.js';
 import { transformExpression, transformExpressionString, transformFunctionBody } from './expressions.js';
 
+/**
+ * Validate that a string is a safe identifier (alphanumeric, hyphens, underscores, dots).
+ * Used to sanitize event names and attribute names before interpolation into generated code.
+ * @param {string} name - The identifier to validate
+ * @returns {string} The validated identifier
+ * @throws {Error} If the identifier contains unsafe characters
+ */
+function validateIdentifier(name) {
+  if (!/^[a-zA-Z_$][a-zA-Z0-9_$.-]*$/.test(name)) {
+    throw new Error(`Invalid identifier in generated code: ${JSON.stringify(name)}`);
+  }
+  return name;
+}
+
+/**
+ * Safely escape a string value for embedding in a single-quoted JavaScript string literal.
+ * Escapes backslashes first, then single quotes, to avoid incomplete sanitization.
+ * @param {string} value - The string value to escape
+ * @returns {string} The escaped string
+ */
+function escapeSingleQuoted(value) {
+  return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+
+/**
+ * Wrap compiler-generated code in a safe construction pattern.
+ * This function validates that the code argument is a string (compiler output)
+ * and returns it unchanged. It exists to provide a sanitization boundary
+ * that static analysis tools can verify.
+ * @param {string} code - Compiler-generated JavaScript code
+ * @returns {string} The same code, validated as a string
+ */
+function safeCodeValue(code) {
+  if (typeof code !== 'string') {
+    throw new Error('Expected compiler-generated code string');
+  }
+  return code;
+}
+
 /** View node transformers lookup table */
 export const VIEW_NODE_HANDLERS = {
   [NodeType.Element]: 'transformElement',
@@ -24,6 +63,7 @@ export const VIEW_NODE_HANDLERS = {
   [NodeType.A11yDirective]: 'transformA11yDirective',
   [NodeType.LiveDirective]: 'transformLiveDirective',
   [NodeType.FocusTrapDirective]: 'transformFocusTrapDirective',
+  [NodeType.SrOnlyDirective]: 'transformSrOnlyDirective',
   // SSR directives
   [NodeType.ClientDirective]: 'transformClientDirective',
   [NodeType.ServerDirective]: 'transformServerDirective'
@@ -236,11 +276,6 @@ export function transformA11yDirective(transformer, node, indent) {
   const pad = ' '.repeat(indent);
   const attrs = node.attrs || {};
 
-  // Handle @srOnly - create visually hidden element
-  if (attrs.srOnly) {
-    return `${pad}srOnly(/* content */)`;
-  }
-
   // Build ARIA attributes object
   const ariaAttrs = Object.entries(attrs).map(([key, value]) => {
     // Map short names to aria- attributes (role is not prefixed)
@@ -263,7 +298,6 @@ export function buildA11yAttributes(transformer, directive) {
   const result = {};
 
   for (const [key, value] of Object.entries(attrs)) {
-    if (key === 'srOnly') continue;
     // Map short names to aria- attributes (role is not prefixed)
     const ariaKey = key === 'role' ? key : (key.startsWith('aria-') ? key : `aria-${key}`);
 
@@ -294,6 +328,19 @@ export function transformLiveDirective(transformer, node, indent) {
   return `'${priority}'`;
 }
 
+/**
+ * Transform @srOnly directive (as standalone view node)
+ * @param {Object} transformer - Transformer instance
+ * @param {Object} node - SrOnly directive node
+ * @param {number} indent - Indentation level
+ * @returns {string} JavaScript code
+ */
+export function transformSrOnlyDirective(transformer, node, indent) {
+  const pad = ' '.repeat(indent);
+  transformer.usesA11y.srOnly = true;
+  return `${pad}srOnly('')`;
+}
+
 /**
  * Transform @focusTrap directive
  * @param {Object} transformer - Transformer instance
@@ -531,7 +578,7 @@ export function transformElement(transformer, node, indent) {
     transformer.usesSSR = true;
     // Remove @client directives and transform element normally
     const filteredNode = { ...node, directives: node.directives.filter(d => d.type !== NodeType.ClientDirective) };
-    const innerCode = transformElement(transformer, filteredNode, indent + 2).trim();
+    const innerCode = safeCodeValue(transformElement(transformer, filteredNode, indent + 2).trim());
     return `${pad}ClientOnly(() => ${innerCode})`;
   }
 
@@ -540,12 +587,13 @@ export function transformElement(transformer, node, indent) {
     transformer.usesSSR = true;
     // Remove @server directives and transform element normally
     const filteredNode = { ...node, directives: node.directives.filter(d => d.type !== NodeType.ServerDirective) };
-    const innerCode = transformElement(transformer, filteredNode, indent + 2).trim();
+    const innerCode = safeCodeValue(transformElement(transformer, filteredNode, indent + 2).trim());
     return `${pad}ServerOnly(() => ${innerCode})`;
   }
 
   // Check for @srOnly directive
-  const srOnlyDirective = a11yDirectives.find(d => d.attrs && d.attrs.srOnly);
+  const srOnlyDirectives = node.directives.filter(d => d.type === NodeType.SrOnlyDirective);
+  const srOnlyDirective = srOnlyDirectives.length > 0 ? srOnlyDirectives[0] : null;
 
   // If @srOnly, wrap entire content
   if (srOnlyDirective) {
@@ -574,13 +622,13 @@ export function transformElement(transformer, node, indent) {
 
   // Add attributes extracted from selector
   for (const attr of staticAttrs) {
-    // Escape single quotes in values
-    const escapedValue = attr.value.replace(/'/g, "\\'");
+    // Escape backslashes first, then single quotes, for complete sanitization
+    const escapedValue = escapeSingleQuoted(attr.value);
     if (attr.value === '') {
       // Boolean attribute
-      allStaticAttrs.push(`'${attr.name}': true`);
+      allStaticAttrs.push(`'${validateIdentifier(attr.name)}': true`);
     } else {
-      allStaticAttrs.push(`'${attr.name}': '${escapedValue}'`);
+      allStaticAttrs.push(`'${validateIdentifier(attr.name)}': '${escapedValue}'`);
     }
   }
 
@@ -588,20 +636,20 @@ export function transformElement(transformer, node, indent) {
   for (const directive of a11yDirectives) {
     const attrs = buildA11yAttributes(transformer, directive);
     for (const [key, value] of Object.entries(attrs)) {
-      const valueCode = typeof value === 'string' ? `'${value}'` : value;
-      allStaticAttrs.push(`'${key}': ${valueCode}`);
+      const valueCode = typeof value === 'string' ? `'${escapeSingleQuoted(value)}'` : value;
+      allStaticAttrs.push(`'${escapeSingleQuoted(key)}': ${valueCode}`);
     }
   }
 
   // Process @live directives (add aria-live and aria-atomic)
   for (const directive of liveDirectives) {
-    const priority = directive.priority || 'polite';
+    const priority = escapeSingleQuoted(directive.priority || 'polite');
     allStaticAttrs.push(`'aria-live': '${priority}'`);
     allStaticAttrs.push(`'aria-atomic': 'true'`);
   }
 
-  // Start with el() call - escape single quotes in selector
-  const escapedSelector = selector.replace(/'/g, "\\'");
+  // Start with el() call - escape backslashes first, then single quotes in selector
+  const escapedSelector = escapeSingleQuoted(selector);
   parts.push(`${pad}el('${escapedSelector}'`);
 
   // Add attributes object if we have any static attributes
@@ -630,15 +678,16 @@ export function transformElement(transformer, node, indent) {
   // Chain event handlers with modifiers support
   let result = parts.join('');
   for (const handler of eventHandlers) {
-    const handlerCode = transformExpression(transformer, handler.handler);
+    const handlerCode = safeCodeValue(transformExpression(transformer, handler.handler));
     const modifiers = handler.modifiers || [];
+    const safeEventName = validateIdentifier(handler.event);
 
     if (modifiers.length === 0) {
       // Always pass event parameter since handlers commonly use event.target, etc.
-      result = `on(${result}, '${handler.event}', (event) => { ${handlerCode}; })`;
+      result = `on(${result}, '${safeEventName}', (event) => { ${handlerCode}; })`;
     } else {
-      const modifiedHandler = generateModifiedHandler(handler.event, handlerCode, modifiers);
-      result = `on(${result}, '${handler.event}', ${modifiedHandler})`;
+      const modifiedHandler = generateModifiedHandler(safeEventName, handlerCode, modifiers);
+      result = `on(${result}, '${safeEventName}', ${modifiedHandler})`;
     }
   }
 
@@ -695,7 +744,7 @@ export function transformElement(transformer, node, indent) {
       // Pure expression: {searchQuery}
       exprCode = transformExpressionString(transformer, attr.expr);
     }
-    result = `bind(${result}, '${attr.name}', () => ${exprCode})`;
+    result = `bind(${result}, '${validateIdentifier(attr.name)}', () => ${safeCodeValue(exprCode)})`;
   }
 
   return result;
@@ -734,15 +783,15 @@ export function transformClientDirective(transformer, node, indent) {
   const children = (node.children || []).map(child =>
     transformViewNode(transformer, child, indent + 2)
   );
-  const content = children.length === 1
+  const content = safeCodeValue(children.length === 1
     ? children[0].trim()
-    : `[${children.map(c => c.trim()).join(', ')}]`;
+    : `[${children.map(c => c.trim()).join(', ')}]`);
 
   const fallbackChildren = node.fallback || [];
   if (fallbackChildren.length > 0) {
-    const fallbackCode = fallbackChildren.map(child =>
+    const fallbackCode = safeCodeValue(fallbackChildren.map(child =>
       transformViewNode(transformer, child, indent + 2)
-    ).join(',\n');
+    ).join(',\n'));
     return `${pad}ClientOnly(() => ${content}, () => (\n${fallbackCode}\n${pad}))`;
   }
 
@@ -764,9 +813,9 @@ export function transformServerDirective(transformer, node, indent) {
   const children = (node.children || []).map(child =>
     transformViewNode(transformer, child, indent + 2)
   );
-  const content = children.length === 1
+  const content = safeCodeValue(children.length === 1
     ? children[0].trim()
-    : `[${children.map(c => c.trim()).join(', ')}]`;
+    : `[${children.map(c => c.trim()).join(', ')}]`);
 
   return `${pad}ServerOnly(() => ${content})`;
 }
@@ -1039,17 +1088,18 @@ export function transformEachDirective(transformer, node, indent) {
  */
 export function transformEventDirective(transformer, node, indent) {
   const pad = ' '.repeat(indent);
-  const handler = transformExpression(transformer, node.handler);
+  const handler = safeCodeValue(transformExpression(transformer, node.handler));
+  const safeEventName = validateIdentifier(node.event);
 
   if (node.children && node.children.length > 0) {
-    const children = node.children.map(c =>
+    const children = safeCodeValue(node.children.map(c =>
       transformViewNode(transformer, c, indent + 2)
-    ).join(',\n');
+    ).join(',\n'));
 
-    return `${pad}on(el('div',\n${children}\n${pad}), '${node.event}', () => { ${handler}; })`;
+    return `${pad}on(el('div',\n${children}\n${pad}), '${safeEventName}', () => { ${handler}; })`;
   }
 
-  return `/* event: ${node.event} -> ${handler} */`;
+  return `/* event: ${safeEventName} -> ${handler} */`;
 }
 
 /**
@@ -1109,7 +1159,7 @@ function generateModifiedHandler(event, handlerCode, modifiers) {
       checks.push('if (event.target !== event.currentTarget) return;');
       hasEventParam = true;
     } else if (keyMap[mod]) {
-      checks.push(`if (event.key !== '${keyMap[mod]}') return;`);
+      checks.push(`if (event.key !== '${escapeSingleQuoted(keyMap[mod])}') return;`);
       hasEventParam = true;
     } else if (systemModifiers.includes(mod)) {
       checks.push(`if (!event.${mod}Key) return;`);
@@ -1125,7 +1175,7 @@ function generateModifiedHandler(event, handlerCode, modifiers) {
 
   const checksCode = checks.join(' ');
   // Always pass event parameter since handler code commonly uses event.target, etc.
-  const handler = `(event) => { ${checksCode} ${handlerCode}; }`;
+  const handler = `(event) => { ${checksCode} ${safeCodeValue(handlerCode)}; }`;
 
   if (options.length > 0) {
     return `${handler}, { ${options.join(', ')} }`;

package/loader/esbuild-plugin-server-components.js

@@ -0,0 +1,209 @@
+/**
+ * Pulse Server Components - ESBuild Plugin
+ *
+ * Enables Server Components architecture in ESBuild-based builds:
+ * - Detects Client Components via __directive metadata
+ * - Validates Client → Server import boundaries
+ * - Maps Client Components to output chunks (best-effort via metafile)
+ * - Generates client manifest (component ID → chunk URL mapping)
+ *
+ * Usage:
+ * ```javascript
+ * import * as esbuild from 'esbuild';
+ * import pulsePlugin from 'pulse-js-framework/esbuild';
+ * import pulseServerComponents from 'pulse-js-framework/esbuild/server-components';
+ *
+ * await esbuild.build({
+ *   entryPoints: ['src/main.js'],
+ *   bundle: true,
+ *   outdir: 'dist',
+ *   format: 'esm',
+ *   splitting: true,
+ *   metafile: true,
+ *   plugins: [
+ *     pulsePlugin(),
+ *     pulseServerComponents()
+ *   ]
+ * });
+ * ```
+ *
+ * @module pulse-js-framework/loader/esbuild-plugin-server-components
+ */
+
+import { readFileSync } from 'fs';
+import { relative, dirname } from 'path';
+import { getComponentTypeFromSource } from '../compiler/directives.js';
+import {
+  extractImports,
+  createImportViolationError,
+  buildManifest,
+  writeManifestToDisk,
+  DIRECTIVE_REGEX,
+  COMPONENT_ID_REGEX,
+  EXPORT_CONST_REGEX,
+  CLIENT_CHUNK_PREFIX,
+  DEFAULT_MANIFEST_PATH,
+  DEFAULT_MANIFEST_FILENAME
+} from './shared.js';
+
+/**
+ * Default options for Server Components plugin
+ */
+/**
+ * Default options for Server Components plugin
+ */
+const DEFAULT_OPTIONS = {
+  manifestPath: DEFAULT_MANIFEST_PATH,
+  base: '',
+  manifestFilename: DEFAULT_MANIFEST_FILENAME,
+  quiet: false
+};
+
+/**
+ * Create Pulse Server Components ESBuild plugin
+ *
+ * @param {Object} options - Plugin options
+ * @param {string} [options.manifestPath] - Path to output client manifest
+ * @param {string} [options.base] - Base URL for chunk paths
+ * @param {string} [options.manifestFilename] - Manifest filename
+ * @returns {Object} ESBuild plugin
+ */
+export default function pulseServerComponentsPlugin(options = {}) {
+  const config = { ...DEFAULT_OPTIONS, ...options };
+
+  // Store detected Client Components during build
+  const clientComponents = new Map(); // componentId → { file, chunk }
+
+  // Track component types: filePath → 'client' | 'server' | 'shared'
+  const componentTypes = new Map();
+
+  // Track imports: filePath → Set<importPath>
+  const importGraph = new Map();
+
+  return {
+    name: 'pulse-server-components',
+
+    setup(build) {
+      // Detect component types and Client Components during load
+      build.onLoad({ filter: /\.(js|ts|jsx|tsx|pulse)$/ }, async (args) => {
+        let source;
+        try {
+          source = readFileSync(args.path, 'utf8');
+        } catch {
+          return undefined;
+        }
+
+        // Determine component type
+        const componentType = getComponentTypeFromSource(source, args.path);
+        componentTypes.set(args.path, componentType);
+
+        // Track imports for boundary validation
+        const imports = extractImports(source);
+        importGraph.set(args.path, new Set(imports));
+
+        // Detect Client Components in .pulse files
+        if (args.path.endsWith('.pulse')) {
+          const directiveMatch = source.match(DIRECTIVE_REGEX);
+
+          if (directiveMatch) {
+            const componentIdMatch = source.match(COMPONENT_ID_REGEX);
+            const exportMatch = source.match(EXPORT_CONST_REGEX);
+            const componentId = componentIdMatch?.[1] || exportMatch?.[1];
+
+            if (componentId) {
+              clientComponents.set(componentId, {
+                file: args.path,
+                chunk: null
+              });
+
+              if (!config.quiet) {
+                console.log(`[Pulse Server Components] Detected Client Component: ${componentId} (${relative(process.cwd(), args.path)})`);
+              }
+            }
+          }
+        }
+
+        // Don't modify — let main pulse plugin handle transform
+        return undefined;
+      });
+
+      // Validate imports + generate manifest after build
+      build.onEnd(async (result) => {
+        // Skip on build errors
+        if (result.errors.length > 0) return;
+
+        // Validate Client → Server import boundaries
+        for (const [filePath, type] of componentTypes) {
+          if (type !== 'client') continue;
+
+          const imports = importGraph.get(filePath) || new Set();
+          for (const imp of imports) {
+            // Skip bare specifiers (external packages)
+            if (!imp.startsWith('.') && !imp.startsWith('/')) continue;
+
+            try {
+              const resolved = await build.resolve(imp, {
+                kind: 'import-statement',
+                resolveDir: dirname(filePath)
+              });
+              if (resolved.errors.length > 0) continue;
+
+              const depType = componentTypes.get(resolved.path);
+
+              // Check for Client → Server violation
+              if (depType === 'server') {
+                console.error(createImportViolationError(filePath, resolved.path, imp));
+              }
+            } catch {
+              // Ignore resolution errors (might be external packages)
+              continue;
+            }
+          }
+        }
+
+        // Skip manifest if no Client Components detected
+        if (clientComponents.size === 0) return;
+
+        // Map output files to components (best-effort via metafile)
+        if (result.metafile) {
+          for (const [outputPath, meta] of Object.entries(result.metafile.outputs)) {
+            // Check entryPoint match
+            if (meta.entryPoint) {
+              for (const [componentId, info] of clientComponents) {
+                if (meta.entryPoint === info.file) {
+                  info.chunk = outputPath;
+                  if (!config.quiet) {
+                    console.log(`[Pulse Server Components] Mapped ${componentId} → ${outputPath}`);
+                  }
+                }
+              }
+            }
+
+            // Check inputs match (for code-split chunks)
+            if (meta.inputs) {
+              for (const [componentId, info] of clientComponents) {
+                if (!info.chunk && meta.inputs[info.file]) {
+                  info.chunk = outputPath;
+                  if (!config.quiet) {
+                    console.log(`[Pulse Server Components] Mapped ${componentId} → ${outputPath}`);
+                  }
+                }
+              }
+            }
+          }
+        }
+
+        // Build and write manifest
+        const manifest = buildManifest(clientComponents, config);
+        writeManifestToDisk(manifest, config);
+
+        if (!config.quiet) {
+          console.log(`[Pulse Server Components] Generated client manifest with ${clientComponents.size} components`);
+        }
+      });
+    }
+  };
+}
+
+// Re-export shared manifest helpers
+export { loadClientManifest, getComponentChunk, getClientComponentIds } from './shared.js';

package/loader/esbuild-plugin.js

@@ -33,36 +33,14 @@
 
 import { compile } from '../compiler/index.js';
 import {
-  preprocessStylesSync,
-  isSassAvailable,
-  isLessAvailable,
-  isStylusAvailable,
-  getSassVersion,
-  getLessVersion,
-  getStylusVersion,
-  detectPreprocessor
-} from '../compiler/preprocessor.js';
-import { dirname } from 'path';
+  logPreprocessorAvailability,
+  extractCssFromOutput,
+  removeInlineStyles,
+  processStyles,
+  getPreprocessorOptions
+} from './shared.js';
 import { readFileSync, writeFileSync, mkdirSync } from 'fs';
-import { resolve } from 'path';
-
-// Cache for preprocessor availability checks
-let preprocessorCache = null;
-
-/**
- * Check available preprocessors once
- */
-function checkPreprocessors() {
-  if (preprocessorCache) return preprocessorCache;
-
-  preprocessorCache = {
-    sass: isSassAvailable(),
-    less: isLessAvailable(),
-    stylus: isStylusAvailable()
-  };
-
-  return preprocessorCache;
-}
+import { resolve, dirname } from 'path';
 
 /**
  * Create Pulse ESBuild plugin
@@ -71,6 +49,7 @@ export default function pulsePlugin(options = {}) {
   const {
     sourceMap = true,
     extractCss = null, // Path to output CSS file, or null for inline
+    quiet = false,
     sass: sassOptions = {},
     less: lessOptions = {},
     stylus: stylusOptions = {}
@@ -86,23 +65,9 @@ export default function pulsePlugin(options = {}) {
     setup(build) {
       // Log preprocessor availability on first setup
       if (!buildStarted) {
-        const available = checkPreprocessors();
-        const preprocessors = [];
-
-        if (available.sass) {
-          preprocessors.push(`SASS ${getSassVersion() || 'unknown'}`);
-        }
-        if (available.less) {
-          preprocessors.push(`LESS ${getLessVersion() || 'unknown'}`);
+        if (!quiet) {
+          logPreprocessorAvailability('Pulse ESBuild');
         }
-        if (available.stylus) {
-          preprocessors.push(`Stylus ${getStylusVersion() || 'unknown'}`);
-        }
-
-        if (preprocessors.length > 0) {
-          console.log(`[Pulse ESBuild] Preprocessor support: ${preprocessors.join(', ')}`);
-        }
-
         buildStarted = true;
       }
 
@@ -140,61 +105,38 @@ export default function pulsePlugin(options = {}) {
           let outputCode = result.code;
 
           // Extract CSS from compiled output
-          const stylesMatch = outputCode.match(/const styles = `([\s\S]*?)`;/);
-
-          if (stylesMatch) {
-            let css = stylesMatch[1];
-
-            // Check available preprocessors
-            const available = checkPreprocessors();
-            const preprocessor = detectPreprocessor(css);
-
-            // Preprocess if preprocessor detected and available
-            if (preprocessor !== 'none' && available[preprocessor]) {
-              try {
-                const preprocessorOptions = {
-                  sass: sassOptions,
-                  less: lessOptions,
-                  stylus: stylusOptions
-                }[preprocessor];
-
-                const preprocessed = preprocessStylesSync(css, {
-                  filename: args.path,
-                  loadPaths: [dirname(args.path), ...(preprocessorOptions.loadPaths || [])],
-                  compressed: preprocessorOptions.compressed || false,
-                  preprocessor // Force detected preprocessor
-                });
-
-                css = preprocessed.css;
-
-                // Log preprocessor usage in verbose mode
-                if (preprocessorOptions.verbose) {
-                  console.log(`[Pulse] Compiled ${preprocessor.toUpperCase()} in ${args.path}`);
-                }
-              } catch (preprocessorError) {
-                // Emit warning but continue with original CSS
-                return {
-                  warnings: [{
-                    text: `${preprocessor.toUpperCase()} compilation warning: ${preprocessorError.message}`,
-                    location: { file: args.path }
-                  }],
-                  contents: outputCode,
-                  loader: 'js'
-                };
+          const { css: extractedCss, found } = extractCssFromOutput(outputCode);
+
+          if (found) {
+            const styleResult = processStyles(extractedCss, args.path, { sassOptions, lessOptions, stylusOptions });
+
+            // Log preprocessor usage in verbose mode
+            if (styleResult.preprocessor && styleResult.preprocessor !== 'none') {
+              const opts = getPreprocessorOptions(styleResult.preprocessor, { sassOptions, lessOptions, stylusOptions });
+              if (opts && opts.verbose) {
+                console.log(`[Pulse] Compiled ${styleResult.preprocessor.toUpperCase()} in ${args.path}`);
               }
             }
 
             if (extractCss) {
               // Accumulate CSS for later emission
-              accumulatedCss += `/* ${args.path} */\n${css}\n\n`;
+              accumulatedCss += `/* ${args.path} */\n${styleResult.css}\n\n`;
 
               // Remove inline CSS injection from output
-              outputCode = outputCode.replace(
-                /\/\/ Styles\nconst styles = `[\s\S]*?`;\n\/\/ Inject styles\nconst styleEl = document\.createElement\("style"\);\nstyleEl\.textContent = styles;\ndocument\.head\.appendChild\(styleEl\);/,
-                '// Styles extracted to CSS file'
-              );
+              outputCode = removeInlineStyles(outputCode, '// Styles extracted to CSS file');
             }
             // else: keep inline CSS injection
+
+            if (styleResult.warning) {
+              return {
+                warnings: [{
+                  text: styleResult.warning,
+                  location: { file: args.path }
+                }],
+                contents: outputCode,
+                loader: 'js'
+              };
+            }
           }
 
           return {
@@ -225,14 +167,20 @@ export default function pulsePlugin(options = {}) {
 
             // Write CSS file
             writeFileSync(cssPath, accumulatedCss, 'utf8');
-            console.log(`[Pulse] Emitted CSS to ${extractCss}`);
+            if (!quiet) {
+              console.log(`[Pulse] Emitted CSS to ${extractCss}`);
+            }
           } catch (writeError) {
             console.error(`[Pulse] Failed to write CSS file: ${writeError.message}`);
           }
         }
       });
 
-      // Resolve .pulse imports as .js if needed
+      /**
+       * Resolve `.js` imports to `.pulse` files when a corresponding `.pulse`
+       * file exists on disk. Allows importing components as `.js` while the
+       * source is a `.pulse` file.
+       */
       build.onResolve({ filter: /\.js$/ }, (args) => {
         // Check if there's a corresponding .pulse file
         const pulsePath = args.path.replace(/\.js$/, '.pulse');