@asciidoctor/core 4.0.0-alpha.5 → 4.0.0

package/build/browser/index.js

@@ -1,4 +1,4 @@
-var version = "4.0.0-alpha.5";
+var version = "4.0.0";
 const packageJson = {
 	version: version};
 
@@ -4079,7 +4079,7 @@ class AbstractBlock extends AbstractNode {
       if (anyContext || contextSelector !== 'section') {
         // optimisation
         // NOTE dlist items can be null
-        for (const b of this.blocks.flat()) {
+        for (const b of this.blocks.flat(Infinity)) {
           if (b) b.#findByInternal(selector, result, filter);
         }
       }
@@ -8921,6 +8921,25 @@ class Cell extends AbstractBlock {
     if (cell._innerDocSetup) {
       const { lines, parentDoc, parentDoctitle, options } = cell._innerDocSetup;
       cell._innerDocSetup = null;
+      // If the first line may be a preprocessor directive (include, ifdef…), expand it using a
+      // temporary PreprocessorReader — matching the Ruby behaviour in table.rb.
+      if (lines.length > 0 && lines[0].includes('::')) {
+        const firstLine = lines[0];
+        const tmpReader = new PreprocessorReader(
+          parentDoc,
+          [firstLine],
+          options.cursor
+        );
+        const preprocessedLines = await tmpReader.readLines();
+        if (
+          !(
+            preprocessedLines.length === 1 && preprocessedLines[0] === firstLine
+          )
+        ) {
+          lines.shift();
+          if (preprocessedLines.length > 0) lines.unshift(...preprocessedLines);
+        }
+      }
       const innerDoc = await parentDoc.constructor.create(lines, options);
       if (parentDoctitle) parentDoc.attributes.doctitle = parentDoctitle;
       cell._innerDocument = innerDoc;
@@ -11012,8 +11031,8 @@ class Parser {
           const admStyle = attributes.style ?? blockContext;
           attributes.name = admStyle.toLowerCase();
           attributes.textlabel =
-            (attributes.caption && delete attributes.caption) ??
-            docAttrs[`${attributes.name}-caption`];
+            attributes.caption ?? docAttrs[`${attributes.name}-caption`];
+          delete attributes.caption;
           block = await Parser.buildBlock(
             blockContext,
             'compound',
@@ -13447,6 +13466,7 @@ function _uniform(str, chr, len) {
  * DSL interface for include processors.
  *
  * @typedef {DocumentProcessorDslInterface & {
+ *   handles(fn: (target: string) => boolean): void;
  *   handles(fn: (doc: Document, target: string) => boolean): void;
  * }} IncludeProcessorDslInterface
  */
@@ -13497,7 +13517,7 @@ function _uniform(str, chr, len) {
  *   - Called with a single Function argument → stores it as the process block.
  *   - Called with non-Function arguments   → invokes the stored process block.
  *
- * The this context inside a stored process function is bound to the processor
+ * The `this` context inside a stored process function is bound to the processor
  * instance at definition time.
  */
 const ProcessorDsl = {
@@ -13671,6 +13691,35 @@ const SyntaxProcessorDsl = {
 const IncludeProcessorDsl = {
   ...DocumentProcessorDsl,
 
+  /**
+   * @overload
+   * @param {(target: string) => boolean} fn - Predicate that receives only the include target.
+   * @returns {void}
+   */
+  /**
+   * @overload
+   * @param {(doc: Document, target: string) => boolean} fn - Predicate that receives the document and the include target.
+   * @returns {void}
+   */
+  /**
+   * @overload
+   * @param {Document} doc - The document being parsed.
+   * @param {string} target - The include target.
+   * @returns {boolean}
+   */
+  /**
+   * Register a function that decides whether this include processor handles a given target,
+   * or invoke the registered handler.
+   *
+   * **Setter form** — register a predicate. The callback may accept either just the target
+   * string (arity 1) or both the document and the target string (arity 2).
+   *
+   * **Invoker form** — call the registered predicate with `(doc, target)` and return its
+   * result, or return `true` if no predicate has been registered.
+   *
+   * @param {...*} args
+   * @returns {boolean | void}
+   */
   handles(...args) {
     if (args.length === 1 && typeof args[0] === 'function') {
       const fn = args[0];
@@ -14438,6 +14487,8 @@ class ProcessorExtension extends Extension {
     super(kind, instance, instance.config);
     this.processMethod =
       processMethod || ((...args) => instance.process(...args));
+    /** @internal */
+    this._direct = false;
   }
 }
 
@@ -14465,10 +14516,24 @@ const SYNTAX_PROCESSOR_CLASSES = {
  * Registry holds the extensions which have been registered and activated, has
  * methods for registering or defining a processor and looks up extensions
  * stored in the registry during parsing.
+ *
+ * A registry can be reused across multiple conversions. Extensions registered
+ * via a group block (passed to {@link Extensions.create} or
+ * {@link Extensions.register}) are re-executed on every activation. Extensions
+ * registered directly on the registry instance (e.g. `registry.preprocessor(fn)`)
+ * are preserved across activations.
+ *
+ * @example
+ * const registry = Extensions.create('my-ext', function () {
+ *   this.preprocessor(function () { ... })
+ * })
+ * // registry can be passed to multiple conversions safely
  */
 class Registry {
   constructor(groups = {}) {
     this.groups = groups;
+    /** @internal */
+    this._activating = false;
     this._reset();
   }
 
@@ -14485,18 +14550,26 @@ class Registry {
       ...Object.values(Extensions.groups()),
       ...Object.values(this.groups),
     ];
-    for (const group of extGroups) {
-      if (typeof group === 'function') {
-        // Check if it is a class (constructor) with an activate prototype method.
-        if (group.prototype && typeof group.prototype.activate === 'function') {
-          new group().activate(this);
-        } else {
-          // Plain function — call in the context of this registry (like instance_exec).
-          group.length === 0 ? group.call(this) : group(this);
+    this._activating = true;
+    try {
+      for (const group of extGroups) {
+        if (typeof group === 'function') {
+          // Check if it is a class (constructor) with an activate prototype method.
+          if (
+            group.prototype &&
+            typeof group.prototype.activate === 'function'
+          ) {
+            new group().activate(this);
+          } else {
+            // Plain function — call in the context of this registry (like instance_exec).
+            group.length === 0 ? group.call(this) : group(this);
+          }
+        } else if (group && typeof group.activate === 'function') {
+          group.activate(this);
         }
-      } else if (group && typeof group.activate === 'function') {
-        group.activate(this);
       }
+    } finally {
+      this._activating = false;
     }
     return this
   }
@@ -15072,6 +15145,7 @@ class Registry {
     }
 
     const extension = new ProcessorExtension(kind, processorInstance);
+    extension._direct = !this._activating;
     extension.config.position === '>>'
       ? store.unshift(extension)
       : store.push(extension);
@@ -15143,27 +15217,44 @@ class Registry {
     }
 
     store[name] = new ProcessorExtension(kind, processorInstance);
+    store[name]._direct = !this._activating;
     return store[name]
   }
 
   /** @internal */
   _reset() {
+    // Keep extensions registered directly (outside a group); only clear group-registered ones.
+    // Extensions tagged with _direct=true survive across activations.
+    const keepArr = (arr) => {
+      const kept = arr?.filter((e) => e._direct) ?? [];
+      return kept.length ? kept : null
+    };
+    const keepMap = (map) => {
+      if (!map) return null
+      const kept = Object.create(null);
+      for (const [k, v] of Object.entries(map)) if (v._direct) kept[k] = v;
+      return Object.keys(kept).length ? kept : null
+    };
     /** @internal */
-    this._preprocessor_extensions = null;
+    this._preprocessor_extensions = keepArr(this._preprocessor_extensions);
     /** @internal */
-    this._tree_processor_extensions = null;
+    this._tree_processor_extensions = keepArr(this._tree_processor_extensions);
     /** @internal */
-    this._postprocessor_extensions = null;
+    this._postprocessor_extensions = keepArr(this._postprocessor_extensions);
     /** @internal */
-    this._include_processor_extensions = null;
+    this._include_processor_extensions = keepArr(
+      this._include_processor_extensions
+    );
     /** @internal */
-    this._docinfo_processor_extensions = null;
+    this._docinfo_processor_extensions = keepArr(
+      this._docinfo_processor_extensions
+    );
     /** @internal */
-    this._block_extensions = null;
+    this._block_extensions = keepMap(this._block_extensions);
     /** @internal */
-    this._block_macro_extensions = null;
+    this._block_macro_extensions = keepMap(this._block_macro_extensions);
     /** @internal */
-    this._inline_macro_extensions = null;
+    this._inline_macro_extensions = keepMap(this._inline_macro_extensions);
     this.document = null;
   }
 
@@ -15246,6 +15337,13 @@ const Extensions = {
   /**
    * Create a new Registry, optionally pre-populated with a named block.
    *
+   * When a `block` is provided it is stored as a group and re-executed on every
+   * activation, making the registry safe to reuse across multiple conversions.
+   * Without a `block`, any extensions registered directly on the returned registry
+   * (e.g. `registry.preprocessor(fn)`) are stored in transient state that is
+   * cleared on every activation — those registrations will be lost from the second
+   * conversion onwards. Prefer the block form when the registry may be reused.
+   *
    * @param {string|null} [name=null] - Optional name for the group; auto-generated if omitted.
    * @param {Function|null} [block=null] - Optional function to register as the group.
    * @returns {Registry}
@@ -16022,8 +16120,8 @@ class Document extends AbstractBlock {
       if ((this.doctype = attrs.doctype = parentDoctype) !== DEFAULT_DOCTYPE) {
         this._updateDoctypeAttributes(DEFAULT_DOCTYPE);
       }
-      // Set up reader only — parsing is deferred to Document.create() / doc.parse().
-      this.reader = new PreprocessorReader(this, data, options.cursor);
+      // Nested documents use a plain Reader (no include/conditional processing), matching Ruby behaviour.
+      this.reader = new Reader(data, options.cursor, { document: this });
       if (this.sourcemap) this.sourceLocation = this.reader.cursor;
     } else {
       this.backend = null;

package/build/node/index.cjs

@@ -5,7 +5,7 @@ const node_fs = require('node:fs');
 const path = require('node:path');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
-var version = "4.0.0-alpha.5";
+var version = "4.0.0";
 const packageJson = {
 	version: version};
 
@@ -4086,7 +4086,7 @@ class AbstractBlock extends AbstractNode {
       if (anyContext || contextSelector !== 'section') {
         // optimisation
         // NOTE dlist items can be null
-        for (const b of this.blocks.flat()) {
+        for (const b of this.blocks.flat(Infinity)) {
           if (b) b.#findByInternal(selector, result, filter);
         }
       }
@@ -8928,6 +8928,25 @@ class Cell extends AbstractBlock {
     if (cell._innerDocSetup) {
       const { lines, parentDoc, parentDoctitle, options } = cell._innerDocSetup;
       cell._innerDocSetup = null;
+      // If the first line may be a preprocessor directive (include, ifdef…), expand it using a
+      // temporary PreprocessorReader — matching the Ruby behaviour in table.rb.
+      if (lines.length > 0 && lines[0].includes('::')) {
+        const firstLine = lines[0];
+        const tmpReader = new PreprocessorReader(
+          parentDoc,
+          [firstLine],
+          options.cursor
+        );
+        const preprocessedLines = await tmpReader.readLines();
+        if (
+          !(
+            preprocessedLines.length === 1 && preprocessedLines[0] === firstLine
+          )
+        ) {
+          lines.shift();
+          if (preprocessedLines.length > 0) lines.unshift(...preprocessedLines);
+        }
+      }
       const innerDoc = await parentDoc.constructor.create(lines, options);
       if (parentDoctitle) parentDoc.attributes.doctitle = parentDoctitle;
       cell._innerDocument = innerDoc;
@@ -11019,8 +11038,8 @@ class Parser {
           const admStyle = attributes.style ?? blockContext;
           attributes.name = admStyle.toLowerCase();
           attributes.textlabel =
-            (attributes.caption && delete attributes.caption) ??
-            docAttrs[`${attributes.name}-caption`];
+            attributes.caption ?? docAttrs[`${attributes.name}-caption`];
+          delete attributes.caption;
           block = await Parser.buildBlock(
             blockContext,
             'compound',
@@ -13454,6 +13473,7 @@ function _uniform(str, chr, len) {
  * DSL interface for include processors.
  *
  * @typedef {DocumentProcessorDslInterface & {
+ *   handles(fn: (target: string) => boolean): void;
  *   handles(fn: (doc: Document, target: string) => boolean): void;
  * }} IncludeProcessorDslInterface
  */
@@ -13504,7 +13524,7 @@ function _uniform(str, chr, len) {
  *   - Called with a single Function argument → stores it as the process block.
  *   - Called with non-Function arguments   → invokes the stored process block.
  *
- * The this context inside a stored process function is bound to the processor
+ * The `this` context inside a stored process function is bound to the processor
  * instance at definition time.
  */
 const ProcessorDsl = {
@@ -13678,6 +13698,35 @@ const SyntaxProcessorDsl = {
 const IncludeProcessorDsl = {
   ...DocumentProcessorDsl,
 
+  /**
+   * @overload
+   * @param {(target: string) => boolean} fn - Predicate that receives only the include target.
+   * @returns {void}
+   */
+  /**
+   * @overload
+   * @param {(doc: Document, target: string) => boolean} fn - Predicate that receives the document and the include target.
+   * @returns {void}
+   */
+  /**
+   * @overload
+   * @param {Document} doc - The document being parsed.
+   * @param {string} target - The include target.
+   * @returns {boolean}
+   */
+  /**
+   * Register a function that decides whether this include processor handles a given target,
+   * or invoke the registered handler.
+   *
+   * **Setter form** — register a predicate. The callback may accept either just the target
+   * string (arity 1) or both the document and the target string (arity 2).
+   *
+   * **Invoker form** — call the registered predicate with `(doc, target)` and return its
+   * result, or return `true` if no predicate has been registered.
+   *
+   * @param {...*} args
+   * @returns {boolean | void}
+   */
   handles(...args) {
     if (args.length === 1 && typeof args[0] === 'function') {
       const fn = args[0];
@@ -14445,6 +14494,8 @@ class ProcessorExtension extends Extension {
     super(kind, instance, instance.config);
     this.processMethod =
       processMethod || ((...args) => instance.process(...args));
+    /** @internal */
+    this._direct = false;
   }
 }
 
@@ -14472,10 +14523,24 @@ const SYNTAX_PROCESSOR_CLASSES = {
  * Registry holds the extensions which have been registered and activated, has
  * methods for registering or defining a processor and looks up extensions
  * stored in the registry during parsing.
+ *
+ * A registry can be reused across multiple conversions. Extensions registered
+ * via a group block (passed to {@link Extensions.create} or
+ * {@link Extensions.register}) are re-executed on every activation. Extensions
+ * registered directly on the registry instance (e.g. `registry.preprocessor(fn)`)
+ * are preserved across activations.
+ *
+ * @example
+ * const registry = Extensions.create('my-ext', function () {
+ *   this.preprocessor(function () { ... })
+ * })
+ * // registry can be passed to multiple conversions safely
  */
 class Registry {
   constructor(groups = {}) {
     this.groups = groups;
+    /** @internal */
+    this._activating = false;
     this._reset();
   }
 
@@ -14492,18 +14557,26 @@ class Registry {
       ...Object.values(Extensions.groups()),
       ...Object.values(this.groups),
     ];
-    for (const group of extGroups) {
-      if (typeof group === 'function') {
-        // Check if it is a class (constructor) with an activate prototype method.
-        if (group.prototype && typeof group.prototype.activate === 'function') {
-          new group().activate(this);
-        } else {
-          // Plain function — call in the context of this registry (like instance_exec).
-          group.length === 0 ? group.call(this) : group(this);
+    this._activating = true;
+    try {
+      for (const group of extGroups) {
+        if (typeof group === 'function') {
+          // Check if it is a class (constructor) with an activate prototype method.
+          if (
+            group.prototype &&
+            typeof group.prototype.activate === 'function'
+          ) {
+            new group().activate(this);
+          } else {
+            // Plain function — call in the context of this registry (like instance_exec).
+            group.length === 0 ? group.call(this) : group(this);
+          }
+        } else if (group && typeof group.activate === 'function') {
+          group.activate(this);
         }
-      } else if (group && typeof group.activate === 'function') {
-        group.activate(this);
       }
+    } finally {
+      this._activating = false;
     }
     return this
   }
@@ -15079,6 +15152,7 @@ class Registry {
     }
 
     const extension = new ProcessorExtension(kind, processorInstance);
+    extension._direct = !this._activating;
     extension.config.position === '>>'
       ? store.unshift(extension)
       : store.push(extension);
@@ -15150,27 +15224,44 @@ class Registry {
     }
 
     store[name] = new ProcessorExtension(kind, processorInstance);
+    store[name]._direct = !this._activating;
     return store[name]
   }
 
   /** @internal */
   _reset() {
+    // Keep extensions registered directly (outside a group); only clear group-registered ones.
+    // Extensions tagged with _direct=true survive across activations.
+    const keepArr = (arr) => {
+      const kept = arr?.filter((e) => e._direct) ?? [];
+      return kept.length ? kept : null
+    };
+    const keepMap = (map) => {
+      if (!map) return null
+      const kept = Object.create(null);
+      for (const [k, v] of Object.entries(map)) if (v._direct) kept[k] = v;
+      return Object.keys(kept).length ? kept : null
+    };
     /** @internal */
-    this._preprocessor_extensions = null;
+    this._preprocessor_extensions = keepArr(this._preprocessor_extensions);
     /** @internal */
-    this._tree_processor_extensions = null;
+    this._tree_processor_extensions = keepArr(this._tree_processor_extensions);
     /** @internal */
-    this._postprocessor_extensions = null;
+    this._postprocessor_extensions = keepArr(this._postprocessor_extensions);
     /** @internal */
-    this._include_processor_extensions = null;
+    this._include_processor_extensions = keepArr(
+      this._include_processor_extensions
+    );
     /** @internal */
-    this._docinfo_processor_extensions = null;
+    this._docinfo_processor_extensions = keepArr(
+      this._docinfo_processor_extensions
+    );
     /** @internal */
-    this._block_extensions = null;
+    this._block_extensions = keepMap(this._block_extensions);
     /** @internal */
-    this._block_macro_extensions = null;
+    this._block_macro_extensions = keepMap(this._block_macro_extensions);
     /** @internal */
-    this._inline_macro_extensions = null;
+    this._inline_macro_extensions = keepMap(this._inline_macro_extensions);
     this.document = null;
   }
 
@@ -15253,6 +15344,13 @@ const Extensions = {
   /**
    * Create a new Registry, optionally pre-populated with a named block.
    *
+   * When a `block` is provided it is stored as a group and re-executed on every
+   * activation, making the registry safe to reuse across multiple conversions.
+   * Without a `block`, any extensions registered directly on the returned registry
+   * (e.g. `registry.preprocessor(fn)`) are stored in transient state that is
+   * cleared on every activation — those registrations will be lost from the second
+   * conversion onwards. Prefer the block form when the registry may be reused.
+   *
    * @param {string|null} [name=null] - Optional name for the group; auto-generated if omitted.
    * @param {Function|null} [block=null] - Optional function to register as the group.
    * @returns {Registry}
@@ -16029,8 +16127,8 @@ class Document extends AbstractBlock {
       if ((this.doctype = attrs.doctype = parentDoctype) !== DEFAULT_DOCTYPE) {
         this._updateDoctypeAttributes(DEFAULT_DOCTYPE);
       }
-      // Set up reader only — parsing is deferred to Document.create() / doc.parse().
-      this.reader = new PreprocessorReader(this, data, options.cursor);
+      // Nested documents use a plain Reader (no include/conditional processing), matching Ruby behaviour.
+      this.reader = new Reader(data, options.cursor, { document: this });
       if (this.sourcemap) this.sourceLocation = this.reader.cursor;
     } else {
       this.backend = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asciidoctor/core",
-  "version": "4.0.0-alpha.5",
+  "version": "4.0.0",
   "description": "Asciidoctor.js: AsciiDoc in JavaScript powered by Asciidoctor",
   "type": "module",
   "main": "build/node/index.cjs",
@@ -66,16 +66,16 @@
   },
   "homepage": "https://github.com/asciidoctor/asciidoctor.js",
   "volta": {
-    "node": "24.15.0"
+    "node": "24.16.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",
     "typedoc": "^0.28.4",
     "@rollup/plugin-json": "^6.1.0",
     "@types/node": "^25.6.0",
-    "@vitest/browser": "^4.1.4",
-    "@vitest/browser-playwright": "^4.1.4",
-    "@vitest/ui": "^4.1.4",
+    "@vitest/browser": "^4.1.7",
+    "@vitest/browser-playwright": "^4.1.7",
+    "@vitest/ui": "^4.1.7",
     "@xmldom/xmldom": "^0.9.9",
     "dot": "^1.1.3",
     "ejs": "^5.0.2",
@@ -83,7 +83,7 @@
     "linkedom": "^0.18.12",
     "node-html-parser": "^7.1.0",
     "nunjucks": "^3.2.4",
-    "playwright": "^1.59.1",
+    "playwright": "^1.60.0",
     "pug": "^3.0.4",
     "rollup": "^4.60.2",
     "typescript": "^6.0.3",

package/src/abstract_block.js

@@ -626,7 +626,7 @@ export class AbstractBlock extends AbstractNode {
       if (anyContext || contextSelector !== 'section') {
         // optimisation
         // NOTE dlist items can be null
-        for (const b of this.blocks.flat()) {
+        for (const b of this.blocks.flat(Infinity)) {
           if (b) b.#findByInternal(selector, result, filter)
         }
       }

package/src/document.js

@@ -34,7 +34,7 @@ import { XmlSanitizeRx, AttributeEntryPassMacroRx } from './rx.js'
 import { LF } from './constants.js'
 import { applyLogging } from './logging.js'
 import { SyntaxHighlighter, DefaultFactoryProxy } from './syntax_highlighter.js'
-import { PreprocessorReader, Cursor } from './reader.js'
+import { Reader, PreprocessorReader, Cursor } from './reader.js'
 import { Parser } from './parser.js'
 import { Extensions, Registry } from './extensions.js'
 
@@ -483,8 +483,8 @@ export class Document extends AbstractBlock {
       if ((this.doctype = attrs.doctype = parentDoctype) !== DEFAULT_DOCTYPE) {
         this._updateDoctypeAttributes(DEFAULT_DOCTYPE)
       }
-      // Set up reader only — parsing is deferred to Document.create() / doc.parse().
-      this.reader = new PreprocessorReader(this, data, options.cursor)
+      // Nested documents use a plain Reader (no include/conditional processing), matching Ruby behaviour.
+      this.reader = new Reader(data, options.cursor, { document: this })
       if (this.sourcemap) this.sourceLocation = this.reader.cursor
     } else {
       this.backend = null

package/src/extensions.js

@@ -75,6 +75,7 @@ import { MacroNameRx, CC_ANY } from './rx.js'
  * DSL interface for include processors.
  *
  * @typedef {DocumentProcessorDslInterface & {
+ *   handles(fn: (target: string) => boolean): void;
  *   handles(fn: (doc: Document, target: string) => boolean): void;
  * }} IncludeProcessorDslInterface
  */
@@ -125,7 +126,7 @@ import { MacroNameRx, CC_ANY } from './rx.js'
  *   - Called with a single Function argument → stores it as the process block.
  *   - Called with non-Function arguments   → invokes the stored process block.
  *
- * The this context inside a stored process function is bound to the processor
+ * The `this` context inside a stored process function is bound to the processor
  * instance at definition time.
  */
 export const ProcessorDsl = {
@@ -299,6 +300,35 @@ export const SyntaxProcessorDsl = {
 export const IncludeProcessorDsl = {
   ...DocumentProcessorDsl,
 
+  /**
+   * @overload
+   * @param {(target: string) => boolean} fn - Predicate that receives only the include target.
+   * @returns {void}
+   */
+  /**
+   * @overload
+   * @param {(doc: Document, target: string) => boolean} fn - Predicate that receives the document and the include target.
+   * @returns {void}
+   */
+  /**
+   * @overload
+   * @param {Document} doc - The document being parsed.
+   * @param {string} target - The include target.
+   * @returns {boolean}
+   */
+  /**
+   * Register a function that decides whether this include processor handles a given target,
+   * or invoke the registered handler.
+   *
+   * **Setter form** — register a predicate. The callback may accept either just the target
+   * string (arity 1) or both the document and the target string (arity 2).
+   *
+   * **Invoker form** — call the registered predicate with `(doc, target)` and return its
+   * result, or return `true` if no predicate has been registered.
+   *
+   * @param {...*} args
+   * @returns {boolean | void}
+   */
   handles(...args) {
     if (args.length === 1 && typeof args[0] === 'function') {
       const fn = args[0]
@@ -1072,22 +1102,48 @@ export class ProcessorExtension extends Extension {
     super(kind, instance, instance.config)
     this.processMethod =
       processMethod || ((...args) => instance.process(...args))
+    /** @internal */
+    this._direct = false
   }
 }
 
 // ── Group ─────────────────────────────────────────────────────────────────────
 
 /**
- * A Group registers one or more extensions with a Registry.
+ * A Group bundles one or more extension registrations that are re-executed on
+ * every document conversion, making the registry safe to reuse.
+ *
+ * Subclass Group, override {@link Group#activate}, and either call
+ * {@link Group.register} to add it globally or pass the subclass to
+ * {@link Extensions.create} / {@link Extensions.register}.
  *
- * Subclass Group and pass the subclass to Extensions.register(), or call
- * the static register() method directly.
+ * @example
+ * class MyGroup extends Group {
+ *   activate (registry) {
+ *     registry.preprocessor(MyPreprocessor)
+ *   }
+ * }
+ * MyGroup.register()
  */
 export class Group {
+  /**
+   * Register this Group class globally under the given name.
+   *
+   * Equivalent to calling `Extensions.register(name, this)`.
+   *
+   * @param {string|null} [name] - Optional name for the group.
+   */
   static register(name = null) {
     Extensions.register(name, this)
   }
 
+  /**
+   * Called by {@link Registry#activate} on every document conversion.
+   *
+   * Override this method to register extensions with the provided registry.
+   *
+   * @param {Registry} _registry - The registry to register extensions with.
+   */
   activate(_registry) {
     throw new Error(
       `${this.constructor.name} must implement the activate method`
@@ -1119,10 +1175,24 @@ const SYNTAX_PROCESSOR_CLASSES = {
  * Registry holds the extensions which have been registered and activated, has
  * methods for registering or defining a processor and looks up extensions
  * stored in the registry during parsing.
+ *
+ * A registry can be reused across multiple conversions. Extensions registered
+ * via a group block (passed to {@link Extensions.create} or
+ * {@link Extensions.register}) are re-executed on every activation. Extensions
+ * registered directly on the registry instance (e.g. `registry.preprocessor(fn)`)
+ * are preserved across activations.
+ *
+ * @example
+ * const registry = Extensions.create('my-ext', function () {
+ *   this.preprocessor(function () { ... })
+ * })
+ * // registry can be passed to multiple conversions safely
  */
 export class Registry {
   constructor(groups = {}) {
     this.groups = groups
+    /** @internal */
+    this._activating = false
     this._reset()
   }
 
@@ -1139,18 +1209,26 @@ export class Registry {
       ...Object.values(Extensions.groups()),
       ...Object.values(this.groups),
     ]
-    for (const group of extGroups) {
-      if (typeof group === 'function') {
-        // Check if it is a class (constructor) with an activate prototype method.
-        if (group.prototype && typeof group.prototype.activate === 'function') {
-          new group().activate(this)
-        } else {
-          // Plain function — call in the context of this registry (like instance_exec).
-          group.length === 0 ? group.call(this) : group(this)
+    this._activating = true
+    try {
+      for (const group of extGroups) {
+        if (typeof group === 'function') {
+          // Check if it is a class (constructor) with an activate prototype method.
+          if (
+            group.prototype &&
+            typeof group.prototype.activate === 'function'
+          ) {
+            new group().activate(this)
+          } else {
+            // Plain function — call in the context of this registry (like instance_exec).
+            group.length === 0 ? group.call(this) : group(this)
+          }
+        } else if (group && typeof group.activate === 'function') {
+          group.activate(this)
         }
-      } else if (group && typeof group.activate === 'function') {
-        group.activate(this)
       }
+    } finally {
+      this._activating = false
     }
     return this
   }
@@ -1726,6 +1804,7 @@ export class Registry {
     }
 
     const extension = new ProcessorExtension(kind, processorInstance)
+    extension._direct = !this._activating
     extension.config.position === '>>'
       ? store.unshift(extension)
       : store.push(extension)
@@ -1797,27 +1876,44 @@ export class Registry {
     }
 
     store[name] = new ProcessorExtension(kind, processorInstance)
+    store[name]._direct = !this._activating
     return store[name]
   }
 
   /** @internal */
   _reset() {
+    // Keep extensions registered directly (outside a group); only clear group-registered ones.
+    // Extensions tagged with _direct=true survive across activations.
+    const keepArr = (arr) => {
+      const kept = arr?.filter((e) => e._direct) ?? []
+      return kept.length ? kept : null
+    }
+    const keepMap = (map) => {
+      if (!map) return null
+      const kept = Object.create(null)
+      for (const [k, v] of Object.entries(map)) if (v._direct) kept[k] = v
+      return Object.keys(kept).length ? kept : null
+    }
     /** @internal */
-    this._preprocessor_extensions = null
+    this._preprocessor_extensions = keepArr(this._preprocessor_extensions)
     /** @internal */
-    this._tree_processor_extensions = null
+    this._tree_processor_extensions = keepArr(this._tree_processor_extensions)
     /** @internal */
-    this._postprocessor_extensions = null
+    this._postprocessor_extensions = keepArr(this._postprocessor_extensions)
     /** @internal */
-    this._include_processor_extensions = null
+    this._include_processor_extensions = keepArr(
+      this._include_processor_extensions
+    )
     /** @internal */
-    this._docinfo_processor_extensions = null
+    this._docinfo_processor_extensions = keepArr(
+      this._docinfo_processor_extensions
+    )
     /** @internal */
-    this._block_extensions = null
+    this._block_extensions = keepMap(this._block_extensions)
     /** @internal */
-    this._block_macro_extensions = null
+    this._block_macro_extensions = keepMap(this._block_macro_extensions)
     /** @internal */
-    this._inline_macro_extensions = null
+    this._inline_macro_extensions = keepMap(this._inline_macro_extensions)
     this.document = null
   }
 
@@ -1900,6 +1996,13 @@ export const Extensions = {
   /**
    * Create a new Registry, optionally pre-populated with a named block.
    *
+   * When a `block` is provided it is stored as a group and re-executed on every
+   * activation, making the registry safe to reuse across multiple conversions.
+   * Without a `block`, any extensions registered directly on the returned registry
+   * (e.g. `registry.preprocessor(fn)`) are stored in transient state that is
+   * cleared on every activation — those registrations will be lost from the second
+   * conversion onwards. Prefer the block form when the registry may be reused.
+   *
    * @param {string|null} [name=null] - Optional name for the group; auto-generated if omitted.
    * @param {Function|null} [block=null] - Optional function to register as the group.
    * @returns {Registry}

package/src/parser.js

@@ -1284,8 +1284,8 @@ export class Parser {
           const admStyle = attributes.style ?? blockContext
           attributes.name = admStyle.toLowerCase()
           attributes.textlabel =
-            (attributes.caption && delete attributes.caption) ??
-            docAttrs[`${attributes.name}-caption`]
+            attributes.caption ?? docAttrs[`${attributes.name}-caption`]
+          delete attributes.caption
           block = await Parser.buildBlock(
             blockContext,
             'compound',

package/src/table.js

@@ -14,6 +14,7 @@ import { Inline } from './inline.js'
 import { applyLogging } from './logging.js'
 import { LF, ATTR_REF_HEAD, BASIC_SUBS, NORMAL_SUBS } from './constants.js'
 import { BlankLineRx, LeadingInlineAnchorRx } from './rx.js'
+import { PreprocessorReader } from './reader.js'
 
 /**
  * Truncate a float to `precision` decimal places (like Ruby's Float#truncate).
@@ -474,6 +475,25 @@ class Cell extends AbstractBlock {
     if (cell._innerDocSetup) {
       const { lines, parentDoc, parentDoctitle, options } = cell._innerDocSetup
       cell._innerDocSetup = null
+      // If the first line may be a preprocessor directive (include, ifdef…), expand it using a
+      // temporary PreprocessorReader — matching the Ruby behaviour in table.rb.
+      if (lines.length > 0 && lines[0].includes('::')) {
+        const firstLine = lines[0]
+        const tmpReader = new PreprocessorReader(
+          parentDoc,
+          [firstLine],
+          options.cursor
+        )
+        const preprocessedLines = await tmpReader.readLines()
+        if (
+          !(
+            preprocessedLines.length === 1 && preprocessedLines[0] === firstLine
+          )
+        ) {
+          lines.shift()
+          if (preprocessedLines.length > 0) lines.unshift(...preprocessedLines)
+        }
+      }
       const innerDoc = await parentDoc.constructor.create(lines, options)
       if (parentDoctitle) parentDoc.attributes.doctitle = parentDoctitle
       cell._innerDocument = innerDoc

package/types/document.d.ts

@@ -489,7 +489,7 @@ export namespace Document {
 import { Footnote } from './footnote.js';
 import { AttributeEntry } from './attribute_entry.js';
 import { AbstractBlock } from './abstract_block.js';
-import type { Reader } from './reader.js';
+import { Reader } from './reader.js';
 import { Section } from './section.js';
 import { Inline } from './inline.js';
 export { Footnote, AttributeEntry };

package/types/extensions.d.ts

@@ -38,7 +38,25 @@ export namespace SyntaxProcessorDsl {
     function resolvesAttributes(...args: any[]): void;
 }
 export namespace IncludeProcessorDsl {
-    function handles(...args: any[]): any;
+    /**
+     * @overload
+     * @param {(target: string) => boolean} fn - Predicate that receives only the include target.
+     * @returns {void}
+     */
+    function handles(fn: (target: string) => boolean): void;
+    /**
+     * @overload
+     * @param {(doc: Document, target: string) => boolean} fn - Predicate that receives the document and the include target.
+     * @returns {void}
+     */
+    function handles(fn: (doc: Document, target: string) => boolean): void;
+    /**
+     * @overload
+     * @param {Document} doc - The document being parsed.
+     * @param {string} target - The include target.
+     * @returns {boolean}
+     */
+    function handles(doc: Document, target: string): boolean;
 }
 export namespace DocinfoProcessorDsl {
     function atLocation(value: any): void;
@@ -486,14 +504,38 @@ export class ProcessorExtension extends Extension {
     processMethod: any;
 }
 /**
- * A Group registers one or more extensions with a Registry.
+ * A Group bundles one or more extension registrations that are re-executed on
+ * every document conversion, making the registry safe to reuse.
  *
- * Subclass Group and pass the subclass to Extensions.register(), or call
- * the static register() method directly.
+ * Subclass Group, override {@link Group#activate}, and either call
+ * {@link Group.register} to add it globally or pass the subclass to
+ * {@link Extensions.create} / {@link Extensions.register}.
+ *
+ * @example
+ * class MyGroup extends Group {
+ *   activate (registry) {
+ *     registry.preprocessor(MyPreprocessor)
+ *   }
+ * }
+ * MyGroup.register()
  */
 export class Group {
-    static register(name?: any): void;
-    activate(_registry: any): void;
+    /**
+     * Register this Group class globally under the given name.
+     *
+     * Equivalent to calling `Extensions.register(name, this)`.
+     *
+     * @param {string|null} [name] - Optional name for the group.
+     */
+    static register(name?: string | null): void;
+    /**
+     * Called by {@link Registry#activate} on every document conversion.
+     *
+     * Override this method to register extensions with the provided registry.
+     *
+     * @param {Registry} _registry - The registry to register extensions with.
+     */
+    activate(_registry: Registry): void;
 }
 /**
  * The primary entry point into the extension system.
@@ -501,6 +543,18 @@ export class Group {
  * Registry holds the extensions which have been registered and activated, has
  * methods for registering or defining a processor and looks up extensions
  * stored in the registry during parsing.
+ *
+ * A registry can be reused across multiple conversions. Extensions registered
+ * via a group block (passed to {@link Extensions.create} or
+ * {@link Extensions.register}) are re-executed on every activation. Extensions
+ * registered directly on the registry instance (e.g. `registry.preprocessor(fn)`)
+ * are preserved across activations.
+ *
+ * @example
+ * const registry = Extensions.create('my-ext', function () {
+ *   this.preprocessor(function () { ... })
+ * })
+ * // registry can be passed to multiple conversions safely
  */
 export class Registry {
     constructor(groups?: {});
@@ -826,6 +880,13 @@ export namespace Extensions {
     /**
      * Create a new Registry, optionally pre-populated with a named block.
      *
+     * When a `block` is provided it is stored as a group and re-executed on every
+     * activation, making the registry safe to reuse across multiple conversions.
+     * Without a `block`, any extensions registered directly on the returned registry
+     * (e.g. `registry.preprocessor(fn)`) are stored in transient state that is
+     * cleared on every activation — those registrations will be lost from the second
+     * conversion onwards. Prefer the block form when the registry may be reused.
+     *
      * @param {string|null} [name=null] - Optional name for the group; auto-generated if omitted.
      * @param {Function|null} [block=null] - Optional function to register as the group.
      * @returns {Registry}
@@ -1032,6 +1093,7 @@ export type SyntaxProcessorDslInterface = ProcessorDslInterface & {
  * DSL interface for include processors.
  */
 export type IncludeProcessorDslInterface = DocumentProcessorDslInterface & {
+    handles(fn: (target: string) => boolean): void;
     handles(fn: (doc: Document, target: string) => boolean): void;
 };
 /**