satteri 0.9.4 → 0.10.0

package/dist/hast/element-props.js

@@ -1,7 +1,7 @@
 /** Decode a HAST element property value from its wire `(kind, value)` — shared
  *  by the walk decoder and the snapshot reader so the kind dispatch lives once.
  *  The bool kinds carry no value string (callers pass `""`). */
-import { PROP_BOOL_TRUE, PROP_BOOL_FALSE, PROP_SPACE_SEP, PROP_COMMA_SEP, PROP_INT, } from "../generated/wire-constants.js";
+import { PROP_BOOL_TRUE, PROP_BOOL_FALSE, PROP_SPACE_SEP, PROP_COMMA_SEP, PROP_COMMA_SEP_NUM, PROP_INT, } from "../generated/wire-constants.js";
 export function decodeElementProp(kind, value) {
     switch (kind) {
         case PROP_BOOL_TRUE:
@@ -10,11 +10,19 @@ export function decodeElementProp(kind, value) {
             return false;
         case PROP_SPACE_SEP:
             return value.split(" ").filter((s) => s.length > 0);
-        case PROP_COMMA_SEP:
-            return value
-                .split(",")
-                .map((s) => s.trim())
-                .filter((s) => s.length > 0);
+        case PROP_COMMA_SEP: {
+            // Interior empty items are kept; only a trailing empty is dropped.
+            const items = value.split(",").map((s) => s.trim());
+            if (items[items.length - 1] === "")
+                items.pop();
+            return items;
+        }
+        case PROP_COMMA_SEP_NUM: {
+            const items = value.split(",").map((s) => s.trim());
+            if (items[items.length - 1] === "")
+                items.pop();
+            return items.map((s) => (s !== "" && !Number.isNaN(Number(s)) ? Number(s) : s));
+        }
         case PROP_INT:
             return Number(value);
         default:

package/dist/hast/hast-materializer.d.ts

@@ -2,10 +2,14 @@ import { HastReader } from "./hast-reader.js";
 import type { Root } from "hast";
 import type { HastNode } from "../types.js";
 export type { HastNode };
+/** Container node types (the ones that carry `children`); everything else is a leaf. */
+export declare const HAST_CONTAINER_TYPES: ReadonlySet<number>;
 /**
- * Materialize a single HAST node from a binary buffer as a lazy JS object.
+ * Materialize a single HAST node; scalars eager, `children` lazy, memoized per
+ * `(reader, id)`; `frozen` (the plugin walk path) deep-freezes so plugins
+ * cannot corrupt the shared cache.
  */
-export declare function materializeHastNode(reader: HastReader, nodeId: number): HastNode;
+export declare const materializeHastNode: (reader: HastReader, nodeId: number, frozen?: boolean, refs?: import("../visitor-shared.js").NodeRefs) => import("hast").Nodes;
 /**
  * Materialize the full HAST tree from root (nodeId=0).
  */

package/dist/hast/hast-materializer.js

@@ -1,143 +1,57 @@
-import { HastReader, HAST_ROOT, HAST_ELEMENT, HAST_TEXT, HAST_COMMENT, HAST_DOCTYPE, HAST_RAW, HAST_MDX_JSX_ELEMENT, HAST_MDX_JSX_TEXT_ELEMENT, HAST_MDX_FLOW_EXPRESSION, HAST_MDX_TEXT_EXPRESSION, HAST_MDX_ESM, } from "./hast-reader.js";
+import { HastReader, HAST_ROOT, HAST_ELEMENT, HAST_TEXT, HAST_COMMENT, HAST_RAW, HAST_MDX_JSX_ELEMENT, HAST_MDX_JSX_TEXT_ELEMENT, HAST_MDX_FLOW_EXPRESSION, HAST_MDX_TEXT_EXPRESSION, HAST_MDX_ESM, } from "./hast-reader.js";
 import { TYPE_NAMES } from "./generated/node-types.js";
-import { lazyProp, lazyGroup } from "../lazy-props.js";
 import { restorePhantomSpaces } from "../phantom.js";
-function propsToRecord(props) {
-    const result = {};
-    for (const p of props) {
-        result[p.name] = p.value;
-    }
-    return result;
-}
-/**
- * Materialize a single HAST node from a binary buffer as a lazy JS object.
- */
-export function materializeHastNode(reader, nodeId) {
-    const nodeType = reader.getNodeType(nodeId);
-    const typeName = TYPE_NAMES[nodeType] ?? `unknown(${nodeType})`;
-    const node = { type: typeName };
-    // Position decodes to three objects; defer it — passthrough children (e.g.
-    // replaceNode keeping `node.children`) never read it.
-    if (reader.hasPosition(nodeId)) {
-        Object.defineProperty(node, "position", lazyProp("position", () => reader.getPosition(nodeId)));
-    }
-    // _nodeId: non-enumerable internal reference
-    Object.defineProperty(node, "_nodeId", {
-        value: nodeId,
-        writable: false,
-        configurable: true,
-        enumerable: false,
-    });
-    switch (nodeType) {
-        case HAST_ROOT:
-            // children: lazy getter
-            Object.defineProperty(node, "children", {
-                get() {
-                    const childIds = reader.getChildIds(nodeId);
-                    const children = childIds.map((id) => materializeHastNode(reader, id));
-                    Object.defineProperty(this, "children", {
-                        value: children,
-                        writable: true,
-                        configurable: true,
-                        enumerable: true,
-                    });
-                    return children;
-                },
-                configurable: true,
-                enumerable: true,
-            });
-            break;
-        case HAST_ELEMENT: {
-            // tagName and properties: lazy, resolved together from one reader call
-            lazyGroup(node, ["tagName", "properties"], () => {
-                const { tagName, properties } = reader.getElementData(nodeId);
-                return { tagName, properties: propsToRecord(properties) };
-            });
-            // children: lazy
-            Object.defineProperty(node, "children", {
-                get() {
-                    const childIds = reader.getChildIds(nodeId);
-                    const children = childIds.map((id) => materializeHastNode(reader, id));
-                    Object.defineProperty(this, "children", {
-                        value: children,
-                        writable: true,
-                        configurable: true,
-                        enumerable: true,
-                    });
-                    return children;
-                },
-                configurable: true,
-                enumerable: true,
-            });
-            break;
-        }
-        case HAST_TEXT:
-        case HAST_COMMENT:
-        case HAST_RAW:
-            Object.defineProperties(node, {
-                value: lazyProp("value", () => reader.getTextValue(nodeId)),
-            });
-            break;
-        case HAST_DOCTYPE:
-            // No extra properties
-            break;
-        case HAST_MDX_JSX_ELEMENT:
-        case HAST_MDX_JSX_TEXT_ELEMENT:
-            lazyGroup(node, ["name", "attributes"], () => reader.getMdxJsxElementData(nodeId));
-            Object.defineProperty(node, "children", {
-                get() {
-                    const childIds = reader.getChildIds(nodeId);
-                    const children = childIds.map((id) => materializeHastNode(reader, id));
-                    Object.defineProperty(this, "children", {
-                        value: children,
-                        writable: true,
-                        configurable: true,
-                        enumerable: true,
-                    });
-                    return children;
-                },
-                configurable: true,
-                enumerable: true,
-            });
-            break;
-        case HAST_MDX_FLOW_EXPRESSION:
-        case HAST_MDX_TEXT_EXPRESSION:
-            Object.defineProperties(node, {
-                value: lazyProp("value", () => restorePhantomSpaces(reader.getTextValue(nodeId))),
-            });
-            break;
-        case HAST_MDX_ESM:
-            Object.defineProperties(node, {
-                value: lazyProp("value", () => reader.getTextValue(nodeId)),
-            });
-            break;
-    }
-    // Plugins can set `data` on any node type, so rehydrate generically
-    // (see website/content/docs/divergences.md for the code-block case).
-    const rawData = reader.getNodeData(nodeId);
-    if (rawData !== null) {
-        try {
-            const parsed = JSON.parse(rawData);
-            if (parsed && typeof parsed === "object" && Object.keys(parsed).length > 0) {
-                Object.defineProperty(node, "data", {
-                    value: parsed,
-                    writable: true,
-                    configurable: true,
-                    enumerable: true,
-                });
+import { createMaterializer } from "../materializer-cache.js";
+/** Container node types (the ones that carry `children`); everything else is a leaf. */
+export const HAST_CONTAINER_TYPES = new Set([
+    HAST_ROOT,
+    HAST_ELEMENT,
+    HAST_MDX_JSX_ELEMENT,
+    HAST_MDX_JSX_TEXT_ELEMENT,
+]);
+const hastMaterializer = createMaterializer({
+    label: "materializeHastNode",
+    typeNames: TYPE_NAMES,
+    hasChildren: (nodeType) => HAST_CONTAINER_TYPES.has(nodeType),
+    populate(node, reader, nodeId, nodeType) {
+        switch (nodeType) {
+            case HAST_ELEMENT:
+                reader.readElementInto(nodeId, node);
+                break;
+            case HAST_TEXT:
+            case HAST_COMMENT:
+            case HAST_RAW:
+                node.value = reader.getTextValue(nodeId);
+                break;
+            case HAST_MDX_JSX_ELEMENT:
+            case HAST_MDX_JSX_TEXT_ELEMENT: {
+                const { name, attributes } = reader.getMdxJsxElementData(nodeId);
+                node.name = name;
+                node.attributes = attributes;
+                break;
             }
+            case HAST_MDX_FLOW_EXPRESSION:
+            case HAST_MDX_TEXT_EXPRESSION:
+                node.value = restorePhantomSpaces(reader.getTextValue(nodeId));
+                break;
+            case HAST_MDX_ESM:
+                node.value = reader.getTextValue(nodeId);
+                break;
+            // HAST_ROOT / HAST_DOCTYPE: no extra properties
+            default:
+                break;
         }
-        catch (err) {
-            if (process.env.NODE_ENV !== "production") {
-                console.warn(`materializeHastNode: malformed node_data for nodeId=${nodeId}`, err);
-            }
-        }
-    }
-    return node;
-}
+    },
+});
+/**
+ * Materialize a single HAST node; scalars eager, `children` lazy, memoized per
+ * `(reader, id)`; `frozen` (the plugin walk path) deep-freezes so plugins
+ * cannot corrupt the shared cache.
+ */
+export const materializeHastNode = hastMaterializer.node;
 /**
  * Materialize the full HAST tree from root (nodeId=0).
  */
 export function materializeHastTree(reader) {
-    return materializeHastNode(reader, 0);
+    return hastMaterializer.tree(reader, 0);
 }

package/dist/hast/hast-reader.d.ts

@@ -6,7 +6,6 @@ export declare const HAST_ROOT: number;
 export declare const HAST_ELEMENT: number;
 export declare const HAST_TEXT: number;
 export declare const HAST_COMMENT: number;
-export declare const HAST_DOCTYPE: number;
 export declare const HAST_RAW: number;
 export declare const HAST_MDX_JSX_ELEMENT: number;
 export declare const HAST_MDX_JSX_TEXT_ELEMENT: number;
@@ -15,7 +14,7 @@ export declare const HAST_MDX_ESM: number;
 export declare const HAST_MDX_TEXT_EXPRESSION: number;
 export interface HastProperty {
     name: string;
-    value: string | number | boolean | string[];
+    value: string | number | boolean | (string | number)[];
 }
 export declare class HastReader {
     #private;
@@ -36,9 +35,6 @@ export declare class HastReader {
     getString(offset: number, len: number): string;
     /** Get position data for a node. */
     getPosition(nodeId: number): Position | undefined;
-    /** Whether the node carries a source position (line 0 + offset 0 is the
-     *  synthesized-node sentinel), without decoding the three position objects. */
-    hasPosition(nodeId: number): boolean;
     /** Get the node_type byte for a given node ID. */
     getNodeType(nodeId: number): number;
     /** Get the parent id for a given node (0xffffffff at the root). */
@@ -49,14 +45,12 @@ export declare class HastReader {
     pushChildIds(nodeId: number, stack: number[]): void;
     /** Get the raw type_data bytes for a node. */
     getTypeData(nodeId: number): Uint8Array;
-    /**
-     * Get element data for a HAST_ELEMENT node.
-     *
-     * Element type_data layout:
-     *   [tag_name: StringRef(8B)][prop_count: u32(4B)][_pad: u32(4B)] = 16-byte header
-     *   then prop_count * 20 bytes:
-     *     [name: StringRef(8B)][value_type: u8(1B)][_pad: [u8;3](3B)][value: StringRef(8B)]
-     */
+    /** Element `tagName`, `properties` count, and the i-th property, read without
+     *  building the intermediate views and records `getElementData` allocates. */
+    getElementTagName(nodeId: number): string;
+    getElementPropCount(nodeId: number): number;
+    getElementPropName(nodeId: number, index: number): string;
+    getElementPropValue(nodeId: number, index: number): HastProperty["value"];
     getElementData(nodeId: number): {
         tagName: string;
         properties: HastProperty[];

package/dist/hast/hast-reader.js

@@ -2,13 +2,13 @@ import { restorePhantomSpaces } from "../phantom.js";
 import { readPosition } from "../wire-read.js";
 import { MDX_ATTR_BOOLEAN_PROP, MDX_ATTR_LITERAL_PROP, MDX_ATTR_EXPRESSION_PROP, MDX_ATTR_SPREAD, } from "../op-stream.js";
 import { decodeElementProp } from "./element-props.js";
+import { PoolOffsets } from "../string-pool.js";
 import { NAME_TO_TYPE } from "./generated/node-types.js";
 import { ARENA_MAGIC, KIND_HAST, FIELD, HEADER } from "../generated/arena-layout.js";
 export const HAST_ROOT = NAME_TO_TYPE.root;
 export const HAST_ELEMENT = NAME_TO_TYPE.element;
 export const HAST_TEXT = NAME_TO_TYPE.text;
 export const HAST_COMMENT = NAME_TO_TYPE.comment;
-export const HAST_DOCTYPE = NAME_TO_TYPE.doctype;
 export const HAST_RAW = NAME_TO_TYPE.raw;
 export const HAST_MDX_JSX_ELEMENT = NAME_TO_TYPE.mdxJsxFlowElement;
 export const HAST_MDX_JSX_TEXT_ELEMENT = NAME_TO_TYPE.mdxJsxTextElement;
@@ -20,6 +20,8 @@ export class HastReader {
     #header;
     #textDecoder;
     #stringPoolCache = null;
+    #poolChecked = false;
+    #poolOffsets = null;
     constructor(buffer) {
         if (buffer instanceof Uint8Array) {
             this.#view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
@@ -27,7 +29,7 @@ export class HastReader {
         else {
             this.#view = new DataView(buffer);
         }
-        this.#textDecoder = new TextDecoder("utf-8");
+        this.#textDecoder = new TextDecoder("utf-8", { ignoreBOM: true });
         this.#header = this.#readHeader();
     }
     #readHeader() {
@@ -101,23 +103,27 @@ export class HastReader {
     getString(offset, len) {
         if (len === 0)
             return "";
-        const { stringPoolOffset } = this.#header;
-        const bytes = new Uint8Array(this.#view.buffer, this.#view.byteOffset + stringPoolOffset + offset, len);
-        return this.#textDecoder.decode(bytes);
+        const pool = this.getStringPool();
+        if (!this.#poolChecked) {
+            this.#poolChecked = true;
+            const { stringPoolOffset, stringPoolLen } = this.#header;
+            const extraBytes = stringPoolLen - pool.length;
+            if (extraBytes > 0) {
+                const bytes = new Uint8Array(this.#view.buffer, this.#view.byteOffset + stringPoolOffset, stringPoolLen);
+                this.#poolOffsets = new PoolOffsets(bytes, extraBytes);
+            }
+        }
+        // An all-ASCII pool has byte offsets equal to its UTF-16 indices.
+        const offsets = this.#poolOffsets;
+        return offsets === null
+            ? pool.substring(offset, offset + len)
+            : offsets.slice(pool, offset, len);
     }
     /** Get position data for a node. */
     getPosition(nodeId) {
         const base = this.#header.nodesOffset + nodeId * this.#header.nodeStructSize;
         return readPosition(this.#view, base + FIELD.start_offset);
     }
-    /** Whether the node carries a source position (line 0 + offset 0 is the
-     *  synthesized-node sentinel), without decoding the three position objects. */
-    hasPosition(nodeId) {
-        const base = this.#header.nodesOffset + nodeId * this.#header.nodeStructSize;
-        const v = this.#view;
-        return (v.getUint32(base + FIELD.start_line, true) !== 0 ||
-            v.getUint32(base + FIELD.start_offset, true) !== 0);
-    }
     /** Get the node_type byte for a given node ID. */
     getNodeType(nodeId) {
         const { nodesOffset, nodeStructSize } = this.#header;
@@ -168,10 +174,10 @@ export class HastReader {
     }
     /** Read a StringRef (offset: u32 LE, len: u32 LE) from a byte array at byteOffset. */
     #readStringRef(data, byteOffset) {
-        const view = new DataView(data.buffer, data.byteOffset + byteOffset);
+        const at = data.byteOffset - this.#view.byteOffset + byteOffset;
         return {
-            offset: view.getUint32(0, true),
-            len: view.getUint32(4, true),
+            offset: this.#view.getUint32(at, true),
+            len: this.#view.getUint32(at + 4, true),
         };
     }
     /**
@@ -182,6 +188,58 @@ export class HastReader {
      *   then prop_count * 20 bytes:
      *     [name: StringRef(8B)][value_type: u8(1B)][_pad: [u8;3](3B)][value: StringRef(8B)]
      */
+    /** Byte position of a node's `type_data`, relative to this reader's view, or
+     *  `-1` when the node stores fewer than `min` bytes. */
+    #typeDataAt(nodeId, min) {
+        const base = this.#header.nodesOffset + nodeId * this.#header.nodeStructSize;
+        const v = this.#view;
+        if (v.getUint32(base + FIELD.data_len, true) < min)
+            return -1;
+        return this.#header.typeDataOffset + v.getUint32(base + FIELD.data_offset, true);
+    }
+    #stringAt(at) {
+        return this.getString(this.#view.getUint32(at, true), this.#view.getUint32(at + 4, true));
+    }
+    /** @internal Both element fields in one pass; the per-field accessors below
+     *  each re-resolve the node's `type_data` position. */
+    readElementInto(nodeId, node) {
+        const at = this.#typeDataAt(nodeId, 16);
+        if (at === -1) {
+            node.tagName = "";
+            node.properties = {};
+            return;
+        }
+        const v = this.#view;
+        node.tagName = this.#stringAt(at);
+        const count = v.getUint32(at + 8, true);
+        const properties = {};
+        for (let i = 0; i < count; i++) {
+            const base = at + 16 + i * 20;
+            properties[this.#stringAt(base)] = decodeElementProp(v.getUint8(base + 8), this.#stringAt(base + 12));
+        }
+        node.properties = properties;
+    }
+    /** Element `tagName`, `properties` count, and the i-th property, read without
+     *  building the intermediate views and records `getElementData` allocates. */
+    getElementTagName(nodeId) {
+        const at = this.#typeDataAt(nodeId, 16);
+        return at === -1 ? "" : this.#stringAt(at);
+    }
+    getElementPropCount(nodeId) {
+        const at = this.#typeDataAt(nodeId, 16);
+        return at === -1 ? 0 : this.#view.getUint32(at + 8, true);
+    }
+    getElementPropName(nodeId, index) {
+        const at = this.#typeDataAt(nodeId, 16);
+        return at === -1 ? "" : this.#stringAt(at + 16 + index * 20);
+    }
+    getElementPropValue(nodeId, index) {
+        const at = this.#typeDataAt(nodeId, 16);
+        if (at === -1)
+            return "";
+        const base = at + 16 + index * 20;
+        return decodeElementProp(this.#view.getUint8(base + 8), this.#stringAt(base + 12));
+    }
     getElementData(nodeId) {
         const data = this.getTypeData(nodeId);
         if (data.length < 16) {
@@ -266,10 +324,7 @@ export class HastReader {
      * These store a single StringRef (8 bytes) as their type_data.
      */
     getTextValue(nodeId) {
-        const data = this.getTypeData(nodeId);
-        if (data.length < 8)
-            return "";
-        const ref = this.#readStringRef(data, 0);
-        return this.getString(ref.offset, ref.len);
+        const at = this.#typeDataAt(nodeId, 8);
+        return at === -1 ? "" : this.#stringAt(at);
     }
 }

package/dist/hast/hast-visitor.d.ts

@@ -1,10 +1,11 @@
 import { type HastNode } from "./hast-materializer.js";
-import type { HastRaw, Data } from "../types.js";
+import type { HastRaw, Data, SourceFormat } from "../types.js";
 import type { Element, Text, Comment, Doctype, Parents as HastParents, Root as HastRoot } from "hast";
 import type { Program } from "estree-jsx";
 import type { MdxJsxFlowElementHast, MdxJsxTextElementHast } from "../mdx-types.js";
 import type { MdxFlowExpressionHast, MdxTextExpressionHast } from "../mdx-types.js";
 import type { MdxjsEsmHast } from "../mdx-types.js";
+import { type PluginOptions } from "../visitor-shared.js";
 import type { HastHandle } from "../handles.js";
 export type { HastHandle };
 /** ESTree-compatible Program node returned by `parseExpression()`. */
@@ -30,16 +31,30 @@ export interface HastVisitorContext {
      * instances. Returned to the caller as `result.data`.
      */
     readonly data: Data;
+    /**
+     * The source format this compile is processing: `"markdown"` for a plain
+     * Markdown compile, `"mdx"` for an MDX one. Lets a plugin shared between both
+     * pipelines branch on which it is handling.
+     */
+    readonly sourceFormat: SourceFormat;
     removeNode(node: Readonly<HastNode>): void;
-    replaceNode(node: Readonly<HastNode>, newNode: HastContent): void;
+    /**
+     * Swap `node` for one node, or for an array of nodes placed in order at its
+     * position. An empty array drops the node, the same as `removeNode`.
+     * The document root takes a `root` and nothing else: the one place a `root`
+     * is accepted as content.
+     */
+    replaceNode(node: Readonly<HastNode>, newNode: HastContent | HastContent[]): void;
     insertBefore(node: Readonly<HastNode>, newNode: HastContent | HastContent[]): void;
     insertAfter(node: Readonly<HastNode>, newNode: HastContent | HastContent[]): void;
     /**
      * Wrap `node` in `parentNode`, making it `parentNode`'s first child. Any
      * children `parentNode` declares are kept after it, so a `div` with an anchor
-     * child wraps a heading as `div > [heading, anchor]`.
+     * child wraps a heading as `div > [heading, anchor]`. `parentNode` is an
+     * element, an MDX JSX element, or `{ raw }` HTML parsing to exactly one
+     * element, never a void element, whose children would not render.
      */
-    wrapNode(node: Readonly<HastNode>, parentNode: HastContent): void;
+    wrapNode(node: Readonly<HastNode>, parentNode: HastParentContent | RawHastContent | RawHtmlHastContent): void;
     prependChild(node: Readonly<HastNode>, childNode: HastContent | HastContent[]): void;
     appendChild(node: Readonly<HastNode>, childNode: HastContent | HastContent[]): void;
     /** Insert one node or an array at `index`; clamps (`0` or less prepends, past the end appends). */
@@ -71,13 +86,37 @@ export interface HastVisitorContext {
 /** New content for a HAST structural mutation. Unlike [`MdastContent`], HAST has
  *  a `raw` node type, so it needs no raw/rawHtml escape hatch. */
 export type HastContent = HastNode;
+/** A `wrapNode` wrapper: node types that can hold children. */
+export type HastParentContent = Exclude<Extract<HastNode, {
+    children: unknown[];
+}>, HastRoot>;
+/** Raw `wrapNode` wrapper: the HTML is parsed at apply time (not call time)
+ *  and must yield exactly one non-void element, which becomes the wrapper.
+ *  `mdxExpressions` is accepted for parity with the MDAST phase and has no
+ *  effect: braces in HTML text are always literal. */
+export interface RawHastContent {
+    raw: string;
+    mdxExpressions?: boolean;
+}
+export interface RawHtmlHastContent {
+    /** @deprecated Use the equivalent `{ raw }`. */
+    rawHtml: string;
+}
 /** A filtered visitor: Rust filters by tag/component name, only matched nodes cross the boundary. */
 export interface HastFilteredVisitor<N extends HastNode = HastNode> {
     filter: string[];
     visit(node: Readonly<N>, ctx: HastVisitorContext): HastNode | void | Promise<HastNode | void>;
 }
 type HastVisitorFn<N extends HastNode = HastNode> = (node: Readonly<N>, ctx: HastVisitorContext) => HastNode | void | Promise<HastNode | void>;
+export type HastHookFn = (root: Readonly<HastRoot>, ctx: HastVisitorContext) => void | Promise<void>;
 export interface HastVisitorInstance {
+    /** Plugin-level configuration (e.g. `{ position: true }` to read positions). */
+    options?: PluginOptions;
+    /** Runs once per document, before the plugin's visitors. Awaited when async. */
+    before?: HastHookFn;
+    /** Runs once per document, after the plugin's visitors have settled. Awaited
+     *  when async. */
+    after?: HastHookFn;
     element?: HastFilteredVisitor<Element> | HastFilteredVisitor<Element>[];
     mdxJsxFlowElement?: HastFilteredVisitor<MdxJsxFlowElementHast> | HastFilteredVisitor<MdxJsxFlowElementHast>[];
     mdxJsxTextElement?: HastFilteredVisitor<MdxJsxTextElementHast> | HastFilteredVisitor<MdxJsxTextElementHast>[];
@@ -109,4 +148,15 @@ export declare function resolveSubscriptions(plugin: HastVisitorInstance): Resol
  * replaced earlier in the same pass (the caller warns when non-zero), or a
  * Promise of that count if any visitor is async.
  */
-export declare function visitHastHandle(handle: HastHandle, plugin: HastVisitorInstance, subs: ResolvedSubscription[], source: string | (() => string), fileURL: URL | undefined, data?: Data): number | Promise<number>;
+export declare function visitHastHandle(handle: HastHandle, plugin: HastVisitorInstance, subs: ResolvedSubscription[], source: string | (() => string), fileURL: URL | undefined, data?: Data, sourceFormat?: SourceFormat, diagnostics?: HastDiagnostic[]): number | Promise<number>;
+/** Run a HAST visitor, build the command buffer, but do NOT apply it. Returns
+ *  the merged commands so the caller can choose how to dispatch: either via
+ *  `applyCommandsToHandle` (intermediate plugins in a chain) or via a fused
+ *  NAPI call like `applyCommandsAndRenderHandle` (final plugin, saves one
+ *  apply + one render + one drop crossing). Empty result means no mutations.
+ */
+export declare function visitHastHandleCollect(handle: HastHandle, plugin: HastVisitorInstance, subs: ResolvedSubscription[], source: string | (() => string), fileURL: URL | undefined, data?: Data, sourceFormat?: SourceFormat, diagnostics?: HastDiagnostic[]): Uint8Array | Promise<Uint8Array>;
+/** Its own pass so the caller can apply what `before` queued before the
+ *  visitors walk, and the visitors' mutations before `after` reads the tree. */
+export declare function visitHastHookCollect(handle: HastHandle, plugin: HastVisitorInstance, hook: HastHookFn, source: string | (() => string), fileURL: URL | undefined, data?: Data, sourceFormat?: SourceFormat, diagnostics?: HastDiagnostic[]): Uint8Array | Promise<Uint8Array>;
+export declare function visitHastHook(handle: HastHandle, plugin: HastVisitorInstance, hook: HastHookFn, source: string | (() => string), fileURL: URL | undefined, data?: Data, sourceFormat?: SourceFormat, diagnostics?: HastDiagnostic[]): number | Promise<number>;