@asciidoctor/core 3.0.4 → 4.0.0-alpha.1

package/types/abstract_node.d.ts

@@ -0,0 +1,471 @@
+/**
+ * An abstract base class that provides state and methods for managing a node of AsciiDoc content.
+ * The state and methods on this class are common to all content segments in an AsciiDoc document.
+ * @abstract
+ */
+export abstract class AbstractNode {
+    /**
+     * @param {AbstractNode} parent
+     * @param {string} context
+     * @param {object} [opts={}]
+     */
+    constructor(parent: AbstractNode, context: string, opts?: object);
+    /** @type {Document} */
+    document: Document;
+    context: string;
+    nodeName: string;
+    id: string;
+    attributes: any;
+    passthroughs: any[];
+    /**
+     * Alias for {@link setParent}.
+     * @see {setParent}
+     */
+    set parent(parent: AbstractNode);
+    /**
+     * Alias for {@link getParent}.
+     * @see {getParent}
+     */
+    get parent(): AbstractNode;
+    /**
+     * Set the value of the role attribute on this node.
+     *
+     * Accepts a single role name, a space-separated String, or an Array.
+     *
+     * @param {string|string[]} names - A single role name, a space-separated String, or an Array.
+     */
+    set role(names: string | string[]);
+    /**
+     * Alias for {@link getRole}.
+     * @see {getRole}
+     */
+    get role(): string | string[];
+    /**
+     * Alias for {@link getRoles}.
+     * @see {getRoles}
+     */
+    get roles(): any;
+    /**
+     * @returns {boolean} true if this AbstractNode is an instance of Block.
+     * @throws {Error} Subclasses must override this method.
+     */
+    isBlock(): boolean;
+    /**
+     * @returns {boolean} true if this AbstractNode is an instance of Inline.
+     * @throws {Error} Subclasses must override this method.
+     */
+    isInline(): boolean;
+    /**
+     * Alias for {@link getConverter}.
+     * @see {getConverter}
+     * @returns {object} the converter instance.
+     */
+    get converter(): object;
+    /**
+     * Get the value of the specified attribute.
+     *
+     * Looks for the attribute on this node first. If not found and `fallbackName` is
+     * set, and this node is not the Document node, look for that attribute on the
+     * Document node. Otherwise, return `defaultValue`.
+     *
+     * @param {string} name - The attribute name to resolve.
+     * @param {*} [defaultValue=null] - The value to return if the attribute is not found.
+     * @param {string|boolean|null} [fallbackName=null] - When truthy, also checks the Document's
+     *   attributes. Pass `true` to fall back using the same name, or a string to use a different name.
+     * @returns {*} the attribute value or defaultValue.
+     *
+     * @example <caption>Simple lookup</caption>
+     * block.getAttribute('language')           // → 'ruby' or null
+     *
+     * @example <caption>With default</caption>
+     * block.getAttribute('linenums', false)    // → false if not set
+     *
+     * @example <caption>Inherit from document if absent on block</caption>
+     * block.getAttribute('source-highlighter', null, true)    // → falls back to doc attribute of same name
+     * block.getAttribute('linenums', null, 'source-linenums') // → falls back to 'source-linenums' on doc
+     */
+    getAttribute(name: string, defaultValue?: any, fallbackName?: string | boolean | null): any;
+    /**
+     * Check if the specified attribute is defined on this node, with optional
+     * value match and document-level fallback.
+     *
+     * @param {string} name - The attribute name.
+     * @param {*} [expectedValue=null] - When truthy, also checks that the resolved value equals this.
+     * @param {string|boolean|null} [fallbackName=null] - When truthy, also checks the Document's
+     *   attributes. Pass `true` to use the same name, or a string for a different fallback name.
+     * @returns {boolean}
+     *
+     * @example <caption>Presence check</caption>
+     * block.hasAttribute('linenums')                       // → true/false
+     *
+     * @example <caption>Value match</caption>
+     * block.hasAttribute('language', 'ruby')               // → true only when language === 'ruby'
+     *
+     * @example <caption>Inherit presence from document</caption>
+     * block.hasAttribute('source-highlighter', null, true) // → also checks doc-level attribute
+     */
+    hasAttribute(name: string, expectedValue?: any, fallbackName?: string | boolean | null): boolean;
+    /**
+     * Set the value of the specified attribute on this node.
+     *
+     * @param {string} name - The attribute name to assign.
+     * @param {*} [value=''] - The value to assign.
+     * @param {boolean} [overwrite=true] - When `false`, does nothing if the attribute already exists.
+     * @returns {string|boolean|null} `true` if the attribute was set, `false` if blocked by `overwrite=false`.
+     *   Subclasses (e.g. `Document`) may return the resolved value string or `null` when the attribute is locked.
+     */
+    setAttribute(name: string, value?: any, overwrite?: boolean): string | boolean | null;
+    /**
+     * Check if the specified attribute is defined with an optional value match.
+     * Alias for {@link hasAttribute}.
+     * @see {hasAttribute}
+     */
+    isAttribute(name: any, expectedValue?: any): boolean;
+    /**
+     * Remove the attribute from this node.
+     *
+     * @param {string} name - The attribute name to remove.
+     * @returns {*} the previous value, or `undefined` if the attribute was not present.
+     */
+    removeAttribute(name: string): any;
+    /**
+     * Check if the specified option attribute is enabled on this node.
+     * This method checks whether the `<name>-option` attribute is set.
+     *
+     * @param {string} name - The String or Symbol name of the option.
+     * @returns {boolean} true if the option is enabled, false otherwise.
+     */
+    hasOption(name: string): boolean;
+    /**
+     * Set the specified option on this node by setting the `<name>-option` attribute.
+     *
+     * @param {string} name - The String name of the option.
+     */
+    setOption(name: string): void;
+    /**
+     * Retrieve the Set of option names that are enabled on this node.
+     *
+     * @returns {Set<string>} a Set of option name strings.
+     */
+    enabledOptions(): Set<string>;
+    /**
+     * Update the attributes of this node with the new values.
+     *
+     * @param {Object} newAttributes - A plain object of additional attributes to assign.
+     * @returns {Object} the updated attributes object on this node.
+     */
+    updateAttributes(newAttributes: any): any;
+    /**
+     * Check if the `role` attribute is set on this node, optionally matching an exact value.
+     *
+     * Unlike {@link hasRole}, which checks for an individual role name within a
+     * space-separated list, this method tests the raw `role` attribute string as a whole.
+     *
+     * @param {string|null} [expectedValue=null] - When provided, checks that the `role`
+     *   attribute equals this string exactly.
+     * @returns {boolean}
+     *
+     * @example
+     * node.hasRoleAttribute()         // → true if role attribute is set at all
+     * node.hasRoleAttribute('lead')   // → true only when role === 'lead' (not 'lead primary')
+     */
+    hasRoleAttribute(expectedValue?: string | null): boolean;
+    /**
+     * Check if the specified role name is present in this node's role list.
+     *
+     * @param {string} name - The String role name to find.
+     * @returns {boolean}
+     */
+    hasRole(name: string): boolean;
+    /**
+     * Add the given role directly to this node.
+     *
+     * @param {string} name - The String role name to add.
+     * @returns {boolean} true if the role was added, false if it was already present.
+     */
+    addRole(name: string): boolean;
+    /**
+     * Remove the given role directly from this node.
+     *
+     * @param {string} name - The String role name to remove.
+     * @returns {boolean} true if the role was removed, false if it was not present.
+     */
+    removeRole(name: string): boolean;
+    /**
+     * Get the value of the reftext attribute with substitutions applied.
+     * The result is pre-computed during Document.parse() via {@link precomputeReftext}.
+     * Falls back to the raw reftext attribute if precomputeReftext() has not been called yet.
+     *
+     * @returns {string|null} the String reftext or null if not set.
+     */
+    get reftext(): string | null;
+    /**
+     * Pre-compute the reftext with substitutions applied asynchronously.
+     * Called during Document.parse() so the synchronous getter works during conversion.
+     *
+     * @returns {Promise<void>}
+     */
+    precomputeReftext(): Promise<void>;
+    /**
+     * Check if the reftext attribute is defined.
+     *
+     * @returns {boolean}
+     */
+    hasReftext(): boolean;
+    /**
+     * Check whether this node has reftext — either an explicit 'reftext' attribute
+     * or a title that can serve as the cross-reference text.
+     * Mirrors Ruby's AbstractNode#reftext?
+     * @returns {boolean}
+     */
+    isReftext(): boolean;
+    /**
+     * Construct a reference or data URI to an icon image for the given name.
+     *
+     * If the 'icon' attribute is set on this node the name is ignored and the
+     * attribute value is used as the target path. Otherwise the icon path is built
+     * from 'iconsdir', the name, and 'icontype' (default: 'png').
+     *
+     * @param {string} name - The String name of the icon.
+     * @returns {Promise<string>} a Promise resolving to a String reference or data URI for the icon image.
+     */
+    iconUri(name: string): Promise<string>;
+    /**
+     * Construct a URI reference or data URI to the target image.
+     *
+     * If the target image is already a URI it is left untouched (unless data-uri
+     * conversion is requested). The image is resolved relative to the directory
+     * named by assetDirKey. When data-uri is enabled and the safe level permits,
+     * the image is embedded as a Base64 data URI.
+     *
+     * NOTE: When the document has both 'data-uri' and 'allow-uri-read' enabled
+     * and the resolved image URL is a remote URI, this method returns a Promise
+     * rather than a String. Await the result when that combination may be active.
+     *
+     * @param {string} targetImage - A String path to the target image.
+     * @param {string} [assetDirKey='imagesdir'] - The String attribute key for the image directory.
+     * @returns {Promise<string>} a Promise resolving to a String reference or data URI.
+     */
+    imageUri(targetImage: string, assetDirKey?: string): Promise<string>;
+    /**
+     * Construct a URI reference to the target media.
+     *
+     * @param {string} target - A String reference to the target media.
+     * @param {string} [assetDirKey='imagesdir'] - The String attribute key for the media directory.
+     * @returns {string} a String reference for the target media.
+     */
+    mediaUri(target: string, assetDirKey?: string): string;
+    /**
+     * Generate a data URI that embeds the image at the given local path.
+     *
+     * The image path is cleaned to prevent access outside the jail when the
+     * document safe level is SafeMode.SAFE or higher. The image data is read
+     * and Base64-encoded. In non-Node environments this method returns an empty
+     * data URI with a warning.
+     *
+     * @param {string} targetImage - A String path to the target image.
+     * @param {string|null} [assetDirKey=null] - The String attribute key for the image directory.
+     * @returns {Promise<string>} a Promise resolving to a String data URI.
+     */
+    generateDataUri(targetImage: string, assetDirKey?: string | null): Promise<string>;
+    /**
+     * Read the image data from the specified URI and generate a data URI.
+     *
+     * The image data is fetched and Base64-encoded. The MIME type is taken from
+     * the Content-Type response header.
+     *
+     * NOTE: This method is async in JS (the Fetch API is async). When called from
+     * imageUri, the caller must await the returned Promise.
+     *
+     * @param {string} imageUri - The URI from which to read the image data (http/https/ftp).
+     * @param {boolean} [cacheUri=false] - A Boolean to control caching (not yet supported in JS).
+     * @returns {Promise<string>} a Promise resolving to a String data URI.
+     */
+    generateDataUriFromUri(imageUri: string, cacheUri?: boolean): Promise<string>;
+    /**
+     * Normalize the asset file or directory to a concrete and rinsed path.
+     *
+     * Delegates to {@link normalizeSystemPath} with start set to document.baseDir.
+     *
+     * @param {string} assetRef - The String asset reference to normalize.
+     * @param {string} [assetName='path'] - The String label for the asset used in messages.
+     * @param {boolean} [autocorrect=true] - A Boolean indicating whether to recover from an illegal path.
+     * @returns {string} the normalized String path.
+     */
+    normalizeAssetPath(assetRef: string, assetName?: string, autocorrect?: boolean): string;
+    /**
+     * Resolve and normalize a secure path from the target and start paths.
+     *
+     * Prevents resolving a path outside the jail (defaulting to document.baseDir)
+     * when the document safe level is SafeMode.SAFE or higher.
+     *
+     * @param {string} target - The String target path.
+     * @param {string|null} [start=null] - The String start (parent) path.
+     * @param {string|null} [jail=null] - The String jail path.
+     * @param {Object} [opts={}] - A plain object of options:
+     *   - `recover` {boolean} - Whether to automatically recover for illegal paths.
+     *   - `targetName` {string} - Label used in messages for the path being resolved.
+     * @throws {Error} if a jail is specified and the resolved path is outside it.
+     * @returns {string} the resolved String path.
+     */
+    normalizeSystemPath(target: string, start?: string | null, jail?: string | null, opts?: any): string;
+    /**
+     * Normalize the web path using the PathResolver.
+     *
+     * @param {string} target - The String target path.
+     * @param {string|null} [start=null] - The String start (parent) path.
+     * @param {boolean} [preserveUriTarget=true] - Whether a URI target should be preserved as-is.
+     * @returns {string} the resolved String path.
+     */
+    normalizeWebPath(target: string, start?: string | null, preserveUriTarget?: boolean): string;
+    /**
+     * Read the contents of the file at the specified path.
+     *
+     * This method checks that the file is readable before attempting to read it.
+     *
+     * @param {string} path - The String path from which to read the contents.
+     * @param {Object} [opts={}] - A plain object of options:
+     *   - `warnOnFailure` {boolean} - Whether a warning is issued when the file cannot be read (default: false).
+     *   - `normalize` {boolean} - Whether lines are normalized and coerced to UTF-8 (default: false).
+     *   - `label` {string} - Label for the file used in warning messages.
+     * @returns {Promise<string|null>} a Promise resolving to the file content, or null if not readable.
+     */
+    readAsset(path: string, opts?: any): Promise<string | null>;
+    /**
+     * Resolve the URI or system path to the target, then read and return its contents.
+     *
+     * When the resolved path is a URI and allow-uri-read is enabled, the content is
+     * fetched via the Fetch API (async). When it is a local path, the file is read
+     * via {@link readAsset}.
+     *
+     * @param {string} target - The URI or local path String from which to read the data.
+     * @param {Object} [opts={}] - A plain object of options:
+     *   - `label` {string} - Label used in warning messages (default: 'asset').
+     *   - `normalize` {boolean} - Whether the data should be normalized (default: false).
+     *   - `start` {string} - Relative base path for resolving the target.
+     *   - `warnOnFailure` {boolean} - Whether warnings are issued on failure (default: true).
+     *   - `warnIfEmpty` {boolean} - Whether a warning is issued when the target contents are empty (default: false).
+     * @returns {Promise<string|null>} a Promise resolving to the content, or null on failure.
+     */
+    readContents(target: string, opts?: any): Promise<string | null>;
+    /**
+     * @deprecated Use `isUriish` from helpers.js instead.
+     * @param {string} str
+     * @returns {boolean}
+     */
+    isUri(str: string): boolean;
+    /**
+     * Provide a default logger.
+     * The Logging mixin (logging.js) overrides this getter on the prototype.
+     */
+    get logger(): any;
+    /**
+     * Get the logger for this node.
+     * @returns {object} the logger instance.
+     */
+    getLogger(): object;
+    /**
+     * Retrieve the space-separated String role for this node.
+     *
+     * @returns {string|undefined} the role as a space-separated String.
+     */
+    getRole(): string | undefined;
+    /**
+     * Set the value of the role attribute on this node.
+     *
+     * Accepts a single role name, a space-separated String, an Array, or spread arguments.
+     *
+     * @param {...string|string[]} names - A single role name, a space-separated String, an Array,
+     *   or multiple role names as spread arguments.
+     * @returns {string} the value of the role attribute.
+     */
+    setRole(...names: (string | string[])[]): string;
+    /**
+     * Retrieve the String role names for this node as an Array.
+     *
+     * @returns {string[]} the role names as a String Array, empty if the role attribute is absent.
+     */
+    getRoles(): string[];
+    /**
+     * Get the attributes hash for this node.
+     *
+     * @returns {Object} a plain Object of attributes.
+     */
+    getAttributes(): any;
+    /**
+     * Get the document to which this node belongs.
+     *
+     * @returns {Document} the Document.
+     */
+    getDocument(): Document;
+    /**
+     * Get the parent node of this node.
+     *
+     * @returns {AbstractNode|undefined} the parent AbstractNode, or undefined for the root document.
+     */
+    getParent(): AbstractNode | undefined;
+    /**
+     * Set the parent of this node.
+     * Also updates the document reference.
+     */
+    setParent(parent: any): void;
+    /**
+     * Get the String name of this node.
+     *
+     * @returns {string} the node name.
+     */
+    getNodeName(): string;
+    /**
+     * Get the String id for this node.
+     *
+     * @returns {string|undefined} the id, or undefined if not set.
+     */
+    getId(): string | undefined;
+    /**
+     * Set the String id for this node.
+     *
+     * @param {string} id - The String id to assign.
+     */
+    setId(id: string): void;
+    /**
+     * Get the context name for this node.
+     *
+     * @returns {string} the context name.
+     */
+    getContext(): string;
+    /**
+     * Get the {Converter} instance being used to convert the current {Document}.
+     *
+     * @returns {object} the converter instance.
+     */
+    getConverter(): object;
+    /**
+     * Get the icon URI for the named icon.
+     *
+     * @param {string} name - The String icon name.
+     * @returns {Promise<string>} a Promise resolving to a String URI.
+     */
+    getIconUri(name: string): Promise<string>;
+    /**
+     * Get the media URI for the target.
+     *
+     * @param {string} target - The String target path or URL.
+     * @param {string} [assetDirKey='imagesdir'] - The String asset directory attribute key.
+     * @returns {string} a String URI.
+     */
+    getMediaUri(target: string, assetDirKey?: string): string;
+    /**
+     * Get the image URI for the target image.
+     *
+     * @param {string} targetImage - The String target image path or URL.
+     * @param {string|null} [assetDirKey=null] - The String asset directory attribute key.
+     * @returns {Promise<string>} a Promise resolving to a String URI.
+     */
+    getImageUri(targetImage: string, assetDirKey?: string | null): Promise<string>;
+    /**
+     * Get the value of the reftext attribute with substitutions applied.
+     *
+     * @returns {string|undefined} the reftext value, or undefined if not set.
+     */
+    getReftext(): string | undefined;
+}

package/types/attribute_entry.d.ts

@@ -0,0 +1,7 @@
+export class AttributeEntry {
+    constructor(name: any, value: any, negate?: any);
+    name: any;
+    value: any;
+    negate: any;
+    saveTo(blockAttributes: any): this;
+}

package/types/attribute_list.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Handles parsing AsciiDoc attribute lists into a plain object of key/value pairs.
+ * By default, attributes must each be separated by a comma and quotes may be used
+ * around the value. If a key is not detected, the value is assigned to a 1-based
+ * positional key. Positional attributes can be "rekeyed" when given a positionalAttrs
+ * array either during parsing or after.
+ *
+ * @example
+ * const attrlist = new AttributeList('astyle')
+ * await attrlist.parse()
+ * // => { 1: 'astyle' }
+ *
+ * attrlist.rekey(['style'])
+ * // => { 1: 'astyle', style: 'astyle' }
+ *
+ * @example
+ * const attrlist2 = new AttributeList('quote, Famous Person, Famous Book (2001)')
+ * await attrlist2.parse(['style', 'attribution', 'citetitle'])
+ * // => { 1: 'quote', style: 'quote', 2: 'Famous Person', attribution: 'Famous Person',
+ * //      3: 'Famous Book (2001)', citetitle: 'Famous Book (2001)' }
+ */
+export class AttributeList {
+    /**
+     * Assign string keys to the positional (numeric-keyed) values of the given attributes object.
+     * @param {Object} attributes - A plain object produced by parse().
+     * @param {Array<string|null>} positionalAttrs - Keys to assign (null entries are skipped).
+     * @returns {Object} The updated attributes object.
+     */
+    static rekey(attributes: any, positionalAttrs: Array<string | null>): any;
+    constructor(source: any, block?: any, delimiter?: string);
+    /**
+     * Parse the attribute list and merge the result into the given object.
+     * @param {Object} attributes - The target plain object to update.
+     * @param {string[]} [positionalAttrs=[]] - An array of keys to assign to positional values.
+     * @returns {Promise<Object>} The updated attributes object.
+     */
+    parseInto(attributes: any, positionalAttrs?: string[]): Promise<any>;
+    /**
+     * Parse the attribute list and return a plain object of key/value pairs.
+     * Subsequent calls return the already-parsed result without re-parsing.
+     * @param {string[]} [positionalAttrs=[]] - An array of keys to assign to positional values.
+     * @returns {Promise<Object>} A plain object of parsed attributes.
+     */
+    parse(positionalAttrs?: string[]): Promise<any>;
+    /**
+     * Rekey the parsed positional attributes using the given key names.
+     * @param {string[]} positionalAttrs - An array of keys to assign to positional values.
+     * @returns {Object} The updated attributes object.
+     */
+    rekey(positionalAttrs: string[]): any;
+    #private;
+}

package/types/block.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Maps block context strings to their default content model.
+ * Any context not listed defaults to 'simple'.
+ * @type {Object<string, string>}
+ */
+export const DEFAULT_CONTENT_MODEL: {
+    [x: string]: string;
+};
+/**
+ * Methods for managing AsciiDoc content blocks.
+ */
+export class Block extends AbstractBlock<string> {
+    /**
+     * Factory method — mirrors the core Block.create(parent, context, opts) API.
+     * @param {AbstractBlock} parent
+     * @param {string} context
+     * @param {Object} [opts={}]
+     * @returns {Block}
+     */
+    static create(parent: AbstractBlock, context: string, opts?: any): Block;
+    /**
+     * Initialize an Asciidoctor::Block object.
+     * @param {AbstractBlock} parent - The parent AbstractBlock.
+     * @param {string} context - The context name (e.g. 'paragraph', 'listing').
+     * @param {Object} [opts={}]
+     * @param {'compound'|'simple'|'verbatim'|'raw'|'empty'} [opts.content_model] - Defaults to lookup from DEFAULT_CONTENT_MODEL.
+     * @param {Object} [opts.attributes] - Attributes to merge in.
+     * @param {string|string[]} [opts.source] - Raw source string or lines.
+     * @param {'default'|string[]|string|null} [opts.subs]
+     * @param {string[]} [opts.default_subs] - Override for default subs (used with subs: 'default').
+     */
+    constructor(parent: AbstractBlock, context: string, opts?: {
+        content_model?: "compound" | "simple" | "verbatim" | "raw" | "empty";
+        attributes?: any;
+        source?: string | string[];
+        subs?: "default" | string[] | string | null;
+        default_subs?: string[];
+    });
+    /** @type {string[]} */
+    lines: string[];
+    /** @returns {string} Alias for context — consistent with AsciiDoc terminology. */
+    get blockname(): string;
+    /** @returns {string[]} The source lines for this block (matches the core API). */
+    getSourceLines(): string[];
+    /** @returns {string} The preprocessed source of this block as a single String. */
+    get source(): string;
+    /** @returns {string} The source as a single String (alias for the source getter). */
+    getSource(): string;
+    /**
+     * Get the block name (alias for context).
+     * @returns {string}
+     */
+    getBlockName(): string;
+}
+import { AbstractBlock } from './abstract_block.js';

package/types/browser/asset.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Fetch the text content of a URI.
+ *
+ * @param {string} uri - The URI to fetch.
+ * @returns {Promise<string|null>} the response text, or null on failure.
+ */
+export function readBrowserAsset(uri: string): Promise<string | null>;

package/types/browser/reader.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Resolve an include path in a browser (URI-based) environment.
+ *
+ * Implements the rules from the browser-include-test, in the same order:
+ *
+ * Top-level include (includeStack is empty):
+ * 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)
+ * 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
+ *
+ * Nested include (includeStack is non-empty):
+ * Rules 1–3 same as top-level.
+ * 4. parentDir == '.' → inc_path = relpath = target
+ * 5. parentDir starts with file:// OR parentDir is not a URI
+ *      → inc_path = parentDir/target
+ *      → relpath = inc_path if baseDir=='.' or inc_path not under baseDir, else path difference
+ * 6. parentDir is an absolute URL
+ *      → must descend from baseDir or allow-uri-read; else → link
+ *      → inc_path = parentDir/target
+ *      → relpath = path difference if parentDir descends from baseDir, else target
+ * @param {object} reader - a PreprocessorReader instance
+ * @param {string} target - the raw include target string
+ * @param {string|null} attrlist - the raw attribute list string
+ * @returns {[string, string]|boolean} [incPath, relpath] on success, or boolean when the line was consumed.
+ */
+export function resolveBrowserIncludePath(reader: object, target: string, attrlist: string | null): [string, string] | boolean;

package/types/callouts.d.ts

@@ -0,0 +1,36 @@
+/** Maintains a catalog of callouts and their associations. */
+export class Callouts {
+    /**
+     * Register a new callout for the given list item ordinal.
+     * @param {number} liOrdinal - The 1-based ordinal of the list item.
+     * @returns {string} The unique id of this callout (e.g. 'CO1-1').
+     */
+    register(liOrdinal: number): string;
+    /**
+     * Get the next callout id in document order (used during conversion).
+     * @returns {string|null} The unique id of the next callout, or null.
+     */
+    readNextId(): string | null;
+    /**
+     * Get a space-separated list of callout ids for the given list item.
+     * @param {number} liOrdinal - The 1-based ordinal of the list item.
+     * @returns {string} Space-separated callout ids.
+     */
+    getCalloutIds(liOrdinal: number): string;
+    /** @returns {Array<{ordinal: number, id: string}>} The callout objects at the current list index. */
+    getCurrentList(): Array<{
+        ordinal: number;
+        id: string;
+    }>;
+    /** @returns {Array<Array<{ordinal: number, id: string}>>} All callout lists in the document. */
+    getLists(): Array<Array<{
+        ordinal: number;
+        id: string;
+    }>>;
+    /** @returns {number} The 1-based index of the current callout list. */
+    getListIndex(): number;
+    /** Advance to the next callout list in the document. */
+    nextList(): void;
+    /** Rewind the list pointer to the beginning (switching parse → convert). */
+    rewind(): void;
+}