satteri 0.9.4 → 0.10.0

package/dist/hast/hast-visitor.js

@@ -1,18 +1,17 @@
 import { materializeHastNode } from "./hast-materializer.js";
-import { HastReader, HAST_ELEMENT, HAST_TEXT, HAST_COMMENT, HAST_RAW, HAST_MDX_JSX_ELEMENT, HAST_MDX_JSX_TEXT_ELEMENT, HAST_MDX_FLOW_EXPRESSION, HAST_MDX_TEXT_EXPRESSION, HAST_MDX_ESM, } from "./hast-reader.js";
+import { HastReader, HAST_ROOT, HAST_ELEMENT, HAST_TEXT, HAST_COMMENT, HAST_RAW, HAST_MDX_JSX_ELEMENT, HAST_MDX_JSX_TEXT_ELEMENT, HAST_MDX_FLOW_EXPRESSION, HAST_MDX_TEXT_EXPRESSION, HAST_MDX_ESM, } from "./hast-reader.js";
 import { TYPE_NAMES, NAME_TO_TYPE, VISITOR_KEYS, HAST_OPSTREAM_TYPES, } from "./generated/node-types.js";
-import { CommandBuffer } from "../command-buffer.js";
+import { acquireCommandBuffer, releaseCommandBuffer, CommandBuffer, STRUCTURAL_CMD, } from "../command-buffer.js";
+import { CMD_SET_CHILDREN } from "../generated/wire-constants.js";
 import { OpWriter, OF_VALUE, OF_TAGNAME, OF_NAME, OF_EXPLICIT, PROP_STRING, PROP_BOOL_TRUE, PROP_BOOL_FALSE, PROP_SPACE_SEP, PROP_INT, emitMdxAttr, } from "../op-stream.js";
 import { restorePhantomSpaces } from "../phantom.js";
 import { decodeMdxJsxAttr } from "../mdx-attr.js";
 import { decodeElementProp } from "./element-props.js";
 import { readPosition, rstr } from "../wire-read.js";
 import { walkHandle, applyCommandsToHandle, textContentHandle, parseExpression as napiParseExpression, parseEsm as napiParseEsm, } from "#binding";
-import { asArray, makeRequireNid, mergeAndReset, unencodableContentError, } from "../visitor-shared.js";
-import { LazyChildResolver, markHandleMutated } from "../lazy-child-resolver.js";
+import { asArray, makeRequireNid, mergeAndReset, ROOT_NODE_ID, requireRootReplacement, rootReplacementError, crossPipelineForeign, FOREIGN_REF, unencodableContentError, } from "../visitor-shared.js";
+import { LazyChildResolver, markHandleMutated, registerEpochCacheSlot, } from "../lazy-child-resolver.js";
 import { HastChildStub } from "./child-stub.js";
-/** Maps HastNode objects to their arena node IDs without Object.defineProperty overhead. */
-const nodeIdMap = new WeakMap();
 /** Attach `parseExpression()` to an MDX expression or ESM node. */
 function attachParseExpression(node, parseFn) {
     Object.defineProperty(node, "parseExpression", {
@@ -42,91 +41,87 @@ function attachParseExpression(node, parseFn) {
  * the WeakMap or a NON-enumerable `_nodeId` (the materializers' convention,
  * which spread cannot copy).
  */
-function nid(node) {
+function nid(node, refs) {
     if (node instanceof WalkElement)
-        return node._nid;
+        return node._refs === refs ? node._nid : FOREIGN_REF;
     if (node instanceof HastChildStub)
-        return node._id;
-    const id = nodeIdMap.get(node);
+        return node._refs === refs ? node._id : FOREIGN_REF;
+    const id = refs.get(node);
     if (id !== undefined)
         return id;
     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);
-function hastReusedId(node) {
+/** `wrapNode` allowlist: an unlisted type fails loud instead of silently
+ *  mis-wrapping. */
+const HAST_PARENT_TYPES = ["element", "mdxJsxFlowElement", "mdxJsxTextElement"];
+const HAST_PARENT_TYPE_SET = new Set(HAST_PARENT_TYPES);
+/** A leaf wrapper would make the patch engine drop or displace the wrapped node. */
+function assertHastWrapParent(parentNode) {
+    const type = parentNode.type;
+    if (typeof type === "string" && HAST_PARENT_TYPE_SET.has(type))
+        return;
+    throw new Error(`wrapNode: "${String(type)}" nodes cannot hold children, so they cannot wrap a node. ` +
+        'Wrap in an element instead, e.g. { type: "element", tagName: "div", properties: {}, children: [] } ' +
+        'or { raw: "<div></div>" }.');
+}
+function hastReusedId(node, refs) {
     if (node === null || typeof node !== "object")
         return undefined;
-    const id = nid(node);
-    return typeof id === "number" ? id : undefined;
+    const id = nid(node, refs);
+    return id !== undefined && id !== FOREIGN_REF ? id : undefined;
 }
-// Reused across replacements in a pass — see the note on `mdastWriter`.
-const hastWriter = new OpWriter();
-/** 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 compileHastChildrenToOpstream(children) {
+function emitHastChildrenCommand(buffer, id, children, refs) {
     if (!Array.isArray(children))
-        return null;
-    hastWriter.begin();
-    try {
-        hastWriter.open(NAME_TO_TYPE.root);
+        return false;
+    return buffer.emitOpstreamCommand(CMD_SET_CHILDREN, id, () => {
+        buffer.open(HAST_ROOT);
         for (const c of children) {
-            if (!emitHastOp(hastWriter, c, false))
-                return null;
+            if (!emitHastOp(buffer, c, false, refs))
+                return false;
         }
-        hastWriter.close();
-        return hastWriter.take();
-    }
-    finally {
-        hastWriter.end();
-    }
+        buffer.close();
+        return true;
+    });
 }
-/** Encode `node` as the `op` structural command. HAST content is always a
- *  declarative node (no raw escape hatch), so it compiles to the op-stream or
- *  it's a hard error — the op-stream is the only structural encoding. The
- *  switch stays inline so the buffer calls are monomorphic (computed method
- *  names defeat inline caches on this warm path). */
-function emitHastTree(buffer, op, id, node) {
-    const ops = compileHastToOpstream(node);
-    if (ops === null)
+/** Encode `node` as the `op` structural command, emitting the op-stream
+ *  payload directly into the command buffer (no intermediate copy). HAST
+ *  content is always a declarative node (no raw escape hatch), so it
+ *  compiles or it's a hard error. */
+function emitHastTree(buffer, op, id, node, refs) {
+    const ok = buffer.emitOpstreamCommand(STRUCTURAL_CMD[op], id, () => emitHastOp(buffer, node, true, refs));
+    if (!ok)
         throw unencodableContentError(node);
-    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);
-    }
 }
-/**
- * Compile a declarative HAST replacement tree to the op-stream — the only
- * structural encoding. Reused nodes become `ref`s (transparent passthrough).
- * Returns null when the tree holds a type the replay can't reproduce
- * identically; the caller throws.
- */
-function compileHastToOpstream(root) {
-    hastWriter.begin();
-    try {
-        if (!emitHastOp(hastWriter, root, true))
-            return null;
-        return hastWriter.take();
-    }
-    finally {
-        hastWriter.end();
+/** Separate from the per-node encoder, which rejects a `root` payload. */
+function emitHastRootReplace(buffer, root, refs) {
+    const ok = buffer.emitOpstreamCommand(STRUCTURAL_CMD.replace, ROOT_NODE_ID, () => emitHastRootOp(buffer, root, refs));
+    if (!ok)
+        throw unencodableContentError(root);
+}
+function emitHastRootOp(w, n, refs) {
+    w.open(HAST_ROOT);
+    if (n.data != null)
+        w.data(n.data);
+    const children = n.children;
+    if (Array.isArray(children)) {
+        for (const c of children)
+            if (!emitHastOp(w, c, false, refs))
+                return false;
     }
+    w.close();
+    return true;
 }
-function emitHastOp(w, node, isRoot) {
+function emitHastOp(w, node, isRoot, refs) {
     if (node === null || typeof node !== "object")
         return false;
     if (!isRoot) {
-        const id = hastReusedId(node);
+        const id = hastReusedId(node, refs);
         if (id !== undefined) {
             w.ref(id);
             return true;
@@ -167,7 +162,7 @@ function emitHastOp(w, node, isRoot) {
     const children = n.children;
     if (Array.isArray(children)) {
         for (const c of children)
-            if (!emitHastOp(w, c, false))
+            if (!emitHastOp(w, c, false, refs))
                 return false;
     }
     w.close();
@@ -188,24 +183,29 @@ function emitHastProp(w, name, value) {
         w.prop(name, PROP_SPACE_SEP, value.filter((v) => typeof v === "string").join(" "));
 }
 class HastVisitorContextImpl {
-    #commandBuffer = new CommandBuffer();
-    #diagnostics = [];
+    #commandBuffer = acquireCommandBuffer();
+    #diagnostics;
     /** Track accumulated node state for multiple setProperty calls on the same node. */
     #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;
     fileURL;
     data;
-    constructor(handle, getSource, fileURL, resolver, data) {
+    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();
@@ -213,37 +213,71 @@ class HastVisitorContextImpl {
         return value;
     }
     removeNode(node) {
-        this.#commandBuffer.removeNode(requireNid(node, "removeNode"));
+        this.#commandBuffer.removeNode(requireNid(node, "removeNode", this.#refs));
     }
     replaceNode(node, newNode) {
-        const id = requireNid(node, "replaceNode");
-        emitHastTree(this.#commandBuffer, "replace", id, newNode);
+        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)
+                    emitHastTree(this.#commandBuffer, "insertBefore", id, previous, this.#refs);
+                previous = n;
+            }
+            if (previous === undefined) {
+                // Replacing with nothing drops the node, like removeNode.
+                this.removeNode(node);
+            }
+            else if (id === ROOT_NODE_ID) {
+                emitHastRootReplace(this.#commandBuffer, requireRootReplacement(previous), this.#refs);
+            }
+            else {
+                emitHastTree(this.#commandBuffer, "replace", id, previous, this.#refs);
+            }
+            // A stale queued replacement would win: setProperty folds into it, landing last.
+            this.#pendingNodes.delete(id);
+            return;
+        }
+        if (id === ROOT_NODE_ID) {
+            emitHastRootReplace(this.#commandBuffer, requireRootReplacement(newNode), this.#refs);
+            return;
+        }
+        emitHastTree(this.#commandBuffer, "replace", id, newNode, this.#refs);
         // Track the replacement so a later mdxJsx setProperty can fold into it.
         this.#pendingNodes.set(id, newNode);
     }
     insertBefore(node, newNode) {
-        const id = requireNid(node, "insertBefore");
+        const id = requireNid(node, "insertBefore", this.#refs);
         for (const n of asArray(newNode))
-            emitHastTree(this.#commandBuffer, "insertBefore", id, n);
+            emitHastTree(this.#commandBuffer, "insertBefore", id, n, this.#refs);
     }
     insertAfter(node, newNode) {
-        const id = requireNid(node, "insertAfter");
+        const id = requireNid(node, "insertAfter", this.#refs);
         for (const n of asArray(newNode))
-            emitHastTree(this.#commandBuffer, "insertAfter", id, n);
+            emitHastTree(this.#commandBuffer, "insertAfter", id, n, this.#refs);
     }
     wrapNode(node, parentNode) {
-        const id = requireNid(node, "wrapNode");
-        emitHastTree(this.#commandBuffer, "wrapNode", id, parentNode);
+        const id = requireNid(node, "wrapNode", this.#refs);
+        if (typeof parentNode.raw === "string" ||
+            typeof parentNode.rawHtml === "string") {
+            this.#commandBuffer.wrapNode(id, parentNode);
+            return;
+        }
+        assertHastWrapParent(parentNode);
+        emitHastTree(this.#commandBuffer, "wrapNode", id, parentNode, this.#refs);
     }
     prependChild(node, childNode) {
-        const id = requireNid(node, "prependChild");
+        const id = requireNid(node, "prependChild", this.#refs);
         for (const n of asArray(childNode))
-            emitHastTree(this.#commandBuffer, "prependChild", id, n);
+            emitHastTree(this.#commandBuffer, "prependChild", id, n, this.#refs);
     }
     appendChild(node, childNode) {
-        const id = requireNid(node, "appendChild");
+        const id = requireNid(node, "appendChild", this.#refs);
         for (const n of asArray(childNode))
-            emitHastTree(this.#commandBuffer, "appendChild", id, n);
+            emitHastTree(this.#commandBuffer, "appendChild", id, n, this.#refs);
     }
     insertChildAt(node, index, childNode) {
         const children = "children" in node ? node.children : [];
@@ -263,14 +297,13 @@ class HastVisitorContextImpl {
             this.removeNode(child);
     }
     setProperty(node, key, value) {
-        const id = requireNid(node, "setProperty");
+        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 ops = compileHastChildrenToOpstream(value);
-            if (!ops)
+            if (!emitHastChildrenCommand(this.#commandBuffer, id, value, this.#refs)) {
                 throw unencodableContentError(value);
-            this.#commandBuffer.setChildrenOpstream(id, ops);
+            }
             return;
         }
         if (key === "data") {
@@ -319,10 +352,10 @@ class HastVisitorContextImpl {
         this.#commandBuffer.setProperty(id, key, value);
     }
     textContent(node) {
-        return textContentHandle(this.#handle, requireNid(node, "textContent"));
+        return textContentHandle(this.#handle, requireNid(node, "textContent", this.#refs));
     }
     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());
@@ -334,10 +367,15 @@ class HastVisitorContextImpl {
         return parent;
     }
     indexOf(node) {
-        return this.#resolver.indexInParent(requireNid(node, "indexOf"));
+        return this.#resolver.indexInParent(requireNid(node, "indexOf", this.#refs));
     }
     report({ message, node, severity = "error", }) {
-        this.#diagnostics.push({ message, nodeId: node ? nid(node) : undefined, severity });
+        const id = node ? nid(node, this.#refs) : undefined;
+        this.#diagnostics.push({
+            message,
+            nodeId: id === FOREIGN_REF ? undefined : id,
+            severity,
+        });
     }
     getCommandBuffer() {
         return this.#commandBuffer;
@@ -348,7 +386,40 @@ class HastVisitorContextImpl {
 }
 /** Node types that use filtered visitors (have tag/component names). */
 const FILTERED_METHODS = new Set(["element", "mdxJsxFlowElement", "mdxJsxTextElement"]);
+const subscriptionCache = new WeakMap();
 export function resolveSubscriptions(plugin) {
+    const cached = subscriptionCache.get(plugin);
+    if (cached !== undefined)
+        return cached.subs;
+    const built = buildSubscriptions(plugin);
+    subscriptionCache.set(plugin, built);
+    return built.subs;
+}
+/** Get the (cached) Rust-side projection of `subs` that strips visitFn so it
+ *  can cross NAPI. Computed once per plugin object alongside `subs`. */
+function getRustSubs(plugin) {
+    const cached = subscriptionCache.get(plugin);
+    if (cached !== undefined)
+        return cached.rustSubs;
+    const built = buildSubscriptions(plugin);
+    subscriptionCache.set(plugin, built);
+    return built.rustSubs;
+}
+function isFilteredVisitor(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        Array.isArray(value.filter) &&
+        typeof value.visit === "function");
+}
+/** Caught pre-wire so the failure names the API shape, not the internal `tagFilter` field. */
+function malformedFilteredVisitorError(plugin, methodName) {
+    const name = plugin.name;
+    const pluginName = typeof name === "string" && name !== "" ? name : "(unnamed)";
+    return new Error(`hast plugin "${pluginName}": "${methodName}" visitors filter by tag/component name, ` +
+        `so each must be an object { filter: string[], visit: function } (or an array of those). ` +
+        `Use filter: [] to visit every "${methodName}" node.`);
+}
+function buildSubscriptions(plugin) {
     const subs = [];
     for (const [methodName, nodeType] of Object.entries(METHOD_TO_TYPE)) {
         const value = plugin[methodName];
@@ -357,6 +428,8 @@ export function resolveSubscriptions(plugin) {
         if (FILTERED_METHODS.has(methodName)) {
             const items = Array.isArray(value) ? value : [value];
             for (const fv of items) {
+                if (!isFilteredVisitor(fv))
+                    throw malformedFilteredVisitorError(plugin, methodName);
                 subs.push({
                     nodeType,
                     tagFilter: fv.filter,
@@ -369,7 +442,8 @@ export function resolveSubscriptions(plugin) {
             subs.push({ nodeType, tagFilter: [], visitFn: value });
         }
     }
-    return subs;
+    const rustSubs = subs.map((s) => ({ nodeType: s.nodeType, tagFilter: s.tagFilter }));
+    return { subs, rustSubs };
 }
 /** Visitor method name → node-type tag (method names are the subscribable AST names). */
 const METHOD_TO_TYPE = Object.fromEntries([...VISITOR_KEYS].map((name) => [name, NAME_TO_TYPE[name]]));
@@ -393,11 +467,18 @@ function decodeProperties(view, buf, pos) {
     return properties;
 }
 /** 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 readChildStubs(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(view.getUint32(idsPos + i * 4, true));
+        }
+        return nodes;
+    }
     const stubs = new Array(count);
     for (let i = 0; i < count; i++) {
         stubs[i] = new HastChildStub(resolver, view.getUint32(idsPos + i * 4, true), buf[typesPos + i]);
@@ -421,23 +502,19 @@ class WalkElement {
     type = "element";
     tagName;
     #nodeId;
-    #view;
-    #buf;
+    #wire;
     #propsPos;
     #childIdsPos;
     #childTypesPos;
     #childCount;
-    #resolver;
-    constructor(tagName, nodeId, view, buf, propsPos, propCount, childIdsPos, childTypesPos, childCount, resolver) {
+    constructor(tagName, nodeId, wire, propsPos, propCount, childIdsPos, childTypesPos, childCount) {
         this.tagName = tagName;
         this.#nodeId = nodeId;
-        this.#view = view;
-        this.#buf = buf;
+        this.#wire = wire;
         this.#propsPos = propsPos;
         this.#childIdsPos = childIdsPos;
         this.#childTypesPos = childTypesPos;
         this.#childCount = childCount;
-        this.#resolver = resolver;
         if (propCount === 0) {
             this.properties = {};
         }
@@ -455,12 +532,17 @@ class WalkElement {
     get _nid() {
         return this.#nodeId;
     }
+    /** @internal */
+    get _refs() {
+        return this.#wire.resolver.refs;
+    }
     static {
         WALK_PROPS_DESC = {
             enumerable: true,
             configurable: true,
             get() {
-                const val = decodeProperties(this.#view, this.#buf, this.#propsPos);
+                const w = this.#wire;
+                const val = decodeProperties(w.view, w.buf, this.#propsPos);
                 Object.defineProperty(this, "properties", {
                     value: val,
                     writable: true,
@@ -474,7 +556,8 @@ class WalkElement {
             enumerable: true,
             configurable: true,
             get() {
-                const val = readChildStubs(this.#view, this.#buf, this.#childIdsPos, this.#childTypesPos, this.#childCount, this.#resolver);
+                const w = this.#wire;
+                const val = readChildStubs(w.view, w.buf, this.#childIdsPos, this.#childTypesPos, this.#childCount, w.resolver);
                 Object.defineProperty(this, "children", {
                     value: val,
                     writable: true,
@@ -488,15 +571,15 @@ class WalkElement {
 }
 /** Read the tail of a matched element node (tag + properties).
  *  Common prelude (data/position/children) is already consumed by `readMatchedNode`. */
-function readElementFromBinary(view, buf, offset, nodeId, resolver, position, childIdsPos, childTypesPos, childCount, data) {
+function readElementFromBinary(wire, offset, nodeId, position, childIdsPos, childTypesPos, childCount, data) {
     let pos = offset;
     // Eager: tagName (almost always accessed by visitors)
-    const tagLen = view.getUint16(pos, true);
+    const tagLen = wire.view.getUint16(pos, true);
     pos += 2;
-    const tagName = rstr(buf, pos, tagLen);
+    const tagName = rstr(wire.buf, pos, tagLen);
     pos += tagLen;
-    const propCount = view.getUint16(pos, true);
-    const node = new WalkElement(tagName, nodeId, view, buf, pos, propCount, childIdsPos, childTypesPos, childCount, resolver);
+    const propCount = wire.view.getUint16(pos, true);
+    const node = new WalkElement(tagName, nodeId, wire, pos, propCount, childIdsPos, childTypesPos, childCount);
     if (position !== undefined)
         node.position = position;
     if (data !== null)
@@ -505,7 +588,7 @@ function readElementFromBinary(view, buf, offset, nodeId, resolver, position, ch
 }
 /** Value-carrying types read by `readTextFromBinary` (tag → AST name). */
 const TEXT_NODE_TYPES = Object.fromEntries(["text", "comment", "raw", "mdxFlowExpression", "mdxTextExpression", "mdxjsEsm"].map((name) => [NAME_TO_TYPE[name], name]));
-function readTextFromBinary(view, buf, offset, nodeId, nodeType, position, data) {
+function readTextFromBinary(view, buf, offset, nodeId, nodeType, position, data, refs) {
     const valLen = view.getUint32(offset, true);
     const rawValue = rstr(buf, offset + 4, valLen);
     // MDX flow/text expressions store phantom-space sentinels; restore them so
@@ -519,7 +602,7 @@ function readTextFromBinary(view, buf, offset, nodeId, nodeType, position, data)
     if (data !== null)
         base.data = data;
     const node = base;
-    nodeIdMap.set(node, nodeId);
+    refs.set(node, nodeId);
     if (nodeType === HAST_MDX_FLOW_EXPRESSION || nodeType === HAST_MDX_TEXT_EXPRESSION) {
         attachParseExpression(node, napiParseExpression);
     }
@@ -557,11 +640,12 @@ function readMdxJsxFromBinary(view, buf, offset, nodeId, nodeType, resolver, pos
         base.position = position;
     if (data !== null)
         base.data = data;
-    nodeIdMap.set(base, nodeId);
+    resolver.refs.set(base, nodeId);
     makeLazyChildren(base, view, buf, childIdsPos, childTypesPos, childCount, resolver);
     return base;
 }
-function readMatchedNode(view, buf, offset, nodeId, nodeType, resolver) {
+function readMatchedNode(wire, offset, nodeId, nodeType) {
+    const { view, buf, resolver } = wire;
     let pos = offset;
     // Shared prelude (matches serialize_hast_node_inline / serialize_mdast_node_inline):
     //   [data_len: u32][data_bytes][position: 24B][child_count: u32][child_ids: N×u32][child_types: N×u8]
@@ -591,7 +675,7 @@ function readMatchedNode(view, buf, offset, nodeId, nodeType, resolver) {
     pos += childCount;
     // Dispatch to type-specific tail (pos now sits at the type-specific section)
     if (nodeType === HAST_ELEMENT) {
-        return readElementFromBinary(view, buf, pos, nodeId, resolver, position, childIdsPos, childTypesPos, childCount, data);
+        return readElementFromBinary(wire, pos, nodeId, position, childIdsPos, childTypesPos, childCount, data);
     }
     else if (nodeType === HAST_TEXT ||
         nodeType === HAST_COMMENT ||
@@ -599,27 +683,40 @@ function readMatchedNode(view, buf, offset, nodeId, nodeType, resolver) {
         nodeType === HAST_MDX_FLOW_EXPRESSION ||
         nodeType === HAST_MDX_TEXT_EXPRESSION ||
         nodeType === HAST_MDX_ESM) {
-        return readTextFromBinary(view, buf, pos, nodeId, nodeType, position, data);
+        return readTextFromBinary(view, buf, pos, nodeId, nodeType, position, data, resolver.refs);
     }
     else if (nodeType === HAST_MDX_JSX_ELEMENT || nodeType === HAST_MDX_JSX_TEXT_ELEMENT) {
         return readMdxJsxFromBinary(view, buf, pos, nodeId, nodeType, resolver, position, childIdsPos, childTypesPos, childCount, data);
     }
-    // Fallback (e.g. doctype): minimal node carrying whatever prelude data we found
+    // Fallback: root and doctype.
     const base = { type: TYPE_NAMES[nodeType] ?? `unknown(${nodeType})` };
     if (position !== undefined)
         base.position = position;
     if (data !== null)
         base.data = data;
+    if (nodeType === HAST_ROOT) {
+        // `...root.children` has to work in a hook.
+        if (childCount > 0) {
+            makeLazyChildren(base, view, buf, childIdsPos, childTypesPos, childCount, resolver);
+        }
+        else {
+            base.children = [];
+        }
+    }
     const node = base;
-    nodeIdMap.set(node, nodeId);
+    resolver.refs.set(node, nodeId);
     return node;
 }
+const HAST_EPOCH_CACHE = registerEpochCacheSlot(new WeakMap());
 class HastLazyChildResolver extends LazyChildResolver {
+    cacheSlot() {
+        return HAST_EPOCH_CACHE;
+    }
     createReader(wire) {
         return new HastReader(wire);
     }
-    materializeNode(reader, nodeId) {
-        return materializeHastNode(reader, nodeId);
+    materializeNode(reader, nodeId, refs) {
+        return materializeHastNode(reader, nodeId, true, refs);
     }
     readParentId(reader, nodeId) {
         return reader.getParentId(nodeId);
@@ -649,27 +746,54 @@ function makeLazyChildren(node, view, buf, childIdsPos, childTypesPos, childCoun
     });
 }
 /** 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 handleVisitResult(result, nodeId, returnBuffer, deferred, originalNode) {
+ *  mutations (e.g. setProperty) are not clobbered.
+ *
+ *  A same-type text-like node carrying only a new `value` becomes a
+ *  setProperty("value") rather than a structural replace, which would force
+ *  the arena into a full rebuild for a shape that didn't change. */
+function applyHastVisitResult(result, nodeId, returnBuffer, originalNode, refs) {
     if (result == null)
-        return deferred;
+        return;
     if (result === originalNode)
-        return deferred;
+        return;
+    if (isTextValueSwap(result, originalNode)) {
+        returnBuffer.setProperty(nodeId, "value", result.value);
+        return;
+    }
+    emitHastTree(returnBuffer, "replace", nodeId, result, refs);
+}
+function handleVisitResult(result, nodeId, returnBuffer, deferred, originalNode, refs) {
     if (result instanceof Promise) {
         const list = deferred ?? [];
         list.push({ nodeId, promise: result, originalNode });
         return list;
     }
-    emitHastTree(returnBuffer, "replace", nodeId, result);
+    applyHastVisitResult(result, nodeId, returnBuffer, originalNode, refs);
     return deferred;
 }
-/**
- * Dispatch matched nodes from a binary match buffer to visitor functions.
- * Returns null if all sync, or an array of deferred promises if any visitor was async.
- */
+/** True when `result` is a same-type text-like node carrying only `type` +
+ *  `value`. The explicit `=== undefined` checks avoid the array alloc of
+ *  `Object.keys().length` on this per-text-node hot path. */
+function isTextValueSwap(result, original) {
+    if (result.type !== original.type)
+        return false;
+    if (result.type !== "text" && result.type !== "comment" && result.type !== "raw")
+        return false;
+    const r = result;
+    if (typeof r.value !== "string")
+        return false;
+    return (r.children === undefined &&
+        r.position === undefined &&
+        r.data === undefined &&
+        r.tagName === undefined &&
+        r.properties === undefined &&
+        r.name === undefined &&
+        r.attributes === undefined);
+}
 function dispatchMatches(matchBuf, subs, ctx, returnBuffer, resolver) {
     const matchView = new DataView(matchBuf.buffer, matchBuf.byteOffset, matchBuf.byteLength);
     const matchCount = matchView.getUint32(0, true);
+    const wire = { view: matchView, buf: matchBuf, resolver };
     let deferred = null;
     for (let i = 0; i < matchCount; i++) {
         const indexBase = 4 + i * 10;
@@ -677,9 +801,9 @@ function dispatchMatches(matchBuf, subs, ctx, returnBuffer, resolver) {
         const subIndex = matchBuf[indexBase + 4];
         const dataOffset = matchView.getUint32(indexBase + 6, true);
         const sub = subs[subIndex];
-        const node = readMatchedNode(matchView, matchBuf, dataOffset, nodeId, sub.nodeType, resolver);
+        const node = readMatchedNode(wire, dataOffset, nodeId, sub.nodeType);
         const result = sub.visitFn(node, ctx);
-        deferred = handleVisitResult(result, nodeId, returnBuffer, deferred, node);
+        deferred = handleVisitResult(result, nodeId, returnBuffer, deferred, node, resolver.refs);
     }
     return deferred;
 }
@@ -691,35 +815,77 @@ function dispatchMatches(matchBuf, subs, ctx, returnBuffer, resolver) {
  * replaced earlier in the same pass (the caller warns when non-zero), or a
  * Promise of that count if any visitor is async.
  */
-export function visitHastHandle(handle, plugin, subs, source, fileURL, data = {}) {
+export function visitHastHandle(handle, plugin, subs, source, fileURL, data = {}, sourceFormat = "markdown", diagnostics = []) {
+    const result = visitHastHandleCollect(handle, plugin, subs, source, fileURL, data, sourceFormat, diagnostics);
+    if (result instanceof Promise) {
+        return result.then((commands) => applyCollectedCommands(handle, commands));
+    }
+    return applyCollectedCommands(handle, result);
+}
+/** Apply commands collected by `visitHastHandleCollect`; returns the number of
+ *  patches dropped as stranded (0 when none). */
+function applyCollectedCommands(handle, commands) {
+    if (commands.length === 0)
+        return 0;
+    markHandleMutated(handle);
+    return applyCommandsToHandle(handle, commands);
+}
+/** Run a HAST visitor, build the command buffer, but do NOT apply it. Returns
+ *  the merged commands so the caller can choose how to dispatch: either via
+ *  `applyCommandsToHandle` (intermediate plugins in a chain) or via a fused
+ *  NAPI call like `applyCommandsAndRenderHandle` (final plugin, saves one
+ *  apply + one render + one drop crossing). Empty result means no mutations.
+ */
+export function visitHastHandleCollect(handle, plugin, subs, source, fileURL, data = {}, sourceFormat = "markdown", diagnostics = []) {
     const getSource = typeof source === "function" ? source : () => source;
     const resolver = new HastLazyChildResolver(handle);
-    const ctx = new HastVisitorContextImpl(handle, getSource, fileURL, resolver, data);
-    const returnBuffer = new CommandBuffer();
-    const rustSubs = subs.map((s) => ({ nodeType: s.nodeType, tagFilter: s.tagFilter }));
+    const ctx = new HastVisitorContextImpl(handle, getSource, fileURL, resolver, data, sourceFormat, diagnostics);
+    const returnBuffer = acquireCommandBuffer();
+    const rustSubs = getRustSubs(plugin);
     const deferred = dispatchMatches(walkHandle(handle, rustSubs), subs, ctx, returnBuffer, resolver);
     if (deferred) {
         return Promise.all(deferred.map((d) => d.promise.then((result) => ({ nodeId: d.nodeId, result, originalNode: d.originalNode })))).then((results) => {
             for (const { nodeId, result, originalNode } of results) {
-                if (result != null && result !== originalNode) {
-                    emitHastTree(returnBuffer, "replace", nodeId, result);
-                }
+                applyHastVisitResult(result, nodeId, returnBuffer, originalNode, resolver.refs);
             }
-            // Mutations land next, renumbering the arena: snapshots taken after
-            // this point would resolve match-time child ids against wrong nodes.
-            resolver.seal();
-            return applyMutations(handle, returnBuffer, ctx);
+            return collectCommands(returnBuffer, ctx);
         });
     }
-    resolver.seal();
-    return applyMutations(handle, returnBuffer, ctx);
+    return collectCommands(returnBuffer, ctx);
+}
+const HAST_ROOT_SUBS = [
+    { nodeType: HAST_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 visitHastHookCollect(handle, plugin, hook, source, fileURL, data = {}, sourceFormat = "markdown", diagnostics = []) {
+    const getSource = typeof source === "function" ? source : () => source;
+    const resolver = new HastLazyChildResolver(handle);
+    const ctx = new HastVisitorContextImpl(handle, getSource, fileURL, resolver, data, sourceFormat, diagnostics);
+    const returnBuffer = acquireCommandBuffer();
+    const matchBuf = walkHandle(handle, HAST_ROOT_SUBS);
+    const matchView = new DataView(matchBuf.buffer, matchBuf.byteOffset, matchBuf.byteLength);
+    if (matchView.getUint32(0, true) === 0)
+        return collectCommands(returnBuffer, ctx);
+    const wire = { view: matchView, buf: matchBuf, resolver };
+    const root = readMatchedNode(wire, matchView.getUint32(10, true), matchView.getUint32(4, true), HAST_ROOT);
+    const result = hook.call(plugin, root, ctx);
+    if (result instanceof Promise)
+        return result.then(() => collectCommands(returnBuffer, ctx));
+    return collectCommands(returnBuffer, ctx);
 }
-/** Returns the number of patches dropped as stranded (0 when none). */
-function applyMutations(handle, returnBuffer, ctx) {
-    const { merged, hasMutations } = mergeAndReset(returnBuffer, ctx);
-    if (hasMutations) {
-        markHandleMutated(handle);
-        return applyCommandsToHandle(handle, merged);
+export function visitHastHook(handle, plugin, hook, source, fileURL, data = {}, sourceFormat = "markdown", diagnostics = []) {
+    const result = visitHastHookCollect(handle, plugin, hook, source, fileURL, data, sourceFormat, diagnostics);
+    if (result instanceof Promise) {
+        return result.then((commands) => applyCollectedCommands(handle, commands));
     }
-    return 0;
+    return applyCollectedCommands(handle, result);
+}
+function collectCommands(returnBuffer, ctx) {
+    const { merged } = mergeAndReset(returnBuffer, ctx);
+    // Return the buffers to the pool. The merged Uint8Array above already
+    // copied the bytes out, so the underlying ArrayBuffers can be reused.
+    releaseCommandBuffer(returnBuffer);
+    releaseCommandBuffer(ctx.getCommandBuffer());
+    return merged;
 }