@asciidoctor/core 4.0.0-alpha.2 → 4.0.0-alpha.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asciidoctor/core",
-  "version": "4.0.0-alpha.2",
+  "version": "4.0.0-alpha.4",
   "description": "Asciidoctor.js: AsciiDoc in JavaScript powered by Asciidoctor",
   "type": "module",
   "main": "build/node/index.cjs",
@@ -28,6 +28,7 @@
     "build:types": "tsc && node scripts/strip-internal.js && node scripts/patch-jsdoc.js",
     "docs": "typedoc --tsconfig tsconfig.docs.json",
     "test": "node --test test/**.test.js",
+    "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",
     "lint": "biome lint src test",
@@ -65,7 +66,7 @@
   },
   "homepage": "https://github.com/asciidoctor/asciidoctor.js",
   "volta": {
-    "node": "24.14.1"
+    "node": "24.15.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",

package/src/abstract_node.js

@@ -31,6 +31,7 @@ import {
   extname,
   prepareSourceString,
 } from './helpers.js'
+import { fetchUri } from './http_cache.js'
 
 // ── Node.js fs (lazy, optional) ───────────────────────────────────────────────
 // Loaded on first use in Node.js; silently absent in browser/WebWorker environments.
@@ -485,10 +486,7 @@ export class AbstractNode {
           (targetImage = this.normalizeWebPath(targetImage, imagesBase, false)))
       ) {
         return doc.hasAttribute('allow-uri-read')
-          ? this.generateDataUriFromUri(
-              targetImage,
-              doc.hasAttribute('cache-uri')
-            )
+          ? this.generateDataUriFromUri(targetImage)
           : targetImage
       }
       return this.generateDataUri(targetImage, assetDirKey)
@@ -541,10 +539,7 @@ export class AbstractNode {
         )
       : this.normalizeSystemPath(targetImage)
     if (isUriish(imagePath)) {
-      return await this.generateDataUriFromUri(
-        imagePath,
-        this.document.hasAttribute('cache-uri')
-      )
+      return await this.generateDataUriFromUri(imagePath)
     }
     if (await isReadable(imagePath)) {
       const data = await _fsp.readFile(imagePath)
@@ -564,12 +559,12 @@ export class AbstractNode {
    * imageUri, the caller must await the returned Promise.
    *
    * @param {string} imageUri - The URI from which to read the image data (http/https/ftp).
-   * @param {boolean} [cacheUri=false] - A Boolean to control caching (not yet supported in JS).
    * @returns {Promise<string>} a Promise resolving to a String data URI.
    */
-  async generateDataUriFromUri(imageUri, cacheUri = false) {
+  async generateDataUriFromUri(imageUri) {
     try {
-      const response = await fetch(imageUri)
+      const doc = this.document
+      const response = await fetchUri(imageUri, doc)
       if (response.ok) {
         const mimetype = (
           response.headers.get('content-type') || 'application/octet-stream'
@@ -740,7 +735,7 @@ export class AbstractNode {
     ) {
       if (doc.hasAttribute('allow-uri-read')) {
         try {
-          const response = await fetch(resolvedTarget)
+          const response = await fetchUri(resolvedTarget, doc)
           const text = await response.text()
           contents = opts.normalize ? prepareSourceString(text).join(LF) : text
         } catch {
@@ -765,7 +760,7 @@ export class AbstractNode {
       })
     }
 
-    if (contents && opts.warnIfEmpty && contents.length === 0) {
+    if (contents != null && opts.warnIfEmpty && contents.length === 0) {
       this.logger.warn(`contents of ${label} is empty: ${resolvedTarget}`)
     }
     return contents

package/src/attribute_entry.js

@@ -1,3 +1,19 @@
+// Symbol key used to store attribute entries on a block-attributes object without
+// polluting the public attributes (invisible to Object.keys / for-in / JSON.stringify).
+// Spread ({ ...attrs }) copies Symbol-keyed properties, so the entry survives the
+// shallow clone made in AbstractNode's constructor.
+export const ATTR_ENTRIES_KEY = Symbol('attribute_entries')
+
+/**
+ * Return the attribute entries stored for the given block attributes object,
+ * or undefined if none have been saved.
+ * @param {Object} blockAttributes
+ * @returns {AttributeEntry[]|undefined}
+ */
+export function getAttributeEntries(blockAttributes) {
+  return blockAttributes[ATTR_ENTRIES_KEY]
+}
+
 export class AttributeEntry {
   constructor(name, value, negate = null) {
     this.name = name
@@ -6,7 +22,7 @@ export class AttributeEntry {
   }
 
   saveTo(blockAttributes) {
-    ;(blockAttributes.attribute_entries ??= []).push(this)
+    ;(blockAttributes[ATTR_ENTRIES_KEY] ??= []).push(this)
     return this
   }
 }

package/src/browser/reader.js

@@ -5,7 +5,7 @@
 //
 // This logic is specific to Asciidoctor.js and has no equivalent in the upstream Ruby asciidoctor
 // implementation. It handles the case where the document is loaded in a browser environment
-// (XMLHttpRequest / Fetch IO module) where paths can be file:// or http(s):// URIs.
+// where paths can be file:// or http(s):// URIs.
 //
 // The key behavioural differences from the standard file-system resolver:
 //   - Relative targets are resolved by string concatenation against a URI context dir,
@@ -55,7 +55,7 @@ function _linkReplacement(reader, target, attrlist) {
  * 1. target starts with file:// → inc_path = relpath = target
  * 2. target is a URI → must descend from baseDir or allow-uri-read; else → link
  * 3. target is an absolute OS path → prepend file:// (or file:///)
- * 4. baseDir == '.' → inc_path = relpath = target  (resolved by XMLHttpRequest/fetch)
+ * 4. baseDir == '.' → inc_path = relpath = target  (resolved by fetch)
  * 5. baseDir starts with file:// OR baseDir is not a URI → inc_path = baseDir/target; relpath = target
  * 6. baseDir is an absolute URL → inc_path = baseDir/target; relpath = target
  *

package/src/browser.js

@@ -10,6 +10,7 @@ import {
   RevisionInfo,
 } from './document.js'
 import { Logger, LoggerManager, MemoryLogger, NullLogger } from './logging.js'
+import { HttpCache, MemoryHttpCache, HttpCacheManager } from './http_cache.js'
 import { SafeMode, ContentModel } from './constants.js'
 import { Timings } from './timings.js'
 import { AbstractNode } from './abstract_node.js'
@@ -28,9 +29,23 @@ import {
   BlockMacroProcessor,
   Extensions,
 } from './extensions.js'
+// Re-export DSL interface types for TypeScript consumers.
+/**
+ * @typedef {import('./extensions.js').ProcessorDslInterface} ProcessorDslInterface
+ * @typedef {import('./extensions.js').DocumentProcessorDslInterface} DocumentProcessorDslInterface
+ * @typedef {import('./extensions.js').SyntaxProcessorDslInterface} SyntaxProcessorDslInterface
+ * @typedef {import('./extensions.js').IncludeProcessorDslInterface} IncludeProcessorDslInterface
+ * @typedef {import('./extensions.js').DocinfoProcessorDslInterface} DocinfoProcessorDslInterface
+ * @typedef {import('./extensions.js').BlockProcessorDslInterface} BlockProcessorDslInterface
+ * @typedef {import('./extensions.js').MacroProcessorDslInterface} MacroProcessorDslInterface
+ * @typedef {import('./extensions.js').InlineMacroProcessorDslInterface} InlineMacroProcessorDslInterface
+ */
 import {
   Converter,
+  ConverterBase,
+  CustomFactory,
   DefaultFactory as DefaultConverterFactory,
+  deriveBackendTraits,
 } from './converter.js'
 import { Inline } from './inline.js'
 import { Block } from './block.js'
@@ -97,6 +112,9 @@ export {
   LoggerManager,
   MemoryLogger,
   NullLogger,
+  HttpCache,
+  MemoryHttpCache,
+  HttpCacheManager,
   SafeMode,
   ContentModel,
   Timings,
@@ -114,7 +132,10 @@ export {
   Extensions,
   Cursor,
   Converter as ConverterFactory,
+  ConverterBase,
+  CustomFactory as ConverterCustomFactory,
   DefaultConverterFactory,
+  deriveBackendTraits,
   DefaultSyntaxHighlighterFactory,
   Html5Converter,
   SyntaxHighlighter,

package/src/convert.js

@@ -11,7 +11,7 @@
 //   - Ruby File.write → async writeFile() via node:fs/promises.
 //   - Ruby Helpers.mkdir_p → mkdirP() from helpers.js.
 //   - Ruby Helpers.uriish? → isUriish() from helpers.js.
-//   - Ruby Stylesheets.instance.write_primary_stylesheet → not yet ported to JS; skipped.
+//   - Ruby Stylesheets.instance.write_primary_stylesheet → Stylesheets.instance.writePrimaryStylesheet() in stylesheets.js; returns false in browser environments.
 //   - Ruby doc.syntax_highlighter → doc.syntaxHighlighter.
 //   - Ruby syntax_hl.write_stylesheet? doc → syntaxHl.writeStylesheet(doc).
 //   - Ruby syntax_hl.write_stylesheet doc, dir → syntaxHl.writeStylesheetToDisk(doc, dir).
@@ -24,6 +24,7 @@
 import { load } from './load.js'
 import { isUriish, mkdirP } from './helpers.js'
 import { SafeMode, DEFAULT_STYLESHEET_KEYS } from './constants.js'
+import { Stylesheets } from './stylesheets.js'
 
 // ── convert ───────────────────────────────────────────────────────────────────
 
@@ -214,7 +215,7 @@ export async function convert(input, options = {}) {
       let copyAsciidoctorStylesheet = false
       let copyUserStylesheet = false
       const stylesheet = doc.getAttribute('stylesheet')
-      if (stylesheet) {
+      if (stylesheet != null) {
         if (DEFAULT_STYLESHEET_KEYS.has(stylesheet)) {
           copyAsciidoctorStylesheet = true
         } else if (!isUriish(stylesheet)) {
@@ -246,7 +247,13 @@ export async function convert(input, options = {}) {
         }
 
         if (copyAsciidoctorStylesheet) {
-          // NOTE Stylesheets.instance.write_primary_stylesheet is not yet ported to JS
+          if (
+            !(await Stylesheets.instance.writePrimaryStylesheet(stylesoutdir))
+          ) {
+            doc.logger.info(
+              'skipping default stylesheet copy: filesystem writes are not supported in this environment'
+            )
+          }
         } else if (copyUserStylesheet) {
           let stylesheetSrc = doc.getAttribute('copycss')
           if (stylesheetSrc === '' || stylesheetSrc === true) {

package/src/converter/html5.js

@@ -29,7 +29,7 @@ import {
   INLINE_MATH_DELIMITERS,
 } from '../constants.js'
 import { XmlSanitizeRx } from '../rx.js'
-import { extname, isUriish } from '../helpers.js'
+import { extname } from '../helpers.js'
 import { Stylesheets } from '../stylesheets.js'
 
 // ── Local regex constants ─────────────────────────────────────────────────────
@@ -1767,32 +1767,13 @@ Your browser does not support the video tag.
 
   // NOTE expose readSvgContents for Bespoke converter
   async readSvgContents(node, target) {
-    const imagesdir = node.document.getAttribute('imagesdir')
-    let resolvedPath
-    let svg
-    if (isUriish(target) || (imagesdir && isUriish(imagesdir))) {
-      svg = await node.readContents(target, {
-        start: imagesdir,
-        normalize: true,
-        warnOnFailure: true,
-        label: 'SVG',
-      })
-      resolvedPath = target
-    } else {
-      resolvedPath = node.normalizeSystemPath(target, imagesdir, null, {
-        targetName: 'image',
-      })
-      svg = await node.readAsset(resolvedPath, {
-        normalize: true,
-        warnOnFailure: true,
-        label: 'SVG',
-      })
-    }
-    if (svg == null) return null // file not found/readable; warning already emitted
-    if (!svg) {
-      node.logger.warn(`contents of SVG is empty: ${resolvedPath}`)
-      return null
-    }
+    let svg = 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.
     // This handles cases like: <svg width="500"\n<circle .../> where the > is missing.

package/src/converter/template.js

@@ -276,7 +276,7 @@ export class TemplateConverter extends ConverterBase {
 
     let entries
     try {
-      entries = await fsp.readdir(templateDir)
+      entries = (await fsp.readdir(templateDir)).sort()
     } catch {
       return result
     }

package/src/document.js

@@ -68,7 +68,11 @@ export class ImageReference {
 import { Footnote } from './footnote.js'
 export { Footnote }
 
-import { AttributeEntry } from './attribute_entry.js'
+import {
+  AttributeEntry,
+  getAttributeEntries,
+  ATTR_ENTRIES_KEY,
+} from './attribute_entry.js'
 export { AttributeEntry }
 
 /**
@@ -927,8 +931,9 @@ export class Document extends AbstractBlock {
    * @param {Object} blockAttributes
    */
   playbackAttributes(blockAttributes) {
-    if (!('attribute_entries' in blockAttributes)) return
-    for (const entry of blockAttributes.attribute_entries) {
+    const entries = getAttributeEntries(blockAttributes)
+    if (!entries) return
+    for (const entry of entries) {
       if (entry.negate) {
         delete this.attributes[entry.name]
         if (entry.name === 'compat-mode') this.compatMode = false
@@ -1657,6 +1662,12 @@ export class Document extends AbstractBlock {
    * Handles titles (AbstractBlock), list item text, table cell text, and reftexts.
    */
   async _resolveAllTexts(block) {
+    // The header section lives outside document.blocks; pre-compute its title here so
+    // that doc.doctitle() returns the fully-substituted title (with replacements applied,
+    // e.g. ' → ’) rather than the header-subs-only fallback.
+    if (block === this && this.header) {
+      await this.header.precomputeTitle?.()
+    }
     // Skip title pre-computation for blocks with an explicit empty id ([id=]).
     // In Ruby, apply_title_subs is lazy: it is never called during parsing for such
     // blocks because section.title is never accessed.  An explicit empty id is
@@ -1740,7 +1751,7 @@ export class Document extends AbstractBlock {
    * @internal
    */
   _clearPlaybackAttributes(attributes) {
-    delete attributes.attribute_entries
+    delete attributes[ATTR_ENTRIES_KEY]
   }
 
   /**
@@ -2080,11 +2091,10 @@ export class Document extends AbstractBlock {
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
 function _expandPath(p) {
-  try {
-    return require('node:path').resolve(p)
-  } catch {
-    return p
-  }
+  const resolver = new PathResolver()
+  const posixed = p.replace(/\\/g, '/')
+  if (resolver.absolutePath(posixed)) return resolver.expandPath(posixed)
+  return resolver.expandPath(`${resolver.workingDir}/${posixed}`)
 }
 
 function _cwd() {