@asciidoctor/core 4.0.1 → 4.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asciidoctor/core",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "description": "Asciidoctor.js: AsciiDoc in JavaScript powered by Asciidoctor",
   "type": "module",
   "main": "build/node/index.cjs",
@@ -31,6 +31,7 @@
     "test:deno": "deno test --allow-env --no-check --allow-read --allow-sys --allow-write --allow-run --allow-net test/*.test.js",
     "test:coverage": "node --test --experimental-test-coverage --test-coverage-include='src/**' test/**.test.js",
     "test:browser": "vitest run --config vitest.browser.config.js",
+    "test:types": "tsc -p test/types/tsconfig.json",
     "lint": "biome lint src test",
     "format": "biome format --write src test",
     "check": "biome check src test"

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
@@ -1584,6 +1594,10 @@ export 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()
               }
             }
@@ -1664,12 +1678,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 +1730,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 +1745,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 +2044,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)