satteri 0.9.4 → 0.10.0

package/dist/mdast/mdast-visitor.js

@@ -1,37 +1,39 @@
-import { materializeNode } from "./mdast-materializer.js";
+import { LEAF_TYPES, isCustomLeaf, materializeNode } from "./mdast-materializer.js";
 import { MdastReader } from "./mdast-reader.js";
-import { CommandBuffer, classifyReturn } from "../command-buffer.js";
+import { acquireCommandBuffer, releaseCommandBuffer, classifyReturn, CommandBuffer, STRUCTURAL_CMD, } from "../command-buffer.js";
+import { CMD_SET_CHILDREN } from "../generated/wire-constants.js";
 import { ru32, rstr, readPosition } from "../wire-read.js";
 import { decodeMdastTypeData } from "./generated/layout.js";
 import { TYPE_NAMES, NAME_TO_TYPE, VISITOR_KEYS, MDAST_OPSTREAM_TYPES, } from "./generated/node-types.js";
 import { OpWriter, OF_VALUE, OF_URL, OF_TITLE, OF_ALT, OF_LANG, OF_META, OF_IDENTIFIER, OF_LABEL, OF_NAME, OF_REFERENCE_TYPE, OF_DEPTH, OF_CHECKED, OF_START, OF_ORDERED, OF_SPREAD, OF_EXPLICIT, PROP_STRING, emitMdxAttr, } from "../op-stream.js";
 import { walkMdastHandle, mdastTextContentHandle } from "#binding";
-import { asArray, makeRequireNid, mergeAndReset, unencodableContentError, } from "../visitor-shared.js";
-import { LazyChildResolver } from "../lazy-child-resolver.js";
+import { asArray, makeRequireNid, mergeAndReset, crossPipelineForeign, FOREIGN_REF, ROOT_NODE_ID, requireRootReplacement, rootReplacementError, unencodableContentError, } from "../visitor-shared.js";
+import { LazyChildResolver, registerEpochCacheSlot, } from "../lazy-child-resolver.js";
 import { MdastChildStub } from "./child-stub.js";
-/** Maps MdastNode objects to their arena node IDs without Object.defineProperty overhead. */
-const mdastNodeIdMap = new WeakMap();
-function nid(node) {
+function nid(node, refs) {
     // Genuine stubs carry their id as a plain field; a spread copy is not
     // `instanceof` and has no `_nodeId`, so it correctly reads as new content.
     if (node instanceof MdastChildStub)
-        return node._id;
-    const id = mdastNodeIdMap.get(node);
+        return node._refs === refs ? node._id : FOREIGN_REF;
+    const id = refs.get(node);
     if (id !== undefined)
         return id;
-    // Plain objects are trusted only via the WeakMap or a NON-enumerable
+    // Plain objects are trusted only via this tree's refs or a NON-enumerable
     // `_nodeId` (the materializer's convention, which spread cannot copy) — an
     // enumerable one rode in on a copy and must read as new content.
     const d = Object.getOwnPropertyDescriptor(node, "_nodeId");
-    return d !== undefined && !d.enumerable ? d.value : undefined;
+    if (d !== undefined && !d.enumerable)
+        return FOREIGN_REF;
+    return crossPipelineForeign(node);
 }
 const requireNid = makeRequireNid(nid);
 export class MdastVisitorContext {
-    #commandBuffer = new CommandBuffer();
-    #diagnostics = [];
+    #commandBuffer = acquireCommandBuffer();
+    #diagnostics;
     #handle;
     #getSource;
     #resolver;
+    #refs;
     /** One canonical object per parent id, so visitors can dedupe by identity.
      *  Null until the first `parent()` call; most passes never make one. */
     #parentsById = null;
@@ -49,12 +51,21 @@ export class MdastVisitorContext {
      * instances. Returned to the caller as `result.data`.
      */
     data;
-    constructor(handle, getSource, fileURL, resolver, 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.
+     */
+    sourceFormat;
+    constructor(handle, getSource, fileURL, resolver, data, sourceFormat, diagnostics) {
         this.#handle = handle;
         this.#getSource = getSource;
         this.fileURL = fileURL;
         this.#resolver = resolver;
+        this.#refs = resolver.refs;
         this.data = data;
+        this.sourceFormat = sourceFormat;
+        this.#diagnostics = diagnostics;
     }
     get source() {
         const value = this.#getSource();
@@ -62,39 +73,44 @@ export class MdastVisitorContext {
         return value;
     }
     removeNode(node) {
-        this.#commandBuffer.removeNode(requireNid(node, "removeNode"));
+        this.#commandBuffer.removeNode(requireNid(node, "removeNode", this.#refs));
     }
     insertBefore(node, newNode) {
-        const id = requireNid(node, "insertBefore");
+        const id = requireNid(node, "insertBefore", this.#refs);
         for (const n of asArray(newNode))
-            emitMdastTree(this.#commandBuffer, "insertBefore", id, n);
+            emitMdastTree(this.#commandBuffer, "insertBefore", id, n, false, this.#refs);
     }
     insertAfter(node, newNode) {
-        const id = requireNid(node, "insertAfter");
+        const id = requireNid(node, "insertAfter", this.#refs);
         for (const n of asArray(newNode))
-            emitMdastTree(this.#commandBuffer, "insertAfter", id, n);
+            emitMdastTree(this.#commandBuffer, "insertAfter", id, n, false, this.#refs);
     }
     /**
      * Wrap `node` in `parentNode`, making it `parentNode`'s first child. Any
-     * children `parentNode` declares are kept after it.
+     * children `parentNode` declares are kept after it. `parentNode` must be a
+     * node type that can hold children, or a raw string parsing to exactly one
+     * such block (`{ raw: "> " }` wraps in a blockquote); to surround a node
+     * with raw HTML tags, use `replaceNode(node, [openTag, node, closeTag])`
+     * instead.
      */
     wrapNode(node, parentNode) {
-        const id = requireNid(node, "wrapNode");
-        emitMdastTree(this.#commandBuffer, "wrapNode", id, parentNode);
+        const id = requireNid(node, "wrapNode", this.#refs);
+        assertMdastWrapParent(parentNode);
+        emitMdastTree(this.#commandBuffer, "wrapNode", id, parentNode, false, this.#refs);
     }
     prependChild(node, childNode) {
-        const id = requireNid(node, "prependChild");
+        const id = requireNid(node, "prependChild", this.#refs);
         for (const n of asArray(childNode))
-            emitMdastTree(this.#commandBuffer, "prependChild", id, n);
+            emitMdastTree(this.#commandBuffer, "prependChild", id, n, false, this.#refs);
     }
     appendChild(node, childNode) {
-        const id = requireNid(node, "appendChild");
+        const id = requireNid(node, "appendChild", this.#refs);
         for (const n of asArray(childNode))
-            emitMdastTree(this.#commandBuffer, "appendChild", id, n);
+            emitMdastTree(this.#commandBuffer, "appendChild", id, n, false, this.#refs);
     }
     /** Insert one node or an array at `index`; clamps (`0` or less prepends, past the end appends). */
     insertChildAt(node, index, childNode) {
-        const children = "children" in node ? node.children : [];
+        const children = ("children" in node ? node.children : undefined) ?? [];
         if (index <= 0 || children.length === 0) {
             this.prependChild(node, childNode);
         }
@@ -107,38 +123,70 @@ export class MdastVisitorContext {
     }
     /** Remove the `index`-th child of `node`; a no-op when there is no such child. */
     removeChildAt(node, index) {
-        const child = "children" in node ? node.children[index] : undefined;
+        const child = "children" in node ? node.children?.[index] : undefined;
         if (child)
             this.removeNode(child);
     }
+    /**
+     * 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`, the one place a `root` is accepted as
+     * content, or a raw string, which parses to a root of its own.
+     */
     replaceNode(node, newNode) {
-        const id = requireNid(node, "replaceNode");
-        emitMdastTree(this.#commandBuffer, "replace", id, newNode, true);
+        const id = requireNid(node, "replaceNode", this.#refs);
+        if (Array.isArray(newNode)) {
+            if (id === ROOT_NODE_ID && newNode.length > 1)
+                throw rootReplacementError(newNode);
+            // The last node carries the `replace` so refs back to the target still splice.
+            let previous;
+            for (const n of newNode) {
+                if (previous !== undefined) {
+                    emitMdastTree(this.#commandBuffer, "insertBefore", id, previous, false, this.#refs);
+                }
+                previous = n;
+            }
+            if (previous === undefined) {
+                // Replacing with nothing drops the node, like removeNode.
+                this.removeNode(node);
+            }
+            else if (id === ROOT_NODE_ID && !isRawMdastContent(previous)) {
+                emitMdastRootReplace(this.#commandBuffer, requireRootReplacement(previous), this.#refs);
+            }
+            else {
+                emitMdastTree(this.#commandBuffer, "replace", id, previous, true, this.#refs);
+            }
+            return;
+        }
+        if (id === ROOT_NODE_ID && !isRawMdastContent(newNode)) {
+            emitMdastRootReplace(this.#commandBuffer, requireRootReplacement(newNode), this.#refs);
+            return;
+        }
+        emitMdastTree(this.#commandBuffer, "replace", id, newNode, true, this.#refs);
     }
     setProperty(node, key, value) {
         if (key === "children") {
             // children is structural: set-children keeps the node and swaps only its
             // child list (reused children keep their id).
-            const id = requireNid(node, "setProperty");
-            const ops = compileMdastChildrenToOpstream(value);
-            if (!ops)
+            const id = requireNid(node, "setProperty", this.#refs);
+            if (!emitMdastChildrenCommand(this.#commandBuffer, id, value, this.#refs)) {
                 throw unencodableContentError(value);
-            this.#commandBuffer.setChildrenOpstream(id, ops);
+            }
             return;
         }
         if (key === "data") {
             // data is stored as JSON in the arena, serialize it for the command buffer
-            this.#commandBuffer.setProperty(requireNid(node, "setProperty"), key, value != null ? JSON.stringify(value) : null);
+            this.#commandBuffer.setProperty(requireNid(node, "setProperty", this.#refs), key, value != null ? JSON.stringify(value) : null);
             return;
         }
-        this.#commandBuffer.setProperty(requireNid(node, "setProperty"), key, value);
+        this.#commandBuffer.setProperty(requireNid(node, "setProperty", this.#refs), key, value);
     }
     /** Collect the concatenated text of all descendant text nodes (like mdast-util-to-string). */
     textContent(node, options) {
-        return mdastTextContentHandle(this.#handle, requireNid(node, "textContent"), options);
+        return mdastTextContentHandle(this.#handle, requireNid(node, "textContent", this.#refs), options);
     }
     parent(node) {
-        const parentId = this.#resolver.parentIdOf(requireNid(node, "parent"));
+        const parentId = this.#resolver.parentIdOf(requireNid(node, "parent", this.#refs));
         if (parentId === undefined)
             return undefined;
         const byId = (this.#parentsById ??= new Map());
@@ -154,12 +202,13 @@ export class MdastVisitorContext {
      * Use this rather than `parent.children.indexOf(node)`, which won't find it.
      */
     indexOf(node) {
-        return this.#resolver.indexInParent(requireNid(node, "indexOf"));
+        return this.#resolver.indexInParent(requireNid(node, "indexOf", this.#refs));
     }
     report({ message, node, severity = "error", }) {
+        const id = node ? nid(node, this.#refs) : undefined;
         this.#diagnostics.push({
             message,
-            nodeId: node ? nid(node) : undefined,
+            nodeId: id === FOREIGN_REF ? undefined : id,
             position: node?.position,
             severity,
         });
@@ -172,7 +221,24 @@ export class MdastVisitorContext {
         return this.#diagnostics;
     }
 }
+const mdastSubscriptionCache = new WeakMap();
 export function resolveMdastSubscriptions(plugin) {
+    const cached = mdastSubscriptionCache.get(plugin);
+    if (cached !== undefined)
+        return cached.subs;
+    const built = buildMdastSubscriptions(plugin);
+    mdastSubscriptionCache.set(plugin, built);
+    return built.subs;
+}
+function getMdastRustSubs(plugin) {
+    const cached = mdastSubscriptionCache.get(plugin);
+    if (cached !== undefined)
+        return cached.rustSubs;
+    const built = buildMdastSubscriptions(plugin);
+    mdastSubscriptionCache.set(plugin, built);
+    return built.rustSubs;
+}
+function buildMdastSubscriptions(plugin) {
     const subs = [];
     for (const [name, fn] of Object.entries(plugin)) {
         if (VISITOR_KEYS.has(name) && typeof fn === "function") {
@@ -185,14 +251,19 @@ export function resolveMdastSubscriptions(plugin) {
             }
         }
     }
-    return subs;
+    const rustSubs = subs.map((s) => ({ nodeType: s.nodeType, tagFilter: [] }));
+    return { subs, rustSubs };
 }
+const MDAST_EPOCH_CACHE = registerEpochCacheSlot(new WeakMap());
 class MdastLazyChildResolver extends LazyChildResolver {
+    cacheSlot() {
+        return MDAST_EPOCH_CACHE;
+    }
     createReader(wire) {
         return new MdastReader(wire);
     }
-    materializeNode(reader, nodeId) {
-        return materializeNode(reader, nodeId);
+    materializeNode(reader, nodeId, refs) {
+        return materializeNode(reader, nodeId, true, refs);
     }
     readParentId(reader, nodeId) {
         return reader.getParentId(nodeId);
@@ -202,11 +273,18 @@ class MdastLazyChildResolver extends LazyChildResolver {
     }
 }
 /** Build the child-stub list for a matched node from the wire's `[child_ids]
- *  [child_types]` blocks — no arena snapshot. The seal check still applies:
- *  post-pass ids are stale, and a stub built from them could later splice the
- *  wrong node as a ref. */
+ *  [child_types]` blocks, no arena snapshot. Stale ids are caught at
+ *  materialization: the resolver's epoch check refuses a snapshot once the
+ *  arena has mutated or been dropped. */
 function readMdastChildStubs(view, buf, idsPos, typesPos, count, resolver) {
-    resolver.assertUnsealed();
+    // With a hot snapshot a stub's deferral buys nothing; real nodes skip its per-field getters.
+    if (resolver.hasHotSnapshot()) {
+        const nodes = new Array(count);
+        for (let i = 0; i < count; i++) {
+            nodes[i] = resolver.materializeOne(ru32(view, idsPos + i * 4));
+        }
+        return nodes;
+    }
     const stubs = new Array(count);
     for (let i = 0; i < count; i++) {
         stubs[i] = new MdastChildStub(resolver, ru32(view, idsPos + i * 4), buf[typesPos + i]);
@@ -293,82 +371,124 @@ function readMdastMatchedNode(view, buf, dataOffset, nodeId, nodeType, resolver)
                 node.spread = buf[pos + 1] !== 0;
                 break;
             }
+            case 37: {
+                // descriptionDetails
+                node.spread = buf[pos] !== 0;
+                break;
+            }
             // table (21), directives (30/31/32) and mdxJsx elements (100/101) are
             // decoded by the generated `decodeMdastTypeData` from their tails.
             // root(0), paragraph(1), thematicBreak(3), blockquote(4), emphasis(11),
             // strong(12), break(14), tableRow(22), tableCell(23), delete(24): no extra data
         }
     }
-    mdastNodeIdMap.set(node, nodeId);
+    // User-defined node: the stored `name` field holds the author's public type
+    // string. Surface it as `node.type` (open type string) instead of the
+    // internal `"custom"`, drop the redundant `name`, and drop an empty `value`
+    // so a parent node isn't given a spurious leaf field.
+    if (nodeType === MDAST_CUSTOM) {
+        node.type = node.name;
+        delete node.name;
+        if (node.value === "")
+            delete node.value;
+    }
+    const leafCustom = nodeType === MDAST_CUSTOM && isCustomLeaf({ value: node.value, data: initialData }, childCount);
+    if (childCount === 0 && !LEAF_TYPES.has(nodeType) && !leafCustom) {
+        node.children = [];
+    }
+    resolver.refs.set(node, nodeId);
     if (initialData) {
         node.data = initialData;
     }
     return node;
 }
+const MDAST_ROOT = NAME_TO_TYPE.root;
+/** Internal tag for user-defined nodes. The stored `name` field holds the
+ *  author's public `type` string; the read paths surface it as `node.type`
+ *  and the emit path routes any unrecognized `type` here. */
+const MDAST_CUSTOM = NAME_TO_TYPE.custom;
 /** The arena id of a node if it is an existing (materialized) node, else
  *  undefined for a freshly-built one. */
-function reusedId(node) {
+function reusedId(node, refs) {
     if (node === null || typeof node !== "object")
         return undefined;
-    const id = nid(node);
-    return typeof id === "number" ? id : undefined;
-}
-// Reused across every replacement in a pass: compile is synchronous and its
-// result is copied into the command buffer before the next call, so a single
-// writer is safe and avoids a 512-byte allocation per built node.
-const mdastWriter = new OpWriter();
-/**
- * Compile a declarative MDAST replacement tree to the op-stream — the only
- * structural encoding. Reused nodes (those still carrying an arena id) become
- * `ref`s so the rebuild splices the original back in place. Returns null when
- * the replay can't reproduce the tree identically (unsupported node type or
- * out-of-range numeric field); the caller turns that into a hard error.
- */
-function compileMdastToOpstream(root, forReplace = false) {
-    mdastWriter.begin();
-    try {
-        if (!emitMdastOp(mdastWriter, root, true, forReplace))
-            return null;
-        return mdastWriter.take();
-    }
-    finally {
-        mdastWriter.end();
-    }
+    const id = nid(node, refs);
+    return id !== undefined && id !== FOREIGN_REF ? id : undefined;
 }
-/** Compile a set-children payload: a root-wrapped child list, the shape
+/** Emit a set-children command in place: a root-wrapped child list, the shape
  *  `Patch::SetChildren` splices in. Reused children become refs. */
-function compileMdastChildrenToOpstream(children) {
+function emitMdastChildrenCommand(buffer, id, children, refs) {
     if (!Array.isArray(children))
-        return null;
-    mdastWriter.begin();
-    try {
-        mdastWriter.open(NAME_TO_TYPE.root);
+        return false;
+    return buffer.emitOpstreamCommand(CMD_SET_CHILDREN, id, () => {
+        buffer.open(MDAST_ROOT);
         for (const c of children) {
-            if (!emitMdastOp(mdastWriter, c, false, false))
-                return null;
+            if (!emitMdastOp(buffer, c, false, false, refs))
+                return false;
         }
-        mdastWriter.close();
-        return mdastWriter.take();
+        buffer.close();
+        return true;
+    });
+}
+/** Separate from the per-node encoder, which rejects a `root` payload. */
+function emitMdastRootReplace(buffer, root, refs) {
+    const ok = buffer.emitOpstreamCommand(STRUCTURAL_CMD.replace, ROOT_NODE_ID, () => emitMdastRootOp(buffer, root, refs));
+    if (!ok)
+        throw unencodableContentError(root);
+}
+function emitMdastRootOp(w, n, refs) {
+    w.open(MDAST_ROOT);
+    if (n.data != null)
+        w.data(n.data);
+    if (n._keepChildren === true) {
+        w.keepChildren();
     }
-    finally {
-        mdastWriter.end();
+    else {
+        const children = n.children;
+        if (Array.isArray(children)) {
+            for (const c of children)
+                if (!emitMdastOp(w, c, false, true, refs))
+                    return false;
+        }
     }
+    w.close();
+    return true;
 }
-function emitMdastOp(w, node, isRoot, forReplace) {
+function emitMdastOp(w, node, isRoot, forReplace, refs) {
     if (node === null || typeof node !== "object")
         return false;
     if (!isRoot) {
-        const id = reusedId(node);
+        const id = reusedId(node, refs);
         if (id !== undefined) {
             w.ref(id);
             return true;
         }
     }
     const n = node;
-    const type = MDAST_OPSTREAM_TYPES[n.type];
-    if (type === undefined)
-        return false;
+    // Any `type` outside the built-in set is a user-defined node: route it to the
+    // internal `custom` tag and carry the author's `type` string as the name.
+    let type = MDAST_OPSTREAM_TYPES[n.type];
+    let isCustom = false;
+    if (type === undefined) {
+        if (typeof n.type !== "string" || n.type.length === 0)
+            return false;
+        // A known built-in that just isn't op-stream-encodable (e.g. `root`) is a
+        // real type used wrong, so fail loudly rather than reinterpreting it as a
+        // user-defined node. Only genuinely-unknown type strings become custom.
+        if (NAME_TO_TYPE[n.type] !== undefined)
+            return false;
+        type = MDAST_CUSTOM;
+        isCustom = true;
+    }
+    else if (type === MDAST_CUSTOM) {
+        // `"custom"` is the internal tag's own public name, so it resolves here
+        // instead of falling through as unknown. Still a user-defined node, so carry
+        // the `type` string as the name so it round-trips rather than vanishing.
+        isCustom = true;
+    }
     w.open(type);
+    if (isCustom)
+        w.str(OF_NAME, n.type);
     if (typeof n.value === "string")
         w.str(OF_VALUE, n.value);
     if (typeof n.url === "string")
@@ -405,7 +525,7 @@ function emitMdastOp(w, node, isRoot, forReplace) {
         w.bool(OF_ORDERED, n.ordered);
     if (typeof n.spread === "boolean")
         w.bool(OF_SPREAD, n.spread);
-    if (typeof n.name === "string")
+    if (!isCustom && typeof n.name === "string")
         w.str(OF_NAME, n.name);
     const attrs = n.attributes;
     if (Array.isArray(attrs)) {
@@ -439,7 +559,7 @@ function emitMdastOp(w, node, isRoot, forReplace) {
         const children = n.children;
         if (Array.isArray(children)) {
             for (const c of children)
-                if (!emitMdastOp(w, c, false, forReplace))
+                if (!emitMdastOp(w, c, false, forReplace, refs))
                     return false;
         }
     }
@@ -463,7 +583,7 @@ function isRawMdastContent(content) {
  *  op-stream is the only declarative encoding. The switches stay inline so the
  *  buffer calls are monomorphic (computed method names defeat inline caches on
  *  this warm path). */
-function emitMdastTree(buffer, op, id, content, forReplace = false) {
+function emitMdastTree(buffer, op, id, content, forReplace, refs) {
     if (isRawMdastContent(content)) {
         switch (op) {
             case "replace":
@@ -480,27 +600,65 @@ function emitMdastTree(buffer, op, id, content, forReplace = false) {
                 return buffer.wrapNode(id, content);
         }
     }
-    const ops = compileMdastToOpstream(content, forReplace);
-    if (ops === null)
+    const ok = buffer.emitOpstreamCommand(STRUCTURAL_CMD[op], id, () => emitMdastOp(buffer, content, true, forReplace, refs));
+    if (!ok)
         throw unencodableContentError(content);
-    switch (op) {
-        case "replace":
-            return buffer.replaceOpstream(id, ops);
-        case "insertBefore":
-            return buffer.insertBeforeOpstream(id, ops);
-        case "insertAfter":
-            return buffer.insertAfterOpstream(id, ops);
-        case "prependChild":
-            return buffer.prependChildOpstream(id, ops);
-        case "appendChild":
-            return buffer.appendChildOpstream(id, ops);
-        case "wrapNode":
-            return buffer.wrapNodeOpstream(id, ops);
+}
+/** A leaf wrapper would make the patch engine drop or displace the wrapped node. */
+function assertMdastWrapParent(parentNode) {
+    const sandwich = 'replaceNode(node, [{ type: "html", value: "<div>" }, node, { type: "html", value: "</div>" }])';
+    // A raw wrapper is only a tree once Rust has parsed it, so it is checked there.
+    if (isRawMdastContent(parentNode))
+        return;
+    const type = parentNode.type;
+    const tag = typeof type === "string" ? NAME_TO_TYPE[type] : undefined;
+    if (tag === undefined) {
+        // User-defined type: only the declared shape distinguishes a parent from
+        // a text leaf.
+        if (Array.isArray(parentNode.children))
+            return;
+        throw new Error(`wrapNode: a user-defined "${String(type)}" wrapper must declare a children array. ` +
+            "A leaf-shaped custom node renders as text and cannot hold the wrapped node.");
     }
+    if (!LEAF_TYPES.has(tag))
+        return;
+    throw new Error(`wrapNode: "${String(type)}" nodes cannot hold children, so they cannot wrap a node. ` +
+        'Pass a parent node such as { type: "blockquote", children: [] }, a raw wrapper ' +
+        `such as { raw: "> " }, or surround the node with tags: ${sandwich}.`);
+}
+/** MDAST node types whose `value` Rust can set in place via setProperty. A
+ *  visitor returning one of these as `{type, value}` with no other fields
+ *  skips a full arena rebuild. */
+const MDAST_VALUE_ONLY_TYPES = new Set([
+    "text",
+    "html",
+    "inlineCode",
+    "yaml",
+    "toml",
+    "inlineMath",
+]);
+/** True when the visitor returned a same-type MDAST node carrying only `type`
+ *  + `value`. Any other field present (children, position, data, lang, meta)
+ *  falls back to the full replace path so nothing is silently dropped. */
+function isMdastTextValueSwap(result, original) {
+    if (original === undefined)
+        return false;
+    if (result.type !== original.type)
+        return false;
+    if (!MDAST_VALUE_ONLY_TYPES.has(result.type))
+        return false;
+    const r = result;
+    if (typeof r.value !== "string")
+        return false;
+    return (r.children === undefined &&
+        r.position === undefined &&
+        r.data === undefined &&
+        r.lang === undefined &&
+        r.meta === undefined);
 }
 /** A result that is the same object as the input node is a no-op, so context
  *  mutations (e.g. setProperty) are not clobbered. */
-function applyMdastVisitResult(result, nodeId, returnBuffer, originalNode) {
+function applyMdastVisitResult(result, nodeId, returnBuffer, refs, originalNode) {
     if (result === undefined || result === null)
         return;
     if (result === originalNode)
@@ -513,9 +671,15 @@ function applyMdastVisitResult(result, nodeId, returnBuffer, originalNode) {
         case "raw_html":
             returnBuffer.replace(nodeId, result);
             break;
-        case "structured_node":
-            emitMdastTree(returnBuffer, "replace", nodeId, result, true);
+        case "structured_node": {
+            const node = result;
+            if (isMdastTextValueSwap(node, originalNode)) {
+                returnBuffer.setProperty(nodeId, "value", node.value);
+                break;
+            }
+            emitMdastTree(returnBuffer, "replace", nodeId, node, true, refs);
             break;
+        }
     }
 }
 /**
@@ -525,12 +689,12 @@ function applyMdastVisitResult(result, nodeId, returnBuffer, originalNode) {
  * Returns MdastVisitResult synchronously if all visitors are sync,
  * or Promise<MdastVisitResult> if any visitor is async.
  */
-export function visitMdastHandle(handle, plugin, subs, source, fileURL, data = {}) {
+export function visitMdastHandle(handle, plugin, subs, source, fileURL, data = {}, sourceFormat = "markdown", diagnostics = []) {
     const getSource = typeof source === "function" ? source : () => source;
     const resolver = new MdastLazyChildResolver(handle);
-    const context = new MdastVisitorContext(handle, getSource, fileURL, resolver, data);
-    const returnBuffer = new CommandBuffer();
-    const rustSubs = subs.map((s) => ({ nodeType: s.nodeType, tagFilter: [] }));
+    const context = new MdastVisitorContext(handle, getSource, fileURL, resolver, data, sourceFormat, diagnostics);
+    const returnBuffer = acquireCommandBuffer();
+    const rustSubs = getMdastRustSubs(plugin);
     const matchBuf = walkMdastHandle(handle, rustSubs);
     const matchView = new DataView(matchBuf.buffer, matchBuf.byteOffset, matchBuf.byteLength);
     const matchCount = ru32(matchView, 0);
@@ -548,25 +712,44 @@ export function visitMdastHandle(handle, plugin, subs, source, fileURL, data = {
             deferred.push({ nodeId, promise: result, originalNode: node });
         }
         else {
-            applyMdastVisitResult(result, nodeId, returnBuffer, node);
+            applyMdastVisitResult(result, nodeId, returnBuffer, resolver.refs, node);
         }
     }
     if (deferred) {
         return Promise.all(deferred.map((d) => d.promise.then((r) => ({ nodeId: d.nodeId, result: r, originalNode: d.originalNode })))).then((results) => {
             for (const { nodeId, result, originalNode } of results) {
-                applyMdastVisitResult(result, nodeId, returnBuffer, originalNode);
+                applyMdastVisitResult(result, nodeId, returnBuffer, resolver.refs, originalNode);
             }
-            // End of the pass — the caller applies the returned command buffer next,
-            // renumbering the arena, so later snapshots would resolve match-time
-            // child ids against wrong nodes. This is the last point we control.
-            resolver.seal();
             return finalizeMdastVisit(handle, context, returnBuffer);
         });
     }
-    resolver.seal();
+    return finalizeMdastVisit(handle, context, returnBuffer);
+}
+const MDAST_ROOT_SUBS = [
+    { nodeType: MDAST_ROOT, tagFilter: [] },
+];
+/** 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 function visitMdastHook(handle, plugin, hook, source, fileURL, data = {}, sourceFormat = "markdown", diagnostics = []) {
+    const getSource = typeof source === "function" ? source : () => source;
+    const resolver = new MdastLazyChildResolver(handle);
+    const context = new MdastVisitorContext(handle, getSource, fileURL, resolver, data, sourceFormat, diagnostics);
+    const returnBuffer = acquireCommandBuffer();
+    const matchBuf = walkMdastHandle(handle, MDAST_ROOT_SUBS);
+    const matchView = new DataView(matchBuf.buffer, matchBuf.byteOffset, matchBuf.byteLength);
+    if (ru32(matchView, 0) === 0)
+        return finalizeMdastVisit(handle, context, returnBuffer);
+    const root = readMdastMatchedNode(matchView, matchBuf, ru32(matchView, 10), ru32(matchView, 4), MDAST_ROOT, resolver);
+    const result = hook.call(plugin, root, context);
+    if (result instanceof Promise) {
+        return result.then(() => finalizeMdastVisit(handle, context, returnBuffer));
+    }
     return finalizeMdastVisit(handle, context, returnBuffer);
 }
 function finalizeMdastVisit(handle, context, returnBuffer) {
     const { merged, hasMutations } = mergeAndReset(returnBuffer, context);
+    // Return both buffers to the pool. Bytes were copied into `merged` above.
+    releaseCommandBuffer(returnBuffer);
+    releaseCommandBuffer(context.getCommandBuffer());
     return { commandBuffer: merged, diagnostics: context.getDiagnostics(), hasMutations };
 }