@asciidoctor/core 4.0.0-alpha.1 → 4.0.0-alpha.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asciidoctor/core",
-  "version": "4.0.0-alpha.1",
+  "version": "4.0.0-alpha.3",
   "description": "Asciidoctor.js: AsciiDoc in JavaScript powered by Asciidoctor",
   "type": "module",
   "main": "build/node/index.cjs",
@@ -9,9 +9,14 @@
   "exports": {
     ".": {
       "browser": "./build/browser/index.js",
-      "require": "./build/node/index.cjs",
-      "import": "./src/index.js",
-      "types": "./types/index.d.ts"
+      "require": {
+        "types": "./types/index.d.cts",
+        "default": "./build/node/index.cjs"
+      },
+      "import": {
+        "types": "./types/index.d.ts",
+        "default": "./src/index.js"
+      }
     }
   },
   "engines": {
@@ -23,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",
@@ -60,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_block.js

@@ -502,7 +502,7 @@ export class AbstractBlock extends AbstractNode {
    * - `'reject'` → skip the node and its children
    * - `'stop'` → include the node (if it matched) and stop the entire traversal
    *
-   * @param {Object} [selector={}] - Selector criteria object.
+   * @param {Object|Function} [selector={}] - Selector criteria object, or a filter callback when called as `findBy(callback)`.
    * @param {Function|null} [filter=null] - Per-node filter callback.
    * @returns {AbstractBlock[]} array of matching block-level nodes.
    *
@@ -517,6 +517,9 @@ export class AbstractBlock extends AbstractNode {
    *
    * @example <caption>All image blocks including those inside AsciiDoc table cells</caption>
    * const images = doc.findBy({ context: 'image', traverseDocuments: true })
+   *
+   * @example <caption>Filter-only shorthand (no selector)</caption>
+   * const verbatim = doc.findBy((b) => b.contentModel === ContentModel.VERBATIM)
    */
   findBy(selector = {}, filter = null) {
     const result = []
@@ -525,8 +528,13 @@ export class AbstractBlock extends AbstractNode {
       selector && typeof selector === 'object' && !Array.isArray(selector)
         ? selector
         : {}
-    // Normalise: filter must be a function; ignore string/non-function values (mirrors core API).
-    const normFilter = typeof filter === 'function' ? filter : null
+    // Normalise: support findBy(callback) shorthand — selector is the filter when it's a function.
+    const normFilter =
+      typeof filter === 'function'
+        ? filter
+        : typeof selector === 'function'
+          ? selector
+          : null
     try {
       this.#findByInternal(normSelector, result, normFilter)
     } catch (e) {

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/converter/html5.js

@@ -840,10 +840,7 @@ ${await node.content()}
         img =
           (await this.readSvgContents(node, target)) ||
           `<span class="alt">${node.getAlt()}</span>`
-      } else if (
-        node.hasOption('interactive') &&
-        node.document.safe >= SafeMode.SERVER
-      ) {
+      } else if (node.hasOption('interactive')) {
         const fallback = node.hasAttribute('fallback')
           ? `<img src="${await node.imageUri(node.getAttribute('fallback'))}" alt="${this._encodeAttrValue(node.getAlt())}"${widthAttr}${heightAttr}${slash}>`
           : `<span class="alt">${node.getAlt()}</span>`
@@ -1684,10 +1681,7 @@ Your browser does not support the video tag.
           img =
             (await this.readSvgContents(node, target)) ||
             `<span class="alt">${node.getAlt()}</span>`
-        } else if (
-          node.hasOption('interactive') &&
-          node.document.safe >= SafeMode.SERVER
-        ) {
+        } else if (node.hasOption('interactive')) {
           const fallback = node.hasAttribute('fallback')
             ? `<img src="${await node.imageUri(node.getAttribute('fallback'))}" alt="${this._encodeAttrValue(node.getAlt())}"${attrs}${this._voidSlash}>`
             : `<span class="alt">${node.getAlt()}</span>`

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]
   }
 
   /**

package/src/extensions.js

@@ -27,6 +27,94 @@ import { basename } from './helpers.js'
 import { ATTR_REF_HEAD } from './constants.js'
 import { MacroNameRx, CC_ANY } from './rx.js'
 
+// Type-only imports for JSDoc
+/**
+ * @typedef {import('./document.js').Document} Document
+ * @typedef {import('./abstract_block.js').AbstractBlock} AbstractBlock
+ */
+
+// ── DSL interface types ───────────────────────────────────────────────────────
+
+/**
+ * DSL interface for configuring a {@link Processor} instance.
+ * Applied to a processor instance via `Object.assign(instance, DslMixin)`.
+ *
+ * The `process` property behaves as a setter when called with a single Function
+ * argument (stores the process block), or as a passthrough caller otherwise.
+ *
+ * @typedef {object} ProcessorDslInterface
+ * @property {(key: string, value: unknown) => void} option - Set a config option.
+ * @property {(fn: (...args: unknown[]) => unknown) => void} process - Register the process function.
+ * @property {() => boolean} processBlockGiven - Returns true if a process function has been registered.
+ */
+
+/**
+ * DSL interface for document processors (Preprocessor, TreeProcessor, Postprocessor, DocinfoProcessor).
+ *
+ * @typedef {ProcessorDslInterface & { prefer(): void; prepend(): void }} DocumentProcessorDslInterface
+ */
+
+/**
+ * DSL interface for syntax processors (BlockProcessor, BlockMacroProcessor, InlineMacroProcessor).
+ *
+ * @typedef {ProcessorDslInterface & {
+ *   named(value: string): void;
+ *   contentModel(value: string): void;
+ *   parseContentAs(value: string): void;
+ *   positionalAttributes(...value: string[]): void;
+ *   namePositionalAttributes(...value: string[]): void;
+ *   positionalAttrs(...value: string[]): void;
+ *   defaultAttributes(value: Record<string, string>): void;
+ *   defaultAttrs(value: Record<string, string>): void;
+ *   resolveAttributes(...args: unknown[]): void;
+ *   resolvesAttributes(...args: unknown[]): void;
+ * }} SyntaxProcessorDslInterface
+ */
+
+/**
+ * DSL interface for include processors.
+ *
+ * @typedef {DocumentProcessorDslInterface & {
+ *   handles(fn: (doc: Document, target: string) => boolean): void;
+ * }} IncludeProcessorDslInterface
+ */
+
+/**
+ * DSL interface for docinfo processors.
+ *
+ * @typedef {DocumentProcessorDslInterface & {
+ *   atLocation(value: string): void;
+ * }} DocinfoProcessorDslInterface
+ */
+
+/**
+ * DSL interface for block processors.
+ *
+ * @typedef {SyntaxProcessorDslInterface & {
+ *   contexts(...value: (string | string[])[]): void;
+ *   onContexts(...value: (string | string[])[]): void;
+ *   onContext(...value: (string | string[])[]): void;
+ *   bindTo(...value: (string | string[])[]): void;
+ * }} BlockProcessorDslInterface
+ */
+
+/**
+ * DSL interface for macro processors (block and inline macros).
+ *
+ * @typedef {SyntaxProcessorDslInterface} MacroProcessorDslInterface
+ */
+
+/**
+ * DSL interface for inline macro processors.
+ *
+ * @typedef {MacroProcessorDslInterface & {
+ *   format(value: string): void;
+ *   matchFormat(value: string): void;
+ *   usingFormat(value: string): void;
+ *   match(value: RegExp): void;
+ * }} InlineMacroProcessorDslInterface
+ */
+
 // ── DSL Mixins ────────────────────────────────────────────────────────────────
 
 /**
@@ -625,7 +713,12 @@ export class Processor {
  * Extensions.register(function () { this.preprocessor(CommentStripPreprocessor) })
  */
 export class Preprocessor extends Processor {
-  process(_document, _reader) {
+  /**
+   * @param {Document} document - The document being parsed.
+   * @param {Reader} reader - The reader positioned at the beginning of the source.
+   * @returns {Reader|undefined} The same or a substitute Reader, or undefined to use the original.
+   */
+  process(document, reader) {
     throw new Error(
       `${this.constructor.name} must implement the process method`
     )
@@ -650,7 +743,11 @@ Preprocessor.DSL = DocumentProcessorDsl
  * Extensions.register(function () { this.treeProcessor(ShoutTreeProcessor) })
  */
 export class TreeProcessor extends Processor {
-  process(_document) {
+  /**
+   * @param {Document} document - The parsed document.
+   * @returns {void}
+   */
+  process(document) {
     throw new Error(
       `${this.constructor.name} must implement the process method`
     )
@@ -679,7 +776,12 @@ export const Treeprocessor = TreeProcessor
  * Extensions.register(function () { this.postprocessor(FooterPostprocessor) })
  */
 export class Postprocessor extends Processor {
-  process(_document, _output) {
+  /**
+   * @param {Document} document - The converted document.
+   * @param {string} output - The converted output string.
+   * @returns {string} The (possibly modified) output string.
+   */
+  process(document, output) {
     throw new Error(
       `${this.constructor.name} must implement the process method`
     )
@@ -693,13 +795,25 @@ Postprocessor.DSL = DocumentProcessorDsl
  * Implementations must extend IncludeProcessor.
  */
 export class IncludeProcessor extends Processor {
-  process(_document, _reader, _target, _attributes) {
+  /**
+   * @param {Document} document - The document being parsed.
+   * @param {Reader} reader - The reader for the including document.
+   * @param {string} target - The target of the include directive.
+   * @param {Record<string, string>} attributes - The parsed include attributes.
+   * @returns {void}
+   */
+  process(document, reader, target, attributes) {
     throw new Error(
       `${this.constructor.name} must implement the process method`
     )
   }
 
-  handles(_doc, _target) {
+  /**
+   * @param {Document} doc - The document being parsed.
+   * @param {string} target - The target of the include directive.
+   * @returns {boolean} true if this processor handles the given target.
+   */
+  handles(doc, target) {
     return true
   }
 }
@@ -717,7 +831,11 @@ export class DocinfoProcessor extends Processor {
     this.config.location ??= 'head'
   }
 
-  process(_document) {
+  /**
+   * @param {Document} document - The document being converted.
+   * @returns {string} The docinfo content to inject into the document.
+   */
+  process(document) {
     throw new Error(
       `${this.constructor.name} must implement the process method`
     )
@@ -773,7 +891,13 @@ export class BlockProcessor extends Processor {
     this.config.content_model ??= 'compound'
   }
 
-  process(_parent, _reader, _attributes) {
+  /**
+   * @param {AbstractBlock} parent - The enclosing block.
+   * @param {Reader} reader - The reader positioned at the block content.
+   * @param {Record<string, unknown>} attributes - The parsed block attributes.
+   * @returns {Block|void} A block node, or void to let the parser handle it.
+   */
+  process(parent, reader, attributes) {
     throw new Error(
       `${this.constructor.name} must implement the process method`
     )
@@ -791,7 +915,13 @@ export class MacroProcessor extends Processor {
     this.config.content_model ??= 'attributes'
   }
 
-  process(_parent, _target, _attributes) {
+  /**
+   * @param {AbstractBlock} parent - The enclosing block.
+   * @param {string} target - The macro target (text between `name:` and `[`).
+   * @param {Record<string, unknown>} attributes - The parsed macro attributes.
+   * @returns {Block|Inline|void}
+   */
+  process(parent, target, attributes) {
     throw new Error(
       `${this.constructor.name} must implement the process method`
     )
@@ -837,6 +967,16 @@ export class BlockMacroProcessor extends MacroProcessor {
   set name(value) {
     this._name = value
   }
+
+  /**
+   * @param {AbstractBlock} parent - The enclosing block.
+   * @param {string} target - The macro target.
+   * @param {Record<string, unknown>} attributes - The parsed macro attributes.
+   * @returns {Block} A block node created with one of the `createBlock` helpers.
+   */
+  process(parent, target, attributes) {
+    return super.process(parent, target, attributes)
+  }
 }
 BlockMacroProcessor.DSL = MacroProcessorDsl
 
@@ -880,6 +1020,16 @@ export class InlineMacroProcessor extends MacroProcessor {
     ))
   }
 
+  /**
+   * @param {AbstractBlock} parent - The enclosing block.
+   * @param {string} target - The macro target.
+   * @param {Record<string, unknown>} attributes - The parsed macro attributes.
+   * @returns {Inline} An Inline node created with `this.createInline(...)`.
+   */
+  process(parent, target, attributes) {
+    return super.process(parent, target, attributes)
+  }
+
   resolveRegexp(name, format) {
     if (!MacroNameRx.test(name)) {
       throw new Error(`invalid name for inline macro: ${name}`)
@@ -1263,6 +1413,15 @@ export class Registry {
     return !!this._block_extensions
   }
 
+  /**
+   * Retrieve all BlockProcessor Extension proxy objects.
+   *
+   * @returns {ProcessorExtension[]}
+   */
+  blocks() {
+    return this._block_extensions ? Object.values(this._block_extensions) : []
+  }
+
   /**
    * Check whether a BlockProcessor is registered for the given name and context.
    *
@@ -1309,6 +1468,17 @@ export class Registry {
     return !!this._block_macro_extensions
   }
 
+  /**
+   * Retrieve all BlockMacroProcessor Extension proxy objects.
+   *
+   * @returns {ProcessorExtension[]}
+   */
+  blockMacros() {
+    return this._block_macro_extensions
+      ? Object.values(this._block_macro_extensions)
+      : []
+  }
+
   /**
    * Check whether a BlockMacroProcessor is registered for the given name.
    *
@@ -1414,6 +1584,85 @@ export class Registry {
     return extension
   }
 
+  // ── JavaScript-style accessors ───────────────────────────────────────────────
+
+  /** @returns {object} the plain Object that maps names to groups for this registry. */
+  getGroups() {
+    return this.groups
+  }
+
+  /** Alias for {@link preprocessors}. */
+  getPreprocessors() {
+    return this.preprocessors()
+  }
+
+  /** Alias for {@link treeProcessors}. */
+  getTreeProcessors() {
+    return this.treeProcessors()
+  }
+
+  /** Alias for {@link includeProcessors}. */
+  getIncludeProcessors() {
+    return this.includeProcessors()
+  }
+
+  /** Alias for {@link postprocessors}. */
+  getPostprocessors() {
+    return this.postprocessors()
+  }
+
+  /**
+   * Alias for {@link docinfoProcessors}.
+   *
+   * @param {string|null} [location=null]
+   */
+  getDocinfoProcessors(location = null) {
+    return this.docinfoProcessors(location)
+  }
+
+  /** Alias for {@link blocks}. */
+  getBlocks() {
+    return this.blocks()
+  }
+
+  /** Alias for {@link blockMacros}. */
+  getBlockMacros() {
+    return this.blockMacros()
+  }
+
+  /** Alias for {@link inlineMacros}. */
+  getInlineMacros() {
+    return this.inlineMacros()
+  }
+
+  /**
+   * Alias for {@link registeredForInlineMacro}.
+   *
+   * @param {string} name
+   */
+  getInlineMacroFor(name) {
+    return this.registeredForInlineMacro(name)
+  }
+
+  /**
+   * Alias for {@link registeredForBlock}.
+   *
+   * @param {string} name
+   * @param {string} context
+   */
+  getBlockFor(name, context) {
+    return this.registeredForBlock(name, context)
+  }
+
+  /**
+   * Alias for {@link registeredForBlockMacro}.
+   *
+   * @param {string} name
+   */
+  getBlockMacroFor(name) {
+    return this.registeredForBlockMacro(name)
+  }
+
   // ── Private helpers ──────────────────────────────────────────────────────────
 
   /** @internal */
@@ -1639,6 +1888,15 @@ export const Extensions = {
     return _groups
   },
 
+  /**
+   * Alias for {@link groups}.
+   *
+   * @returns {object}
+   */
+  getGroups() {
+    return this.groups()
+  },
+
   /**
    * Create a new Registry, optionally pre-populated with a named block.
    *

package/src/helpers.js

@@ -38,7 +38,16 @@ const rstrip = (line) => line.replace(/[ \t\r\n\f\v]+$/, '')
  */
 export function prepareSourceArray(data, trimEnd = true) {
   if (!data.length) return []
-  if (data[0].startsWith(BOM)) data[0] = data[0].slice(1)
+  if (data[0].startsWith(BOM)) {
+    data[0] = data[0].slice(1)
+  } else if (
+    data[0].charCodeAt(0) === 0xef &&
+    data[0].charCodeAt(1) === 0xbb &&
+    data[0].charCodeAt(2) === 0xbf
+  ) {
+    // Strip UTF-8 BOM encoded as three raw characters ( / \xEF\xBB\xBF) if not already decoded to U+FEFF
+    data[0] = data[0].slice(3)
+  }
   // Strip trailing \r to normalize Windows CRLF line endings (lines were split on \n, leaving \r).
   return trimEnd
     ? data.map(rstrip)
@@ -58,7 +67,16 @@ export function prepareSourceArray(data, trimEnd = true) {
  */
 export function prepareSourceString(data, trimEnd = true) {
   if (!data) return []
-  if (data.startsWith(BOM)) data = data.slice(1)
+  if (data.startsWith(BOM)) {
+    data = data.slice(1)
+  } else if (
+    data.charCodeAt(0) === 0xef &&
+    data.charCodeAt(1) === 0xbb &&
+    data.charCodeAt(2) === 0xbf
+  ) {
+    // Strip UTF-8 BOM encoded as three raw characters ( / \xEF\xBB\xBF) if not already decoded to U+FEFF
+    data = data.slice(3)
+  }
   // Normalize Windows CRLF to LF so that split('\n') does not leave trailing \r on each line.
   if (data.includes('\r'))
     data = data.replace(/\r\n/g, '\n').replace(/\r/g, '\n')

package/src/index.js

@@ -28,6 +28,18 @@ 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,