@localnerve/web-component-build 3.4.2 → 3.5.0

package/README.md

@@ -11,6 +11,7 @@ The parts are processed and written to an output directory, then exposed to a ca
 
   * [Why This Exists](#why-this-exists)
   * [Processing Possibilities](#processing-map)
+  * [Multiple Templates](#multiple-templates)
   * [Trusted Types Helpers](#trusted-types-helpers)
   * [Usage](#usage)
   * [API](#api)
@@ -43,6 +44,24 @@ The following is a table of _some_ of the possible input, processing, and output
 
 > By default, html minification minifies any css found therein.
 
+## Multiple Templates
+A component can carry several HTML templates (e.g. default / error / empty states), each referenced by its own distinct token in the javascript. Pass a `templates` array:
+
+```javascript
+const result = await build(outputDir, {
+  jsPath: '/some/path/file.js',
+  cssPath: '/some/path/file.css',          // shared, prepended to every template
+  templates: [
+    { name: 'default', htmlPath: '/some/path/default.html', token: '__TPL_DEFAULT__' },
+    { name: 'error',   htmlPath: '/some/path/error.html',   token: '__TPL_ERROR__' }
+  ]
+});
+// result.htmls -> [{ name, path, getHtml }, ...] in input order
+```
+Each entry takes `name` (output filename, defaults to the input basename), `htmlPath`, `token` (String or RegExp), and an optional per-template `cssLinkHref` override. The single-template `htmlPath` + `jsReplacement` options still work and are treated as one template.
+
+> Injection is **syntax-aware**: markup is spliced into the token's string/template literal with escaping for that context, so it may safely contain quotes, backticks, `${`, or backslashes.
+
 ## Trusted Types Helpers
 
 In addition to `build`, this package exports a small set of browser runtime helpers so that web components can be authored to work **with** and **without** [Trusted Types](https://developer.mozilla.org/en-US/docs/Web/API/Trusted_Types) enforcement (CSP `require-trusted-types-for 'script'`).
@@ -138,11 +157,18 @@ Full path to the output directory where css, html, and javascript output are wri
     + html will be inserted into the javascript file if `jsReplacement` and `jsPath` is supplied  
   
 * **jsPath** {String} - Full path to the input javascript file
-* **jsReplacement** {String|RegExp} - The replacement pattern for the css or html in the javascript file. See [pattern](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#pattern) for full documentation  
+* **jsReplacement** {String|RegExp} - The replacement pattern for the css or html in the javascript file (single template). See [pattern](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#pattern) for full documentation  
   If supplied:
     + A replacement will be attempted in the javascript file, `jsPath` must also be supplied
     + If **not supplied** or falsy, No replacement will be attempted and all assets are just copied to `outputDir`  
   
+* **templates** {Array} - Zero or more templates, each an object with:  
+  * **name** {String} - Output filename without extension (`${name}.html`). Defaults to the input basename.
+  * **htmlPath** {String} - Full path to the input html for this template.
+  * **token** {String|RegExp} - The placeholder in the javascript to replace.
+  * **cssLinkHref** {String} - Optional per-template link href override (falls back to the shared `cssLinkHref`).  
+  When supplied, takes precedence over the flat `htmlPath`/`jsReplacement` options. Shared `cssPath`/`cssLinkHref` are applied to every template. Duplicate resolved output names throw.
+  
 * **terserOptions** {Object} - The [javascript minifier options](https://github.com/terser/terser/blob/master/README.md#minify-options) object  
   Defaults:
   ```
@@ -183,5 +209,7 @@ The output of the build process. Allows access to the output paths and full outp
   
   + **getJs** {asyncFunction}, gets the output javascript  
   
+  + **htmls** {Array}, ordered list (matching `templates` input order) of `{ name, path, getHtml }` — one entry per html template. `getHtml()`/`htmlPath` above are shorthands for the first entry.
+  
 ## License
   * [BSD-3 Clasuse, Alex Grant, LocalNerve](LICENSE.md)

package/lib/build.js

@@ -2,7 +2,7 @@
  * Web Component Build
  * Builds the component parts
  * 
- * Copyright (c) 2023 - 2025 Alex Grant (@localnerve), LocalNerve LLC
+ * Copyright (c) 2023 - 2026 Alex Grant (@localnerve), LocalNerve LLC
  * Copyrights licensed under the BSD License. See the accompanying LICENSE file for terms.
  */
 import * as path from 'node:path';
@@ -27,36 +27,42 @@ class WebComponentBuild {
    * @param {String} outputDir - The full path to output directory.
    * @param {String} [jsPath] - The full path to the input js file.
    * @param {String} [cssPath] - The full path to the input css file.
-   * @param {String} [htmlPath] - The full path to the input html file.
    * @param {Boolean} [minifySkip] - flag to skip minification (debug), default false.
+   *
+   * HTML outputs are registered dynamically via addHtmlOutput(); a component may
+   * have zero or more of them (one per template).
    */
-  constructor (outputDir, jsPath, cssPath, htmlPath, minifySkip = false) {
-    const minimumInput = jsPath || cssPath || htmlPath;
-
-    if (!minimumInput) {
-      throw new Error(
-        'One of jsPath, cssPath, or htmlPath MUST be supplied to do\
- something meaningful. Did you forget something?'
-      );
-    }
+  constructor (outputDir, jsPath, cssPath, minifySkip = false) {
+    // Validation of "at least one meaningful input" is owned by build(), which
+    // can see the full option set (including html templates). The constructor
+    // stays lenient so an html-only component is not rejected here.
 
     this.inputCssFile = cssPath;
-    this.inputHtmlFile = htmlPath;
     this.inputJsFile = jsPath;
     this.outputDir = outputDir;
     this.minifySkip = minifySkip;
-    
+    this.htmlOutputs = [];
+
     if (jsPath) {
       this.outputJsFile = path.join(this.outputDir, path.basename(jsPath));
     }
-    if (htmlPath) {
-      this.outputHtmlFile = path.join(this.outputDir, path.basename(htmlPath));
-    }
     if (cssPath) {
       this.outputCssFile = path.join(this.outputDir, path.basename(cssPath));
     }
   }
 
+  /**
+   * Register an html output file for a template.
+   *
+   * @param {String} baseName - The output filename without extension (e.g. "default").
+   * @returns {String} The full path to the output html file.
+   */
+  addHtmlOutput (baseName) {
+    const outputPath = path.join(this.outputDir, `${baseName}.html`);
+    this.htmlOutputs.push({ name: baseName, path: outputPath });
+    return outputPath;
+  }
+
   /**
    * Minify the input css file and write it to the outputDir.
    *
@@ -79,17 +85,18 @@ class WebComponentBuild {
   }
 
   /**
-   * Minify the given html and write it to the outputDir.
-   * 
+   * Minify the given html and write it to a specific output file.
+   *
    * @param {String} htmlText - The full new html text.
+   * @param {String} outputPath - The full path to write the html to.
    * @param {Object} options - The html-minifier options.
    * @returns {String} minified html.
    */
-  async minifyHtml (htmlText, options = defaultHtmlMinifyOptions) {
+  async writeHtml (htmlText, outputPath, options = defaultHtmlMinifyOptions) {
     const minifiedHtml =
       this.minifySkip ? htmlText : await _minifyHtml(htmlText, options);
 
-    await fs.writeFile(this.outputHtmlFile, minifiedHtml, {
+    await fs.writeFile(outputPath, minifiedHtml, {
       encoding: 'utf8'
     });
 
@@ -122,9 +129,16 @@ class WebComponentBuild {
    */
   get output () {
     const _cssPath = this.outputCssFile;
-    const _htmlPath = this.outputHtmlFile;
     const _jsPath = this.outputJsFile;
 
+    const htmls = this.htmlOutputs.map(output => ({
+      name: output.name,
+      path: output.path,
+      async getHtml () {
+        return fs.readFile(output.path, { encoding: 'utf8' });
+      }
+    }));
+
     return {
       get cssPath () {
         return _cssPath;
@@ -136,13 +150,14 @@ class WebComponentBuild {
         }
         return cssText;
       },
+      // Backward-compatible shorthands resolve to the first html output.
       get htmlPath () {
-        return _htmlPath;
+        return htmls[0] ? htmls[0].path : undefined;
       },
       async getHtml () {
         let htmlText;
-        if (_htmlPath) {
-          htmlText = await fs.readFile(_htmlPath, { encoding: 'utf8' });
+        if (htmls[0]) {
+          htmlText = await htmls[0].getHtml();
         }
         return htmlText;
       },
@@ -155,7 +170,8 @@ class WebComponentBuild {
           jsText = await fs.readFile(_jsPath, { encoding: 'utf8' });
         }
         return jsText;
-      }
+      },
+      htmls
     };
   }
 }
@@ -163,15 +179,12 @@ class WebComponentBuild {
 /**
  * Create WebComponentBuild instance.
  *
- * @param {String} cssPath - The full path to the input css file.
- * @param {String} htmlPath - The full path to the input html file.
- * @param {String} jsPath - The full path to the input js file.
- * @param {String} outputDir - The full path to output directory.
+ * @param {String} outputDir - The full path to the output directory.
+ * @param {String} [jsPath] - The full path to the input js file.
+ * @param {String} [cssPath] - The full path to the input css file.
  * @param {Boolean} [minifySkip] - True to skip minifications (debug), default false.
  * @returns {WebComponentBuild} an instance of WebComponentBuild
  */
-export function createBuild (
-  cssPath, htmlPath, jsPath, outputDir, minifySkip = false
-) {
-  return new WebComponentBuild(cssPath, htmlPath, jsPath, outputDir, minifySkip);
+export function createBuild (outputDir, jsPath, cssPath, minifySkip = false) {
+  return new WebComponentBuild(outputDir, jsPath, cssPath, minifySkip);
 }

package/lib/index.js

@@ -3,12 +3,28 @@
  * Assemble and minify a web component from its parts.
  * Expose parts back to the calling build process.
  * 
- * Copyright (c) 2023 - 2025 Alex Grant (@localnerve), LocalNerve LLC
+ * Copyright (c) 2023 - 2026 Alex Grant (@localnerve), LocalNerve LLC
  * Copyrights licensed under the BSD License. See the accompanying LICENSE file for terms.
  */
+import * as path from 'node:path';
 import * as fs from 'node:fs/promises';
 import * as cheerio from 'cheerio';
 import { createBuild, defaultHtmlMinifyOptions } from './build.js';
+import { injectTokens } from './replace.js';
+import { log, deprecationsEnabled } from './log.js';
+
+/**
+ * Derive an html output base name (without extension) from an input path.
+ * A trailing ".html" is stripped so the registered output path ends in a single
+ * ".html". Other names are used as-is.
+ *
+ * @param {String} htmlPath - The full path to the input html file.
+ * @returns {String} The base name without extension.
+ */
+function htmlBaseName (htmlPath) {
+  const base = path.basename(htmlPath);
+  return base.endsWith('.html') ? base.slice(0, -'.html'.length) : base;
+}
 
 /**
  * Build entry point.
@@ -18,13 +34,20 @@ import { createBuild, defaultHtmlMinifyOptions } from './build.js';
  * @param {String} [options.jsPath] - full path to the javascript file
  * @param {String} [options.cssPath] - full path to the input css file
  * @param {String} [options.cssLinkHref] - http href to css resource
- * @param {String} [options.htmlPath] - full path to the input html file
- * @param {String} [options.jsReplacement] - Replacement token in the js file
+ * @param {String} [options.htmlPath] - full path to the input html file (single template)
+ * @param {String} [options.jsReplacement] - Replacement token in the js file (single template)
+ * @param {Array} [options.templates] - list of templates, each {name, htmlPath, token,
+ *   cssLinkHref}. When supplied, takes precedence over the flat options. Shared
+ *   cssPath/cssLinkHref are applied to every template unless a template overrides
+ *   its own cssLinkHref.
  * @param {Object} [options.terserOptions] - Js minifier options (terser)
  * @param {Object} [options.htmlminOptions] - html-minifier options
  * @param {Object} [options.cleancssOptions] - clean-css options
  * @param {Boolean} [options.minifySkip] - default false, flag to skip all minification (debug)
- * @returns {Object} Interface to getCss, getHtml, getJs for further processing
+ * @param {Boolean} [options.deprecationWarnings=true] - default true, emit console.warn
+ *   messages for flat single-template options and the htmlPath/getHtml shorthands
+ *   that are removed in v4.0.0. Set false (or env WEB_COMPONENT_BUILD_NO_DEPRECATION_WARNINGS) to suppress.
+ * @returns {Object} Interface to getCss, getHtml, getJs, and htmls for further processing
  */
 export async function build (outputDir, {
   jsPath,
@@ -32,52 +55,112 @@ export async function build (outputDir, {
   cssLinkHref,
   htmlPath,
   jsReplacement,
+  templates = [],
   terserOptions,
   htmlminOptions,
   cleancssOptions,
-  minifySkip = false
+  minifySkip = false,
+  deprecationWarnings
 } = {}) {
-  const build = createBuild(outputDir, jsPath, cssPath, htmlPath, minifySkip);
-  let jsText, cssText, htmlText;
+  // Deprecation / migration warnings for the flat single-template API. These
+  // options (and the getHtml()/htmlPath result shorthands) are removed in
+  // v4.0.0, where "templates" becomes required and html outputs become a named
+  // map (result.html[name]). Suppressed by deprecationWarnings: false or the
+  // WEB_COMPONENT_BUILD_NO_DEPRECATION_WARNINGS env var.
+  const usesFlatOptions = (!Array.isArray(templates) || templates.length === 0)
+    && Boolean(htmlPath || jsReplacement);
+
+  if (usesFlatOptions && deprecationsEnabled({ deprecationWarnings })) {
+    log(
+      'web-component-build',
+      'The flat single-template options "htmlPath"/"jsReplacement" are deprecated and will be removed in v4.0.0. Migrate to the "templates" array, e.g. templates: [{ name, htmlPath, token }].',
+      'warn'
+    );
+    log(
+      'web-component-build',
+      'In v4.0.0 the result\'s html surface changes from getHtml()/htmlPath to a named map: result.html[name] (each { name, path, getHtml }). Per-template cssPath/cssLinkHref overrides will also be supported.',
+      'warn'
+    );
+  }
+
+  // Resolve the template list. When `templates` is absent, synthesize a single
+  // template from the flat options for backward compatibility.
+  const resolved = (Array.isArray(templates) && templates.length > 0)
+    ? templates.map((t, i) => ({
+      name: t.name || (t.htmlPath ? htmlBaseName(t.htmlPath) : `template-${i}`),
+      htmlPath: t.htmlPath,
+      token: t.token,
+      cssLinkHref: t.cssLinkHref !== undefined ? t.cssLinkHref : cssLinkHref
+    }))
+    : [{
+      name: htmlPath ? htmlBaseName(htmlPath) : undefined,
+      htmlPath,
+      token: jsReplacement,
+      cssLinkHref
+    }];
+
+  const hasHtmlTemplate = resolved.some(t => t.htmlPath);
+  if (!jsPath && !cssPath && !hasHtmlTemplate) {
+    throw new Error(
+      'One of jsPath, cssPath, or htmlPath MUST be supplied to do something\n meaningful. Did you forget something?'
+    );
+  }
+
+  const build = createBuild(outputDir, jsPath, cssPath, minifySkip);
+  let jsText, cssText;
 
   if (jsPath) {
     jsText = await fs.readFile(jsPath, { encoding: 'utf8' });
-  } else if (jsReplacement) {
-    throw new Error('Invalid input, jsReplacement supplied without jsPath. Did you forget \'jsPath\'?');
+  } else if (jsReplacement || resolved.some(t => t.token)) {
+    throw new Error('Invalid input, a replacement token was supplied without jsPath. Did you forget \'jsPath\'?');
   }
 
   if (cssPath) {
     cssText = await build.minifyCss(cleancssOptions);
   }
 
-  if (htmlPath) {
-    htmlText = await fs.readFile(htmlPath, { encoding: 'utf8' });
-    const $ = cheerio.load(htmlText);
-    if (cssText) {
-      $('body').prepend(`<style>${cssText}</style>`);
-      htmlminOptions = htmlminOptions || defaultHtmlMinifyOptions;
-      htmlminOptions.minifyCSS = cleancssOptions;
-    }
-    if (cssLinkHref) {
-      $('body').prepend(`<link href="${cssLinkHref}" rel="stylesheet" />`);
+  // Detect duplicate html output names before writing anything.
+  const seenNames = new Set();
+  for (const template of resolved.filter(t => t.htmlPath)) {
+    if (seenNames.has(template.name)) {
+      throw new Error(
+        `Duplicate html output name "${template.name}". Give each template a distinct "name".`
+      );
     }
-    htmlText = await build.minifyHtml($('body').html(), htmlminOptions);
+    seenNames.add(template.name);
   }
 
-  if (jsReplacement) {
-    if (htmlText) {
-      htmlText = htmlText.replace(/$/mg, '\\');
-      if (htmlText.endsWith('\\')) {
-        htmlText = htmlText.slice(0, -1);
+  // Process each template: minify its html (with shared style/link prepended) and
+  // write it, or compute an inline css/link payload when there is no html file.
+  const injection = [];
+  for (const template of resolved) {
+    let payload;
+    if (template.htmlPath) {
+      const outputPath = build.addHtmlOutput(template.name);
+      const sourceHtml = await fs.readFile(template.htmlPath, { encoding: 'utf8' });
+      const $ = cheerio.load(sourceHtml);
+      const opts = { ...(htmlminOptions || defaultHtmlMinifyOptions) };
+      if (cssText) {
+        $('body').prepend(`<style>${cssText}</style>`);
+        opts.minifyCSS = cleancssOptions;
       }
-      jsText = jsText.replace(jsReplacement, htmlText);
+      if (template.cssLinkHref) {
+        $('body').prepend(`<link href="${template.cssLinkHref}" rel="stylesheet" />`);
+      }
+      payload = await build.writeHtml($('body').html(), outputPath, opts);
     } else if (cssText) {
-      jsText = jsText.replace(jsReplacement, `<style>${cssText}</style>`);
-    } else if (cssLinkHref) {
-      jsText = jsText.replace(
-        jsReplacement, `<link href="${cssLinkHref}" rel="stylesheet" />`
-      );
+      payload = `<style>${cssText}</style>`;
+    } else if (template.cssLinkHref) {
+      payload = `<link href="${template.cssLinkHref}" rel="stylesheet" />`;
     }
+
+    if (payload !== undefined && template.token) {
+      injection.push({ pattern: template.token, payload });
+    }
+  }
+
+  if (injection.length > 0) {
+    jsText = injectTokens(jsText, injection);
   }
 
   if (jsText) {

package/lib/log.js

@@ -0,0 +1,59 @@
+/**
+ * Web Component Build
+ * Colorized console logger + deprecation warning gate.
+ * 
+ * Copyright (c) 2023 - 2026 Alex Grant (@localnerve), LocalNerve LLC
+ * Copyrights licensed under the BSD License. See the accompanying LICENSE file for terms.
+ */
+import * as path from 'node:path';
+
+/**
+ * Colorized console logger.
+ *
+ * @param {string} owner - The plugin/function/owner name, the named source
+ * @param {string} message - The log message
+ * @param {'log'|'error'|'warn'} [method='log'] - console method to use
+ * @param {import('vinyl')|string} [file=null] - Vinyl file object or file/path string
+ */
+export function log (owner, message, method = 'log', file = null) {
+  const colors = {
+    magenta: '\x1b[35m',
+    yellow: '\x1b[33m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    reset: '\x1b[0m'
+  };
+  let filepath;
+  if (file) {
+    filepath = path.relative(process.cwd(), file?.path ?? file);
+  }
+  const now = new Date();
+  const TN = i => i < 10 ? `0${i}` : i;
+  const timestring = `${TN(now.getHours())}:${TN(now.getMinutes())}:${TN(now.getSeconds())}`;
+
+  console[method](
+    `[${colors.magenta}${timestring}${colors.reset}] ${owner}: ${method === 'log' ? colors.green : colors.red}${filepath ? `File ${filepath} - ` : ''}${colors.yellow}${message}${colors.reset}`
+  );
+}
+
+/**
+ * Determine whether deprecation warnings should be suppressed.
+ *
+ * Precedence (first match wins):
+ *   1. options.deprecationWarnings === false  → suppress
+ *   2. process.env.WEB_COMPONENT_BUILD_NO_DEPRECATION_WARNINGS truthy → suppress
+ *   3. Otherwise → emit warnings
+ *
+ * @param {Object} [options] - the build() options object
+ * @returns {boolean} true if deprecation warnings should be emitted
+ */
+export function deprecationsEnabled (options) {
+  if (options && options.deprecationWarnings === false) {
+    return false;
+  }
+  const env = process.env.WEB_COMPONENT_BUILD_NO_DEPRECATION_WARNINGS;
+  if (env !== undefined && env !== '' && env !== '0' && env !== 'false') {
+    return false;
+  }
+  return true;
+}

package/lib/replace.js

@@ -0,0 +1,197 @@
+/**
+ * Web Component Build
+ * Syntax-aware injection of payloads into string/template literals in a JS source file.
+ * 
+ * Replaces brittle text replacement (String.replace of a token) with an AST-based
+ * splice: the token is located inside its containing string or template literal via
+ * acorn, and the payload is escaped for that literal's quote context before being
+ * spliced in at the exact character offsets. This keeps the surrounding JavaScript
+ * valid regardless of quotes, backticks, "${" sequences, backslashes, or newlines
+ * present in the payload.
+ * 
+ * Copyright (c) 2023 - 2026 Alex Grant (@localnerve), LocalNerve LLC
+ * Copyrights licensed under the BSD License. See the accompanying LICENSE file for terms.
+ */
+import * as acorn from 'acorn';
+
+/**
+ * Parse javascript source, tolerating both module and script syntax.
+ *
+ * @param {String} code - The javascript source text.
+ * @returns {Object} The acorn AST.
+ */
+function parseJs (code) {
+  const attempts = [{ sourceType: 'module' }, { sourceType: 'script' }];
+  let lastError;
+  for (const opt of attempts) {
+    try {
+      return acorn.parse(code, { ecmaVersion: 'latest', ...opt });
+    } catch (e) {
+      lastError = e;
+    }
+  }
+  throw new Error(
+    `Failed to parse javascript for token injection: ${lastError.message}`,
+    { cause: lastError }
+  );
+}
+
+/**
+ * Collect all string Literal and TemplateLiteral nodes from an AST.
+ *
+ * @param {Object} ast - The acorn AST.
+ * @returns {Array} of literal nodes (absolute start/end offsets).
+ */
+function collectLiterals (ast) {
+  const literals = [];
+
+  (function walk (node) {
+    if (!node || typeof node.type !== 'string') return;
+    if ((node.type === 'Literal' && typeof node.value === 'string') ||
+        node.type === 'TemplateLiteral') {
+      literals.push(node);
+    }
+    for (const key in node) {
+      const value = node[key];
+      if (Array.isArray(value)) {
+        value.forEach(child => walk(child));
+      } else if (value && typeof value.type === 'string') {
+        walk(value);
+      }
+    }
+  })(ast);
+
+  return literals;
+}
+
+/**
+ * Resolve the character span of a pattern within text.
+ *
+ * @param {String} text - The full source text.
+ * @param {String|RegExp} pattern - The token to locate (string or regular expression).
+ * @returns {Object|null} {start, end} offsets into text, or null when not found.
+ */
+function findSpan (text, pattern) {
+  if (typeof pattern === 'string') {
+    const i = text.indexOf(pattern);
+    return i < 0 ? null : { start: i, end: i + pattern.length };
+  }
+  const re = pattern.global
+    ? new RegExp(pattern.source, pattern.flags.replace(/g/g, ''))
+    : pattern;
+  const m = re.exec(text);
+  if (!m) return null;
+  return { start: m.index, end: m.index + m[0].length };
+}
+
+/**
+ * Human-readable label for a pattern, used in error messages.
+ *
+ * @param {String|RegExp} pattern - The token pattern.
+ * @returns {String} A short description of the pattern.
+ */
+function describePattern (pattern) {
+  if (typeof pattern === 'string') {
+    const short = pattern.length > 60 ? `${pattern.slice(0, 60)}…` : pattern;
+    return `'${short}'`;
+  }
+  return String(pattern);
+}
+
+/**
+ * Escape a payload so it is valid inside the given string literal context.
+ * 
+ * For single/double quoted literals the result is a one-line interior (newlines,
+ * line separators, and the delimiter are escaped). For template literals only the
+ * backtick, "${", and backslash need escaping; raw newlines are legal.
+ *
+ * @param {String} payload - The content to inject.
+ * @param {String} context - The opening quote of the containing literal: ', ", or `.
+ * @returns {String} The escaped interior text.
+ */
+export function escapeForContext (payload, context) {
+  let out = String(payload).replace(/\\/g, '\\\\');
+
+  if (context === '`') {
+    return out
+      .replace(/`/g, '\\`')
+      .replace(/\$\{/g, '\\${');
+  }
+
+  const delimEscape = context === '\'' ? '\\\'' : '\\"';
+
+  return out
+    .replace(context === '\'' ? /'/g : /"/g, delimEscape)
+    .replace(/\r/g, '\\r')
+    .replace(/\n/g, '\\n')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+
+/**
+ * Inject payloads into the string/template literals containing the given tokens.
+ * 
+ * The source is parsed once; every token's literal node and absolute span are
+ * located on the original source, then splices are applied back-to-front so that
+ * earlier offsets remain valid. Multiple tokens may share a single literal or be
+ * spread across the file.
+ *
+ * @param {String} jsText - The full javascript source text.
+ * @param {Array} entries - Array of {pattern: String|RegExp, payload: String}.
+ * @returns {String} The new javascript source text with all tokens replaced.
+ * @throws {Error} When the source does not parse, a token is missing or lies
+ * outside any string/template literal, a template token crosses a "${}"
+ * expression boundary, or token spans overlap.
+ */
+export function injectTokens (jsText, entries) {
+  if (!Array.isArray(entries) || entries.length === 0) return jsText;
+
+  const literals = collectLiterals(parseJs(jsText));
+
+  // locate every token on the original source before splicing anything
+  const splices = entries.map(entry => {
+    const label = describePattern(entry.pattern);
+    const span = findSpan(jsText, entry.pattern);
+    if (!span) {
+      throw new Error(`Replacement token ${label} not found in javascript source.`);
+    }
+
+    const node = literals
+      .filter(n => n.start <= span.start && span.end <= n.end)
+      .sort((a, b) => (a.end - a.start) - (b.end - b.start))[0];
+
+    if (!node) {
+      throw new Error(`Replacement token ${label} is not inside a string or template literal.`);
+    }
+
+    if (node.type === 'TemplateLiteral') {
+      const quasi = node.quasis.find(q => q.start <= span.start && span.end <= q.end);
+      if (!quasi) {
+        throw new Error(
+          `Replacement token ${label} crosses a template expression boundary (${'{…}'}); not supported.`
+        );
+      }
+    }
+
+    return { ...span, context: jsText[node.start], payload: entry.payload, label };
+  });
+
+  // reject overlapping spans (including duplicates)
+  const ascending = [...splices].sort((a, b) => a.start - b.start);
+  for (let i = 1; i < ascending.length; i++) {
+    if (ascending[i].start < ascending[i - 1].end) {
+      throw new Error(
+        `Replacement tokens ${ascending[i - 1].label} and ${ascending[i].label} overlap in the javascript source.`
+      );
+    }
+  }
+
+  // apply splices back-to-front so earlier offsets stay valid
+  let out = jsText;
+  const descending = [...splices].sort((a, b) => b.start - a.start);
+  for (const s of descending) {
+    out = out.slice(0, s.start) + escapeForContext(s.payload, s.context) + out.slice(s.end);
+  }
+
+  return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localnerve/web-component-build",
-  "version": "3.4.2",
+  "version": "3.5.0",
   "description": "A library to help build web components",
   "main": "index.js",
   "type": "module",
@@ -54,6 +54,7 @@
   },
   "homepage": "https://github.com/localnerve/web-component-build#readme",
   "dependencies": {
+    "acorn": "^8.18.0",
     "cheerio": "^1.2.0",
     "clean-css": "^5.3.3",
     "html-minifier-terser": "^7.2.0",