@asciidoctor/core 4.0.1 → 4.0.3

package/build/node/index.cjs

@@ -1,11 +1,12 @@
 'use strict';
 
 const node_module = require('node:module');
+const node_url = require('node:url');
 const node_fs = require('node:fs');
 const path = require('node:path');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
-var version = "4.0.1";
+var version = "4.0.3";
 const packageJson = {
 	version: version};
 
@@ -3039,9 +3040,10 @@ class AbstractNode {
    * Construct a URI reference or data URI to the target image.
    *
    * If the target image is already a URI it is left untouched (unless data-uri
-   * conversion is requested). The image is resolved relative to the directory
-   * named by assetDirKey. When data-uri is enabled and the safe level permits,
-   * the image is embedded as a Base64 data URI.
+   * conversion is requested). If the target image is a data URI, then it is
+   * already an embedded image, so it is returned as-is. The image is resolved
+   * relative to the directory named by assetDirKey. When data-uri is enabled and
+   * the safe level permits, the image is embedded as a Base64 data URI.
    *
    * NOTE: When the document has both 'data-uri' and 'allow-uri-read' enabled
    * and the resolved image URL is a remote URI, this method returns a Promise
@@ -3052,6 +3054,8 @@ class AbstractNode {
    * @returns {Promise<string>} a Promise resolving to a String reference or data URI.
    */
   async imageUri(targetImage, assetDirKey = 'imagesdir') {
+    // A data URI is already an embedded image, so use it as-is rather than reading or re-encoding it.
+    if (targetImage.startsWith('data:')) return targetImage
     const doc = this.document;
     if (doc.safe < SafeMode.SECURE && doc.hasAttribute('data-uri')) {
       let imagesBase;
@@ -5459,7 +5463,18 @@ class SecurityError extends Error {
 function applyBackendTraits(instance) {
   instance._backendTraits = null;
 
-  instance.basebackend = function (value = null) {
+  // Install a Ruby-style trait accessor method, but never clobber a flat string
+  // property the converter already declared (convention #2). Overwriting e.g.
+  // `converter.outfilesuffix = '.html'` with a method would silently turn the
+  // author's string into a function; the backend traits stay reachable through
+  // `_getBackendTraits()` instead.
+  const defineTraitAccessor = (name, fn) => {
+    const existing = Object.getOwnPropertyDescriptor(instance, name);
+    if (existing && typeof existing.value !== 'function') return
+    instance[name] = fn;
+  };
+
+  defineTraitAccessor('basebackend', function (value = null) {
     if (value) {
       const traits = (this._backendTraits ??= {});
       traits.basebackend = value;
@@ -5473,19 +5488,19 @@ function applyBackendTraits(instance) {
       return value
     }
     return this._getBackendTraits().basebackend
-  };
-  instance.filetype = function (value = null) {
+  });
+  defineTraitAccessor('filetype', function (value = null) {
     if (value) return (this._getBackendTraits().filetype = value)
     return this._getBackendTraits().filetype
-  };
-  instance.htmlsyntax = function (value = null) {
+  });
+  defineTraitAccessor('htmlsyntax', function (value = null) {
     if (value) return (this._getBackendTraits().htmlsyntax = value)
     return this._getBackendTraits().htmlsyntax
-  };
-  instance.outfilesuffix = function (value = null) {
+  });
+  defineTraitAccessor('outfilesuffix', function (value = null) {
     if (value) return (this._getBackendTraits().outfilesuffix = value)
     return this._getBackendTraits().outfilesuffix
-  };
+  });
   instance.supportsTemplates = function (value = true) {
     this._getBackendTraits().supportsTemplates = value;
   };
@@ -5569,7 +5584,9 @@ function normalizeConverter(converter, backend) {
     }
   }
 
-  // Apply the BackendTraits mixin so Document can call the standard accessor methods.
+  // Apply the BackendTraits mixin so Document can read traits via
+  // _getBackendTraits(). Flat string properties (convention #2) are preserved:
+  // applyBackendTraits does not overwrite an existing same-named data property.
   applyBackendTraits(converter);
   if (traits) {
     converter._backendTraits = traits;
@@ -13506,6 +13523,30 @@ function _uniform(str, chr, len) {
  * @typedef {ProcessorDslInterface & { prefer(): void; prepend(): void }} DocumentProcessorDslInterface
  */
 
+/**
+ * DSL interface for preprocessors.
+ *
+ * @typedef {Omit<DocumentProcessorDslInterface, 'process'> & {
+ *   process(fn: (this: PreprocessorDslInterface, document: Document, reader: Reader) => Reader | void): void;
+ * }} PreprocessorDslInterface
+ */
+
+/**
+ * DSL interface for tree processors.
+ *
+ * @typedef {Omit<DocumentProcessorDslInterface, 'process'> & {
+ *   process(fn: (this: TreeProcessorDslInterface, document: Document) => Document | void): void;
+ * }} TreeProcessorDslInterface
+ */
+
+/**
+ * DSL interface for postprocessors.
+ *
+ * @typedef {Omit<DocumentProcessorDslInterface, 'process'> & {
+ *   process(fn: (this: PostprocessorDslInterface, document: Document, output: string) => string): void;
+ * }} PostprocessorDslInterface
+ */
+
 /**
  * DSL interface for syntax processors (BlockProcessor, BlockMacroProcessor, InlineMacroProcessor).
  *
@@ -13526,28 +13567,35 @@ function _uniform(str, chr, len) {
 /**
  * DSL interface for include processors.
  *
- * @typedef {DocumentProcessorDslInterface & {
+ * @typedef {Omit<DocumentProcessorDslInterface, 'process'> & {
  *   handles(fn: (target: string) => boolean): void;
  *   handles(fn: (doc: Document, target: string) => boolean): void;
+ *   process(fn: (this: IncludeProcessorDslInterface, document: Document, reader: Reader, target: string, attributes: Record<string, string>) => void): void;
  * }} IncludeProcessorDslInterface
  */
 
 /**
  * DSL interface for docinfo processors.
  *
- * @typedef {DocumentProcessorDslInterface & {
+ * @typedef {Omit<DocumentProcessorDslInterface, 'process'> & {
  *   atLocation(value: string): void;
+ *   process(fn: (this: DocinfoProcessorDslInterface, document: Document) => string): void;
  * }} DocinfoProcessorDslInterface
  */
 
 /**
  * DSL interface for block processors.
  *
- * @typedef {SyntaxProcessorDslInterface & {
+ * The `process` callback is bound to the processor instance, so `this` inside it
+ * (and inside the registration function) exposes the `createBlock` helpers.
+ *
+ * @typedef {Omit<SyntaxProcessorDslInterface, 'process'> & {
  *   contexts(...value: (string | string[])[]): void;
  *   onContexts(...value: (string | string[])[]): void;
  *   onContext(...value: (string | string[])[]): void;
  *   bindTo(...value: (string | string[])[]): void;
+ *   createBlock(parent: AbstractBlock, context: string, source?: string | string[] | null, attrs?: object, opts?: object): Block;
+ *   process(fn: (this: BlockProcessorDslInterface, parent: AbstractBlock, reader: Reader, attributes: Record<string, unknown>) => AbstractBlock | void): void;
  * }} BlockProcessorDslInterface
  */
 
@@ -13557,14 +13605,31 @@ function _uniform(str, chr, len) {
  * @typedef {SyntaxProcessorDslInterface} MacroProcessorDslInterface
  */
 
+/**
+ * DSL interface for block macro processors.
+ *
+ * The `process` callback is bound to the processor instance, so `this` inside it
+ * (and inside the registration function) exposes the `createBlock` helpers.
+ *
+ * @typedef {Omit<MacroProcessorDslInterface, 'process'> & {
+ *   createBlock(parent: AbstractBlock, context: string, source?: string | string[] | null, attrs?: object, opts?: object): Block;
+ *   process(fn: (this: BlockMacroProcessorDslInterface, parent: AbstractBlock, target: string, attributes: Record<string, unknown>) => AbstractBlock | void): void;
+ * }} BlockMacroProcessorDslInterface
+ */
+
 /**
  * DSL interface for inline macro processors.
  *
- * @typedef {MacroProcessorDslInterface & {
+ * The `process` callback is bound to the processor instance, so `this` inside it
+ * (and inside the registration function) exposes the `createInline` helper.
+ *
+ * @typedef {Omit<MacroProcessorDslInterface, 'process'> & {
  *   format(value: string): void;
  *   matchFormat(value: string): void;
  *   usingFormat(value: string): void;
  *   match(value: RegExp): void;
+ *   createInline(parent: AbstractBlock, context: string, text: string, opts?: object): Inline;
+ *   process(fn: (this: InlineMacroProcessorDslInterface, parent: AbstractBlock, target: string, attributes: Record<string, unknown>) => Inline | void): void;
  * }} InlineMacroProcessorDslInterface
  */
 
@@ -14285,7 +14350,15 @@ class IncludeProcessor extends Processor {
   }
 
   /**
-   * @param {Document} doc - The document being parsed.
+   * Decide whether this include processor handles the given target.
+   *
+   * Override this method in a subclass. The override may accept either just the
+   * target string (Ruby-style, arity 1) or both the document and the target
+   * (arity 2) — an arity-1 override is adapted at registration time so the
+   * parser can always invoke it as `handles(doc, target)`. The first parameter
+   * is therefore typed `Document | string` so both override shapes type-check.
+   *
+   * @param {Document|string} doc - The document being parsed, or (for a Ruby-style arity-1 override) the include target.
    * @param {string} target - The target of the include directive.
    * @returns {boolean} true if this processor handles the given target.
    */
@@ -14653,6 +14726,14 @@ class Registry {
    *   this.process(function (doc, reader) { ... })
    * })
    *
+   * @overload
+   * @param {typeof Preprocessor} processor - A Preprocessor subclass or instance.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
+   * @overload
+   * @param {(this: PreprocessorDslInterface) => void} fn - Registration function bound to the preprocessor DSL.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
    * @param {...*} args - Class constructor, instance, or block function.
    * @returns {ProcessorExtension} the Extension stored in the registry.
    */
@@ -14686,6 +14767,14 @@ class Registry {
   /**
    * Register a TreeProcessor with the extension registry.
    *
+   * @overload
+   * @param {typeof TreeProcessor} processor - A TreeProcessor subclass or instance.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
+   * @overload
+   * @param {(this: TreeProcessorDslInterface) => void} fn - Registration function bound to the tree processor DSL.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
    * @param {...*} args - Class constructor, instance, or block function.
    * @returns {ProcessorExtension} the Extension stored in the registry.
    */
@@ -14739,6 +14828,14 @@ class Registry {
   /**
    * Register a Postprocessor with the extension registry.
    *
+   * @overload
+   * @param {typeof Postprocessor} processor - A Postprocessor subclass or instance.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
+   * @overload
+   * @param {(this: PostprocessorDslInterface) => void} fn - Registration function bound to the postprocessor DSL.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
    * @param {...*} args - Class constructor, instance, or block function.
    * @returns {ProcessorExtension} the Extension stored in the registry.
    */
@@ -14772,6 +14869,14 @@ class Registry {
   /**
    * Register an IncludeProcessor with the extension registry.
    *
+   * @overload
+   * @param {typeof IncludeProcessor} processor - An IncludeProcessor subclass or instance.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
+   * @overload
+   * @param {(this: IncludeProcessorDslInterface) => void} fn - Registration function bound to the include processor DSL.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
    * @param {...*} args - Class constructor, instance, or block function.
    * @returns {ProcessorExtension} the Extension stored in the registry.
    */
@@ -14810,6 +14915,14 @@ class Registry {
   /**
    * Register a DocinfoProcessor with the extension registry.
    *
+   * @overload
+   * @param {typeof DocinfoProcessor} processor - A DocinfoProcessor subclass or instance.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
+   * @overload
+   * @param {(this: DocinfoProcessorDslInterface) => void} fn - Registration function bound to the docinfo processor DSL.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
    * @param {...*} args - Class constructor, instance, or block function.
    * @returns {ProcessorExtension} the Extension stored in the registry.
    */
@@ -14877,6 +14990,20 @@ class Registry {
    *   this.process(function (parent, reader, attrs) { ... })
    * })
    *
+   * @overload
+   * @param {typeof BlockProcessor} processor - A BlockProcessor subclass.
+   * @param {string} [name] - Optional explicit block name.
+   * @returns {ProcessorExtension} an Extension proxy object.
+   *
+   * @overload
+   * @param {string} name - The block name.
+   * @param {(this: BlockProcessorDslInterface) => void} fn - Registration function bound to the block DSL.
+   * @returns {ProcessorExtension} an Extension proxy object.
+   *
+   * @overload
+   * @param {(this: BlockProcessorDslInterface) => void} fn - Registration function bound to the block DSL.
+   * @returns {ProcessorExtension} an Extension proxy object.
+   *
    * @param {...*} args - Class constructor, instance, block function, or name + one of those.
    * @returns {ProcessorExtension} an Extension proxy object.
    */
@@ -14927,6 +15054,20 @@ class Registry {
   /**
    * Register a BlockMacroProcessor with the extension registry.
    *
+   * @overload
+   * @param {typeof BlockMacroProcessor} processor - A BlockMacroProcessor subclass.
+   * @param {string} [name] - Optional explicit macro name.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
+   * @overload
+   * @param {string} name - The macro name.
+   * @param {(this: BlockMacroProcessorDslInterface) => void} fn - Registration function bound to the block macro DSL.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
+   * @overload
+   * @param {(this: BlockMacroProcessorDslInterface) => void} fn - Registration function bound to the block macro DSL.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
    * @param {...*} args - Class constructor, instance, or block function.
    * @returns {ProcessorExtension} the Extension stored in the registry.
    */
@@ -14982,6 +15123,20 @@ class Registry {
   /**
    * Register an InlineMacroProcessor with the extension registry.
    *
+   * @overload
+   * @param {typeof InlineMacroProcessor} processor - An InlineMacroProcessor subclass.
+   * @param {string} [name] - Optional explicit macro name.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
+   * @overload
+   * @param {string} name - The macro name.
+   * @param {(this: InlineMacroProcessorDslInterface) => void} fn - Registration function bound to the inline macro DSL.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
+   * @overload
+   * @param {(this: InlineMacroProcessorDslInterface) => void} fn - Registration function bound to the inline macro DSL.
+   * @returns {ProcessorExtension} the Extension stored in the registry.
+   *
    * @param {...*} args - Class constructor, instance, or block function.
    * @returns {ProcessorExtension} the Extension stored in the registry.
    */
@@ -16098,7 +16253,7 @@ class Document extends AbstractBlock {
 
     const attrOverrides = this._attributeOverrides;
     attrOverrides.asciidoctor = '';
-    attrOverrides['asciidoctor-version'] = '3.0.0.dev'; // matches Ruby VERSION
+    attrOverrides['asciidoctor-version'] = packageJson.version;
 
     const safeModeName = SafeMode.nameForValue(this.safe);
     attrOverrides['safe-mode-name'] = safeModeName;
@@ -16290,16 +16445,16 @@ class Document extends AbstractBlock {
     // attribute (re)assignments are in scope; snapshot and restore the document
     // attributes so the downstream steps and conversion still start from the restored
     // (header) state, matching Ruby's restore_attributes-before-convert invariant.
+    //
+    // This runs in two passes because list item / table cell / dlist text may contain
+    // natural cross-references (e.g. <<Some section title>>) that resolve against the
+    // reftext→id map. Pass 1 substitutes titles and reftexts only, so every section
+    // reftext is known; the map is then built; pass 2 substitutes the block content
+    // text, where resolveId() can now match those natural references.
     const attributesSnapshot = { ...this.attributes };
-    await this._resolveAllTexts(this);
-    for (const key of Reflect.ownKeys(this.attributes))
-      delete this.attributes[key];
-    Object.assign(this.attributes, attributesSnapshot);
-    // Reset the footnote counter so that body-content footnotes (processed during conversion)
-    // start numbering from 1, reproducing Ruby's "out of sequence" quirk: title footnotes are
-    // numbered during parsing via apply_title_subs, then the counter restarts for body content.
-    delete this.attributes['footnote-number'];
-    delete this._counters['footnote-number'];
+    // Pass 1: titles + reftexts (no block content text yet).
+    await this._resolveAllTexts(this, false);
+    this._restoreAttributeSnapshot(attributesSnapshot);
     // Pre-compute reftext for all registered inline anchor nodes.
     for (const ref of Object.values(this.catalog.refs)) {
       if (ref && typeof ref.precomputeReftext === 'function') {
@@ -16308,6 +16463,15 @@ class Document extends AbstractBlock {
     }
     // Build the reftext→id lookup map so that resolveId() is synchronous.
     await this._buildReftextsMap();
+    // Pass 2: list item / table cell / dlist text, now that natural cross-references
+    // can be resolved against the reftext→id map.
+    await this._resolveAllTexts(this, true);
+    this._restoreAttributeSnapshot(attributesSnapshot);
+    // Reset the footnote counter so that body-content footnotes (processed during conversion)
+    // start numbering from 1, reproducing Ruby's "out of sequence" quirk: title footnotes are
+    // numbered during parsing via apply_title_subs, then the counter restarts for body content.
+    delete this.attributes['footnote-number'];
+    delete this._counters['footnote-number'];
 
     this._parsed = true;
     return this
@@ -17282,6 +17446,10 @@ class Document extends AbstractBlock {
                 cell._innerDocument &&
                 cell._innerContent == null
               ) {
+                // Recurse into the inner document first so that AsciiDoc cells
+                // of any nested table have their content computed before the
+                // inner document (and the nested table) is rendered.
+                await this._convertAsciiDocCells(cell._innerDocument);
                 cell._innerContent = await cell._innerDocument.convert();
               }
             }
@@ -17362,12 +17530,33 @@ class Document extends AbstractBlock {
       : ['attributes']
   }
 
+  /**
+   * @private
+   * Restore the document attributes to a previously captured snapshot, discarding any
+   * body-level (re)assignments replayed while pre-computing text. Mirrors Ruby's
+   * restore_attributes-before-convert invariant.
+   * @param {Object} snapshot - The attributes snapshot to restore.
+   */
+  _restoreAttributeSnapshot(snapshot) {
+    for (const key of Reflect.ownKeys(this.attributes))
+      delete this.attributes[key];
+    Object.assign(this.attributes, snapshot);
+  }
+
   /**
    * @private
    * Walk the block tree and pre-compute all async text values.
    * Handles titles (AbstractBlock), list item text, table cell text, and reftexts.
-   */
-  async _resolveAllTexts(block) {
+   *
+   * Runs in two passes (see {@link parse}): with `resolveContent` false only titles and
+   * reftexts are substituted (so the reftext→id map can be built); with `resolveContent`
+   * true the list item / table cell / dlist text is substituted, resolving any natural
+   * cross-references against the now-complete map. Title/reftext pre-computation is
+   * idempotent (results are cached), so running it in both passes is a no-op the second time.
+   * @param {AbstractBlock} block - The block to resolve.
+   * @param {boolean} resolveContent - Whether to substitute list item / cell / dlist text.
+   */
+  async _resolveAllTexts(block, resolveContent) {
     // Replay this block's attribute entries (in document order, since the walk is
     // depth-first pre-order like conversion) so that body-level attribute assignments
     // and reassignments are in scope when the block's — and its descendants' and later
@@ -17393,12 +17582,12 @@ class Document extends AbstractBlock {
       // dlist.blocks is an array of [[term, ...], item_or_null] pairs.
       for (const [terms, item] of block.blocks ?? []) {
         for (const term of terms ?? []) {
-          await term.precomputeText?.();
-          await this._resolveAllTexts(term);
+          if (resolveContent) await term.precomputeText?.();
+          await this._resolveAllTexts(term, resolveContent);
         }
         if (item) {
-          await item.precomputeText?.();
-          await this._resolveAllTexts(item);
+          if (resolveContent) await item.precomputeText?.();
+          await this._resolveAllTexts(item, resolveContent);
         }
       }
     } else if (ctx === 'table') {
@@ -17408,14 +17597,14 @@ class Document extends AbstractBlock {
         ...(block.rows?.foot ?? []),
       ]) {
         for (const cell of row) {
-          await cell.precomputeText?.();
+          if (resolveContent) await cell.precomputeText?.();
           await cell.precomputeReftext?.();
         }
       }
     } else {
       for (const child of block.blocks ?? []) {
-        await child.precomputeText?.();
-        await this._resolveAllTexts(child);
+        if (resolveContent) await child.precomputeText?.();
+        await this._resolveAllTexts(child, resolveContent);
       }
     }
   }
@@ -17707,14 +17896,19 @@ class Document extends AbstractBlock {
     let newBasebackend, newFiletype;
 
     if (converter && typeof converter._getBackendTraits === 'function') {
-      newBasebackend = converter.basebackend();
-      newFiletype = converter.filetype();
-      const htmlsyntax = converter.htmlsyntax();
+      // Read the traits object directly rather than the same-named accessor
+      // methods. A user converter that declares flat string properties
+      // (`converter.outfilesuffix = '.html'`, convention #2) keeps them intact,
+      // so callers reading `converter.outfilesuffix` still see the string.
+      const traits = converter._getBackendTraits();
+      newBasebackend = traits.basebackend;
+      newFiletype = traits.filetype;
+      const htmlsyntax = traits.htmlsyntax;
       if (htmlsyntax) attrs.htmlsyntax = htmlsyntax;
       if (init) {
-        attrs.outfilesuffix ??= converter.outfilesuffix();
+        attrs.outfilesuffix ??= traits.outfilesuffix;
       } else if (!this.isAttributeLocked('outfilesuffix')) {
-        attrs.outfilesuffix = converter.outfilesuffix();
+        attrs.outfilesuffix = traits.outfilesuffix;
       }
     } else if (converter) {
       const traits = deriveBackendTraits(newBackend);
@@ -21025,7 +21219,7 @@ class Html5Converter extends ConverterBase {
     let reproducible;
     if (!(reproducible = node.hasAttribute('reproducible'))) {
       result.push(
-        `<meta name="generator" content="Asciidoctor ${node.getAttribute('asciidoctor-version')}"${slash}>`
+        `<meta name="generator" content="Asciidoctor.js ${node.getAttribute('asciidoctor-version')}"${slash}>`
       );
     }
     if (node.hasAttribute('app-name')) {
@@ -21742,7 +21936,9 @@ ${await node.content()}
     const slash = this._voidSlash;
     let img, src;
     if (
-      (node.hasAttribute('format', 'svg') || target.includes('.svg')) &&
+      (node.hasAttribute('format', 'svg') ||
+        target.includes('.svg') ||
+        target.startsWith('data:image/svg+xml')) &&
       node.document.safe < SafeMode.SECURE
     ) {
       if (node.hasOption('inline')) {
@@ -22583,7 +22779,9 @@ Your browser does not support the video tag.
       if (node.hasAttribute('title'))
         attrs += ` title="${node.getAttribute('title')}"`;
       if (
-        (node.hasAttribute('format', 'svg') || target.includes('.svg')) &&
+        (node.hasAttribute('format', 'svg') ||
+          target.includes('.svg') ||
+          target.startsWith('data:image/svg+xml')) &&
         node.document.safe < SafeMode.SECURE
       ) {
         if (node.hasOption('inline')) {
@@ -22676,12 +22874,17 @@ Your browser does not support the video tag.
 
   // NOTE expose readSvgContents for Bespoke converter
   async readSvgContents(node, target) {
-    let svg = await node.readContents(target, {
-      start: node.document.getAttribute('imagesdir'),
-      normalize: true,
-      label: 'SVG',
-      warnIfEmpty: true,
-    });
+    // A data-URI carries the SVG in the target itself (e.g. an embedded diagram
+    // produced with `:data-uri:`), so decode it directly rather than trying to
+    // read it as a file or remote URI.
+    let svg = target.startsWith('data:')
+      ? this._decodeDataUri(target)
+      : await node.readContents(target, {
+          start: node.document.getAttribute('imagesdir'),
+          normalize: true,
+          label: 'SVG',
+          warnIfEmpty: true,
+        });
     if (!svg) return null
     if (!svg.startsWith('<svg')) svg = svg.replace(SvgPreambleRx, '');
     // Fix incomplete SVG start tag (missing closing >) by inserting > before the first child element.
@@ -22713,6 +22916,27 @@ Your browser does not support the video tag.
 
   // ── Private helpers ─────────────────────────────────────────────────────────
 
+  /**
+   * Decode an inline `data:` URI to its text contents (e.g. an SVG document) so
+   * an image whose target is a data-URI can be embedded inline. Supports both
+   * Base64 (`;base64,`) and percent-encoded payloads. Returns null when the
+   * payload is missing.
+   *
+   * @internal
+   * @private
+   */
+  _decodeDataUri(target) {
+    const comma = target.indexOf(',');
+    if (comma === -1) return null
+    const meta = target.slice('data:'.length, comma);
+    const data = target.slice(comma + 1);
+    if (/;base64\b/i.test(meta)) {
+      const bytes = Uint8Array.from(atob(data), (c) => c.charCodeAt(0));
+      return new TextDecoder('utf-8').decode(bytes)
+    }
+    return decodeURIComponent(data)
+  }
+
   /**
    * @internal
    * @private
@@ -22955,8 +23179,7 @@ const composite = /*#__PURE__*/Object.freeze({
 //   - Ruby File.directory?/File.file? → fsp.stat().isDirectory()/isFile() (async).
 //   - Ruby File.basename / File.expand_path → node:path basename / resolve.
 //   - PathResolver.system_path → pathResolver.systemPath().
-//   - template.render(node, opts) → template.render({node, opts, helpers}).
-//   - Helpers loaded from helpers.js/helpers.cjs; can export configure(enginesContext).
+//   - template.render(node, opts) → template.render({node, opts, helpers}).//   - Helpers loaded from helpers.js/helpers.cjs/helpers.mjs; can export configure(enginesContext).
 //   - Custom engines registered via TemplateConverter.TemplateEngine.register(ext, adapter).
 //   - Thread safety / Mutex → not needed (single-threaded JS).
 //   - load_eruby / eRuby support → not applicable in JS environment.
@@ -23230,7 +23453,11 @@ class TemplateConverter extends ConverterBase {
       if (!(await _isFile(file))) continue
 
       // Collect helpers separately; process after all templates.
-      if (basename === 'helpers.js' || basename === 'helpers.cjs') {
+      if (
+        basename === 'helpers.js' ||
+        basename === 'helpers.cjs' ||
+        basename === 'helpers.mjs'
+      ) {
         helpersFile = file;
         continue
       }
@@ -23298,8 +23525,8 @@ class TemplateConverter extends ConverterBase {
         const pugOpts = { ...(this.engineOptions.pug ?? {}), filename: file };
         const renderFn = pug.compileFile(file, pugOpts);
         template = { render: renderFn, file };
-      } else if (ext === 'js' || ext === 'cjs') {
-        const renderFn = _require(file);
+      } else if (ext === 'js' || ext === 'cjs' || ext === 'mjs') {
+        const renderFn = await _loadModule(file, ext);
         template = { render: renderFn, file };
       } else {
         // Fall back to custom TemplateEngine registry.
@@ -23314,16 +23541,20 @@ class TemplateConverter extends ConverterBase {
       result[name] = template;
     }
 
-    // Load helpers if found (or if a helpers.js exists at the top of the dir).
-    const fallbackHelpers = path.join(templateDir, 'helpers.js');
-    const fallbackHelpersCjs = path.join(templateDir, 'helpers.cjs');
-    if (!helpersFile && (await _isFile(fallbackHelpers)))
-      helpersFile = fallbackHelpers;
-    if (!helpersFile && (await _isFile(fallbackHelpersCjs)))
-      helpersFile = fallbackHelpersCjs;
+    // Load helpers if found (or if a helpers file exists at the top of the dir).
+    if (!helpersFile) {
+      for (const ext of ['js', 'cjs', 'mjs']) {
+        const fallback = path.join(templateDir, `helpers.${ext}`);
+        if (await _isFile(fallback)) {
+          helpersFile = fallback;
+          break
+        }
+      }
+    }
 
     if (helpersFile) {
-      const ctx = _require(helpersFile);
+      const helpersExt = helpersFile.slice(helpersFile.lastIndexOf('.') + 1);
+      const ctx = await _loadModule(helpersFile, helpersExt);
       if (typeof ctx.configure === 'function') ctx.configure(enginesCtx);
       result['helpers.js'] = { file: helpersFile, ctx };
     }
@@ -23351,6 +23582,32 @@ class TemplateConverter extends ConverterBase {
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
+/**
+ * Load a JavaScript module (template render function or helpers object) by
+ * file extension.
+ *
+ * - `.cjs` files are always CommonJS: require() returns `module.exports`.
+ * - `.js` and `.mjs` files are loaded with a dynamic `import()`, which Node
+ *   resolves as either ES modules or CommonJS. The export is taken from the
+ *   module's default export (`export default …` in ESM, `module.exports = …`
+ *   in CommonJS via interop); when there is no default export the module
+ *   namespace is returned instead, so ESM helpers exposing named exports
+ *   (`export function configure() {}`) work too.
+ * @param {string} file - absolute path to the module file
+ * @param {string} ext - file extension without the leading dot ('js' | 'cjs' | 'mjs')
+ * @returns {Promise<*>} the module's default export, or its namespace
+ * @internal
+ * @private
+ */
+async function _loadModule(file, ext) {
+  if (ext === 'cjs') {
+    const mod = _require(file);
+    return mod?.default ? mod.default : mod
+  }
+  const mod = await import(node_url.pathToFileURL(file).href);
+  return mod.default ?? mod
+}
+
 /**
  * @internal
  * @private
@@ -24539,7 +24796,7 @@ class ManPageConverter extends ConverterBase {
       `'\\" t
 .\\"     Title: ${mantitle}
 .\\"    Author: ${node.hasAttribute('authors') ? node.getAttribute('authors') : '[see the "AUTHOR(S)" section]'}
-.\\" Generator: Asciidoctor ${node.getAttribute('asciidoctor-version')}`,
+.\\" Generator: Asciidoctor.js ${node.getAttribute('asciidoctor-version')}`,
     ];
 
     if (docdate) result.push(`.\\"      Date: ${docdate}`);