@asciidoctor/core 4.0.0-alpha.6 → 4.0.0

package/build/browser/index.js

@@ -1,4 +1,4 @@
-var version = "4.0.0-alpha.6";
+var version = "4.0.0";
 const packageJson = {
 	version: version};
 
@@ -13466,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
  */
@@ -13516,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 = {
@@ -13690,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];
@@ -14457,6 +14487,8 @@ class ProcessorExtension extends Extension {
     super(kind, instance, instance.config);
     this.processMethod =
       processMethod || ((...args) => instance.process(...args));
+    /** @internal */
+    this._direct = false;
   }
 }
 
@@ -14484,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();
   }
 
@@ -14504,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
   }
@@ -15091,6 +15145,7 @@ class Registry {
     }
 
     const extension = new ProcessorExtension(kind, processorInstance);
+    extension._direct = !this._activating;
     extension.config.position === '>>'
       ? store.unshift(extension)
       : store.push(extension);
@@ -15162,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;
   }
 
@@ -15265,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}

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.6";
+var version = "4.0.0";
 const packageJson = {
 	version: version};
 
@@ -13473,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
  */
@@ -13523,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 = {
@@ -13697,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];
@@ -14464,6 +14494,8 @@ class ProcessorExtension extends Extension {
     super(kind, instance, instance.config);
     this.processMethod =
       processMethod || ((...args) => instance.process(...args));
+    /** @internal */
+    this._direct = false;
   }
 }
 
@@ -14491,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();
   }
 
@@ -14511,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
   }
@@ -15098,6 +15152,7 @@ class Registry {
     }
 
     const extension = new ProcessorExtension(kind, processorInstance);
+    extension._direct = !this._activating;
     extension.config.position === '>>'
       ? store.unshift(extension)
       : store.push(extension);
@@ -15169,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;
   }
 
@@ -15272,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}

package/package.json

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

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