@asciidoctor/core 4.0.1 → 4.0.2

package/build/browser/index.js

@@ -1,4 +1,4 @@
-var version = "4.0.1";
+var version = "4.0.2";
 const packageJson = {
 	version: version};
 
@@ -3032,9 +3032,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
@@ -3045,6 +3046,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;
@@ -5452,7 +5455,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;
@@ -5466,19 +5480,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;
   };
@@ -5562,7 +5576,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;
@@ -16091,7 +16107,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;
@@ -16283,16 +16299,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') {
@@ -16301,6 +16317,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
@@ -17355,12 +17380,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
@@ -17386,12 +17432,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') {
@@ -17401,14 +17447,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);
       }
     }
   }
@@ -17700,14 +17746,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);
@@ -20954,7 +21005,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')) {
@@ -21671,7 +21722,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')) {
@@ -22512,7 +22565,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')) {
@@ -22605,12 +22660,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.
@@ -22642,6 +22702,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
@@ -24006,7 +24087,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}`);

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.2";
 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;
@@ -16098,7 +16115,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 +16307,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 +16325,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
@@ -17362,12 +17388,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 +17440,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 +17455,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 +17754,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 +21077,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 +21794,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 +22637,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 +22732,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 +22774,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 +23037,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 +23311,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 +23383,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 +23399,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 +23440,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 +24654,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}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asciidoctor/core",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "description": "Asciidoctor.js: AsciiDoc in JavaScript powered by Asciidoctor",
   "type": "module",
   "main": "build/node/index.cjs",

package/src/abstract_node.js

@@ -461,9 +461,10 @@ export 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
@@ -474,6 +475,8 @@ export 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

package/src/converter/html5.js

@@ -116,7 +116,7 @@ export default 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')) {
@@ -833,7 +833,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')) {
@@ -1674,7 +1676,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')) {
@@ -1767,12 +1771,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.
@@ -1804,6 +1813,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

package/src/converter/manpage.js

@@ -108,7 +108,7 @@ export default 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}`)

package/src/converter/template.js

@@ -8,8 +8,7 @@
 //   - 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.
@@ -19,6 +18,7 @@
 import { ConverterBase } from '../converter.js'
 import { PathResolver } from '../path_resolver.js'
 import { createRequire } from 'node:module'
+import { pathToFileURL } from 'node:url'
 import { promises as fsp } from 'node:fs'
 import path from 'node:path'
 
@@ -288,7 +288,11 @@ export 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
       }
@@ -356,8 +360,8 @@ export 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.
@@ -372,16 +376,20 @@ export 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 }
     }
@@ -409,6 +417,32 @@ export 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(pathToFileURL(file).href)
+  return mod.default ?? mod
+}
+
 /**
  * @internal
  * @private

package/src/converter.js

@@ -26,7 +26,18 @@ import { TrailingDigitsRx } from './rx.js'
 export 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
@@ -40,19 +51,19 @@ export 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
   }
@@ -136,7 +147,9 @@ export 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

package/src/document.js

@@ -12,6 +12,7 @@
 //   - Mutex / thread-safety not applicable in single-threaded JS.
 //   - `instance_variable_get :@attribute_overrides` → direct property access.
 
+import packageJson from '../package.json' with { type: 'json' }
 import { AbstractBlock } from './abstract_block.js'
 import { Section } from './section.js'
 import { Inline } from './inline.js'
@@ -400,7 +401,7 @@ export 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
@@ -592,16 +593,16 @@ export 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') {
@@ -610,6 +611,15 @@ export 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
@@ -1664,12 +1674,33 @@ export 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.
+   *
+   * 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) {
+  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
@@ -1695,12 +1726,12 @@ export 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') {
@@ -1710,14 +1741,14 @@ export 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)
       }
     }
   }
@@ -2009,14 +2040,19 @@ export 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)

package/types/abstract_node.d.ts

@@ -234,9 +234,10 @@ export abstract 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

package/types/document.d.ts

@@ -469,10 +469,26 @@ export class Document extends AbstractBlock<string> {
      * @returns {string[]} The list of substitutions to apply.
      */
     private _resolveDocinfoSubs;
+    /**
+     * @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.
+     */
+    private _restoreAttributeSnapshot;
     /**
      * @private
      * Walk the block tree and pre-compute all async text values.
      * Handles titles (AbstractBlock), list item text, table cell text, and reftexts.
+     *
+     * 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.
      */
     private _resolveAllTexts;
     /**