satteri 0.8.1 → 0.9.0

package/dist/mdast/mdast-visitor.js

@@ -1,78 +1,60 @@
-import { materializeNode, TYPE_NAMES } from "./mdast-materializer.js";
+import { materializeNode } from "./mdast-materializer.js";
 import { MdastReader } from "./mdast-reader.js";
 import { CommandBuffer, classifyReturn } from "../command-buffer.js";
-import { walkMdastHandle, serializeHandle, getNodeData as napiGetNodeData, mdastTextContentHandle, } from "#binding";
-const MutationType = {
-    Replace: "replace",
-    Remove: "remove",
-    InsertBefore: "insertBefore",
-    InsertAfter: "insertAfter",
-    Wrap: "wrap",
-    PrependChild: "prependChild",
-    AppendChild: "appendChild",
-    SetProperty: "setProperty",
-};
-const VISITOR_KEYS = new Set([
-    "paragraph",
-    "heading",
-    "thematicBreak",
-    "blockquote",
-    "list",
-    "listItem",
-    "html",
-    "code",
-    "definition",
-    "text",
-    "emphasis",
-    "strong",
-    "inlineCode",
-    "break",
-    "link",
-    "image",
-    "linkReference",
-    "imageReference",
-    "footnoteDefinition",
-    "footnoteReference",
-    "table",
-    "tableRow",
-    "tableCell",
-    "delete",
-    "yaml",
-    "toml",
-    "math",
-    "inlineMath",
-    "containerDirective",
-    "leafDirective",
-    "textDirective",
-    "mdxJsxFlowElement",
-    "mdxJsxTextElement",
-    "mdxFlowExpression",
-    "mdxTextExpression",
-    "mdxjsEsm",
-]);
+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 { MdastChildStub } from "./child-stub.js";
 /** Maps MdastNode objects to their arena node IDs without Object.defineProperty overhead. */
 const mdastNodeIdMap = new WeakMap();
 function nid(node) {
-    return mdastNodeIdMap.get(node) ?? node._nodeId;
-}
-function asArray(value) {
-    return Array.isArray(value) ? value : [value];
+    // 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);
+    if (id !== undefined)
+        return id;
+    // Plain objects are trusted only via the WeakMap 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;
 }
+const requireNid = makeRequireNid(nid);
 export class MdastVisitorContext {
     #commandBuffer = new CommandBuffer();
     #diagnostics = [];
     #handle;
     #getSource;
+    #resolver;
+    /** 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
      * decoded filesystem path.
      */
     fileURL;
-    constructor(handle, getSource, fileURL) {
+    /**
+     * Document-level data bag, shared across every plugin in the compile and
+     * across the mdast→hast phase boundary. Mutate keys directly
+     * (`ctx.data.foo = x`); the bag itself isn't reassignable. Values are kept
+     * on the JS side, so any value is allowed, including functions and class
+     * instances. Returned to the caller as `result.data`.
+     */
+    data;
+    constructor(handle, getSource, fileURL, resolver, data) {
         this.#handle = handle;
         this.#getSource = getSource;
         this.fileURL = fileURL;
+        this.#resolver = resolver;
+        this.data = data;
     }
     get source() {
         const value = this.#getSource();
@@ -80,34 +62,35 @@ export class MdastVisitorContext {
         return value;
     }
     removeNode(node) {
-        this.#commandBuffer.removeNode(nid(node));
+        this.#commandBuffer.removeNode(requireNid(node, "removeNode"));
     }
     insertBefore(node, newNode) {
-        const id = nid(node);
+        const id = requireNid(node, "insertBefore");
         for (const n of asArray(newNode))
-            this.#commandBuffer.insertBefore(id, n);
+            emitMdastTree(this.#commandBuffer, "insertBefore", id, n);
     }
     insertAfter(node, newNode) {
-        const id = nid(node);
+        const id = requireNid(node, "insertAfter");
         for (const n of asArray(newNode))
-            this.#commandBuffer.insertAfter(id, n);
+            emitMdastTree(this.#commandBuffer, "insertAfter", id, n);
     }
     /**
      * Wrap `node` in `parentNode`, making it `parentNode`'s first child. Any
      * children `parentNode` declares are kept after it.
      */
     wrapNode(node, parentNode) {
-        this.#commandBuffer.wrapNode(nid(node), parentNode);
+        const id = requireNid(node, "wrapNode");
+        emitMdastTree(this.#commandBuffer, "wrapNode", id, parentNode);
     }
     prependChild(node, childNode) {
-        const id = nid(node);
+        const id = requireNid(node, "prependChild");
         for (const n of asArray(childNode))
-            this.#commandBuffer.prependChild(id, n);
+            emitMdastTree(this.#commandBuffer, "prependChild", id, n);
     }
     appendChild(node, childNode) {
-        const id = nid(node);
+        const id = requireNid(node, "appendChild");
         for (const n of asArray(childNode))
-            this.#commandBuffer.appendChild(id, n);
+            emitMdastTree(this.#commandBuffer, "appendChild", id, n);
     }
     /** Insert one node or an array at `index`; clamps (`0` or less prepends, past the end appends). */
     insertChildAt(node, index, childNode) {
@@ -129,26 +112,49 @@ export class MdastVisitorContext {
             this.removeNode(child);
     }
     replaceNode(node, newNode) {
-        this.#commandBuffer.replace(nid(node), newNode);
+        const id = requireNid(node, "replaceNode");
+        emitMdastTree(this.#commandBuffer, "replace", id, newNode, true);
     }
     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 wrapper = refifyReusedNodes({ type: "root", children: value }, true);
-            this.#commandBuffer.setChildren(nid(node), JSON.stringify(wrapper));
+            const id = requireNid(node, "setProperty");
+            const ops = compileMdastChildrenToOpstream(value);
+            if (!ops)
+                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(nid(node), key, value != null ? JSON.stringify(value) : null);
+            this.#commandBuffer.setProperty(requireNid(node, "setProperty"), key, value != null ? JSON.stringify(value) : null);
             return;
         }
-        this.#commandBuffer.setProperty(nid(node), key, value);
+        this.#commandBuffer.setProperty(requireNid(node, "setProperty"), key, value);
     }
     /** Collect the concatenated text of all descendant text nodes (like mdast-util-to-string). */
     textContent(node, options) {
-        return mdastTextContentHandle(this.#handle, nid(node), options);
+        return mdastTextContentHandle(this.#handle, requireNid(node, "textContent"), options);
+    }
+    parent(node) {
+        const parentId = this.#resolver.parentIdOf(requireNid(node, "parent"));
+        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;
+    }
+    /**
+     * Index of `node` within its parent's children, or `undefined` at the root.
+     * Use this rather than `parent.children.indexOf(node)`, which won't find it.
+     */
+    indexOf(node) {
+        return this.#resolver.indexInParent(requireNid(node, "indexOf"));
     }
     report({ message, node, severity = "error", }) {
         this.#diagnostics.push({
@@ -166,32 +172,6 @@ export class MdastVisitorContext {
         return this.#diagnostics;
     }
 }
-/** Merge return-value + context command buffers and release internals. */
-function mergeAndReset(returnBuffer, ctx) {
-    const ctxCmdBuf = ctx.getCommandBuffer();
-    const ctxBuf = ctxCmdBuf.getBuffer();
-    const retBuf = returnBuffer.getBuffer();
-    const totalLen = retBuf.length + ctxBuf.length;
-    let merged;
-    if (totalLen === 0) {
-        merged = new Uint8Array(0);
-    }
-    else {
-        merged = new Uint8Array(totalLen);
-        merged.set(retBuf, 0);
-        merged.set(ctxBuf, retBuf.length);
-    }
-    returnBuffer.reset();
-    ctxCmdBuf.reset();
-    return { merged, hasMutations: totalLen > 0 };
-}
-const textDecoder = new TextDecoder("utf-8");
-/** Build name→nodeType map from TYPE_NAMES (reverse of TYPE_NAMES). */
-const NAME_TO_TYPE = {};
-for (const [num, name] of Object.entries(TYPE_NAMES)) {
-    NAME_TO_TYPE[name] = Number(num);
-}
-/** Resolve subscriptions from a plugin instance. */
 export function resolveMdastSubscriptions(plugin) {
     const subs = [];
     for (const [name, fn] of Object.entries(plugin)) {
@@ -207,69 +187,61 @@ export function resolveMdastSubscriptions(plugin) {
     }
     return subs;
 }
-/** Read a u16 from buf at offset (LE). */
-function ru16(view, off) {
-    return view.getUint16(off, true);
-}
-/** Read a u32 from buf at offset (LE). */
-function ru32(view, off) {
-    return view.getUint32(off, true);
+class MdastLazyChildResolver extends LazyChildResolver {
+    createReader(wire) {
+        return new MdastReader(wire);
+    }
+    materializeNode(reader, nodeId) {
+        return materializeNode(reader, nodeId);
+    }
+    readParentId(reader, nodeId) {
+        return reader.getParentId(nodeId);
+    }
+    readChildIds(reader, nodeId) {
+        return reader.getChildIds(nodeId);
+    }
 }
-/** Read a utf8 string from buf. */
-function rstr(buf, off, len) {
-    return len === 0 ? "" : textDecoder.decode(buf.subarray(off, off + len));
+/** 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. */
+function readMdastChildStubs(view, buf, idsPos, typesPos, count, resolver) {
+    resolver.assertUnsealed();
+    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;
 }
-/**
- * Lazy child materializer for the MDAST handle walk path.
- * Serializes the handle once on first child access, then materializes
- * children via MdastReader + materializeNode.
- */
-class MdastLazyChildResolver {
-    #handle;
-    #reader = null;
-    constructor(handle) {
-        this.#handle = handle;
-    }
-    #ensure() {
-        if (!this.#reader) {
-            this.#reader = new MdastReader(serializeHandle(this.#handle));
-        }
-        return this.#reader;
-    }
-    materializeChildren(childIds) {
-        const reader = this.#ensure();
-        const handle = this.#handle;
-        return childIds.map((id) => {
-            const node = materializeNode(reader, id);
-            Object.defineProperty(node, "data", {
-                get() {
-                    const json = napiGetNodeData(handle, id);
-                    const val = json ? JSON.parse(json) : null;
-                    Object.defineProperty(this, "data", {
-                        value: val,
-                        writable: true,
-                        enumerable: true,
-                        configurable: true,
-                    });
-                    return val;
-                },
-                configurable: true,
+/** 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 node;
-        });
-    }
+            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: u16][child_ids: N×u32][type-specific data]
+ *   [node_data: u32+bytes][position: 6×u32 = 24B][child_count: u32][child_ids: N×u32]
+ *   [child_types: N×u8][type-specific data]
  */
-const encoder = new TextEncoder();
 function readMdastMatchedNode(view, buf, dataOffset, nodeId, nodeType, resolver) {
     let pos = dataOffset;
-    // Node data (JSON bytes), always first
     const dataJsonLen = ru32(view, pos);
     pos += 4;
     let initialData = null;
@@ -278,272 +250,54 @@ function readMdastMatchedNode(view, buf, dataOffset, nodeId, nodeType, resolver)
         try {
             initialData = JSON.parse(jsonStr);
         }
-        catch {
-            /* ignore */
+        catch (err) {
+            if (process.env.NODE_ENV !== "production") {
+                console.warn(`readMdastMatchedNode: malformed node_data for nodeId=${nodeId}`, err);
+            }
         }
         pos += dataJsonLen;
     }
-    // Position
-    const position = {
-        start: { offset: ru32(view, pos), line: ru32(view, pos + 8), column: ru32(view, pos + 12) },
-        end: { offset: ru32(view, pos + 4), line: ru32(view, pos + 16), column: ru32(view, pos + 20) },
-    };
+    const position = readPosition(view, pos);
     pos += 24;
-    // Children, read IDs, materialize lazily via resolver
-    const childCount = ru16(view, pos);
-    pos += 2;
-    const childIds = [];
-    for (let i = 0; i < childCount; i++) {
-        childIds.push(ru32(view, pos));
-        pos += 4;
-    }
+    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})`;
-    // Build node with type-specific fields
-    const node = { type: typeName, position };
+    const node = { type: typeName };
+    if (position !== undefined)
+        node.position = position;
     if (childCount > 0) {
-        Object.defineProperty(node, "children", {
-            get() {
-                const val = resolver.materializeChildren(childIds);
-                Object.defineProperty(this, "children", {
-                    value: val,
-                    writable: true,
-                    enumerable: true,
-                    configurable: true,
-                });
-                return val;
-            },
-            configurable: true,
-            enumerable: true,
-        });
-    }
-    switch (nodeType) {
-        case 2: {
-            // heading
-            node.depth = buf[pos];
-            break;
-        }
-        case 10:
-        case 13:
-        case 7:
-        case 25:
-        case 26: {
-            // text, inlineCode, html, yaml, toml
-            const vlen = ru32(view, pos);
-            node.value = rstr(buf, pos + 4, vlen);
-            break;
-        }
-        case 8: {
-            // code
-            const langLen = ru16(view, pos);
-            pos += 2;
-            node.lang = langLen > 0 ? rstr(buf, pos, langLen) : null;
-            pos += langLen;
-            const metaLen = ru16(view, pos);
-            pos += 2;
-            node.meta = metaLen > 0 ? rstr(buf, pos, metaLen) : null;
-            pos += metaLen;
-            const valLen = ru32(view, pos);
-            pos += 4;
-            node.value = rstr(buf, pos, valLen);
-            break;
-        }
-        case 27:
-        case 28: {
-            // math, inlineMath
-            const metaLen = ru16(view, pos);
-            pos += 2;
-            node.meta = metaLen > 0 ? rstr(buf, pos, metaLen) : null;
-            pos += metaLen;
-            const valLen = ru32(view, pos);
-            pos += 4;
-            node.value = rstr(buf, pos, valLen);
-            break;
-        }
-        case 15: {
-            // link
-            const urlLen = ru16(view, pos);
-            pos += 2;
-            node.url = rstr(buf, pos, urlLen);
-            pos += urlLen;
-            const titleLen = ru16(view, pos);
-            pos += 2;
-            node.title = titleLen > 0 ? rstr(buf, pos, titleLen) : null;
-            break;
-        }
-        case 16: {
-            // image
-            const urlLen = ru16(view, pos);
-            pos += 2;
-            node.url = rstr(buf, pos, urlLen);
-            pos += urlLen;
-            const altLen = ru16(view, pos);
-            pos += 2;
-            node.alt = rstr(buf, pos, altLen);
-            pos += altLen;
-            const titleLen = ru16(view, pos);
-            pos += 2;
-            node.title = titleLen > 0 ? rstr(buf, pos, titleLen) : null;
-            break;
-        }
-        case 9: {
-            // definition
-            const urlLen = ru16(view, pos);
-            pos += 2;
-            node.url = rstr(buf, pos, urlLen);
-            pos += urlLen;
-            const titleLen = ru16(view, pos);
-            pos += 2;
-            node.title = titleLen > 0 ? rstr(buf, pos, titleLen) : null;
-            pos += titleLen;
-            const idLen = ru16(view, pos);
-            pos += 2;
-            node.identifier = rstr(buf, pos, idLen);
-            pos += idLen;
-            const labelLen = ru16(view, pos);
-            pos += 2;
-            node.label = rstr(buf, pos, labelLen);
-            break;
-        }
-        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 17:
-        case 18:
-        case 20: {
-            // linkReference, imageReference, footnoteReference
-            const idLen = ru16(view, pos);
-            pos += 2;
-            node.identifier = rstr(buf, pos, idLen);
-            pos += idLen;
-            const labelLen = ru16(view, pos);
-            pos += 2;
-            node.label = rstr(buf, pos, labelLen);
-            pos += labelLen;
-            const kind = buf[pos];
-            pos += 1;
-            // Only link/image references carry `referenceType`; the mdast spec
-            // defines it for those two, not for `footnoteReference`.
-            if (nodeType !== 20) {
-                node.referenceType = ["shortcut", "collapsed", "full"][kind] ?? "shortcut";
-            }
-            // imageReference also carries `alt` (the serializer appends it).
-            if (nodeType === 18) {
-                const altLen = ru16(view, pos);
-                pos += 2;
-                node.alt = rstr(buf, pos, altLen);
-            }
-            break;
-        }
-        case 19: {
-            // footnoteDefinition
-            const idLen = ru16(view, pos);
-            pos += 2;
-            node.identifier = rstr(buf, pos, idLen);
-            pos += idLen;
-            const labelLen = ru16(view, pos);
-            pos += 2;
-            node.label = rstr(buf, pos, labelLen);
-            break;
-        }
-        case 21: {
-            // table
-            const count = ru16(view, pos);
-            pos += 2;
-            const alignNames = [null, "left", "right", "center"];
-            node.align = Array.from({ length: count }, (_, i) => alignNames[buf[pos + i]] ?? null);
-            break;
-        }
-        case 30:
-        case 31:
-        case 32: {
-            // containerDirective, leafDirective, textDirective
-            const nameLen = ru16(view, pos);
-            pos += 2;
-            node.name = rstr(buf, pos, nameLen);
-            pos += nameLen;
-            const attrCount = ru16(view, pos);
-            pos += 2;
-            const attributes = {};
-            for (let i = 0; i < attrCount; i++) {
-                const keyLen = ru16(view, pos);
-                pos += 2;
-                const key = rstr(buf, pos, keyLen);
-                pos += keyLen;
-                const valLen = ru16(view, pos);
-                pos += 2;
-                const val = rstr(buf, pos, valLen);
-                pos += valLen;
-                attributes[key] = val;
+        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;
             }
-            node.attributes = attributes;
-            break;
-        }
-        case 100:
-        case 101: {
-            // mdxJsxFlowElement, mdxJsxTextElement
-            const nameLen = ru16(view, pos);
-            pos += 2;
-            node.name = nameLen > 0 ? rstr(buf, pos, nameLen) : null;
-            pos += nameLen;
-            const attrCount = ru16(view, pos);
-            pos += 2;
-            const attributes = [];
-            for (let i = 0; i < attrCount; i++) {
-                const kind = buf[pos];
-                pos += 1;
-                const anLen = ru16(view, pos);
-                pos += 2;
-                const an = rstr(buf, pos, anLen);
-                pos += anLen;
-                const avLen = ru32(view, pos);
-                pos += 4;
-                const av = rstr(buf, pos, avLen);
-                pos += avLen;
-                switch (kind) {
-                    case 0:
-                        attributes.push({ type: "mdxJsxAttribute", name: an, value: null });
-                        break;
-                    case 1:
-                        attributes.push({ type: "mdxJsxAttribute", name: an, value: av });
-                        break;
-                    case 2:
-                        attributes.push({
-                            type: "mdxJsxAttribute",
-                            name: an,
-                            value: { type: "mdxJsxAttributeValueExpression", value: av },
-                        });
-                        break;
-                    case 3:
-                        attributes.push({ type: "mdxJsxExpressionAttribute", value: av });
-                        break;
-                }
+            case 6: {
+                // listItem
+                const checked = buf[pos];
+                node.checked = checked === 2 ? null : checked === 1;
+                node.spread = buf[pos + 1] !== 0;
+                break;
             }
-            node.attributes = attributes;
-            break;
-        }
-        case 102:
-        case 103:
-        case 104: {
-            // mdxFlowExpression, mdxTextExpression, mdxjsEsm
-            const vlen = ru32(view, pos);
-            node.value = rstr(buf, pos + 4, vlen);
-            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
         }
-        // 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);
     if (initialData) {
@@ -551,9 +305,6 @@ function readMdastMatchedNode(view, buf, dataOffset, nodeId, nodeType, resolver)
     }
     return node;
 }
-/** Apply a sync visitor result to the return buffer.
- *  If the result is the same object as the input node, treat it as a no-op
- *  so that context mutations (e.g. setProperty) are not clobbered. */
 /** The arena id of a node if it is an existing (materialized) node, else
  *  undefined for a freshly-built one. */
 function reusedId(node) {
@@ -562,28 +313,193 @@ function reusedId(node) {
     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();
 /**
- * Rewrite a returned replacement tree so every *reused* node (one that came
- * from the arena, at any depth) becomes a `{ _ref: id }` placeholder. The
- * rebuild splices those originals back in place, preserving their ids — so a
- * patch a nested visitor queued on a passed-through child still lands, in the
- * same pass. Freshly-built nodes serialize as before. The root is never reffed:
- * it is the new shape replacing the visited node.
+ * 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 refifyReusedNodes(node, isRoot) {
+function compileMdastToOpstream(root, forReplace = false) {
+    mdastWriter.begin();
+    try {
+        if (!emitMdastOp(mdastWriter, root, true, forReplace))
+            return null;
+        return mdastWriter.take();
+    }
+    finally {
+        mdastWriter.end();
+    }
+}
+/** Compile a set-children payload: a root-wrapped child list, the shape
+ *  `Patch::SetChildren` splices in. Reused children become refs. */
+function compileMdastChildrenToOpstream(children) {
+    if (!Array.isArray(children))
+        return null;
+    mdastWriter.begin();
+    try {
+        mdastWriter.open(NAME_TO_TYPE.root);
+        for (const c of children) {
+            if (!emitMdastOp(mdastWriter, c, false, false))
+                return null;
+        }
+        mdastWriter.close();
+        return mdastWriter.take();
+    }
+    finally {
+        mdastWriter.end();
+    }
+}
+function emitMdastOp(w, node, isRoot, forReplace) {
     if (node === null || typeof node !== "object")
-        return node;
+        return false;
     if (!isRoot) {
         const id = reusedId(node);
-        if (id !== undefined)
-            return { _ref: id };
+        if (id !== undefined) {
+            w.ref(id);
+            return true;
+        }
     }
-    const children = node.children;
-    if (Array.isArray(children)) {
-        return { ...node, children: children.map((c) => refifyReusedNodes(c, false)) };
+    const n = node;
+    const type = MDAST_OPSTREAM_TYPES[n.type];
+    if (type === undefined)
+        return false;
+    w.open(type);
+    if (typeof n.value === "string")
+        w.str(OF_VALUE, n.value);
+    if (typeof n.url === "string")
+        w.str(OF_URL, n.url);
+    if (typeof n.title === "string")
+        w.str(OF_TITLE, n.title);
+    if (typeof n.alt === "string")
+        w.str(OF_ALT, n.alt);
+    if (typeof n.lang === "string")
+        w.str(OF_LANG, n.lang);
+    if (typeof n.meta === "string")
+        w.str(OF_META, n.meta);
+    if (typeof n.identifier === "string")
+        w.str(OF_IDENTIFIER, n.identifier);
+    if (typeof n.label === "string")
+        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.
+    if (typeof n.depth === "number") {
+        if (!Number.isInteger(n.depth) || n.depth < 0 || n.depth > 255)
+            return false;
+        w.u8(OF_DEPTH, n.depth);
+    }
+    if (typeof n.checked === "boolean")
+        w.u8(OF_CHECKED, n.checked ? 1 : 0);
+    if (typeof n.start === "number") {
+        if (!Number.isInteger(n.start) || n.start < 0 || n.start > 4294967295)
+            return false;
+        w.u32(OF_START, n.start);
+    }
+    if (typeof n.ordered === "boolean")
+        w.bool(OF_ORDERED, n.ordered);
+    if (typeof n.spread === "boolean")
+        w.bool(OF_SPREAD, n.spread);
+    if (typeof n.name === "string")
+        w.str(OF_NAME, n.name);
+    const attrs = n.attributes;
+    if (Array.isArray(attrs)) {
+        for (const a of attrs)
+            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")
+                w.prop(key, PROP_STRING, v);
+        }
+    }
+    if (Array.isArray(n.align))
+        w.align(n.align.map(alignCode));
+    if (n.data?._mdxExplicitJsx === true) {
+        w.bool(OF_EXPLICIT, true);
+    }
+    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.
+        const children = n.children;
+        if (Array.isArray(children)) {
+            for (const c of children)
+                if (!emitMdastOp(w, c, false, forReplace))
+                    return false;
+        }
+    }
+    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 = false) {
+    if (isRawMdastContent(content)) {
+        switch (op) {
+            case "replace":
+                return buffer.replace(id, content);
+            case "insertBefore":
+                return buffer.insertBefore(id, content);
+            case "insertAfter":
+                return buffer.insertAfter(id, content);
+            case "prependChild":
+                return buffer.prependChild(id, content);
+            case "appendChild":
+                return buffer.appendChild(id, content);
+            case "wrapNode":
+                return buffer.wrapNode(id, content);
+        }
+    }
+    const ops = compileMdastToOpstream(content, forReplace);
+    if (ops === null)
+        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);
     }
-    return node;
 }
+/** 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) {
     if (result === undefined || result === null)
         return;
@@ -598,7 +514,7 @@ function applyMdastVisitResult(result, nodeId, returnBuffer, originalNode) {
             returnBuffer.replace(nodeId, result);
             break;
         case "structured_node":
-            returnBuffer.replace(nodeId, refifyReusedNodes(result, true));
+            emitMdastTree(returnBuffer, "replace", nodeId, result, true);
             break;
     }
 }
@@ -609,18 +525,18 @@ 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) {
+export function visitMdastHandle(handle, plugin, subs, source, fileURL, data = {}) {
     const getSource = typeof source === "function" ? source : () => source;
-    const context = new MdastVisitorContext(handle, getSource, fileURL);
-    const returnBuffer = new CommandBuffer();
     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 matchBuf = walkMdastHandle(handle, rustSubs);
     const matchView = new DataView(matchBuf.buffer, matchBuf.byteOffset, matchBuf.byteLength);
     const matchCount = ru32(matchView, 0);
     let deferred = null;
     for (let i = 0; i < matchCount; i++) {
-        const indexBase = 4 + i * 12;
+        const indexBase = 4 + i * 10;
         const nodeId = ru32(matchView, indexBase);
         const subIndex = matchBuf[indexBase + 4];
         const dataOffset = ru32(matchView, indexBase + 6);
@@ -640,9 +556,14 @@ export function visitMdastHandle(handle, plugin, subs, source, fileURL) {
             for (const { nodeId, result, originalNode } of results) {
                 applyMdastVisitResult(result, nodeId, returnBuffer, 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);
 }
 function finalizeMdastVisit(handle, context, returnBuffer) {