satteri 0.10.4 → 0.11.1

package/dist/mdast/mdast-visitor.js

@@ -1,42 +1,23 @@
-import { LEAF_TYPES, isCustomLeaf, materializeNode } from "./mdast-materializer.js";
-import { MdastReader } from "./mdast-reader.js";
-import { acquireCommandBuffer, releaseCommandBuffer, classifyReturn, CommandBuffer, STRUCTURAL_CMD, } from "../command-buffer.js";
+import { mdastTextContentHandle, walkMdastHandle } from "#binding";
+import { acquireCommandBuffer, 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, 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";
-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._refs === refs ? node._id : FOREIGN_REF;
-    const id = refs.get(node);
-    if (id !== undefined)
-        return id;
-    // 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");
-    if (d !== undefined && !d.enumerable)
-        return FOREIGN_REF;
-    return crossPipelineForeign(node);
-}
-const requireNid = makeRequireNid(nid);
+import { LazyChildResolver } from "../lazy-child-resolver.js";
+import { emitMdxAttr, OF_ALT, OF_CHECKED, OF_DEPTH, OF_EXPLICIT, OF_IDENTIFIER, OF_LABEL, OF_LANG, OF_META, OF_NAME, OF_ORDERED, OF_REFERENCE_TYPE, OF_SPREAD, OF_START, OF_TITLE, OF_URL, OF_VALUE, OpWriter, PROP_STRING, } from "../op-stream.js";
+import { asArray, collectCommands, FOREIGN_REF, foreignContentError, makeRequireNid, requireRootReplacement, ROOT_NODE_ID, rootReplacementError, unencodableContentError, withMdxJsxAttribute, } from "../visitor-shared.js";
+import { ru32 } from "../wire-read.js";
+import { MDAST_OPSTREAM_TYPES, NAME_TO_TYPE, VISITOR_KEYS } from "./generated/node-types.js";
+import { LEAF_TYPES } from "./mdast-materializer.js";
+import { MdastReader } from "./mdast-reader.js";
+import { getNodeId, MdastLazyChildResolver, readMdastMatchedNode } from "./mdast-walk.js";
+const requireNid = makeRequireNid(getNodeId);
 export class MdastVisitorContext {
     #commandBuffer = acquireCommandBuffer();
     #diagnostics;
+    #pendingNodes = new Map();
     #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;
     /**
      * The URL of the document being processed (the compile `fileURL` option),
      * or `undefined` when none was given. Use `fileURLToPath(ctx.fileURL)` for a
@@ -73,17 +54,20 @@ export class MdastVisitorContext {
         return value;
     }
     removeNode(node) {
-        this.#commandBuffer.removeNode(requireNid(node, "removeNode", this.#refs));
+        const id = requireNid(node, "removeNode", this.#refs);
+        this.#commandBuffer.removeNode(id);
+        this.#pendingNodes.delete(id);
     }
     insertBefore(node, newNode) {
-        const id = requireNid(node, "insertBefore", this.#refs);
-        for (const n of asArray(newNode))
-            emitMdastTree(this.#commandBuffer, "insertBefore", id, n, false, this.#refs);
+        this.#splice(requireNid(node, "insertBefore", this.#refs), newNode, "insertBefore");
     }
     insertAfter(node, newNode) {
-        const id = requireNid(node, "insertAfter", this.#refs);
-        for (const n of asArray(newNode))
-            emitMdastTree(this.#commandBuffer, "insertAfter", id, n, false, this.#refs);
+        this.#splice(requireNid(node, "insertAfter", this.#refs), newNode, "insertAfter");
+    }
+    #splice(anchorId, content, op) {
+        for (const n of asArray(content)) {
+            emitMdastTree(this.#commandBuffer, op, anchorId, n, false, this.#refs, true);
+        }
     }
     /**
      * Wrap `node` in `parentNode`, making it `parentNode`'s first child. Any
@@ -99,27 +83,20 @@ export class MdastVisitorContext {
         emitMdastTree(this.#commandBuffer, "wrapNode", id, parentNode, false, this.#refs);
     }
     prependChild(node, childNode) {
-        const id = requireNid(node, "prependChild", this.#refs);
-        for (const n of asArray(childNode))
-            emitMdastTree(this.#commandBuffer, "prependChild", id, n, false, this.#refs);
+        this.#splice(requireNid(node, "prependChild", this.#refs), childNode, "prependChild");
     }
     appendChild(node, childNode) {
-        const id = requireNid(node, "appendChild", this.#refs);
-        for (const n of asArray(childNode))
-            emitMdastTree(this.#commandBuffer, "appendChild", id, n, false, this.#refs);
+        this.#splice(requireNid(node, "appendChild", this.#refs), childNode, "appendChild");
     }
     /** 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 : undefined) ?? [];
-        if (index <= 0 || children.length === 0) {
-            this.prependChild(node, childNode);
-        }
-        else if (index >= children.length) {
-            this.appendChild(node, childNode);
-        }
-        else {
-            this.insertBefore(children[index], childNode);
-        }
+        const [anchor, op] = index <= 0 || children.length === 0
+            ? [node, "prependChild"]
+            : index >= children.length
+                ? [node, "appendChild"]
+                : [children[index], "insertBefore"];
+        this.#splice(requireNid(anchor, "insertChildAt", this.#refs), childNode, op);
     }
     /** Remove the `index`-th child of `node`; a no-op when there is no such child. */
     removeChildAt(node, index) {
@@ -135,26 +112,46 @@ export class MdastVisitorContext {
      */
     replaceNode(node, newNode) {
         const id = requireNid(node, "replaceNode", this.#refs);
+        const onlyReplacement = Array.isArray(newNode)
+            ? newNode.length === 1
+                ? newNode[0]
+                : undefined
+            : newNode;
+        if (id === ROOT_NODE_ID &&
+            onlyReplacement !== undefined &&
+            reusedId(onlyReplacement, this.#refs) === id) {
+            return;
+        }
         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.
+            // One command, so the node's replacement is its whole slot and a ref back
+            // to it resolves to all of it rather than to the last element.
+            if (id !== ROOT_NODE_ID && newNode.length > 1 && newNode.every(isPlainReplacement)) {
+                emitMdastMultiReplace(this.#commandBuffer, id, newNode, this.#refs);
+                return;
+            }
             let previous;
             for (const n of newNode) {
                 if (previous !== undefined) {
-                    emitMdastTree(this.#commandBuffer, "insertBefore", id, previous, false, this.#refs);
+                    emitMdastTree(this.#commandBuffer, "insertBefore", id, previous, false, this.#refs, true);
                 }
                 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);
+                emitMdastTree(this.#commandBuffer, "replace", id, previous, true, this.#refs, true);
+            }
+            if (previous !== undefined && !isRawMdastContent(previous)) {
+                this.#pendingNodes.set(id, previous);
+            }
+            else {
+                this.#pendingNodes.delete(id);
             }
             return;
         }
@@ -162,24 +159,84 @@ export class MdastVisitorContext {
             emitMdastRootReplace(this.#commandBuffer, requireRootReplacement(newNode), this.#refs);
             return;
         }
-        emitMdastTree(this.#commandBuffer, "replace", id, newNode, true, this.#refs);
+        if (isRawMdastContent(newNode))
+            this.#pendingNodes.delete(id);
+        else
+            this.#pendingNodes.set(id, newNode);
+        emitMdastTree(this.#commandBuffer, "replace", id, newNode, true, this.#refs, true);
+    }
+    setField(node, key, value) {
+        const id = requireNid(node, "setField", this.#refs);
+        if (this.#foldPendingField(node, id, key, value))
+            return;
+        if (key === "children") {
+            if (!emitMdastChildrenCommand(this.#commandBuffer, id, value, this.#refs)) {
+                throw unencodableContentError(value);
+            }
+            return;
+        }
+        if ((key === "attributes" && (isMdxJsxElement(node) || isDirective(node))) ||
+            (key === "align" && node.type === "table")) {
+            // These are structured node fields, so re-encode the node rather than a scalar command.
+            this.replaceNode(node, { ...node, [key]: value });
+            return;
+        }
+        if (key === "data")
+            value = value != null ? JSON.stringify(value) : null;
+        this.#commandBuffer.setField(id, key, value);
+    }
+    setAttribute(node, name, value) {
+        const id = requireNid(node, "setAttribute", this.#refs);
+        const target = this.#pendingNodes.get(id) ?? node;
+        if (isDirective(target) && typeof value !== "string") {
+            throw new TypeError("setAttribute: directive attributes must be strings");
+        }
+        if (this.#foldPendingAttribute(node, id, name, value))
+            return;
+        this.#commandBuffer.setAttribute(id, name, value);
+    }
+    /** A queued replacement would discard the field, so fold it into a fresh replacement. */
+    #foldPendingField(node, id, key, value) {
+        const pending = this.#pendingNodes.get(id);
+        if (pending === undefined)
+            return false;
+        this.replaceNode(node, { ...pending, [key]: value });
+        return true;
+    }
+    /** A queued replacement would discard the attribute, so fold it in instead. */
+    #foldPendingAttribute(node, id, name, value) {
+        const pending = this.#pendingNodes.get(id);
+        if (pending === undefined)
+            return false;
+        if (isDirective(pending)) {
+            this.replaceNode(node, {
+                ...pending,
+                attributes: { ...pending.attributes, [name]: value },
+            });
+            return true;
+        }
+        if (isMdxJsxElement(pending)) {
+            this.replaceNode(node, withMdxJsxAttribute(pending, name, value));
+            return true;
+        }
+        return false;
     }
     setProperty(node, key, value) {
+        const id = requireNid(node, "setProperty", this.#refs);
         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", this.#refs);
             if (!emitMdastChildrenCommand(this.#commandBuffer, id, value, this.#refs)) {
                 throw unencodableContentError(value);
             }
             return;
         }
-        if (key === "data") {
-            // data is stored as JSON in the arena, serialize it for the command buffer
-            this.#commandBuffer.setProperty(requireNid(node, "setProperty", this.#refs), key, value != null ? JSON.stringify(value) : null);
+        const target = this.#pendingNodes.get(id) ?? node;
+        if (key === "attributes" && isMdxJsxElement(target)) {
+            this.replaceNode(node, { ...target, attributes: value });
             return;
         }
-        this.#commandBuffer.setProperty(requireNid(node, "setProperty", this.#refs), key, value);
+        if (key === "data")
+            value = value != null ? JSON.stringify(value) : null;
+        this.#commandBuffer.setProperty(id, key, value);
     }
     /** Collect the concatenated text of all descendant text nodes (like mdast-util-to-string). */
     textContent(node, options) {
@@ -189,13 +246,7 @@ export class MdastVisitorContext {
         const parentId = this.#resolver.parentIdOf(requireNid(node, "parent", this.#refs));
         if (parentId === undefined)
             return undefined;
-        const byId = (this.#parentsById ??= new Map());
-        let parent = byId.get(parentId);
-        if (parent === undefined) {
-            parent = this.#resolver.materializeOne(parentId);
-            byId.set(parentId, parent);
-        }
-        return parent;
+        return this.#resolver.materializeOne(parentId);
     }
     /**
      * Index of `node` within its parent's children, or `undefined` at the root.
@@ -205,7 +256,7 @@ export class MdastVisitorContext {
         return this.#resolver.indexInParent(requireNid(node, "indexOf", this.#refs));
     }
     report({ message, node, severity = "error", }) {
-        const id = node ? nid(node, this.#refs) : undefined;
+        const id = node ? getNodeId(node, this.#refs) : undefined;
         this.#diagnostics.push({
             message,
             nodeId: id === FOREIGN_REF ? undefined : id,
@@ -213,7 +264,6 @@ export class MdastVisitorContext {
             severity,
         });
     }
-    /** Get the binary command buffer for all mutations recorded via context methods. */
     getCommandBuffer() {
         return this.#commandBuffer;
     }
@@ -254,169 +304,14 @@ function buildMdastSubscriptions(plugin) {
     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, refs) {
-        return materializeNode(reader, nodeId, true, refs);
-    }
-    readParentId(reader, nodeId) {
-        return reader.getParentId(nodeId);
-    }
-    readChildIds(reader, nodeId) {
-        return reader.getChildIds(nodeId);
-    }
-}
-/** Build the child-stub list for a matched node from the wire's `[child_ids]
- *  [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) {
-    // 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]);
-    }
-    return stubs;
-}
-/** Install `children` as an own enumerable getter (spread must carry it),
- *  self-replacing with the one stable stub array on first read. One closure
- *  and one define per node — installing the wire locals as hidden slots
- *  instead measurably regressed every matching pipeline. */
-function makeLazyChildren(node, view, buf, childIdsPos, childTypesPos, childCount, resolver) {
-    Object.defineProperty(node, "children", {
-        get() {
-            const val = readMdastChildStubs(view, buf, childIdsPos, childTypesPos, childCount, resolver);
-            Object.defineProperty(this, "children", {
-                value: val,
-                writable: true,
-                enumerable: true,
-                configurable: true,
-            });
-            return val;
-        },
-        enumerable: true,
-        configurable: true,
-    });
-}
-/**
- * Read an MDAST node from the inline data in a match buffer entry.
- *
- * Inline format (from Rust serialize_mdast_node_inline):
- *   [node_data: u32+bytes][position: 6×u32 = 24B][child_count: u32][child_ids: N×u32]
- *   [child_types: N×u8][type-specific data]
- */
-function readMdastMatchedNode(view, buf, dataOffset, nodeId, nodeType, resolver) {
-    let pos = dataOffset;
-    const dataJsonLen = ru32(view, pos);
-    pos += 4;
-    let initialData = null;
-    if (dataJsonLen > 0) {
-        const jsonStr = rstr(buf, pos, dataJsonLen);
-        try {
-            initialData = JSON.parse(jsonStr);
-        }
-        catch (err) {
-            if (process.env.NODE_ENV !== "production") {
-                console.warn(`readMdastMatchedNode: malformed node_data for nodeId=${nodeId}`, err);
-            }
-        }
-        pos += dataJsonLen;
-    }
-    const position = readPosition(view, pos);
-    pos += 24;
-    const childCount = ru32(view, pos);
-    pos += 4;
-    // Ids/types decode lazily with `.children` — most matched nodes never read them.
-    const childIdsPos = pos;
-    pos += childCount * 4;
-    const childTypesPos = pos;
-    pos += childCount;
-    const typeName = TYPE_NAMES[nodeType] ?? `unknown(${nodeType})`;
-    const node = { type: typeName };
-    if (position !== undefined)
-        node.position = position;
-    if (childCount > 0) {
-        makeLazyChildren(node, view, buf, childIdsPos, childTypesPos, childCount, resolver);
-    }
-    // Fixed-field types decode from the generated layout table; the rest
-    // (variable-length / cross-field) stay in the hand-written switch.
-    if (!decodeMdastTypeData(view, buf, pos, nodeType, node)) {
-        switch (nodeType) {
-            case 5: {
-                // list
-                node.start = ru32(view, pos);
-                node.ordered = buf[pos + 4] !== 0;
-                node.spread = buf[pos + 5] !== 0;
-                if (!node.ordered)
-                    node.start = null;
-                break;
-            }
-            case 6: {
-                // listItem
-                const checked = buf[pos];
-                node.checked = checked === 2 ? null : checked === 1;
-                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
-        }
-    }
-    // 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, refs) {
     if (node === null || typeof node !== "object")
         return undefined;
-    const id = nid(node, refs);
+    const id = getNodeId(node, refs);
     return id !== undefined && id !== FOREIGN_REF ? id : undefined;
 }
-/** Emit a set-children command in place: a root-wrapped child list, the shape
- *  `Patch::SetChildren` splices in. Reused children become refs. */
 function emitMdastChildrenCommand(buffer, id, children, refs) {
     if (!Array.isArray(children))
         return false;
@@ -430,7 +325,25 @@ function emitMdastChildrenCommand(buffer, id, children, refs) {
         return true;
     });
 }
-/** Separate from the per-node encoder, which rejects a `root` payload. */
+/** True for content the op-stream can carry inside one root-wrapped payload. */
+function isPlainReplacement(content) {
+    return (!isRawMdastContent(content) && content._keepChildren !== true);
+}
+/** Replace `id` with several nodes in one command, root-wrapped so the engine
+ *  splices the children in place of the node. */
+function emitMdastMultiReplace(buffer, id, nodes, refs) {
+    const ok = buffer.emitOpstreamCommand(STRUCTURAL_CMD.replace, id, () => {
+        buffer.open(MDAST_ROOT);
+        for (const n of nodes)
+            if (!emitMdastOp(buffer, n, false, true, refs))
+                return false;
+        buffer.close();
+        return true;
+    });
+    if (!ok)
+        throw unencodableContentError(nodes);
+}
+// Root replacement needs a separate encoder because per-node encoding rejects root payloads.
 function emitMdastRootReplace(buffer, root, refs) {
     const ok = buffer.emitOpstreamCommand(STRUCTURAL_CMD.replace, ROOT_NODE_ID, () => emitMdastRootOp(buffer, root, refs));
     if (!ok)
@@ -454,36 +367,29 @@ function emitMdastRootOp(w, n, refs) {
     w.close();
     return true;
 }
-function emitMdastOp(w, node, isRoot, forReplace, refs) {
+function emitMdastOp(w, node, isRoot, forReplace, refs, allowRootRef = false) {
     if (node === null || typeof node !== "object")
         return false;
-    if (!isRoot) {
-        const id = reusedId(node, refs);
-        if (id !== undefined) {
-            w.ref(id);
-            return true;
-        }
+    const id = getNodeId(node, refs);
+    if (id === FOREIGN_REF)
+        throw foreignContentError();
+    if ((!isRoot || allowRootRef) && id !== undefined) {
+        w.ref(id);
+        return true;
     }
     const n = node;
-    // 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.
+        // Unsupported built-in types must fail rather than silently becoming custom nodes.
         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);
@@ -507,8 +413,7 @@ function emitMdastOp(w, node, isRoot, forReplace, refs) {
         w.str(OF_LABEL, n.label);
     if (typeof n.referenceType === "string")
         w.str(OF_REFERENCE_TYPE, n.referenceType);
-    // Out-of-range numbers compile to null and the caller throws — a visible
-    // error instead of silently masking the bits.
+    // Reject out-of-range values before integer writes can truncate them.
     if (typeof n.depth === "number") {
         if (!Number.isInteger(n.depth) || n.depth < 0 || n.depth > 255)
             return false;
@@ -533,8 +438,6 @@ function emitMdastOp(w, node, isRoot, forReplace, refs) {
             emitMdxAttr(w, a);
     }
     else if (attrs !== null && typeof attrs === "object") {
-        // Directive attributes: a string→string map; non-string values are
-        // dropped, since the stored form holds only strings.
         for (const key in attrs) {
             const v = attrs[key];
             if (typeof v === "string")
@@ -549,13 +452,10 @@ function emitMdastOp(w, node, isRoot, forReplace, refs) {
     if (n.data != null)
         w.data(n.data);
     if (isRoot && forReplace && n._keepChildren === true) {
-        // Replace splices the target's original children, discarding any the
-        // replacement declares.
         w.keepChildren();
     }
     else {
-        // `_keepChildren` only applies to replace; other ops ignore the marker
-        // and emit the declared children.
+        // Only replacement can reuse the target’s original children.
         const children = n.children;
         if (Array.isArray(children)) {
             for (const c of children)
@@ -566,24 +466,23 @@ function emitMdastOp(w, node, isRoot, forReplace, refs) {
     w.close();
     return true;
 }
-/** Map a table `align` entry to its arena code (none=0). */
 function alignCode(a) {
     return a === "left" ? 1 : a === "right" ? 2 : a === "center" ? 3 : 0;
 }
-/** True for the `{raw}` / `{rawHtml}` escape hatches — re-parsed by Rust rather
- *  than compiled to an op-stream, so they ride the RAW_MARKDOWN / RAW_HTML
- *  payloads instead of the declarative encoder. */
 function isRawMdastContent(content) {
     const c = content;
     return typeof c.raw === "string" || typeof c.rawHtml === "string";
 }
-/** Encode `content` as the `op` structural command. Declarative nodes compile
- *  to the op-stream; the `{raw}`/`{rawHtml}` escape hatches ride the raw
- *  re-parse payloads. Anything that compiles to neither is a hard error — the
- *  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, refs) {
+function isDirective(node) {
+    return (node.type === "containerDirective" ||
+        node.type === "leafDirective" ||
+        node.type === "textDirective");
+}
+function isMdxJsxElement(node) {
+    return ((node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement") && "attributes" in node);
+}
+// Keep direct method calls so structural command dispatch stays monomorphic.
+function emitMdastTree(buffer, op, id, content, forReplace, refs, allowRootRef = false) {
     if (isRawMdastContent(content)) {
         switch (op) {
             case "replace":
@@ -600,7 +499,7 @@ function emitMdastTree(buffer, op, id, content, forReplace, refs) {
                 return buffer.wrapNode(id, content);
         }
     }
-    const ok = buffer.emitOpstreamCommand(STRUCTURAL_CMD[op], id, () => emitMdastOp(buffer, content, true, forReplace, refs));
+    const ok = buffer.emitOpstreamCommand(STRUCTURAL_CMD[op], id, () => emitMdastOp(buffer, content, true, forReplace, refs, allowRootRef));
     if (!ok)
         throw unencodableContentError(content);
 }
@@ -613,8 +512,6 @@ function assertMdastWrapParent(parentNode) {
     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. ` +
@@ -626,9 +523,7 @@ function assertMdastWrapParent(parentNode) {
         '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. */
+// Updating only value avoids an arena rebuild for these node types.
 const MDAST_VALUE_ONLY_TYPES = new Set([
     "text",
     "html",
@@ -637,9 +532,7 @@ const MDAST_VALUE_ONLY_TYPES = new Set([
     "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. */
+// Extra fields require full replacement so the value-only fast path cannot discard them.
 function isMdastTextValueSwap(result, original) {
     if (original === undefined)
         return false;
@@ -656,8 +549,7 @@ function isMdastTextValueSwap(result, original) {
         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. */
+// Returning the input node must not overwrite mutations queued through the context.
 function applyMdastVisitResult(result, nodeId, returnBuffer, refs, originalNode) {
     if (result === undefined || result === null)
         return;
@@ -677,14 +569,14 @@ function applyMdastVisitResult(result, nodeId, returnBuffer, refs, originalNode)
                 returnBuffer.setProperty(nodeId, "value", node.value);
                 break;
             }
-            emitMdastTree(returnBuffer, "replace", nodeId, node, true, refs);
+            emitMdastTree(returnBuffer, "replace", nodeId, node, true, refs, true);
             break;
         }
     }
 }
 /**
  * Walk an MDAST handle in Rust, dispatch matched nodes to JS visitor functions,
- * and apply mutations back to the handle. No arena buffers cross NAPI.
+ * and collect mutations for the caller to apply. No arena buffers cross NAPI.
  *
  * Returns MdastVisitResult synchronously if all visitors are sync,
  * or Promise<MdastVisitResult> if any visitor is async.
@@ -716,20 +608,21 @@ export function visitMdastHandle(handle, plugin, subs, source, fileURL, data = {
         }
     }
     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, resolver.refs, originalNode);
+        const visits = deferred;
+        return Promise.all(visits.map((visit) => visit.promise)).then((results) => {
+            for (let i = 0; i < visits.length; i++) {
+                const { nodeId, originalNode } = visits[i];
+                applyMdastVisitResult(results[i], nodeId, returnBuffer, resolver.refs, originalNode);
             }
-            return finalizeMdastVisit(handle, context, returnBuffer);
+            return finalizeMdastVisit(context, returnBuffer);
         });
     }
-    return finalizeMdastVisit(handle, context, returnBuffer);
+    return finalizeMdastVisit(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. */
+/** Hooks run in separate passes so each sees mutations from the preceding pass. */
 export function visitMdastHook(handle, plugin, hook, source, fileURL, data = {}, sourceFormat = "markdown", diagnostics = []) {
     const getSource = typeof source === "function" ? source : () => source;
     const resolver = new MdastLazyChildResolver(handle);
@@ -738,18 +631,19 @@ export function visitMdastHook(handle, plugin, hook, source, fileURL, data = {},
     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);
+        return finalizeMdastVisit(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 result.then(() => finalizeMdastVisit(context, returnBuffer));
     }
-    return finalizeMdastVisit(handle, context, returnBuffer);
+    return finalizeMdastVisit(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 };
+function finalizeMdastVisit(context, returnBuffer) {
+    const commandBuffer = collectCommands(returnBuffer, context.getCommandBuffer());
+    return {
+        commandBuffer,
+        diagnostics: context.getDiagnostics(),
+        hasMutations: commandBuffer.length > 0,
+    };
 }